bare-script 3.8.1 → 3.8.2

package/README.md

@@ -93,7 +93,7 @@ console.log(await executeScriptAsync(script, {'fetchFn': fetch}));
 This outputs:
 
 ```
-The BareScript Library has 105 functions
+The BareScript Library has 186 functions
 ```
 
 
@@ -154,14 +154,9 @@ write the body to the path.
 
 ## 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:
+[MarkdownUp](https://craigahobbs.github.io/markdown-up/) is a Markdown Viewer that executes
+BareScript embedded within Markdown documents. The MarkdownUp runtime contains functions for
+dynamically rendering Markdown text, drawing SVG images, etc. For example:
 
 ~~~
 # Markdown Application

package/lib/include/args.bare

@@ -1,10 +1,10 @@
 # Licensed under the MIT License
-# https://github.com/craigahobbs/markdown-up/blob/main/LICENSE
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
 
 # The URL arguments model
 argsTypes = schemaParse( \
-    'group "args.bare"', \
+    'group "<args.bare>"', \
     '', \
     '', \
     '# An argument model list', \
@@ -48,8 +48,8 @@ argsTypes = schemaParse( \
 # $function: argsValidate
 # $group: args.bare
 # $doc: Validate an arguments model
-# $arg arguments: The [arguments model](includeModel.html#var.vName='ArgsArguments')
-# $return: The validated [arguments model](includeModel.html#var.vName='ArgsArguments') or null if validation fails
+# $arg arguments: The [arguments model](model.html#var.vName='ArgsArguments')
+# $return: The validated [arguments model](model.html#var.vName='ArgsArguments') or null if validation fails
 function argsValidate(arguments):
     validatedArguments = schemaValidate(argsTypes, 'ArgsArguments', arguments)
 
@@ -73,9 +73,9 @@ endfunction
 
 # $function: argsParse
 # $group: args.bare
-# $doc: Parse an [arguments model](includeModel.html#var.vName='ArgsArguments').
+# $doc: Parse an [arguments model](model.html#var.vName='ArgsArguments').
 # $doc: Argument globals are validated and added to the arguments object using the argument name.
-# $arg arguments: The [arguments model](includeModel.html#var.vName='ArgsArguments')
+# $arg arguments: The [arguments model](model.html#var.vName='ArgsArguments')
 # $return: The arguments object
 function argsParse(arguments):
     # Create the arguments object
@@ -103,7 +103,7 @@ endfunction
 # $function: argsURL
 # $group: args.bare
 # $doc: Create a MarkdownUp application URL
-# $arg arguments: The [arguments model](includeModel.html#var.vName='ArgsArguments')
+# $arg arguments: The [arguments model](model.html#var.vName='ArgsArguments')
 # $arg args: Optional (default is null). The arguments object. Null argument values are excluded from the URL.
 # $arg explicit: Optional (default is false). If true, arguments are only included in the URL if they are in the arguments object.
 # $arg headerText: Optional (default is null). If non-null, the URL's header text.
@@ -163,7 +163,7 @@ argsTopHeaderId = '_top'
 # $function: argsLink
 # $group: args.bare
 # $doc: Create a Markdown link text to a MarkdownUp application URL
-# $arg arguments: The [arguments model](includeModel.html#var.vName='ArgsArguments')
+# $arg arguments: The [arguments model](model.html#var.vName='ArgsArguments')
 # $arg text: The link text
 # $arg args: Optional (default is null). The arguments object.
 # $arg explicit: Optional (default is false). If true, arguments are only included in the URL if they are in the arguments object.
@@ -178,10 +178,10 @@ endfunction
 
 # $function: argsHelp
 # $group: args.bare
-# $doc: Generate the [arguments model's](includeModel.html#var.vName='ArgsArguments') help content
+# $doc: Generate the [arguments model's](model.html#var.vName='ArgsArguments') help content
 # $doc:
 # $doc: **NOTE:** Calling this function requires `include <dataTable.bare>`
-# $arg arguments: The [arguments model](includeModel.html#var.vName='ArgsArguments')
+# $arg arguments: The [arguments model](model.html#var.vName='ArgsArguments')
 # $return: The array of help Markdown line strings
 function argsHelp(arguments):
     # Create the help data

package/lib/include/baredoc.bare

@@ -0,0 +1,313 @@
+# Licensed under the MIT License
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+include <args.bare>
+
+
+# $function: baredocMain
+# $group: baredocMain.bare
+# $doc: The BareScript library documentation application main entry point
+# $arg url: The library documentation JSON resource URL
+# $arg title: The library title
+# $arg menuLinks: Optional array of text/URL menu link tuples
+# $arg groupURLs: Optional map of group name to group Markdown content URL ('' is index) or JSON resource URL
+async function baredocMain(url, title, menuLinks, groupURLs):
+    # Parse arguments
+    args = argsParse(baredocArguments)
+    group = objectGet(args, 'group')
+    name = objectGet(args, 'name')
+    single = objectGet(args, 'single')
+    url = objectGet(args, 'url', url)
+
+    # Render library JSON documentation page?
+    if objectGet(args, 'doc'):
+        documentSetTitle('Library')
+        elementModelRender(schemaElements(baredocTypes, 'Library'))
+        return
+    endif
+
+    # Fetch and validate the library documentation resource
+    groups = {}
+    urls = if(systemType(url) == 'array', url, [url])
+    for libraryJSON, ixLibrary in systemFetch(urls):
+        libraryPart = if(libraryJSON != null, jsonParse(libraryJSON))
+        libraryPart = if(libraryPart != null, schemaValidate(baredocTypes, 'Library', libraryPart))
+        if libraryPart == null:
+            libraryURL = arrayGet(urls, ixLibrary)
+            markdownPrint('**Error:** Failed to fetch library documentation resource "' + markdownEscape(libraryURL) + '"')
+            return
+        endif
+
+        # Group the function documentation
+        for function_ in objectGet(libraryPart, 'functions'):
+            groupName = objectGet(function_, 'group')
+            groupFunctions = objectGet(groups, groupName)
+            if groupFunctions == null:
+                groupFunctions = []
+                objectSet(groups, groupName, groupFunctions)
+            endif
+            arrayPush(groupFunctions, function_)
+        endfor
+    endfor
+
+    # Group URLs?
+    if groupURLs != null:
+        # Fetch the group URLs, if necessary
+        if systemType(groupURLs) == 'string':
+            groupURLs = jsonParse(systemFetch(groupURLs))
+        endif
+
+        # Add an empty group for any missing group URLs
+        for groupName in objectKeys(groupURLs):
+            if groupName != '' && !objectHas(groups, groupName):
+                objectSet(groups, groupName, [])
+            endif
+        endfor
+    endif
+
+    # Sort the group functions
+    for groupName in objectKeys(groups):
+        groupFunctions = objectGet(groups, groupName)
+        arraySort(groupFunctions, baredocFunctionCompare)
+
+        # Function requested by name?
+        if name != null:
+            for function_ in groupFunctions:
+                functionName = objectGet(function_, 'name')
+                if functionName == name:
+                    # Redirect to the actual URL
+                    windowSetLocation( \
+                        argsURL(baredocArguments, {'group': objectGet(function_, 'group'), 'name': null}, false, functionName) \
+                    )
+                    return
+                endif
+            endfor
+        endif
+    endfor
+    if name != null:
+        markdownPrint('', '**Error:** Unknown function "' + markdownEscape(name) + '"')
+        return
+    endif
+
+    # Render the page
+    title = if(title != null && !objectHas(args, 'url'), title, url)
+    if group != null:
+        baredocGroupPage(args, title, groupURLs, groups, group)
+    elif single:
+        baredocSinglePage(args, title, menuLinks, groupURLs, groups)
+    else:
+        baredocIndexPage(args, title, menuLinks, groupURLs, groups)
+    endif
+endfunction
+
+
+# The BareScript library documentation application arguments
+baredocArguments = argsValidate([ \
+    {'name': 'doc', 'type': 'bool', 'default': false}, \
+    {'name': 'group'}, \
+    {'name': 'name'}, \
+    {'name': 'publish', 'type': 'bool', 'default': false}, \
+    {'name': 'single', 'type': 'bool', 'default': false}, \
+    {'name': 'url', 'global': 'vURL'} \
+])
+
+
+# Helper to compare library function objects by name
+function baredocFunctionCompare(f1, f2):
+    f1Name = objectGet(f1, 'name')
+    f2Name = objectGet(f2, 'name')
+    return if(f1Name < f2Name, -1, if(f1Name == f2Name, 0, 1))
+endfunction
+
+
+# Render a library documentation index page
+async function baredocIndexPage(args, title, menuLinks, groupURLs, groups):
+    publish = objectGet(args, 'publish')
+
+    # Render the menu and title
+    documentSetTitle(title)
+    if menuLinks != null && arrayLength(menuLinks) > 0 && !publish:
+        menuSpacer = '&nbsp;|&nbsp;'
+        for menuLink, ixMenuLink in menuLinks:
+            menuLinkText = arrayGet(menuLink, 0)
+            menuLinkURL = arrayGet(menuLink, 1)
+            markdownPrint(if(ixMenuLink == 0, '', menuSpacer) + '[' + markdownEscape(menuLinkText) + '](' + urlEncode(menuLinkURL) + ')')
+        endfor
+        markdownPrint('')
+    endif
+    markdownPrint('# ' + markdownEscape(title))
+
+    # Render the index Markdown, if any
+    if groupURLs != null && objectHas(groupURLs, ''):
+        rootURL = objectGet(groupURLs, '')
+        rootMarkdown = systemFetch(rootURL)
+        markdownPrint('', if(rootMarkdown != null, rootMarkdown, '**Error:** Failed to load "' + markdownEscape(rootURL) + '"'))
+    endif
+
+    # Render the single page toggle
+    if !publish:
+        markdownPrint('', argsLink(baredocArguments, 'Single Page', {'single': true}))
+    endif
+
+    # Render the library function index
+    markdownPrint('', '## Table of Contents', '')
+    for groupName in arraySort(objectKeys(groups)):
+        markdownPrint('- ' + argsLink(baredocArguments, groupName, {'group': groupName}, false, argsTopHeaderId))
+    endfor
+endfunction
+
+
+# Render the single-page library documentation
+async function baredocSinglePage(args, title, menuLinks, groupURLs, groups):
+    publish = objectGet(args, 'publish')
+
+    # Render the menu and title
+    documentSetTitle(title)
+    if menuLinks != null && arrayLength(menuLinks) > 0 && !publish:
+        menuSpacer = '&nbsp;|&nbsp;'
+        for menuLink, ixMenuLink in menuLinks:
+            menuLinkText = arrayGet(menuLink, 0)
+            menuLinkURL = arrayGet(menuLink, 1)
+            markdownPrint(if(ixMenuLink == 0, '', menuSpacer) + '[' + markdownEscape(menuLinkText) + '](' + urlEncode(menuLinkURL) + ')')
+        endfor
+        markdownPrint('')
+    endif
+    markdownPrint('# ' + markdownEscape(title))
+
+    # Render the index Markdown, if any
+    if groupURLs != null && objectHas(groupURLs, ''):
+        rootURL = objectGet(groupURLs, '')
+        rootMarkdown = systemFetch(rootURL)
+        markdownPrint('', if(rootMarkdown != null, rootMarkdown, '**Error:** Failed to load "' + markdownEscape(rootURL) + '"'))
+    endif
+
+    # Render the single page toggle
+    if !publish:
+        markdownPrint('', argsLink(baredocArguments, 'Multi Page', {'single': false}))
+    endif
+
+    # The table of contents
+    markdownPrint('', '## Table of Contents', '')
+    for groupName in arraySort(objectKeys(groups)):
+        markdownPrint('- ' + argsLink(baredocArguments, groupName, null, false, groupName))
+    endfor
+
+    # Render the library function index
+    for groupName in arraySort(objectKeys(groups)):
+        markdownPrint('', '---', '')
+        baredocGroupPage(args, title, groupURLs, groups, groupName, true)
+    endfor
+endfunction
+
+
+# Render a library documentation group page
+async function baredocGroupPage(args, title, groupURLs, groups, groupName):
+    single = objectGet(args, 'single')
+    baseHeader = if(single, '##', '#')
+
+    if !single:
+        # Set the document title
+        documentSetTitle(title + ' - ' + groupName)
+
+        # Group exist?
+        if !objectHas(groups, groupName):
+            markdownPrint('', '**Error:** Unknown group "' + markdownEscape(groupName) + '"')
+            return
+        endif
+    endif
+
+    # Render the menu and title
+    if !single:
+        markdownPrint(argsLink(baredocArguments, 'Index', {'group': null}), '')
+    endif
+    markdownPrint(baseHeader + ' ' + markdownEscape(groupName))
+    if single:
+        markdownPrint('', argsLink(baredocArguments, 'Back to top', null, false, '_top'))
+    endif
+
+
+    # Render the group Markdown, if any
+    if groupURLs != null && objectHas(groupURLs, groupName):
+        groupURL = objectGet(groupURLs, groupName)
+        groupMarkdown = systemFetch(groupURL)
+        markdownPrint('', if(groupMarkdown != null, groupMarkdown, '**Error:** Failed to load "' + markdownEscape(groupURL) + '"'))
+    endif
+
+    # Render the group function index
+    groupFunctions = objectGet(groups, groupName)
+    if arrayLength(groupFunctions) != 0:
+        markdownPrint('', baseHeader + '# Function Index', '')
+    endif
+    for function_, ixFunction in groupFunctions:
+        functionName = objectGet(function_, 'name')
+        markdownPrint('- ' + argsLink(baredocArguments, functionName, null, false, functionName))
+    endfor
+
+    # Render the group function documentation
+    for function_ in groupFunctions:
+        # Render the function header
+        markdownPrint( \
+            '', \
+            '---', \
+            '', \
+            baseHeader + '# ' + markdownEscape(objectGet(function_, 'name')), \
+            '', \
+            objectGet(function_, 'doc') \
+        )
+
+        # Render the functions's argument documentation
+        markdownPrint('', baseHeader + '## Arguments')
+        arguments = objectGet(function_, 'args')
+        if arguments != null:
+            for argument in arguments:
+                markdownPrint('', '**' + markdownEscape(objectGet(argument, 'name')) + ' -**', objectGet(argument, 'doc'))
+            endfor
+        else:
+            markdownPrint('', 'None')
+        endif
+
+        # Render the function's return documentation
+        markdownPrint('', baseHeader + '## Returns')
+        returnDoc = objectGet(function_, 'return')
+        markdownPrint('', if(returnDoc != null, returnDoc, 'Nothing'))
+    endfor
+endfunction
+
+
+# The library documentation schema
+baredocTypes = schemaParse( \
+    '# A library documentation model', \
+    'struct Library', \
+    '', \
+    '    # The library functions', \
+    '    Function[len > 0] functions', \
+    '', \
+    '', \
+    '# A library function', \
+    'struct Function', \
+    '', \
+    '    # The function name', \
+    '    string(len > 0) name', \
+    '', \
+    '    # The function group (e.g. "Math")', \
+    '    string(len > 0) group', \
+    '', \
+    "    # The function's documentation Markdown lines", \
+    '    string[len > 0] doc', \
+    '', \
+    '    # The function arguments', \
+    '    optional FunctionArgument[len > 0] args', \
+    '', \
+    "    # The function return's documentation Markdown lines", \
+    '    optional string[len > 0] return', \
+    '', \
+    '', \
+    '# A function argument', \
+    'struct FunctionArgument', \
+    '', \
+    '    # The argument name', \
+    '    string(len > 0) name', \
+    '', \
+    "    # The argument's documentation Markdown lines", \
+    '    string[len > 0] doc' \
+)

package/lib/include/dataLineChart.bare

@@ -0,0 +1,90 @@
+# Licensed under the MIT License
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+
+# The line chart model
+dataLineChartTypes = schemaParse( \
+    'group "Line Chart"', \
+    '', \
+    '', \
+    '# A line chart model', \
+    'struct LineChart', \
+    '', \
+    '    # The chart title', \
+    '    optional string title', \
+    '', \
+    '    # The chart width', \
+    '    optional int width', \
+    '', \
+    '    # The chart height', \
+    '    optional int height', \
+    '', \
+    '    # The numeric formatting precision (default is 2)', \
+    '    optional int(>= 0) precision', \
+    '', \
+    '    # The datetime format', \
+    '    optional LineChartDatetimeFormat datetime', \
+    '', \
+    "    # The line chart's X-axis field", \
+    '    string x', \
+    '', \
+    "    # The line chart's Y-axis fields", \
+    '    string[len > 0] y', \
+    '', \
+    '    # The color encoding field', \
+    '    optional string color', \
+    '', \
+    '    # The color encoding value order', \
+    '    optional string[len > 0] colorOrder', \
+    '', \
+    '    # The X-axis tick marks', \
+    '    optional LineChartAxisTicks xTicks', \
+    '', \
+    '    # The Y-axis tick marks', \
+    '    optional LineChartAxisTicks yTicks', \
+    '', \
+    '    # The X-axis annotations', \
+    '    optional LineChartAxisAnnotation[len > 0] xLines', \
+    '', \
+    '    # The Y-axis annotations', \
+    '    optional LineChartAxisAnnotation[len > 0] yLines', \
+    '', \
+    '', \
+    '# The axis tick mark model', \
+    'struct LineChartAxisTicks', \
+    '', \
+    '    # The count of evenly-spaced tick marks. The default is 3.', \
+    '    optional int(>= 0) count', \
+    '', \
+    '    # The value of the first tick mark. Default is the minimum axis value.', \
+    '    optional any start', \
+    '', \
+    '    # The value of the last tick mark. Default is the maximum axis value.', \
+    '    optional any end', \
+    '', \
+    '    # The number of tick mark labels to skip after a rendered label', \
+    '    optional int(> 0) skip', \
+    '', \
+    '', \
+    '# An axis annotation', \
+    'struct LineChartAxisAnnotation', \
+    '', \
+    '    # The axis value', \
+    '    any value', \
+    '', \
+    '    # The annotation label', \
+    '    optional string label', \
+    '', \
+    '', \
+    '# A datetime format', \
+    'enum LineChartDatetimeFormat', \
+    '', \
+    '    # ISO datetime year format', \
+    '    year', \
+    '', \
+    '    # ISO datetime month format', \
+    '    month', \
+    '', \
+    '    # ISO datetime day format', \
+    '    day' \
+)

package/lib/include/dataTable.bare

@@ -1,10 +1,10 @@
 # Licensed under the MIT License
-# https://github.com/craigahobbs/markdown-up/blob/main/LICENSE
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
 
 # The data table model's Schema Markdown
 dataTableTypes = schemaParse( \
-    'group "Data Table"', \
+    'group "<dataTable.bare>"', \
     '', \
     '', \
     '# A data table model', \
@@ -70,7 +70,7 @@ dataTableTypes = schemaParse( \
 # $group: dataTable.bare
 # $doc: Create the array of Markdown table line strings
 # $arg data: The array of row objects
-# $arg model: The [data table model](includeModel.html#var.vName='DataTable')
+# $arg model: The [data table model](model.html#var.vName='DataTable')
 # $return: The array of Markdown table line strings
 function dataTableMarkdown(data, model):
     # Validate the data

package/lib/include/diff.bare

@@ -1,10 +1,10 @@
 # Licensed under the MIT License
-# https://github.com/craigahobbs/markdown-up/blob/main/LICENSE
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
 
 # The text line difference model
 diffTypes = schemaParse( \
-    'group "diff.bare"', \
+    'group "<diff.bare>"', \
     '', \
     '', \
     '# A list of text line differences', \
@@ -40,7 +40,7 @@ diffTypes = schemaParse( \
 # $doc: Compute the line-differences of two strings or arrays of strings
 # $arg left: The "left" string or array of strings
 # $arg right: The "right" string or array of strings
-# $return: The array of [difference models](includeModel.html#var.vName='Differences')
+# $return: The array of [difference models](model.html#var.vName='Differences')
 function diffLines(left, right):
     diffs = []
 

package/lib/include/forms.bare

@@ -1,5 +1,5 @@
 # Licensed under the MIT License
-# https://github.com/craigahobbs/markdown-up/blob/main/LICENSE
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
 
 
 # $function: formsTextElements