@iebh/reflib 2.7.0 → 2.8.0

package/README.md

@@ -30,6 +30,29 @@ Compatibility
 * Medline seems to implement a totally different [publication type system](https://www.nlm.nih.gov/mesh/pubtypes.html) than others. Reflib will attempt to guess the best match, storing the original type in the `medlineType` key. Should the citation library be exported _back_ to Medline / `.nbib` files this key will take precedence to avoid data loss
 
 
+Command Line Interface
+======================
+This NPM ships with a very basic Command Line Interface (CLI) for very basic Reflib files manipulation.
+
+```
+Usage: reflib -i INPUT_FILE [-f FORMAT] [-o -|OUTPUT_FILE]
+
+
+-i, --input <file>             Input file to process
+
+-o, --output <file>            Output file to save. Use '-' for STDOUT
+
+-f, --format <reflib-format>   Override or set the file output type (if omitted the outfile filename
+                               is used to determine the format)
+
+-v, --verbose                  Be verbose when processing
+
+--version                      Print CLI version and exit
+
+-h, --help                     This help screen
+```
+
+
 Reference Structure
 ===================
 Reflib creates a simple Plain-Old-JavaScript-Object (POJO) for each reference it parses, or writes to a file format when given a collection of the same.

package/app.js

@@ -0,0 +1,85 @@
+#!/usr/bin/node
+
+import parseArgs from './shared/parseArgs.js';
+import packageInfo from './package.json' with {type: 'json'};
+import reflib from './lib/default.js';
+
+let help = `
+
+Usage: reflib -i INPUT_FILE [-f FORMAT] [-o -|OUTPUT_FILE]
+
+
+-i, --input <file>             Input file to process
+
+-o, --output <file>            Output file to save. Use '-' for STDOUT
+
+-f, --format <reflib-format>   Override or set the file output type (if omitted the outfile filename
+                               is used to determine the format)
+
+-v, --verbose                  Be verbose when processing
+
+--version                      Print CLI version and exit
+
+-h, --help                     This help screen
+`;
+
+// Parse args {{{
+let args = parseArgs.parse();
+args = parseArgs.expand(args, {
+	'h': 'help',
+	'i': 'input',
+	'o': 'output',
+	'f': 'format',
+	'v': 'verbose',
+});
+// }}}
+
+// Action: Version {{{
+if (args.version) {
+	console.log(`Version: ${packageInfo.version}`);
+	process.exit(0);
+}
+// }}}
+// Action: Convert (if --input) {{{
+if (args.input) {
+	if (args.verbose) console.log('Reading', args.input);
+	let refs = await reflib.readFile(args.input);
+	if (args.verbose) console.log('Read', refs.length, 'refs');
+
+	if (!args.output) {
+		if (args.verbose) console.log('No output file specified - assuming STDOUT JSON');
+		console.log(JSON.stringify(refs, null, 2));
+	} else if (args.output == '-' || args.output === true) {
+		if (!args.format) {
+			if (args.verbose) console.log('No STDOUT format specified - assuming JSON');
+			console.log(JSON.stringify(refs, null, 2));
+		} else {
+			if (args.verbose) console.log(`Raw output to STDOUT using "${args.format}" format`);
+
+			let stream = reflib.writeStream(args.format, process.stdout);
+			await stream.start();
+			await Array.fromAsync(refs, ref =>
+				stream.write(ref)
+			);
+			await stream.end();
+		}
+	} else if (args.output) {
+		if (args.verbose) console.log('Writing', args.output);
+		await reflib.writeFile(args.output, refs);
+	}
+
+	if (args.verbose) console.log('All done');
+	process.exit(0);
+}
+// }}}
+// Action: Help {{{
+if (args.help) {
+	console.log(help);
+	process.exit(0);
+}
+// }}}
+// Action: Unknown {{{
+console.warn('Nothing to do');
+console.log(help);
+process.exit(1);
+// }}}

package/modules/bibtex.js

@@ -23,9 +23,9 @@ const MODES = {
 * @param {Boolean} [options.recNumberNumeric=true] Only process the BibTeX ID into a recNumber if its a finite numeric, otherwise disguard
 * @param {Boolean} [options.recNumberRNPrefix=true] Accept `RN${NUMBER}` as recNumber if present
 * @param {Boolean} [options.recNumberKey=true] If the reference key cannot be otherwise parsed store it in `key<String>` instead
-* @param {Boolean} [options.omitUnkown=false] If true, only keep known reconised fields
 * @param {String} [options.fallbackType='unkown'] Reflib fallback type if the incoming type is unrecognised or unsupported
 * @param {Set<String>} [options.fieldsOverwrite] Set of field names where the value is clobbered rather than appended if discovered more than once
+* @param {Boolean} [options.preserveUnknownKeys=true] Retain keys we do not have a direct lookup for in the output object
 *
 * @returns {Object} A readable stream analogue defined in `modules/interface.js`
 */
@@ -34,9 +34,9 @@ export function readStream(stream, options) {
 		recNumberNumeric: true,
 		recNumberRNPrefix: true,
 		recNumberKey: true,
-		omitUnknown: false,
 		fallbackType: 'unknown',
 		fieldsOverwrite: new Set(['type']),
+		preserveUnkownKeys: true,
 		...options,
 	};
 
@@ -100,7 +100,13 @@ export function readStream(stream, options) {
 						)
 					) {
 						mode = MODES.FIELDS;
-						if (ref[state.field] !== undefined && settings.fieldsOverwrite.has(state.field)) { // Already have content - and we should overwrite
+						if (// Already have content - and we should overwrite
+							ref[state.field] !== undefined
+							&& (
+								settings.preserveUnkownKeys
+								|| settings.fieldsOverwrite.has(state.field)
+							)
+						) {
 							ref[state.field] = unescape(match.groups.value);
 						} else if (ref[state.field] !== undefined) { // Already have content - append
 							ref[state.field] += '\n' + unescape(match.groups.value);
@@ -142,13 +148,13 @@ export function tidyRef(ref, settings) {
 					return rlType
 						? [key, rlType.rl] // Can translate incoming type to Reflib type
 						: [key, settings.fallbackType] // Unknown Reflib type varient
-				} else if (settings.omitUnkown && !rlField) { // Omit unknown fields
+				} else if (!settings.preserveUnkownKeys && !rlField) { // Omit unknown fields
 					return;
 				} else if (rlField && rlField.array) { // Field needs array casting
 					return [rlField.rl, val.split(/\n*\s+and\s+/)];
 				} else if (rlField && rlField.rl) { // Known BT field but different RL field
 					return [rlField.rl, val];
-				} else if (!settings.omitUnkown) { // Everything else - add field
+				} else if (settings.preserveUnkownKeys) { // Everything else - add field
 					return [key, val];
 				}
 			})
@@ -194,10 +200,11 @@ export function escape(str) {
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.defaultType='Misc'] Default citation type to assume when no other type is specified
 * @param {string} [options.delimeter='\r'] How to split multi-line items
-* @param {Boolean} [options.omitUnkown=false] If true, only keep known reconised fields
 * @param {Set} [options.omitFields] Set of special fields to always omit, either because we are ignoring or because we have special treatment for them
+* @param {Boolean} [options.keyForce=true] Force a unique ID to exist if we don't already have one for each reference
 * @param {Boolean} [options.recNumberRNPrefix=true] Rewrite recNumber fields as `RN${NUMBER}`
 * @param {Boolean} [options.recNumberKey=true] If the reference `recNumber` is empty use `key<String>` instead
+* @param {Boolean} [options.preserveUnknownKeys=true] Output keys we do not have a direct lookup for in the output object
 *
 * @returns {Object} A writable stream analogue defined in `modules/interface.js`
 */
@@ -205,10 +212,11 @@ export function writeStream(stream, options) {
 	let settings = {
 		defaultType: 'Misc',
 		delimeter: '\n',
-		omitUnkown: false,
-		omitFields: new Set(['recNumber', 'type']),
+		omitFields: new Set(['key', 'recNumber', 'type']),
+		keyForce: true,
 		recNumberRNPrefix: true,
 		recNumberKey: true,
+		preserveUnkownKeys: true,
 		...options,
 	};
 
@@ -217,12 +225,9 @@ export function writeStream(stream, options) {
 			return Promise.resolve();
 		},
 		write: ref => {
-			if (!ref.key) {
-				ref.key = generateCitationKey(ref);
-			}
-			// console.log("Here is the id",ref.key)
 			// Fetch Reflib type definition
-			let rlType = (ref.type || settings.defaultType) && translations.types.rlMap.get(ref.type.toLowerCase());
+			ref.type ||= settings.defaultType;
+			let rlType = translations.types.rlMap.get(ref.type.toLowerCase());
 			let btType = rlType?.bt || settings.defaultType;
 
 			stream.write(
@@ -231,6 +236,7 @@ export function writeStream(stream, options) {
 					ref.recNumber && settings.recNumberRNPrefix ? `RN${ref.recNumber},`
 					: ref.recNumber ? `${ref.recNumber},`
 					: ref.key ? `${ref.key},`
+					: settings.keyForce ? `${generateCitationKey(ref)},`
 					: ''
 				) + '\n'
 				+ Object.entries(ref)
@@ -241,7 +247,7 @@ export function writeStream(stream, options) {
 					.reduce((buf, [rawKey, rawVal], keyIndex, keys) => {
 						// Fetch Reflib field definition
 						let rlField = translations.fields.rlMap.get(rawKey)
-						if (!rlField && settings.omitUnkown) return buf; // Unknown field mapping - skip if were omitting unknown fields
+						if (!rlField && !settings.preserveUnkownKeys) return buf; // Unknown field mapping - skip if were omitting unknown fields
 
 						let key = rlField ? rlField.bt : rawKey; // Use Reflib->BibTeX field mapping if we have one, otherwise use raw key
 						let val = escape( // Escape input value, either as an Array via join or as a flat string

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@iebh/reflib",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Reference / Citation reference library utilities",
+  "bin": {
+    "reflib": "./app.js"
+  },
   "scripts": {
     "lint": "eslint",
     "test": "testa",
@@ -31,7 +34,7 @@
   "homepage": "https://github.com/IEBH/Reflib",
   "enginesStrict": true,
   "engines": {
-    "node": "^>=16.6.0"
+    "node": ">=16.6.0"
   },
   "type": "module",
   "exports": {
@@ -59,6 +62,7 @@
     "@momsfriendlydevco/eslint-config": "^2.3.1",
     "@momsfriendlydevco/testa": "^1.1.2",
     "eslint": "^9.31.0",
+    "execa": "^9.6.1",
     "nodemon": "^3.1.9",
     "temp": "^0.9.4",
     "vite-plugin-replace": "^0.1.1"

package/shared/parseArgs.js

@@ -0,0 +1,104 @@
+/**
+* Attempt to parse an process.argv like array into extracted flags and their values
+*
+* Supported:
+*     `--flag` → `true`
+*     `--flag val` → `'val'`
+*     `--flag a b c` → `['a', 'b', 'c']` (variadic, stops at next flag)
+*     `-f` → `true`
+*     `-abc` → `{ a: true, b: true, c: true }`
+*     `-n 1 2 3` → `{ n: ['1', '2', '3'] }` (last short flag is variadic)
+*     `--` → remaining args go to `_`
+*     Bare positional args → `_` array
+*
+* @param {Array<String>} [argv=process.argv] `argv` like array to parse, If omitted `process.argv.slice(2)` is used
+* @returns {Object} An object with extracted flags
+*
+* @example Basic argv example
+* parseArgs([
+*   '--name', 'Alice', 'Bob', '--verbose', '-n', '42', '-xvf', 'file1', 'file2',
+* ]) //= {
+*   _: [],
+*   name: ['Alice', 'Bob'],
+*   verbose: true,
+*   	n: '42',
+*   	x: true,
+*   	v: true,
+*   	f: ['file1', 'file2']
+*   }
+*/
+export function parse(argv = process.argv.slice(2)) {
+	let result = { _: [] }
+	let i = 0
+
+	let collectValues = (args, start) => {
+		let values = []
+		let j = start
+		while (j < args.length && !args[j].startsWith('-')) {
+			values.push(args[j++])
+		}
+		return { values, next: j }
+	}
+
+	while (i < argv.length) {
+		let arg = argv[i]
+
+		if (arg.startsWith('--')) {
+			let key = arg.slice(2)
+			if (!key) { i++; break } // -- separator
+			let { values, next } = collectValues(argv, i + 1)
+			result[key] = values.length === 0 ? true
+				: values.length === 1 ? values[0]
+				: values
+			i = next
+		} else if (arg.startsWith('-')) {
+			let flags = arg.slice(1)
+			// Check if last char is the one collecting values
+			for (let f = 0; f < flags.length - 1; f++) {
+				result[flags[f]] = true
+			}
+			let lastFlag = flags.at(-1);
+			let { values, next } = collectValues(argv, i + 1);
+			result[lastFlag] = values.length === 0 ? true
+				: values.length === 1 ? values[0]
+				: values
+			i = next;
+		} else {
+			result._.push(arg)
+			i++
+		}
+	}
+
+	// Remaining after -- go to _
+	while (i < argv.length) result._.push(argv[i++])
+
+	return result
+}
+
+
+/**
+* Accept a parsed args object and expand short-flags into long-flags
+*
+* @param {Object} args Parsed arg object to process
+* @param {Object} argMap Object of `shortFlag:String => longFlag:String` translations to apply
+*
+* @returns {Object} The input `args` object with all short-flags translated to long-flags
+*/
+export function expand(args, argMap) {
+	let outArgs = {...args}; // Shallow copy of incoming args object we are going to mutate
+
+	Object.entries(argMap)
+		.filter(([shortFlag]) => args[shortFlag])
+		.map(([shortFlag, longFlag]) => {
+			outArgs[longFlag] = outArgs[shortFlag];
+			delete outArgs[shortFlag];
+		});
+
+	return outArgs;
+}
+
+
+export default {
+	expand,
+	parse,
+}