bare-script 3.8.2__py3-none-any.whl

bare_script/include/args.bare

@@ -0,0 +1,340 @@
+# Licensed under the MIT License
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+
+# The URL arguments model
+argsTypes = schemaParse( \
+    'group "<args.bare>"', \
+    '', \
+    '', \
+    '# An argument model list', \
+    'typedef ArgsArgument[len > 0] ArgsArguments', \
+    '', \
+    '', \
+    '# An argument model', \
+    'struct ArgsArgument', \
+    '', \
+    '    # The argument name', \
+    '    string(len > 0) name', \
+    '', \
+    '    # The argument type', \
+    '    optional ArgsType type', \
+    '', \
+    "    # The argument's global variable name", \
+    '    optional string(len > 0) global', \
+    '', \
+    '    # If true, the argument is explicit.', \
+    '    # An explicit argument is only included in the URL if it is in the arguments object.', \
+    '    optional bool explicit', \
+    '', \
+    '    # The default argument value', \
+    '    optional object default', \
+    '', \
+    '    # The argument description', \
+    '    optional string(len > 0) description', \
+    '', \
+    '', \
+    '# An argument value type', \
+    'enum ArgsType', \
+    '    bool', \
+    '    date', \
+    '    datetime', \
+    '    float', \
+    '    int', \
+    '    string' \
+)
+
+
+# $function: argsValidate
+# $group: args.bare
+# $doc: Validate an arguments model
+# $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)
+
+    # Check for duplicate arguments
+    if validatedArguments != null:
+        argNames = {}
+        for argument in arguments:
+            name = objectGet(argument, 'name')
+            if objectHas(argNames, name):
+                validatedArguments = null
+                systemLogDebug('args.bare: Duplicate argument "' + name + '"')
+            else:
+                objectSet(argNames, name, true)
+            endif
+        endfor
+    endif
+
+    return validatedArguments
+endfunction
+
+
+# $function: argsParse
+# $group: args.bare
+# $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](model.html#var.vName='ArgsArguments')
+# $return: The arguments object
+function argsParse(arguments):
+    # Create the arguments object
+    args = {}
+    for argument in arguments:
+        # Get the argument value
+        global = argsGlobalName(argument)
+        value = argsValidateValue(systemGlobalGet(global), objectGet(argument, 'type'), global)
+
+        # Apply the default argument value, if any
+        if value == null:
+            value = objectGet(argument, 'default')
+        endif
+
+        # Set the argument value, if any
+        if value != null:
+            objectSet(args, objectGet(argument, 'name'), value)
+        endif
+    endfor
+
+    return args
+endfunction
+
+
+# $function: argsURL
+# $group: args.bare
+# $doc: Create a MarkdownUp application URL
+# $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.
+# $arg headerText: The special "_top" header ID scrolls to the top of the page.
+# $arg url: Optional (default is null). If non-null, the MarkdownUp URL hash parameter.
+# $return: The MarkdownUp application URL
+function argsURL(arguments, args, explicit, headerText, url):
+    # Get the URL variables
+    urlVars = []
+    argNames = {}
+    for argument in arguments:
+        name = objectGet(argument, 'name')
+        type = objectGet(argument, 'type')
+        global = argsGlobalName(argument)
+        default = objectGet(argument, 'default')
+
+        # Add the argument name (for unknown argument check below)
+        objectSet(argNames, name, null)
+
+        # Add the URL variable, if any
+        value = null
+        if args != null && objectHas(args, name):
+            value = argsValidateValue(objectGet(args, name), type, global)
+        elif !(explicit || objectGet(argument, 'explicit')):
+            value = argsValidateValue(systemGlobalGet(global), type, global, false)
+        endif
+
+        # Add the URL variable
+        if value != null && (default == null || !argsValuesEqual(value, default, type)):
+            arrayPush(urlVars, 'var.' + global + '=' + urlEncodeComponent(argsFormatValue(value, type)))
+        endif
+    endfor
+
+    # Sort the URL variables for general consistency
+    arraySort(urlVars)
+
+    # Check for unknown arguments
+    if args != null:
+        for name in objectKeys(args):
+            if !objectHas(argNames, name):
+                systemLogDebug('args.bare: Unknown argument "' + name + '"')
+            endif
+        endfor
+    endif
+
+    # Create the URL
+    return '#' + if(url != null, 'url=' + urlEncodeComponent(url) + '&', '') + \
+        if(arrayLength(urlVars), arrayJoin(urlVars, '&'), 'var=') + \
+        if(headerText != null, '&' + if(headerText == argsTopHeaderId, argsTopHeaderId, markdownHeaderId(headerText)), '')
+endfunction
+
+
+# The special "top" header ID
+argsTopHeaderId = '_top'
+
+
+# $function: argsLink
+# $group: args.bare
+# $doc: Create a Markdown link text to a MarkdownUp application URL
+# $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.
+# $arg headerText: Optional (default is null). If non-null, the URL's header text.
+# $arg headerText: The special "_top" header ID scrolls to the top of the page.
+# $arg url: Optional (default is null). If non-null, the MarkdownUp URL hash parameter.
+# $return: The Markdown link text
+function argsLink(arguments, text, args, explicit, headerText, url):
+    return '[' + markdownEscape(text) + '](' + argsURL(arguments, args, explicit, headerText, url) + ')'
+endfunction
+
+
+# $function: argsHelp
+# $group: args.bare
+# $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](model.html#var.vName='ArgsArguments')
+# $return: The array of help Markdown line strings
+function argsHelp(arguments):
+    # Create the help data
+    helpData = []
+    anyDefault = false
+    anyExplicit = false
+    anyDescription = false
+    for argument in arguments:
+        type = objectGet(argument, 'type', 'string')
+        default = objectGet(argument, 'default')
+        explicit = objectGet(argument, 'explicit')
+        description = objectGet(argument, 'description')
+
+        # Add the help data row
+        arrayPush(helpData, { \
+            'Variable': argsGlobalName(argument), \
+            'Type': type, \
+            'Default': argsFormatValue(default, type), \
+            'Explicit': if(explicit, 'Yes', ''), \
+            'Description': if(description != null, description, '') \
+        })
+
+        # Update the "any" field bools
+        anyDefault = anyDefault || (default != null)
+        anyExplicit = anyExplicit || explicit
+        anyDescription = anyDescription || (description != null)
+    endfor
+
+    # Render the help table
+    helpFields = ['Variable', 'Type']
+    if anyDefault:
+        arrayPush(helpFields, 'Default')
+    endif
+    if anyExplicit:
+        arrayPush(helpFields, 'Explicit')
+    endif
+    if anyDescription:
+        arrayPush(helpFields, 'Description')
+    endif
+    return dataTableMarkdown(helpData, {'fields': helpFields})
+endfunction
+
+
+# Helper function to compute an argument's global name
+function argsGlobalName(argument):
+    global = objectGet(argument, 'global')
+    if global == null:
+        name = objectGet(argument, 'name')
+        global = 'v' + stringUpper(stringSlice(name, 0, 1)) + stringSlice(name, 1)
+    endif
+    return global
+endfunction
+
+
+# Helper function to format an argument value
+function argsFormatValue(value, type):
+    # No value?
+    if value == null:
+        return ''
+    endif
+
+    # Return the formatted value
+    if type == 'bool':
+        return if(value, 'true', 'false')
+    elif type == 'date':
+        return "'" + datetimeISOFormat(value, true) + "'"
+    elif type == 'datetime':
+        return "'" + datetimeISOFormat(value) + "'"
+    elif type == 'float':
+        return stringNew(value)
+    elif type == 'int':
+        return stringNew(value)
+    endif
+
+    # type == 'string'
+    return "'" + value + "'"
+endfunction
+
+
+# Helper function to validate an argument value's type
+function argsValidateValue(value, type, global, warn):
+    # No value?
+    if value == null:
+        return null
+    endif
+
+    # Validate the value's type
+    valueType = systemType(value)
+    if type == 'bool':
+        if valueType == 'number' && (value == 0 || value == 1):
+            value = !!value
+        elif valueType != 'boolean':
+            if warn != false:
+                systemLogDebug('args.bare: Invalid value ' + jsonStringify(value) + ' for URL argument "' + global + '"')
+            endif
+            value = null
+        endif
+    elif type == 'date':
+        valueOrig = value
+        if valueType == 'string':
+            value = datetimeISOParse(value)
+            valueType = systemType(value)
+        endif
+        if valueType != 'datetime' || datetimeHour(value) != 0 || datetimeMinute(value) != 0 || datetimeSecond(value) != 0:
+            if warn != false:
+                systemLogDebug('args.bare: Invalid value ' + jsonStringify(valueOrig) + ' for URL argument "' + global + '"')
+            endif
+            value = null
+        endif
+    elif type == 'datetime':
+        valueOrig = value
+        if valueType == 'string':
+            value = datetimeISOParse(value)
+            valueType = systemType(value)
+        endif
+        if valueType != 'datetime':
+            if warn != false:
+                systemLogDebug('args.bare: Invalid value ' + jsonStringify(valueOrig) + ' for URL argument "' + global + '"')
+            endif
+            value = null
+        endif
+    elif type == 'float':
+        if valueType != 'number':
+            if warn != false:
+                systemLogDebug('args.bare: Invalid value ' + jsonStringify(value) + ' for URL argument "' + global + '"')
+            endif
+            value = null
+        endif
+    elif type == 'int':
+        if valueType != 'number' || value != mathFloor(value):
+            if warn != false:
+                systemLogDebug('args.bare: Invalid value ' + jsonStringify(value) + ' for URL argument "' + global + '"')
+            endif
+            value = null
+        endif
+    else:
+        # type == 'string'
+        if valueType != 'string':
+            if warn != false:
+                systemLogDebug('args.bare: Invalid value ' + jsonStringify(value) + ' for URL argument "' + global + '"')
+            endif
+            value = null
+        endif
+    endif
+
+    return value
+endfunction
+
+
+# Helper function to determine if two values are equal
+function argsValuesEqual(value, valueOther, type):
+    if type == 'date' || type == 'datetime':
+        return (value - valueOther) == 0
+    endif
+    return value == valueOther
+endfunction

bare_script/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' \
+)