bare-script 2.0.2 → 2.1.0

package/README.md

@@ -42,7 +42,7 @@ return N + ' times 2 is ' + double(N)
 
 // Execute the script
 const globals = {'N': 10};
-console.log(executeScript(script, {'globals': globals}));
+console.log(executeScript(script, {globals}));
 ~~~
 
 This outputs:
@@ -54,12 +54,14 @@ This outputs:
 
 ### The BareScript Library
 
-[The BareScript Library](https://craigahobbs.github.io/bare-script/library/) includes a set of
-built-in functions for mathematical operations, object manipulation, array manipulation, regular
-expressions, HTTP fetch and more. The following example demonstrates the use of the
-[httpFetch](https://craigahobbs.github.io/bare-script/library/#var.vName='httpFetch'),
+[The BareScript Library](https://craigahobbs.github.io/bare-script/library/)
+includes a set of built-in functions for mathematical operations, object manipulation, array
+manipulation, regular expressions, HTTP fetch and more. The following example demonstrates the use
+of the
+[systemFetch](https://craigahobbs.github.io/bare-script/library/#var.vName='systemFetch'),
 [objectGet](https://craigahobbs.github.io/bare-script/library/#var.vName='objectGet'), and
-[arrayLength](https://craigahobbs.github.io/bare-script/library/#var.vName='arrayLength') functions.
+[arrayLength](https://craigahobbs.github.io/bare-script/library/#var.vName='arrayLength')
+functions.
 
 ~~~ javascript
 import {executeScriptAsync} from 'bare-script/lib/runtimeAsync.js';
@@ -68,10 +70,10 @@ import {parseScript} from 'bare-script/lib/parser.js';
 // Parse the script
 const script = parseScript(`\
 # Fetch the BareScript library documentation JSON
-libraryDocs = httpFetch('https://craigahobbs.github.io/bare-script/library/library.json')
+docs = systemFetch('https://craigahobbs.github.io/bare-script/library/library.json')
 
 # Return the number of library functions
-return 'The BareScript Library has ' + arrayLength(objectGet(libraryDocs, 'functions')) + ' functions'
+return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' functions'
 `);
 
 // Execute the script
@@ -81,7 +83,7 @@ console.log(await executeScriptAsync(script, {'fetchFn': fetch}));
 This outputs:
 
 ~~~
-The BareScript Library has 86 functions
+The BareScript Library has 89 functions
 ~~~
 
 
@@ -122,6 +124,42 @@ This outputs:
 ~~~
 
 
+## The BareScript Command-Line Interface (CLI)
+
+You can run BareScript from the command line using the BareScript CLI, "bare". BareScript script
+files use the ".bare" file extension.
+
+~~~
+bare script.bare
+~~~
+
+**Note:** In the BareScript CLI, import statements and the
+[systemFetch](https://craigahobbs.github.io/bare-script/library/#var.vName='systemFetch')
+function read non-URL paths from the local file system.
+
+
+## MarkdownUp, a Markdown Viewer with BareScript
+
+[MarkdownUp](https://craigahobbs.github.io/markdown-up/)
+is a Markdown Viewer that executes BareScript embedded within Markdown documents.
+[MarkdownUp](https://craigahobbs.github.io/markdown-up/)
+extends its
+[standard library](https://craigahobbs.github.io/markdown-up/library/)
+with functions for dynamically rendering Markdown text, drawing SVG images, etc.
+
+For example:
+
+```
+# Markdown Application
+
+This is a Markdown document with embedded BareScript:
+
+~~~ markdown-script
+markdownPrint('Hello, Markdown!')
+~~~
+```
+
+
 ## Development
 
 This package is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme).

package/bin/bare.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Licensed under the MIT License
+// https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+import {argv, exit, stdout} from 'node:process';
+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`)
+}));

package/bin/bareDoc.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Licensed under the MIT License
+// https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+import {argv, exit, stdout} from 'node:process';
+import {main} from '../lib/bareDoc.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`)
+}));

package/lib/bare.js

@@ -0,0 +1,176 @@
+// Licensed under the MIT License
+// https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+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
+  -v, --var VAR EXPR  set a global variable to an expression value`;
+
+
+/**
+ * BareScript CLI 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}
+ * @ignore
+ */
+
+
+/**
+ * BareScript command-line interface (CLI) main entry point
+ *
+ * @param {Object} options - The [CLI options]{@link module:lib/bare~BareOptions}
+ * @returns {Number} The exit code
+ * @ignore
+ */
+export async function main(options) {
+    let currentFile = null;
+    try {
+        const args = parseArgs(options.argv);
+
+        // 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) {
+                try {
+                    source = await response.text();
+                } catch {
+                    // Do nothing
+                }
+            }
+            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;
+
+            // Run the bare-script linter?
+            if (args.debug) {
+                const warnings = lintScript(script);
+                const warningPrefix = `BareScript: Static analysis...`;
+                if (warnings.length === 0) {
+                    options.logFn(`${warningPrefix} OK`);
+                } else {
+                    options.logFn(`${warningPrefix} ${warnings.length} warning${warnings.length > 1 ? 's' : ''}:`);
+                    for (const warning of warnings) {
+                        options.logFn(`BareScript:     ${warning}`);
+                    }
+                }
+            }
+
+            // Execute the script
+            const timeBegin = performance.now();
+            // eslint-disable-next-line no-await-in-loop
+            await executeScriptAsync(script, {
+                'debug': args.debug ?? false,
+                'fetchFn': options.fetchFn,
+                'globals': args.variables,
+                'logFn': (message) => options.logFn(message),
+                'systemPrefix': 'https://craigahobbs.github.io/markdown-up/include/',
+                'urlFn': (url) => (rURL.test(url) || url.startsWith('/') ? url : `${file.slice(0, file.lastIndexOf('/') + 1)}${url}`)
+
+            });
+
+            // Log script execution end with timing
+            if (args.debug) {
+                const timeEnd = performance.now();
+                options.logFn(`BareScript: Script executed in ${(timeEnd - timeBegin).toFixed(1)} milliseconds`);
+            }
+        }
+    } catch ({message}) {
+        const fileStr = (currentFile !== null ? `${currentFile}:\n` : '');
+        options.logFn(`${fileStr}${message}`);
+        return 1;
+    }
+
+    return 0;
+}
+
+
+// Regex to match a URL
+const rURL = /^[a-z]+:/;
+
+
+/**
+ * Parse the BareScript command-line interface (CLI) arguments
+ *
+ * @param {string} argv - The command-line arguments
+ * @returns {Object} The arguments object
+ * @throws {Error}
+ * @ignore
+ */
+export function parseArgs(argv) {
+    const args = {'files': [], 'variables': {}};
+    let codeCount = 0;
+    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}`);
+            }
+            args.files.push([`-c ${++codeCount}`, argv[iArg + 1]]);
+            iArg++;
+        } else if (arg === '-d' || arg === '--debug') {
+            args.debug = true;
+        } else if (arg === '-h' || arg === '--help') {
+            args.help = true;
+        } else if (arg === '-v' || arg === '--var') {
+            if (iArg + 2 >= argv.length) {
+                throw new Error(`Missing values for ${arg}`);
+            }
+            args.variables[argv[iArg + 1]] = evaluateExpression(parseExpression(argv[iArg + 2]));
+            iArg += 2;
+        } else if (arg.startsWith('-')) {
+            throw new Error(`Unknown option ${arg}`);
+        } else {
+            args.files.push([arg, null]);
+        }
+    }
+
+    // Show help, if necessary
+    if (args.help || args.files.length === 0) {
+        throw new Error(helpText);
+    }
+
+    return args;
+}

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

@@ -2,6 +2,59 @@
 // https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
 
+/**
+ * BareScript library documentation CLI options
+ *
+ * @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}
+ * @ignore
+ */
+
+
+/**
+ * BareScript library documentation command-line interface (CLI) main entry point
+ *
+ * @param {Object} options - The CLI [options]{@link module:lib/bare~BareDocOptions}
+ * @returns {Number} The exit code
+ * @ignore
+ */
+export async function main(options) {
+    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));
+    } catch ({message}) {
+        options.logFn(message);
+        return 1;
+    }
+
+    return 0;
+}
+
+
 /**
  * Parse the library source for documentation tags
  *
@@ -10,7 +63,7 @@
  * @throws {Error}
  * @ignore
  */
-export function parseLibraryDoc(files) {
+export function parseBareDoc(files) {
     // Parse each source file line-by-line
     const errors = [];
     const funcs = {};

package/lib/library.js

@@ -149,31 +149,6 @@ export const scriptFunctions = {
     ),
 
 
-    //
-    // Console functions
-    //
-
-    // $function: consoleLog
-    // $group: Console
-    // $doc: Log a message to the console
-    // $arg string: The message
-    'consoleLog': ([string], options) => {
-        if (options !== null && 'logFn' in options) {
-            options.logFn(string);
-        }
-    },
-
-    // $function: consoleLogDebug
-    // $group: Console
-    // $doc: Log a debug message
-    // $arg string: The message
-    'consoleLogDebug': ([string], options) => {
-        if (options !== null && 'logFn' in options && options.debug) {
-            options.logFn(string);
-        }
-    },
-
-
     //
     // Datetime functions
     //
@@ -283,47 +258,6 @@ export const scriptFunctions = {
     'datetimeYear': ([datetime]) => (datetime instanceof Date ? datetime.getFullYear() : null),
 
 
-    //
-    // HTTP functions
-    //
-
-    // $function: httpFetch
-    // $group: HTTP
-    // $doc: Retrieve a remote JSON or text resource
-    // $arg url: The resource URL or array of URLs
-    // $arg options: Optional (default is null). The [fetch options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters).
-    // $arg isText: Optional (default is false). If true, retrieve the resource as text.
-    // $return: The resource object/string or array of objects/strings; null if an error occurred.
-    'httpFetch': async ([url, fetchOptions = null, isText = false], options) => {
-        const isArray = Array.isArray(url);
-        const urls = (isArray ? url : [url]).map((mURL) => (options !== null && 'urlFn' in options ? options.urlFn(mURL) : mURL));
-        const responses = await Promise.all(urls.map(async (fURL) => {
-            try {
-                return 'fetchFn' in options ? await (fetchOptions ? options.fetchFn(fURL, fetchOptions) : options.fetchFn(fURL)) : null;
-            } catch {
-                return null;
-            }
-        }));
-        const values = await Promise.all(responses.map(async (response) => {
-            try {
-                return response !== null && response.ok ? await (isText ? response.text() : response.json()) : null;
-            } catch {
-                return null;
-            }
-        }));
-
-        // Log failures
-        for (const [ixValue, value] of values.entries()) {
-            if (value === null && options !== null && 'logFn' in options && options.debug) {
-                const errorURL = urls[ixValue];
-                options.logFn(`BareScript: Function "httpFetch" failed for ${isText ? 'text' : 'JSON'} resource "${errorURL}"`);
-            }
-        }
-
-        return isArray ? values : values[0];
-    },
-
-
     //
     // JSON functions
     //
@@ -664,37 +598,6 @@ export const scriptFunctions = {
     'regexTest': ([regex, string]) => (regex instanceof RegExp ? regex.test(string) : null),
 
 
-    //
-    // Runtime functions
-    //
-
-    // $function: runtimeGetGlobal
-    // $group: Runtime
-    // $doc: Get a global variable value
-    // $arg name: The global variable name
-    // $return: The global variable's value or null if it does not exist
-    'runtimeGetGlobal': ([name], options) => {
-        const globals = (options !== null ? (options.globals ?? null) : null);
-        return (globals !== null ? (globals[name] ?? null) : null);
-    },
-
-    // $function: runtimeSetGlobal
-    // $group: Runtime
-    // $doc: Set a global variable value
-    // $arg name: The global variable name
-    // $arg value: The global variable's value
-    // $return: The global variable's value
-    'runtimeSetGlobal': ([name, value], options) => {
-        if (options !== null) {
-            const globals = options.globals ?? null;
-            if (globals !== null) {
-                globals[name] = value;
-            }
-        }
-        return value;
-    },
-
-
     //
     // Schema functions
     //
@@ -875,6 +778,93 @@ export const scriptFunctions = {
     'stringUpper': ([string]) => (typeof string === 'string' ? string.toUpperCase() : null),
 
 
+    //
+    // System functions
+    //
+
+    // $function: systemFetch
+    // $group: System
+    // $doc: Retrieve a remote JSON or text resource
+    // $arg url: The resource URL or array of URLs
+    // $arg options: Optional (default is null). The [fetch options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters).
+    // $arg isText: Optional (default is false). If true, retrieve the resource as text.
+    // $return: The resource object/string or array of objects/strings; null if an error occurred.
+    'systemFetch': async ([url, fetchOptions = null, isText = false], options) => {
+        const isArray = Array.isArray(url);
+        const urls = (isArray ? url : [url]).map((mURL) => (options !== null && 'urlFn' in options ? options.urlFn(mURL) : mURL));
+        const responses = await Promise.all(urls.map(async (fURL) => {
+            try {
+                return 'fetchFn' in options ? await (fetchOptions ? options.fetchFn(fURL, fetchOptions) : options.fetchFn(fURL)) : null;
+            } catch {
+                return null;
+            }
+        }));
+        const values = await Promise.all(responses.map(async (response) => {
+            try {
+                return response !== null && response.ok ? await (isText ? response.text() : response.json()) : null;
+            } catch {
+                return null;
+            }
+        }));
+
+        // Log failures
+        for (const [ixValue, value] of values.entries()) {
+            if (value === null && options !== null && 'logFn' in options && options.debug) {
+                const errorURL = urls[ixValue];
+                options.logFn(`BareScript: Function "systemFetch" failed for ${isText ? 'text' : 'JSON'} resource "${errorURL}"`);
+            }
+        }
+
+        return isArray ? values : values[0];
+    },
+
+    // $function: systemGlobalGet
+    // $group: System
+    // $doc: Get a global variable value
+    // $arg name: The global variable name
+    // $return: The global variable's value or null if it does not exist
+    'systemGlobalGet': ([name], options) => {
+        const globals = (options !== null ? (options.globals ?? null) : null);
+        return (globals !== null ? (globals[name] ?? null) : null);
+    },
+
+    // $function: systemGlobalSet
+    // $group: System
+    // $doc: Set a global variable value
+    // $arg name: The global variable name
+    // $arg value: The global variable's value
+    // $return: The global variable's value
+    'systemGlobalSet': ([name, value], options) => {
+        if (options !== null) {
+            const globals = options.globals ?? null;
+            if (globals !== null) {
+                globals[name] = value;
+            }
+        }
+        return value;
+    },
+
+    // $function: systemLog
+    // $group: System
+    // $doc: Log a message to the console
+    // $arg string: The message
+    'systemLog': ([string], options) => {
+        if (options !== null && 'logFn' in options) {
+            options.logFn(string);
+        }
+    },
+
+    // $function: systemLogDebug
+    // $group: System
+    // $doc: Log a message to the console, if in debug mode
+    // $arg string: The message
+    'systemLogDebug': ([string], options) => {
+        if (options !== null && 'logFn' in options && options.debug) {
+            options.logFn(string);
+        }
+    },
+
+
     //
     // URL functions
     //
@@ -932,7 +922,6 @@ export const expressionFunctionMap = {
     'date': 'datetimeNew',
     'day': 'datetimeDay',
     'endsWith': 'stringEndsWith',
-    'if': 'if',
     'indexOf': 'stringIndexOf',
     'fixed': 'numberToFixed',
     'floor': 'mathFloor',
@@ -974,5 +963,5 @@ export const expressionFunctionMap = {
 
 // The built-in expression functions
 export const expressionFunctions = Object.fromEntries(Object.entries(expressionFunctionMap).map(
-    ([exprFnName, scriptFnName]) => [exprFnName, scriptFunctions[scriptFnName] ?? null]
+    ([exprFnName, scriptFnName]) => [exprFnName, scriptFunctions[scriptFnName]]
 ).filter(([, exprFn]) => exprFn !== null));

package/package.json

@@ -1,7 +1,7 @@
 {
     "type": "module",
     "name": "bare-script",
-    "version": "2.0.2",
+    "version": "2.1.0",
     "description": "BareScript; a lightweight scripting and expression language",
     "keywords": [
         "expression",
@@ -17,7 +17,8 @@
         "url": "https://github.com/craigahobbs"
     },
     "bin": {
-        "bareScriptDoc": "./bin/bareScriptDoc.js"
+        "bare": "./bin/bare.js",
+        "baredoc": "./bin/bareDoc.js"
     },
     "files": [
         "lib/**/*"
@@ -30,7 +31,7 @@
     },
     "devDependencies": {
         "c8": "~8.0",
-        "eslint": "~8.44",
+        "eslint": "~8.48",
         "jsdoc": "~4.0"
     }
 }

package/bin/bareScriptDoc.js

@@ -1,15 +0,0 @@
-#!/usr/bin/env node
-// Licensed under the MIT License
-// https://github.com/craigahobbs/bare-script/blob/main/LICENSE
-
-import {argv, exit, stderr, stdout} from 'node:process';
-import {parseLibraryDoc} from '../lib/libraryDoc.js';
-import {readFileSync} from 'node:fs';
-
-try {
-    stdout.write(JSON.stringify(parseLibraryDoc(argv.slice(2).map((file) => [file, readFileSync(file, 'utf-8')])), null, 4));
-} catch (error) {
-    stderr.write(error.message);
-    stderr.write('\n');
-    exit(1);
-}