Skip to content
This repository was archived by the owner on Nov 13, 2022. It is now read-only.

Commit ff8c7e7

Browse files
nathanlesagenathanlesage
committed
Initial Commit
0 parents  commit ff8c7e7

20 files changed

+1988
-0
lines changed

‎LICENSE

+674
Large diffs are not rendered by default.

‎README.md

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Citr
2+
3+
> Converts Markdown Citations to CSL JSON
4+
5+
A small library for parsing Markdown citeproc citations to valid CSL JSON (and vice versa).
6+
7+
## Description
8+
9+
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.
10+
11+
## Install
12+
13+
With NPM:
14+
15+
```bash
16+
$ npm install citr
17+
```
18+
19+
With Yarn:
20+
21+
```bash
22+
$ yarn add citr
23+
```
24+
25+
## Usage
26+
27+
```javascript
28+
Citr.parseSingle(markdown) // Parses a single citation from Markdown to CSL JSON
29+
Citr.makeCitation(csl) // Converts a CSL JSON citation to Markdown
30+
Citr.util.extractCitations(text) // Extracts all citations from a text
31+
Citr.util.validateCitationID(key) // Validates a given citation key
32+
```
33+
34+
Citr exposes a small API that you can conveniently use:
35+
36+
```javascript
37+
const Citr = require('Citr')
38+
39+
let myCitation = '[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
40+
41+
let csl = Citr.parseSingle(myCitation)
42+
43+
/*
44+
[
45+
{
46+
prefix: 'see',
47+
suffix: '',
48+
id: 'doe99',
49+
locator: '33-35',
50+
label: 'page',
51+
'suppress-author': true
52+
},
53+
{
54+
prefix: 'also',
55+
suffix: '',
56+
id: 'smith04',
57+
locator: '1',
58+
label: 'chapter',
59+
'suppress-author': false
60+
}
61+
]
62+
*/
63+
```
64+
65+
If the citation contains any malformed partial citations, Citr will throw an error, so to test for errors, use try/catch constructs:
66+
67+
```javascript
68+
const Citr = require('Citr')
69+
let myCitation = '[Malformed ID inside @.this key]'
70+
let csl = ''
71+
72+
try {
73+
csl = Citr.parseSingle(myCitation)
74+
} catch (err) {
75+
console.error(`The citation was malformed.`)
76+
}
77+
```
78+
79+
To extract all citations that are inside a given Markdown file/text, Citr exposes a convenient function:
80+
81+
```javascript
82+
const Citr = require('Citr')
83+
84+
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.'
85+
86+
let citations = Citr.util.extractCitations(myText)
87+
/*
88+
[
89+
'[-doe99]',
90+
'[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
91+
]
92+
*/
93+
```
94+
95+
You can then afterwards pass all citations in a `for`-loop through the `parseSingle`-function.
96+
97+
If you simply want to conveniently check an ID, use the utility function `validateCitationID`:
98+
99+
```javascript
100+
const Citr = require('Citr')
101+
102+
let goodKey = '@Doe1990'
103+
let badKey = '@.wrongKey'
104+
105+
Citr.util.validateCitationID(goodKey) // true
106+
Citr.util.validateCitationID(badKey) // false
107+
```
108+
109+
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.
110+
111+
```javascript
112+
const Citr = require('Citr')
113+
114+
const csl = [
115+
{
116+
prefix: 'see',
117+
suffix: '',
118+
id: 'doe99',
119+
locator: '33-35',
120+
label: 'page',
121+
'suppress-author': true
122+
},
123+
{
124+
prefix: 'also',
125+
suffix: '',
126+
id: 'smith04',
127+
locator: '1',
128+
label: 'chapter',
129+
'suppress-author': false
130+
}
131+
]
132+
133+
let markdownCitation = Citr.makeCitation(csl)
134+
/*
135+
'[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
136+
*/
137+
```
138+
139+
You can, of course, also pass one single object to the engine.
140+
141+
## Contributions
142+
143+
Contributions and PRs are welcome. By contributing, you agree that your code will also be made available under the GNU GPL v3 license.
144+
145+
## License
146+
147+
This software is licenced via the GNU GPL v3-License.
148+
149+
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.

‎dist/citr.js

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
"use strict";
2+
Object.defineProperty(exports, "__esModule", { value: true });
3+
const validator_1 = require("./util/validator");
4+
const retrieve_locator_1 = require("./util/retrieve-locator");
5+
const extract_citations_1 = require("./util/extract-citations");
6+
exports.util = {
7+
"validateCitationID": validator_1.validateCitationID,
8+
"extractCitations": extract_citations_1.extractCitations
9+
};
10+
function parseSingle(citation) {
11+
if (!validator_1.validateFullCitation(citation))
12+
throw new Error(`Invalid Citation - Invalid citation passed: ${citation}.`);
13+
let returnCitations = [];
14+
let _citation = citation.substr(1, citation.length - 2).split(';');
15+
for (let c of _citation) {
16+
if (c === '')
17+
continue;
18+
if (!validator_1.validateCitationPart(c))
19+
throw new Error(`No key or multiple keys Found - Invalid citation passed: ${c}.`);
20+
let prefix = c.split('@')[0].trim();
21+
let suppressAuthor = c.indexOf('@') > 0 && c[c.indexOf('@') - 1] === '-';
22+
if (suppressAuthor)
23+
prefix = prefix.substr(0, prefix.length - 1).trim();
24+
let extractedKey = /^([a-zA-Z0-9_][a-zA-Z0-9_:.#$%&\-+?<>~/]*)/.exec(c.split('@')[1]);
25+
if (extractedKey === null)
26+
throw new Error(`Invalid Key - Invalid citation passed: ${c}`);
27+
let citeKey = extractedKey[1];
28+
let afterKey = extractedKey.input.substr(citeKey.length).trim();
29+
let { suffix, locator, label } = retrieve_locator_1.extractLocator(afterKey);
30+
returnCitations.push({
31+
"prefix": prefix,
32+
"suffix": suffix,
33+
"id": citeKey,
34+
"locator": locator,
35+
"label": label,
36+
"suppress-author": suppressAuthor
37+
});
38+
}
39+
return returnCitations;
40+
}
41+
exports.parseSingle = parseSingle;
42+
function makeCitation(citationArray) {
43+
if (!Array.isArray(citationArray))
44+
citationArray = [citationArray];
45+
let returnArray = [];
46+
for (let csl of citationArray) {
47+
let res = '';
48+
if (!csl.hasOwnProperty('id'))
49+
throw new Error('Citation had no ID given!');
50+
if (csl.hasOwnProperty('prefix'))
51+
res += csl.prefix + ' ';
52+
if (csl.hasOwnProperty('suppress-author') && csl['suppress-author'])
53+
res += '-';
54+
res += '@' + csl.id;
55+
if (csl.hasOwnProperty('label') && csl.hasOwnProperty('locator'))
56+
res += ', ' + csl.label + ' ' + csl.locator;
57+
if (csl.hasOwnProperty('suffix'))
58+
res += ' ' + csl.suffix;
59+
returnArray.push(res.trim());
60+
}
61+
return `[${returnArray.join('; ')}]`;
62+
}
63+
exports.makeCitation = makeCitation;

‎dist/data/de.js

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
"use strict";
2+
Object.defineProperty(exports, "__esModule", { value: true });
3+
exports.de = {
4+
"Buch": "book",
5+
"Bücher": "book",
6+
"Kapitel": "chapter",
7+
"Spalte": "column",
8+
"Spalten": "column",
9+
"Abbildung": "figure",
10+
"Abbildungen": "figure",
11+
"Blatt": "folio",
12+
"Blätter": "folio",
13+
"Nummer": "issue",
14+
"Nummern": "issue",
15+
"Zeile": "line",
16+
"Zeilen": "line",
17+
"Note": "note",
18+
"Noten": "note",
19+
"Opus": "opus",
20+
"Opera": "opus",
21+
"Seite": "page",
22+
"Seiten": "page",
23+
"Absatz": "paragraph",
24+
"Absätze": "paragraph",
25+
"Teil": "part",
26+
"Teile": "part",
27+
"Abschnitt": "section",
28+
"Abschnitte": "section",
29+
"sub verbo": "sub verbo",
30+
"sub verbis": "sub verbo",
31+
"Vers": "verse",
32+
"Verse": "verse",
33+
"Band": "volume",
34+
"Bände": "volume",
35+
"B.": "book",
36+
"Kap.": "chapter",
37+
"Sp.": "column",
38+
"Abb.": "figure",
39+
"Fol.": "folio",
40+
"Nr.": "issue",
41+
"Z.": "line",
42+
"N.": "note",
43+
"op.": "opus",
44+
"S.": "page",
45+
"Abs.": "paragraph",
46+
"Abschn.": "section",
47+
"s.&#160;v.": "sub verbo",
48+
"s.&#160;vv.": "sub verbo",
49+
"V.": "verse",
50+
"Bd.": "volume",
51+
"Bde.": "volume",
52+
"¶": "paragraph",
53+
"¶¶": "paragraph",
54+
"§": "section",
55+
"§§": "section",
56+
};

‎dist/data/en.js

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
"use strict";
2+
Object.defineProperty(exports, "__esModule", { value: true });
3+
exports.en = {
4+
"book": "book",
5+
"books": "book",
6+
"chapter": "chapter",
7+
"chapters": "chapter",
8+
"column": "column",
9+
"columns": "column",
10+
"figure": "figure",
11+
"figures": "figure",
12+
"folio": "folio",
13+
"folios": "folio",
14+
"number": "issue",
15+
"numbers": "issue",
16+
"line": "line",
17+
"lines": "line",
18+
"note": "note",
19+
"notes": "note",
20+
"opus": "opus",
21+
"opera": "opus",
22+
"page": "page",
23+
"pages": "page",
24+
"paragraph": "paragraph",
25+
"paragraphs": "paragraph",
26+
"part": "part",
27+
"parts": "part",
28+
"section": "section",
29+
"sections": "section",
30+
"sub verbo": "sub verbo",
31+
"sub verbis": "sub verbo",
32+
"verse": "verse",
33+
"verses": "verse",
34+
"volume": "volume",
35+
"volumes": "volume",
36+
"bk.": "book",
37+
"bks": "book",
38+
"chap.": "chapter",
39+
"chaps": "chapter",
40+
"col.": "column",
41+
"cols": "column",
42+
"fig.": "figure",
43+
"figs": "figure",
44+
"fol.": "folio",
45+
"fols": "folio",
46+
"no.": "issue",
47+
"nos.": "issue",
48+
"l.": "line",
49+
"ll.": "line",
50+
"n.": "note",
51+
"nn.": "note",
52+
"op.": "opus",
53+
"opp.": "opus",
54+
"p.": "page",
55+
"pp.": "page",
56+
"para.": "paragraph",
57+
"paras": "paragraph",
58+
"pt.": "part",
59+
"pts": "part",
60+
"sec.": "section",
61+
"secs": "section",
62+
"s.v.": "sub verbo",
63+
"s.vv.": "sub verbo",
64+
"v.": "verse",
65+
"vv.": "verse",
66+
"vol.": "volume",
67+
"vols": "volume",
68+
"¶": "paragraph",
69+
"¶¶": "paragraph",
70+
"§": "section",
71+
"§§": "section"
72+
};

‎dist/data/fr.js

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
"use strict";
2+
Object.defineProperty(exports, "__esModule", { value: true });
3+
exports.fr = {
4+
"livre": "book",
5+
"livres": "book",
6+
"chapitre": "chapter",
7+
"chapitres": "chapter",
8+
"colonne": "column",
9+
"colonnes": "column",
10+
"figure": "figure",
11+
"figures": "figure",
12+
"folio": "folio",
13+
"folios": "folio",
14+
"numéro": "issue",
15+
"numéros": "issue",
16+
"ligne": "line",
17+
"lignes": "line",
18+
"note": "note",
19+
"notes": "note",
20+
"opus": "opus",
21+
"page": "page",
22+
"pages": "page",
23+
"paragraphe": "paragraph",
24+
"paragraphes": "paragraph",
25+
"partie": "part",
26+
"parties": "part",
27+
"section": "section",
28+
"sections": "section",
29+
"sub verbo": "sub verbo",
30+
"sub verbis": "sub verbo",
31+
"verset": "verse",
32+
"versets": "verse",
33+
"volume": "volume",
34+
"volumes": "volume",
35+
"liv.": "book",
36+
"chap.": "chapter",
37+
"col.": "column",
38+
"fig.": "figure",
39+
"fᵒ": "folio",
40+
"fᵒˢ": "folio",
41+
"nᵒ": "issue",
42+
"nᵒˢ": "issue",
43+
"l.": "line",
44+
"n.": "note",
45+
"op.": "opus",
46+
"p.": "page",
47+
"paragr.": "paragraph",
48+
"part.": "part",
49+
"sect.": "section",
50+
"s.&#160;v.": "sub verbo",
51+
"s.&#160;vv.": "sub verbo",
52+
"v.": "verse",
53+
"vol.": "volume2",
54+
"§": "section",
55+
};

0 commit comments

Comments
 (0)