JavaScript-based citation generation

Update docs

.gitignore

@@ -1,4 +1,3 @@
-
 # Created by https://www.gitignore.io/api/python,sublimetext,vim
 
 ### Python ###

README.md

@@ -12,6 +12,7 @@ ZotHero
 - [Features](#features)
 - [Download & installation](#download--installation)
 - [Usage](#usage)
+    - [Pasting citations](#pasting-citations)
 - [Configuration](#configuration)
     - [Zotero data](#zotero-data)
     - [Citation styles](#citation-styles)
@@ -45,6 +46,8 @@ Download the `ZotHero-XYZ.alfredworkflow` file from [GitHub releases](https://gi
 Usage
 -----
 
+These are the workflow's default keywords in Alfred:
+
 - `zot <query>` — Search your Zotero database (all fields).
     - `↩` — Open the entry in Zotero.
     - `⌘↩` — Copy citation to the pasteboard (see [Configuration](#configuration)).
@@ -59,13 +62,20 @@ Usage
     - `↩` — Select a field to search against.
 - `zotconf [<query>]` — View and edit workflow configuration.
     - `An Update is Available` / `Workflow is Up To Date` — Whether a newer version of the workflow is available.
-    - `Default Style: …` — Choose citation style for the `⌘↩` and `⌥↩` hotkeys (on search results).
+    - `Default Style: …` — Choose a citation style for the `⌘↩` and `⌥↩` hotkeys (on search results).
+    - `Locale: …` — Choose a locale for the formatting of citations. If unset, the default for the style is used, or if none is set, US English.
     - `Reload Zotero Cache` — Clear the workflow's cache of Zotero data. Useful if the workflow gets out of sync with Zotero.
     - `Open Log File` — Open the workflows log file in the default app (usually Console.app). Useful for checking on indexing problems (the indexer output isn't visible in Alfred's debugger).
     - `View Documentation` — Open this README in your browser.
     - `Report an Issue` — Open the GitHub issue tracker in your browser.
 
 
+<a name="pasting-citations"></a>
+### Pasting citations ###
+
+When you copy a citation, ZotHero puts both HTML and rich text (RTF) representations on the pasteboard. That way, when you paste a citation into an application like Word, the formatted text will be pasted, but when you paste into a text/Markdown document, the HTML will be pasted.
+
+
 <a name="configuration"></a>
 Configuration
 -------------
@@ -98,7 +108,9 @@ For `⌘↩` and `⌥↩` to work on search results, you must first choose a def
 <a name="locales"></a>
 ### Locales ###
 
-[CSL][csl] and ZotHero support the following locales. The default locale is `en-US` (American English). Use the `zotconf` keyword to set a different locale.
+[CSL][csl] and ZotHero support the following locales. The default behaviour is to use the locale specified in the style if there is one, and `en-US` (American English) if not. Setting a locale overrides the style's own locale.
+
+Use the `zotconf` keyword to force a specific locale.
 
 |                    Locale                    |   Code  |
 |----------------------------------------------|---------|

cpjs/.gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+
+# Generated script
+/cite

cpjs/README.md

@@ -0,0 +1,6 @@
+cpjs
+====
+
+A CSL citation generator based on `[citeproc-js][citeproc-js]`.
+
+[citeproc-js]: https://github.com/Juris-M/citeproc-js

cpjs/bench

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# Copyright (c) 2017 Dean Jackson <deanishe@deanishe.net>
+#
+# MIT Licence. See http://opensource.org/licenses/MIT
+#
+# Created on 2017-12-24
+#
+
+"""Benchmark the speed of cite.js."""
+
+
+from __future__ import print_function, absolute_import
+
+from contextlib import contextmanager
+import os
+import subprocess
+import sys
+from time import time
+
+REPS = 20
+TIMES = []
+
+HERE = os.path.dirname(__file__)
+STYLE = os.path.expanduser('~/Zotero/styles/apa.csl')
+LOCALES = os.path.join(HERE, 'locales')
+DATA = os.path.join(HERE, 'test.json')
+
+
+def log(s, *args):
+    """Simple STDERR logger."""
+    if args:
+        s = s % args
+    print(s, file=sys.stderr)
+
+
+@contextmanager
+def timed(name):
+    start = time()
+    yield
+    d = time() - start
+    log('[%s] %0.2fs', name, d)
+    TIMES.append(d)
+
+
+for i in range(REPS):
+    with timed('cite'):
+        subprocess.check_output(['./cite', '-L', LOCALES, STYLE, DATA])
+
+
+log('[average] %0.3fs', sum(TIMES) / len(TIMES))

cpjs/build

@@ -0,0 +1,66 @@
+#!/bin/zsh
+
+set -e
+
+here="$( cd "$( dirname "$0" )"; pwd )"
+outfile="${here}/cite"
+libfile="${here}/../src/lib/cite/cite"
+minify=false
+
+usage() {
+    cat <<EOS
+build [-m|-h]
+
+Build `cite` from citeproc-js and cite.js.
+
+Usage:
+    build [-m]
+    build -h
+
+Options:
+    -m      Minify generated script
+    -h      Show this help message and exit
+EOS
+}
+
+while getopts ":hm" opt; do
+  case $opt in
+    h)
+      usage
+      exit 0
+      ;;
+    m)
+      minify=true
+      ;;
+    \?)
+      log "Invalid option: -$OPTARG"
+      exit 1
+      ;;
+  esac
+done
+shift $((OPTIND-1))
+
+
+echo '' > "$outfile"
+echo '#!/usr/bin/osascript -l JavaScript' > "$outfile"
+echo "\n" >> "$outfile"
+
+echo "window = this;\n\n" >> "$outfile"
+
+echo "// ======================== citeproc ==========================\n" >> "$outfile"
+
+$minify && {
+  browserify -r citeproc -s CSL | uglifyjs -c -m -r CSL >> "$outfile"
+} || {
+  browserify -r citeproc -s CSL  >> "$outfile"
+}
+
+
+echo "\n\n// ======================== /citeproc =========================\n" >> "$outfile"
+
+
+cat "${here}/cite.js" >> "$outfile"
+
+chmod +x "$outfile"
+
+command cp -vf "$outfile" "$libfile"

cpjs/cite.js

@@ -0,0 +1,190 @@
+
+ObjC.import('stdlib')
+ObjC.import('Foundation')
+var fm = $.NSFileManager.defaultManager
+
+
+Array.prototype.contains = function(val) {
+    for (var i; i < this.length; i++) {
+        if (this[i] === val)
+            return true
+    }
+    return false
+}
+
+var usage = `cite [options] <style.csl> <csl.json>
+
+Generate an HTML CSL citation for item defined in <csl.json> using
+the stylesheet specified by <style.csl>.
+
+Usage:
+    cite [-b] [-v] [-l <lang>] [-L <dir>] <style.csl> <csl.json>
+    cite (-h|--help)
+
+Options:
+        -b, --bibliography               Generate bibliography-style citation
+        -l <lang>, --locale <lang>       Locale for citation
+        -L <dir>, --locale-dir <dir>     Directory locale files are in
+        -v, --verbose                    Show status messages
+        -h, --help                       Show this message and exit
+
+`
+
+// Show CLI help and exit.
+function showHelp(errMsg) {
+    var status = 0
+    if (errMsg) {
+        console.log(`error: ${errMsg}`)
+        status = 1
+    }
+    console.log(usage)
+    $.exit(status)
+}
+
+// Parse command-line flags.
+function parseArgs(argv) {
+    argv.forEach(function(s) {
+        if (s == '-h' || s == '--help')
+            showHelp()
+    })
+    if (argv.length == 0)
+        showHelp()
+
+    var args = [],
+        opts = {
+            locale: null,
+            localeDir: './locales',
+            style: null,
+            csl: null,
+            bibliography: false,
+            verbose: false
+        }
+
+    // Extract flags and collect arguments
+    for (var i=0; i < argv.length; i++) {
+        var s = argv[i]
+
+        if (s.startsWith('-')) {
+
+            if (s == '--locale' || s == '-l') {
+                opts.locale = argv[i+1]
+                i++
+            }
+
+            else if (s == '--locale-dir' || s == '-L') {
+                opts.localeDir = argv[i+1]
+                i++
+            }
+
+            else if (s == '--bibliography' || s == '-b')
+                opts.bibliography = true
+
+            else if (s == '--verbose' || s == '-v')
+                opts.verbose = true
+
+            else
+                showHelp('unknown option: ' + s)
+
+        } else {
+            args.push(s)
+        }
+    }
+
+    // Arguments
+    if (args.length > 2)
+        showHelp('script takes 2 arguments')
+
+    if (args.length > 0)
+        opts.style = args[0]
+
+    if (args.length > 1)
+        opts.csl = args[1]
+
+    return opts
+}
+
+// Read file at `path` and return its contents as a string.
+function readFile(path) {
+    var contents = $.NSString.alloc.initWithDataEncoding(fm.contentsAtPath(path), $.NSUTF8StringEncoding)
+    return ObjC.unwrap(contents)
+}
+
+
+function stripOuterDiv(html) {
+    var match = new RegExp('^<div.*?>(.+)</div>$').exec(html)
+    if (match != null)
+        return match[1]
+
+    return html
+}
+
+
+var Citer = function(opts) {
+    this.opts = opts
+    this.item = JSON.parse(readFile(opts.csl))
+    this.style = readFile(opts.style)
+    this.id = this.item.id
+
+    var locale = 'en',
+        force = false
+
+    if (opts.locale) {
+        locale = opts.locale
+        force = true
+    }
+
+    this.citer = new CSL.Engine(this, this.style, locale, force)
+}
+
+
+Citer.prototype.retrieveItem = function(id) {
+    return this.item
+}
+
+Citer.prototype.retrieveLocale = function(lang) {
+    if (this.opts.verbose) {
+        console.log(`locale=${lang}`)
+        console.log(`localeDir=${this.opts.localeDir}`)
+    }
+
+    return readFile(`${this.opts.localeDir}/locales-${lang}.xml`)
+}
+
+Citer.prototype.cite = function() {
+    var data = {html: '', rtf: ''}
+    this.citer.updateItems([this.id])
+
+    if (this.opts.bibliography) {
+
+        // -----------------------------------------------------
+        // HTML
+        var html = this.citer.makeBibliography()[1].join('\n').trim()
+        data.html = stripOuterDiv(html)
+
+        // -----------------------------------------------------
+        // RTF
+        this.citer.setOutputFormat('rtf')
+        data.rtf = this.citer.makeBibliography()[1].join('\n')
+
+    } else {
+        data.html = this.citer.makeCitationCluster([this.id])
+        this.citer.setOutputFormat('rtf')
+        data.rtf = this.citer.makeCitationCluster([this.id])
+    }
+
+    return data
+}
+
+
+function run(argv) {
+
+    var opts = parseArgs(argv)
+
+    if (opts.verbose) {
+        console.log(`bibliography=${opts.bibliography}`)
+        console.log(`csl=${opts.csl}`)
+        console.log(`style=${opts.style}`)
+    }
+
+    return JSON.stringify(new Citer(opts).cite())
+}

cpjs/locales

@@ -0,0 +1 @@
+../src/lib/cite/locales