bare-script 2.3.1 → 3.0.0

package/README.md

@@ -3,8 +3,22 @@
 [![npm](https://img.shields.io/npm/v/bare-script)](https://www.npmjs.com/package/bare-script)
 [![GitHub](https://img.shields.io/github/license/craigahobbs/bare-script)](https://github.com/craigahobbs/bare-script/blob/main/LICENSE)
 
-The bare-script package is the JavaScript implementation of the
-[BareScript language](https://craigahobbs.github.io/bare-script/language/).
+[BareScript](https://craigahobbs.github.io/bare-script/language/)
+is a simple, lightweight, and portable programming language. Its Pythonic syntax is influenced by
+JavaScript, C, and the Unix Shell. BareScript also has a
+[library of built-in functions](#the-barescript-library)
+for common programming operations. BareScript can be
+[embedded within applications](#markdownup-a-markdown-viewer-with-barescript)
+or used as a
+stand-alone programming language using the
+[command-line interface](#the-barescript-command-line-interface-cli).
+
+There are two implementations of BareScript:
+[BareScript for JavaScript](https://github.com/craigahobbs/bare-script#readme)
+(this package) and
+[BareScript for Python](https://github.com/craigahobbs/bare-script-py#readme).
+Both implementations have 100% unit test coverage with identical unit test suites, so you can be
+confident that BareScript will execute the same regardless of the underlying runtime environment.
 
 
 ## Links
@@ -70,7 +84,7 @@ import {parseScript} from 'bare-script/lib/parser.js';
 // Parse the script
 const script = parseScript(`\
 # Fetch the BareScript library documentation JSON
-docs = systemFetch('https://craigahobbs.github.io/bare-script/library/library.json')
+docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script/library/library.json'))
 
 # Return the number of library functions
 return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' functions'
@@ -83,7 +97,7 @@ console.log(await executeScriptAsync(script, {'fetchFn': fetch}));
 This outputs:
 
 ~~~
-The BareScript Library has 100 functions
+The BareScript Library has 105 functions
 ~~~
 
 
@@ -136,6 +150,10 @@ bare script.bare
 **Note:** In the BareScript CLI, import statements and the
 [systemFetch](https://craigahobbs.github.io/bare-script/library/#var.vGroup='System'&systemfetch)
 function read non-URL paths from the local file system.
+[systemFetch](https://craigahobbs.github.io/bare-script/library/#var.vGroup='System'&systemfetch)
+calls with a non-URL path and a
+[request body](https://craigahobbs.github.io/bare-script-py/library/model.html#var.vName='SystemFetchRequest')
+write the body to the path.
 
 
 ## MarkdownUp, a Markdown Viewer with BareScript

package/bin/bare.js

@@ -2,22 +2,9 @@
 // Licensed under the MIT License
 // https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
-import {argv, exit, stdout} from 'node:process';
+import {argv, exit} from 'node:process';
+import {fetchReadWrite, logStdout} from '../lib/optionsNode.js';
 import {main} from '../lib/bare.js';
-import {readFile} from 'node:fs/promises';
 
 
-const rURL = /^[a-z]+:/;
-exit(await main({
-    argv,
-    'fetchFn': (fetchURL, fetchOptions) => {
-        if (rURL.test(fetchURL)) {
-            return fetch(fetchURL, fetchOptions);
-        }
-        return {
-            'ok': true,
-            'text': () => readFile(fetchURL, 'utf-8')
-        };
-    },
-    'logFn': (message) => stdout.write(`${message}\n`)
-}));
+exit(await main({argv, 'fetchFn': fetchReadWrite, 'logFn': logStdout}));

package/bin/baredoc.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Licensed under the MIT License
+// https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+import {argv, exit} from 'node:process';
+import {fetchReadWrite, logStdout} from '../lib/optionsNode.js';
+import {main} from '../lib/baredoc.js';
+
+
+exit(await main({argv, 'fetchFn': fetchReadWrite, 'logFn': logStdout}));

package/lib/bare.js

@@ -5,23 +5,8 @@ import {parseExpression, parseScript} from './parser.js';
 import {evaluateExpression} from './runtime.js';
 import {executeScriptAsync} from './runtimeAsync.js';
 import {lintScript} from './model.js';
-
-
-// The command-line interface (CLI) help text
-export const helpText = `\
-usage: bare [-h] [-c CODE] [-d] [-v VAR EXPR] [filename ...]
-
-The BareScript command-line interface
-
-positional arguments:
-  filename
-
-options:
-  -h, --help          show this help message and exit
-  -c, --code CODE     execute the BareScript code
-  -d, --debug         enable debug mode
-  -s, --static        perform static analysis
-  -v, --var VAR EXPR  set a global variable to an expression value`;
+import {urlFileRelative} from './options.js';
+import {valueBoolean} from './value.js';
 
 
 /**
@@ -29,8 +14,8 @@ options:
  *
  * @typedef {Object} BareOptions
  * @property {string[]} argv - The process command-line arguments
- * @property {function} fetchFn - The [fetch function]{@link module:lib/runtime~FetchFn}
- * @property {function} logFn - The [log function]{@link module:lib/runtime~LogFn}
+ * @property {function} fetchFn - The [fetch function]{@link module:lib/options~FetchFn}
+ * @property {function} logFn - The [log function]{@link module:lib/options~LogFn}
  * @ignore
  */
 
@@ -43,53 +28,62 @@ options:
  * @ignore
  */
 export async function main(options) {
+    // Command line arguments
+    let args;
+    try {
+        args = parseArgs(options.argv);
+    } catch ({message}) {
+        options.logFn(`error: ${message}`);
+        return 1;
+    }
+    if (args.help || args.scripts.length === 0) {
+        options.logFn(helpText);
+        return 1;
+    }
+
     let statusCode = 0;
-    let currentFile = null;
+    let inlineCount = 0;
+    let errorName = null;
     try {
-        const args = parseArgs(options.argv);
+        // Evaluate the global variable expression arguments
+        const globals = {};
+        for (const [varName, varExpr] of Object.entries(args.var)) {
+            globals[varName] = evaluateExpression(parseExpression(varExpr));
+        }
 
-        // Read the source files
-        const responses = await Promise.all(args.files.map(async ([url, source]) => {
-            if (source !== null) {
-                return {'ok': true, 'text': () => source};
-            }
-            try {
-                return await options.fetchFn(url);
-            } catch {
-                throw Error(`Failed to load "${url}"`);
-            }
-        }));
-        const files = await Promise.all(responses.map(async (response, ixResponse) => {
-            const [url] = args.files[ixResponse];
-            let source = null;
-            if (response.ok) {
+        // Parse and execute all source files in order
+        for (const [scriptType, scriptValue] of args.scripts) {
+            // Get the script source
+            let scriptName;
+            let scriptSource;
+            if (scriptType === 'file') {
+                scriptName = scriptValue;
+                scriptSource = null;
                 try {
-                    source = await response.text();
+                    const scriptResponse = await options.fetchFn(scriptValue);
+                    if (scriptResponse.ok) {
+                        scriptSource = await scriptResponse.text();
+                    }
                 } catch {
-                    // Do nothing
+                    // Do nothing...
                 }
+                if (scriptSource === null) {
+                    throw Error(`Failed to load "${scriptValue}"`);
+                }
+            } else {
+                inlineCount += 1;
+                scriptName = `-c ${inlineCount}`;
+                scriptSource = scriptValue;
             }
-            if (source === null) {
-                throw Error(`Failed to load "${url}"`);
-            }
-            return [url, source];
-        }));
-
-        // Parse the source files
-        const scripts = [];
-        for (const [file, source] of files) {
-            currentFile = file;
-            scripts.push([file, parseScript(source)]);
-        }
 
-        // Lint and execute the source scripts
-        for (const [file, script] of scripts) {
-            currentFile = file;
+            // Parse the script source
+            errorName = scriptName;
+            const script = parseScript(scriptSource);
 
             // Run the bare-script linter?
             if (args.static || args.debug) {
                 const warnings = lintScript(script);
-                const warningPrefix = `BareScript: Static analysis "${file}" ...`;
+                const warningPrefix = `BareScript: Static analysis "${scriptName}" ...`;
                 if (warnings.length === 0) {
                     options.logFn(`${warningPrefix} OK`);
                 } else {
@@ -98,29 +92,31 @@ export async function main(options) {
                         options.logFn(`BareScript:     ${warning}`);
                     }
                     if (args.static) {
-                        throw Error('Static analysis failed');
+                        statusCode = 1;
+                        break;
                     }
                 }
-
-                // Skip code execution if linter requested
-                if (args.static) {
-                    continue;
-                }
+            }
+            if (args.static) {
+                continue;
             }
 
             // Execute the script
             const timeBegin = performance.now();
-            // eslint-disable-next-line no-await-in-loop
             const result = await executeScriptAsync(script, {
                 'debug': args.debug ?? false,
                 'fetchFn': options.fetchFn,
-                'globals': args.variables,
-                'logFn': (message) => options.logFn(message),
+                'globals': globals,
+                'logFn': options.logFn,
                 'systemPrefix': 'https://craigahobbs.github.io/markdown-up/include/',
-                'urlFn': (url) => (rURL.test(url) || url.startsWith('/') ? url : `${file.slice(0, file.lastIndexOf('/') + 1)}${url}`)
+                'urlFn': scriptType === 'file' ? (url) => urlFileRelative(scriptName, url) : null
 
             });
-            statusCode = (Number.isInteger(result) && result >= 0 && result <= 255 ? result : (result ? 1 : 0));
+            if (Number.isInteger(result) && result >= 0 && result <= 255) {
+                statusCode = result;
+            } else {
+                statusCode = valueBoolean(result) ? 1 : 0;
+            }
 
             // Log script execution end with timing
             if (args.debug) {
@@ -134,8 +130,8 @@ export async function main(options) {
             }
         }
     } catch ({message}) {
-        if (currentFile !== null) {
-            options.logFn(`${currentFile}:`);
+        if (errorName !== null) {
+            options.logFn(`${errorName}:`);
         }
         options.logFn(message);
         statusCode = 1;
@@ -145,10 +141,6 @@ export async function main(options) {
 }
 
 
-// Regex to match a URL
-const rURL = /^[a-z]+:/;
-
-
 /**
  * Parse the BareScript command-line interface (CLI) arguments
  *
@@ -158,15 +150,14 @@ const rURL = /^[a-z]+:/;
  * @ignore
  */
 export function parseArgs(argv) {
-    const args = {'files': [], 'variables': {}};
-    let codeCount = 0;
+    const args = {'scripts': [], 'var': {}};
     for (let iArg = 2; iArg < argv.length; iArg++) {
         const arg = argv[iArg];
         if (arg === '-c' || arg === '--code') {
             if (iArg + 1 >= argv.length) {
-                throw new Error(`Missing value for ${arg}`);
+                throw new Error('argument -c/--code: expected one argument');
             }
-            args.files.push([`-c ${++codeCount}`, argv[iArg + 1]]);
+            args.scripts.push(['code', argv[iArg + 1]]);
             iArg++;
         } else if (arg === '-d' || arg === '--debug') {
             args.debug = true;
@@ -176,21 +167,33 @@ export function parseArgs(argv) {
             args.static = true;
         } else if (arg === '-v' || arg === '--var') {
             if (iArg + 2 >= argv.length) {
-                throw new Error(`Missing values for ${arg}`);
+                throw new Error('argument -v/--var: expected 2 arguments');
             }
-            args.variables[argv[iArg + 1]] = evaluateExpression(parseExpression(argv[iArg + 2]));
+            args.var[argv[iArg + 1]] = argv[iArg + 2];
             iArg += 2;
         } else if (arg.startsWith('-')) {
-            throw new Error(`Unknown option ${arg}`);
+            throw new Error(`unrecognized arguments: ${arg}`);
         } else {
-            args.files.push([arg, null]);
+            args.scripts.push(['file', arg]);
         }
     }
 
-    // Show help, if necessary
-    if (args.help || args.files.length === 0) {
-        throw new Error(helpText);
-    }
-
     return args;
 }
+
+
+// The command-line interface (CLI) help text
+export const helpText = `\
+usage: bare [-h] [-c CODE] [-d] [-s] [-v VAR EXPR] [file ...]
+
+The BareScript command-line interface
+
+positional arguments:
+  file                files to process
+
+options:
+  -h, --help          show this help message and exit
+  -c, --code CODE     execute the BareScript code
+  -d, --debug         enable debug mode
+  -s, --static        perform static analysis
+  -v, --var VAR EXPR  set a global variable to an expression value`;

package/lib/{bareDoc.js → baredoc.js}

@@ -1,74 +1,62 @@
 // Licensed under the MIT License
 // https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
+import {valueJSON} from './value.js';
+
 
 /**
- * BareScript library documentation CLI options
+ * BareScript documentation tool options
  *
- * @typedef {Object} BareDocOptions
+ * @typedef {Object} BaredocOptions
  * @property {string[]} argv - The process command-line arguments
- * @property {function} fetchFn - The [fetch function]{@link module:lib/runtime~FetchFn}
- * @property {function} logFn - The [log function]{@link module:lib/runtime~LogFn}
+ * @property {function} fetchFn - The [fetch function]{@link module:lib/options~FetchFn}
+ * @property {function} logFn - The [log function]{@link module:lib/options~LogFn}
  * @ignore
  */
 
 
 /**
- * BareScript library documentation command-line interface (CLI) main entry point
+ * BareScript documentation tool main entry point
  *
- * @param {Object} options - The CLI [options]{@link module:lib/bare~BareDocOptions}
+ * @param {Object} options - The [baredoc options]{@link module:lib/bare~BaredocOptions}
  * @returns {Number} The exit code
  * @ignore
  */
 export async function main(options) {
+    // Command line arguments
+    let args;
     try {
-        const urls = options.argv.slice(2);
-        const responses = await Promise.all(urls.map(async (url) => {
-            try {
-                return await options.fetchFn(url);
-            } catch {
-                throw Error(`Failed to load "${url}"`);
-            }
-        }));
-        const files = await Promise.all(responses.map(async (response, ixResponse) => {
-            const url = urls[ixResponse];
-            let text = null;
-            if (response.ok) {
-                try {
-                    text = await response.text();
-                } catch {
-                    // Do nothing
-                }
-            }
-            if (text === null) {
-                throw Error(`Failed to load "${url}"`);
-            }
-            return [url, text];
-        }));
-        options.logFn(JSON.stringify(parseBareDoc(files), null, 4));
+        args = parseArgs(options.argv);
     } catch ({message}) {
-        options.logFn(message);
+        options.logFn(`error: ${message}`);
+        return 1;
+    }
+    if (args.help || args.files.length === 0) {
+        options.logFn(helpText);
         return 1;
     }
 
-    return 0;
-}
-
-
-/**
- * Parse the library source for documentation tags
- *
- * @param {string[][]} files - The list of file name and source tuples
- * @returns {Object} The [library documentation model]{@link https://craigahobbs.github.io/bare-script/library/#var.vDoc=1}
- * @throws {Error}
- * @ignore
- */
-export function parseBareDoc(files) {
     // Parse each source file line-by-line
     const errors = [];
     const funcs = {};
     let func = null;
-    for (const [file, source] of files) {
+    for (const file of args.files) {
+        // Read the source file
+        let source = null;
+        try {
+            const response = await options.fetchFn(file);
+            if (response.ok) {
+                source = await response.text();
+            }
+        } catch {
+            // Do nothing...
+        }
+        if (source === null) {
+            errors.push(`Failed to load "${file}"`);
+            continue;
+        }
+
+        // Split the source lines and process documentation comments
         const lines = source.split(rSplit);
         for (const [ixLine, line] of lines.entries()) {
             // function/group/doc/return documentation keywords?
@@ -137,21 +125,32 @@ export function parseBareDoc(files) {
                     continue;
                 }
 
-                // Add the function arg documentation line - don't add leading blank lines
-                let args = func.args ?? null;
-                let arg = (args !== null ? args.find((argFind) => argFind.name === name) : null) ?? null;
-                if (arg !== null || textTrim !== '') {
-                    if (args === null) {
-                        args = [];
-                        func.args = args;
-                    }
-                    if (arg === null) {
-                        arg = {'name': name, 'doc': []};
-                        args.push(arg);
-                    }
-                    arg.doc.push(text);
+                // Get the function argument model, if it exists
+                let funcArgs = func.args ?? null;
+                let funcArg = null;
+                if (funcArgs !== null) {
+                    funcArg = funcArgs.find((findArg) => findArg.name === name) ?? null;
+                }
+
+                // Ignore leading argument documentation blank lines
+                if (funcArg === null && textTrim === '') {
+                    continue;
                 }
 
+                // Add the fuction model arguments member, if necessary
+                if (funcArgs === null) {
+                    funcArgs = [];
+                    func.args = funcArgs;
+                }
+
+                // Add the function argument model, if necessary
+                if (funcArg === null) {
+                    funcArg = {'name': name, 'doc': []};
+                    funcArgs.push(funcArg);
+                }
+
+                // Add the function argument documentation line
+                funcArg.doc.push(text);
                 continue;
             }
 
@@ -188,10 +187,35 @@ export function parseBareDoc(files) {
 
     // Errors?
     if (errors.length !== 0) {
-        throw new Error(errors.join('\n'));
+        options.logFn(errors.join('\n'));
+        return 1;
     }
 
-    return library;
+    // JSON-serialize the library documentation model
+    const libraryJSON = valueJSON(library);
+
+    // Output to stdout?
+    if (args.output === '-') {
+        options.logFn(libraryJSON);
+    } else {
+        // Output to file
+        let success = false;
+        try {
+            const response = await options.fetchFn(args.output, {'body': libraryJSON});
+            if (response.ok) {
+                await response.text();
+                success = true;
+            }
+        } catch {
+            // Do nothing
+        }
+        if (!success) {
+            options.logFn(`error: Failed to write "${args.output}"`);
+            return 1;
+        }
+    }
+
+    return 0;
 }
 
 
@@ -200,3 +224,53 @@ const rKey = /^\s*(?:\/\/|#)\s*\$(?<key>function|group|doc|return):\s?(?<text>.*
 const rArg = /^\s*(?:\/\/|#)\s*\$arg\s+(?<name>[A-Za-z_][A-Za-z0-9_]*(?:\.\.\.)?):\s?(?<text>.*)$/;
 const rUnknown = /^\s*(?:\/\/|#)\s*\$(?<unknown>[^:]+):/;
 const rSplit = /\r?\n/;
+
+
+/**
+ * Parse the baredoc command-line arguments
+ *
+ * @param {string} argv - The command-line arguments
+ * @returns {Object} The arguments object
+ * @throws {Error}
+ * @ignore
+ */
+export function parseArgs(argv) {
+    const args = {'files': [], 'output': '-'};
+    for (let iArg = 2; iArg < argv.length; iArg++) {
+        const arg = argv[iArg];
+        if (arg === '-o') {
+            if (iArg + 1 >= argv.length) {
+                throw new Error('argument -o: expected one argument');
+            }
+            args.output = argv[iArg + 1];
+            iArg++;
+        } else if (arg === '-h' || arg === '--help') {
+            args.help = true;
+        } else if (arg.startsWith('-')) {
+            throw new Error(`unrecognized arguments: ${arg}`);
+        } else {
+            args.files.push(arg);
+        }
+    }
+
+    // Files is required
+    if (!args.help && args.files.length === 0) {
+        throw new Error('the following arguments are required: file');
+    }
+
+    return args;
+}
+
+
+// The baredoc command-line help text
+export const helpText = `\
+usage: baredoc [-h] [-o file] file [file ...]
+
+The BareScript documentation tool
+
+positional arguments:
+  file        files to process
+
+options:
+  -h, --help  show this help message and exit
+  -o file     write output to file (default is "-")`;