Initial Commit

Zettlr · Jun 10, 2019 · ff8c7e7 · ff8c7e7
commit ff8c7e7
Show file tree

Hide file tree

Showing 20 changed files with 1,988 additions and 0 deletions.
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -0,0 +1,149 @@
+# Citr
+
+> Converts Markdown Citations to CSL JSON
+
+A small library for parsing Markdown citeproc citations to valid CSL JSON (and vice versa).
+
+## Description
+
+This module transforms citations as they are described in the Pandoc manual into valid CSL JSON that can then -- for instance -- be passed to citeproc-js.
+
+## Install
+
+With NPM:
+
+```bash
+$ npm install citr
+```
+
+With Yarn:
+
+```bash
+$ yarn add citr
+```
+
+## Usage
+
+```javascript
+Citr.parseSingle(markdown) // Parses a single citation from Markdown to CSL JSON
+Citr.makeCitation(csl) // Converts a CSL JSON citation to Markdown
+Citr.util.extractCitations(text) // Extracts all citations from a text
+Citr.util.validateCitationID(key) // Validates a given citation key
+```
+
+Citr exposes a small API that you can conveniently use:
+
+```javascript
+const Citr = require('Citr')
+
+let myCitation = '[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
+
+let csl = Citr.parseSingle(myCitation)
+
+/*
+[
+  {
+    prefix: 'see',
+    suffix: '',
+    id: 'doe99',
+    locator: '33-35',
+    label: 'page',
+    'suppress-author': true
+  },
+  {
+    prefix: 'also',
+    suffix: '',
+    id: 'smith04',
+    locator: '1',
+    label: 'chapter',
+    'suppress-author': false
+  }
+]
+*/
+```
+
+If the citation contains any malformed partial citations, Citr will throw an error, so to test for errors, use try/catch constructs:
+
+```javascript
+const Citr = require('Citr')
+let myCitation = '[Malformed ID inside @.this key]'
+let csl = ''
+
+try {
+  csl = Citr.parseSingle(myCitation)
+} catch (err) {
+  console.error(`The citation was malformed.`)
+}
+```
+
+To extract all citations that are inside a given Markdown file/text, Citr exposes a convenient function:
+
+```javascript
+const Citr = require('Citr')
+
+let myText = 'This is some Text, where both Doe [-@doe99] and others said something [see -@doe99, pp. 33-35; also @smith04, chap. 1]. Of course, this is debatable.'
+
+let citations = Citr.util.extractCitations(myText)
+/*
+[
+  '[-doe99]',
+  '[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
+]
+*/
+```
+
+You can then afterwards pass all citations in a `for`-loop through the `parseSingle`-function.
+
+If you simply want to conveniently check an ID, use the utility function `validateCitationID`:
+
+```javascript
+const Citr = require('Citr')
+
+let goodKey = '@Doe1990'
+let badKey = '@.wrongKey'
+
+Citr.util.validateCitationID(goodKey) // true
+Citr.util.validateCitationID(badKey) // false
+```
+
+Last but not least you may want to generate a Markdown citation string from a given CSL JSON object. To do so, simply pass a CSL JSON object to the `makeCitation` function. The only required attribute is `id`. Please note that this conversion is **not** language-sensitive, but will output everything as English text. Thereby it can be passed again to the `parseSingle`-function to retrieve the correct citation.
+
+```javascript
+const Citr = require('Citr')
+
+const csl = [
+  {
+    prefix: 'see',
+    suffix: '',
+    id: 'doe99',
+    locator: '33-35',
+    label: 'page',
+    'suppress-author': true
+  },
+  {
+    prefix: 'also',
+    suffix: '',
+    id: 'smith04',
+    locator: '1',
+    label: 'chapter',
+    'suppress-author': false
+  }
+]
+
+let markdownCitation = Citr.makeCitation(csl)
+/*
+'[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
+*/
+```
+
+You can, of course, also pass one single object to the engine.
+
+## Contributions
+
+Contributions and PRs are welcome. By contributing, you agree that your code will also be made available under the GNU GPL v3 license.
+
+## License
+
+This software is licenced via the GNU GPL v3-License.
+
+The brand (including name, icons and everything Citr can be identified with) is exluded and all rights reserved. If you want to fork Citr to develop another library, feel free but please change name and icons.
diff --git a/dist/citr.js b/dist/citr.js
@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const validator_1 = require("./util/validator");
+const retrieve_locator_1 = require("./util/retrieve-locator");
+const extract_citations_1 = require("./util/extract-citations");
+exports.util = {
+    "validateCitationID": validator_1.validateCitationID,
+    "extractCitations": extract_citations_1.extractCitations
+};
+function parseSingle(citation) {
+    if (!validator_1.validateFullCitation(citation))
+        throw new Error(`Invalid Citation - Invalid citation passed: ${citation}.`);
+    let returnCitations = [];
+    let _citation = citation.substr(1, citation.length - 2).split(';');
+    for (let c of _citation) {
+        if (c === '')
+            continue;
+        if (!validator_1.validateCitationPart(c))
+            throw new Error(`No key or multiple keys Found - Invalid citation passed: ${c}.`);
+        let prefix = c.split('@')[0].trim();
+        let suppressAuthor = c.indexOf('@') > 0 && c[c.indexOf('@') - 1] === '-';
+        if (suppressAuthor)
+            prefix = prefix.substr(0, prefix.length - 1).trim();
+        let extractedKey = /^([a-zA-Z0-9_][a-zA-Z0-9_:.#$%&\-+?<>~/]*)/.exec(c.split('@')[1]);
+        if (extractedKey === null)
+            throw new Error(`Invalid Key - Invalid citation passed: ${c}`);
+        let citeKey = extractedKey[1];
+        let afterKey = extractedKey.input.substr(citeKey.length).trim();
+        let { suffix, locator, label } = retrieve_locator_1.extractLocator(afterKey);
+        returnCitations.push({
+            "prefix": prefix,
+            "suffix": suffix,
+            "id": citeKey,
+            "locator": locator,
+            "label": label,
+            "suppress-author": suppressAuthor
+        });
+    }
+    return returnCitations;
+}
+exports.parseSingle = parseSingle;
+function makeCitation(citationArray) {
+    if (!Array.isArray(citationArray))
+        citationArray = [citationArray];
+    let returnArray = [];
+    for (let csl of citationArray) {
+        let res = '';
+        if (!csl.hasOwnProperty('id'))
+            throw new Error('Citation had no ID given!');
+        if (csl.hasOwnProperty('prefix'))
+            res += csl.prefix + ' ';
+        if (csl.hasOwnProperty('suppress-author') && csl['suppress-author'])
+            res += '-';
+        res += '@' + csl.id;
+        if (csl.hasOwnProperty('label') && csl.hasOwnProperty('locator'))
+            res += ', ' + csl.label + ' ' + csl.locator;
+        if (csl.hasOwnProperty('suffix'))
+            res += ' ' + csl.suffix;
+        returnArray.push(res.trim());
+    }
+    return `[${returnArray.join('; ')}]`;
+}
+exports.makeCitation = makeCitation;
diff --git a/dist/data/de.js b/dist/data/de.js
@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.de = {
+    "Buch": "book",
+    "Bücher": "book",
+    "Kapitel": "chapter",
+    "Spalte": "column",
+    "Spalten": "column",
+    "Abbildung": "figure",
+    "Abbildungen": "figure",
+    "Blatt": "folio",
+    "Blätter": "folio",
+    "Nummer": "issue",
+    "Nummern": "issue",
+    "Zeile": "line",
+    "Zeilen": "line",
+    "Note": "note",
+    "Noten": "note",
+    "Opus": "opus",
+    "Opera": "opus",
+    "Seite": "page",
+    "Seiten": "page",
+    "Absatz": "paragraph",
+    "Absätze": "paragraph",
+    "Teil": "part",
+    "Teile": "part",
+    "Abschnitt": "section",
+    "Abschnitte": "section",
+    "sub verbo": "sub verbo",
+    "sub verbis": "sub verbo",
+    "Vers": "verse",
+    "Verse": "verse",
+    "Band": "volume",
+    "Bände": "volume",
+    "B.": "book",
+    "Kap.": "chapter",
+    "Sp.": "column",
+    "Abb.": "figure",
+    "Fol.": "folio",
+    "Nr.": "issue",
+    "Z.": "line",
+    "N.": "note",
+    "op.": "opus",
+    "S.": "page",
+    "Abs.": "paragraph",
+    "Abschn.": "section",
+    "s.&#160;v.": "sub verbo",
+    "s.&#160;vv.": "sub verbo",
+    "V.": "verse",
+    "Bd.": "volume",
+    "Bde.": "volume",
+    "¶": "paragraph",
+    "¶¶": "paragraph",
+    "§": "section",
+    "§§": "section",
+};
diff --git a/dist/data/en.js b/dist/data/en.js
@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.en = {
+    "book": "book",
+    "books": "book",
+    "chapter": "chapter",
+    "chapters": "chapter",
+    "column": "column",
+    "columns": "column",
+    "figure": "figure",
+    "figures": "figure",
+    "folio": "folio",
+    "folios": "folio",
+    "number": "issue",
+    "numbers": "issue",
+    "line": "line",
+    "lines": "line",
+    "note": "note",
+    "notes": "note",
+    "opus": "opus",
+    "opera": "opus",
+    "page": "page",
+    "pages": "page",
+    "paragraph": "paragraph",
+    "paragraphs": "paragraph",
+    "part": "part",
+    "parts": "part",
+    "section": "section",
+    "sections": "section",
+    "sub verbo": "sub verbo",
+    "sub verbis": "sub verbo",
+    "verse": "verse",
+    "verses": "verse",
+    "volume": "volume",
+    "volumes": "volume",
+    "bk.": "book",
+    "bks": "book",
+    "chap.": "chapter",
+    "chaps": "chapter",
+    "col.": "column",
+    "cols": "column",
+    "fig.": "figure",
+    "figs": "figure",
+    "fol.": "folio",
+    "fols": "folio",
+    "no.": "issue",
+    "nos.": "issue",
+    "l.": "line",
+    "ll.": "line",
+    "n.": "note",
+    "nn.": "note",
+    "op.": "opus",
+    "opp.": "opus",
+    "p.": "page",
+    "pp.": "page",
+    "para.": "paragraph",
+    "paras": "paragraph",
+    "pt.": "part",
+    "pts": "part",
+    "sec.": "section",
+    "secs": "section",
+    "s.v.": "sub verbo",
+    "s.vv.": "sub verbo",
+    "v.": "verse",
+    "vv.": "verse",
+    "vol.": "volume",
+    "vols": "volume",
+    "¶": "paragraph",
+    "¶¶": "paragraph",
+    "§": "section",
+    "§§": "section"
+};
diff --git a/dist/data/fr.js b/dist/data/fr.js
@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fr = {
+    "livre": "book",
+    "livres": "book",
+    "chapitre": "chapter",
+    "chapitres": "chapter",
+    "colonne": "column",
+    "colonnes": "column",
+    "figure": "figure",
+    "figures": "figure",
+    "folio": "folio",
+    "folios": "folio",
+    "numéro": "issue",
+    "numéros": "issue",
+    "ligne": "line",
+    "lignes": "line",
+    "note": "note",
+    "notes": "note",
+    "opus": "opus",
+    "page": "page",
+    "pages": "page",
+    "paragraphe": "paragraph",
+    "paragraphes": "paragraph",
+    "partie": "part",
+    "parties": "part",
+    "section": "section",
+    "sections": "section",
+    "sub verbo": "sub verbo",
+    "sub verbis": "sub verbo",
+    "verset": "verse",
+    "versets": "verse",
+    "volume": "volume",
+    "volumes": "volume",
+    "liv.": "book",
+    "chap.": "chapter",
+    "col.": "column",
+    "fig.": "figure",
+    "fᵒ": "folio",
+    "fᵒˢ": "folio",
+    "nᵒ": "issue",
+    "nᵒˢ": "issue",
+    "l.": "line",
+    "n.": "note",
+    "op.": "opus",
+    "p.": "page",
+    "paragr.": "paragraph",
+    "part.": "part",
+    "sect.": "section",
+    "s.&#160;v.": "sub verbo",
+    "s.&#160;vv.": "sub verbo",
+    "v.": "verse",
+    "vol.": "volume2",
+    "§": "section",
+};