feat: Support multiple exports with different JSON-LD context mappings.

about-code · Oct 13, 2021 · 4cfcdc3 · 4cfcdc3
1 parent 4be032b
commit 4cfcdc3
Show file tree

Hide file tree

Showing 11 changed files with 195 additions and 35 deletions.
diff --git a/conf/v5/doc/schema-defs-exportfile-properties-context.md b/conf/v5/doc/schema-defs-exportfile-properties-context.md
diff --git a/conf/v5/doc/schema-defs-exportfile-properties-file.md b/conf/v5/doc/schema-defs-exportfile-properties-file.md
diff --git a/conf/v5/doc/schema-defs-exportfile.md b/conf/v5/doc/schema-defs-exportfile.md
@@ -0,0 +1,23 @@
+# items Properties
+
+
+
+## file
+
+The filename to write output to. Recommended extension is '.json'.
+
+`file`
+
+*   is optional
+
+*   Type: `string`
+
+## context
+
+File name of a custom JSON-LD context document to embed. Should end with `.jsonld`.  May also be JSON-LD document URL starting with `https://`.
+
+`context`
+
+*   is optional
+
+*   Type: `string`
diff --git a/conf/v5/doc/schema-defs-glossaryfile-properties-exports-items.md b/conf/v5/doc/schema-defs-glossaryfile-properties-exports-items.md
@@ -0,0 +1,23 @@
+# items Properties
+
+
+
+## file
+
+The filename to write output to. Recommended extension is '.json'.
+
+`file`
+
+*   is optional
+
+*   Type: `string`
+
+## context
+
+File name of a custom JSON-LD context document to embed. Should end with `.jsonld`.  May also be JSON-LD document URL starting with `https://`.
+
+`context`
+
+*   is optional
+
+*   Type: `string`
diff --git a/conf/v5/doc/schema-defs-glossaryfile-properties-exports.md b/conf/v5/doc/schema-defs-glossaryfile-properties-exports.md
diff --git a/conf/v5/doc/schema-defs-glossaryfile.md b/conf/v5/doc/schema-defs-glossaryfile.md
@@ -12,6 +12,16 @@ Export terms from the markdown file as a JSON glossary. Output will contain JSON
 
 *   Type: `string`
 
+## exports
+
+Export terms from the markdown file as a JSON glossary. Output will contain JSON-LD mappings onto <http://w3.org/skos> for interoperability with knowledge organization systems supporting SKOS. Other JSON-LD context files may be embedded using `context`.
+
+`exports`
+
+*   is optional
+
+*   Type: `object[]` ([Details](schema-defs-exportfile.md))
+
 ## file
 
 Name of the glossary file. Conventional default is *glossary.md*. You can use a glob pattern to enable cross-linking of headings across multiple files. Note that 'termHint' and 'title' will be ignored if 'file' is a glob pattern.

diff --git a/conf/v5/doc/schema-properties-glossaries-items.md b/conf/v5/doc/schema-properties-glossaries-items.md
@@ -12,6 +12,16 @@ Export terms from the markdown file as a JSON glossary. Output will contain JSON
 
 *   Type: `string`
 
+## exports
+
+Export terms from the markdown file as a JSON glossary. Output will contain JSON-LD mappings onto <http://w3.org/skos> for interoperability with knowledge organization systems supporting SKOS. Other JSON-LD context files may be embedded using `context`.
+
+`exports`
+
+*   is optional
+
+*   Type: `object[]` ([Details](schema-defs-glossaryfile-properties-exports-items.md))
+
 ## file
 
 Name of the glossary file. Conventional default is *glossary.md*. You can use a glob pattern to enable cross-linking of headings across multiple files. Note that 'termHint' and 'title' will be ignored if 'file' is a glob pattern.

diff --git a/conf/v5/doc/schema.md b/conf/v5/doc/schema.md
@@ -376,6 +376,36 @@ Generate a file with a list of tables and where they can be found.
 
 *   Type: `object` ([Details](schema-defs-generatefiles-properties-listoftables.md))
 
+## Definitions group exportFile
+
+Reference this group by using
+
+```json
+{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v5.1.0/conf/v5/schema.json#/$defs/exportFile"}
+```
+
+
+
+### file
+
+The filename to write output to. Recommended extension is '.json'.
+
+`file`
+
+*   is optional
+
+*   Type: `string`
+
+### context
+
+File name of a custom JSON-LD context document to embed. Should end with `.jsonld`.  May also be JSON-LD document URL starting with `https://`.
+
+`context`
+
+*   is optional
+
+*   Type: `string`
+
 ## Definitions group glossaryFile
 
 Reference this group by using
@@ -396,6 +426,16 @@ Export terms from the markdown file as a JSON glossary. Output will contain JSON
 
 *   Type: `string`
 
+### exports
+
+Export terms from the markdown file as a JSON glossary. Output will contain JSON-LD mappings onto <http://w3.org/skos> for interoperability with knowledge organization systems supporting SKOS. Other JSON-LD context files may be embedded using `context`.
+
+`exports`
+
+*   is optional
+
+*   Type: `object[]` ([Details](schema-defs-glossaryfile-properties-exports-items.md))
+
 ### file
 
 Name of the glossary file. Conventional default is *glossary.md*. You can use a glob pattern to enable cross-linking of headings across multiple files. Note that 'termHint' and 'title' will be ignored if 'file' is a glob pattern.

diff --git a/conf/v5/schema.json b/conf/v5/schema.json
@@ -156,6 +156,19 @@
                 }
             }
         }
+        ,"exportFile": {
+            "type": "object",
+            "properties": {
+                "file": {
+                    "description": "The filename to write output to. Recommended extension is '.json'."
+                    ,"type": "string"
+                }
+                ,"context": {
+                    "description": "File name of a custom JSON-LD context document to embed. Should end with `.jsonld`.  May also be JSON-LD document URL starting with `https://`."
+                    ,"type": "string"
+                }
+            }
+        }
         ,"glossaryFile": {
             "type": "object"
             ,"properties": {
@@ -164,6 +177,14 @@
                     ,"type": "string"
                     ,"since": "6.0.0"
                 }
+                ,"exports": {
+                    "description": "Export terms from the markdown file as a JSON glossary. Output will contain JSON-LD mappings onto http://w3.org/skos for interoperability with knowledge organization systems supporting SKOS. Other JSON-LD context files may be embedded using `context`."
+                    ,"type": "array"
+                    ,"since": "6.0.0"
+                    ,"items": {
+                        "$ref": "#/$defs/exportFile"
+                    }
+                }
                 ,"file": {
                     "description": "Name of the glossary file. Conventional default is *glossary.md*. You can use a glob pattern to enable cross-linking of headings across multiple files. Note that 'termHint' and 'title' will be ignored if 'file' is a glob pattern."
                     ,"type": "string"

diff --git a/lib/exporter.js b/lib/exporter.js
@@ -1,10 +1,14 @@
+import { readFileSync } from "fs";
+import path from "node:path";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
 import { TermDefinitionNode } from "./ast/with/term-definition.js";
 
+const MAX_EXPORTS = 10;
+const LD_VOCAB = "https://about-code.github.io/vocab/glossarify-md/2021/10/#";
 const LD_CONTEXT = {
     "@context": {
-        "@vocab": "https://about-code.github.io/vocab/glossarify-md/2021/10/#"
+        "@vocab": LD_VOCAB
         ,"skos": "http://www.w3.org/2004/02/skos/core#"
         ,"dc": "http://purl.org/dc/terms/"
         ,"uri": "@id"
@@ -32,46 +36,72 @@ const LD_CONTEXT = {
 
 export function exporter(context) {
     const { exportFiles, conf } = context;
-    const { i18n, linking } = conf;
+    const { baseDir, i18n, linking } = conf;
     return (tree, vFile) => {
         if (vFile.isGlossary !== true) {
             return;
         }
-        const { uri, title, export: exportPath } = vFile.glossConf;
-        if (! exportPath) {
+        const { uri, title, exports: exportConfs } = vFile.glossConf;
+        if (! exportConfs || ! Array.isArray(exportConfs) || exportConfs.length === 0) {
             return;
         }
-        let exportData;
-        let exportFile = exportFiles[exportPath];
-        if (! exportFile) {
-            exportFile = exportFiles[exportPath] = new VFile({ path: exportPath });
-            context.writeFiles.push(exportFile);
-            exportData = {
-                ...LD_CONTEXT
-                ,type: "Glossary"
-                ,uri: uri
-                ,title: title
-                ,language: i18n.locale
-                ,terms: {}
-            };
-            exportData["@context"]["@language"] = i18n.locale;
-        } else {
-            exportData = exportFile.data;
-        }
 
-        const filter = node => node.type === TermDefinitionNode.type && linking.headingDepths[node.headingDepth];
-        visit(tree, filter, (node) => {
-            const termUri = node.uri;
-            exportData.terms[termUri] = {
-                type: "Term"
-                ,uri: termUri
-                ,label: node.value
-                ,definition: node.longDesc
-                ,abstract: node.shortDesc
-                ,aliases: [... node.aliases ]
-            };
+        exportConfs.slice(0, MAX_EXPORTS).forEach(exportConf => {
+            const exportPath = exportConf.file;
+
+            let exportData;
+            let exportFile = exportFiles[exportPath];
+            if (! exportFile) {
+                exportFile = exportFiles[exportPath] = new VFile({ path: exportPath });
+                context.writeFiles.push(exportFile);
+                exportData = {
+                    ...getLDContext(baseDir, i18n.locale, exportConf.context)
+                    ,type: "Glossary"
+                    ,uri: uri
+                    ,title: title
+                    ,language: i18n.locale
+                    ,terms: {}
+                };
+            } else {
+                exportData = exportFile.data;
+            }
+
+            const filter = node => node.type === TermDefinitionNode.type && linking.headingDepths[node.headingDepth];
+            visit(tree, filter, (node) => {
+                const termUri = node.uri;
+                exportData.terms[termUri] = {
+                    type: "Term"
+                    ,uri: termUri
+                    ,label: node.value
+                    ,definition: node.longDesc
+                    ,abstract: node.shortDesc
+                    ,aliases: [... node.aliases ]
+                };
+            });
+            exportFile.data = exportData;
+            exportFile.value = JSON.stringify(exportData, null, 2);
         });
-        exportFile.data = exportData;
-        exportFile.value = JSON.stringify(exportData, null, 2);
     };
 }
+
+function getLDContext(baseDir = "", locale = "", fileOrUrl = "") {
+    let jsonld = LD_CONTEXT;
+    if (fileOrUrl.match(/^https:\/\//)) {
+        jsonld = { "@context": `${fileOrUrl}` };
+    } else if (fileOrUrl) {
+        try {
+            jsonld = JSON.parse(readFileSync(path.resolve(baseDir, fileOrUrl)));
+        } catch (err) {
+            console.error(`✗ Reading from: ${fileOrUrl}: Failed to load (see config 'glossaries.exports.context').\n`);
+        }
+    }
+
+    const ldContext = jsonld["@context"];
+    const type = Object.prototype.toString.call(ldContext);
+    if (type === "[object Object]") {
+        ldContext["@language"] = locale;
+    } else if (type === "[object Array]") {
+        ldContext.unshift({ "@language": locale });
+    }
+    return jsonld;
+}
diff --git a/lib/model/glossary.js b/lib/model/glossary.js
@@ -15,7 +15,10 @@ export class Glossary {
         this.file     = data.file     || "./glossary.md";
 
         /** @type {VFile} */
-        this.export   = data.export    || "";
+        this.exports  = [
+            ...data.exports || []
+            ,...[data.export].filter(v => !!v).map(v => { return {"file": v }; })
+        ];
 
         /** @type {string} */
         this.termHint = data.termHint || "";