bare-script 4.2.5__tar.gz → 4.2.7__tar.gz

{bare_script-4.2.5/src/bare_script.egg-info → bare_script-4.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bare-script
-Version: 4.2.5
+Version: 4.2.7
 Summary: bare-script
 Home-page: https://github.com/craigahobbs/bare-script
 Author: Craig A. Hobbs
@@ -104,11 +104,11 @@ from bare_script import execute_script, fetch_http, parse_script
 
 # Parse the script
 script = parse_script('''\
-# Fetch the BareScript library documentation JSON
-docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script-py/library/library.json'))
+# Fetch the BareScript builtin library documentation JSON
+docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script-py/library/library-builtin.json'))
 
-# Return the number of library functions
-return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' functions'
+# Return the number of builtin functions
+return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' builtin functions'
 ''')
 
 # Execute the script
@@ -118,7 +118,7 @@ print(execute_script(script, {'fetchFn': fetch_http}))
 This outputs:
 
 ```
-The BareScript Library has 209 functions
+The BareScript Library has 108 builtin functions
 ```
 
 
@@ -193,10 +193,30 @@ markdownPrint('Hello, Markdown!')
 
 ## C Runtime
 
-The package ships with an optional CPython C extension (`runtime_c`) that mirrors the pure-Python
-runtime for faster script execution. When the compiled extension is available, it is used
-automatically; otherwise the pure-Python runtime is used as a fallback. Set the environment
-variable `BARESCRIPT_RUNTIME_PY=1` to force the pure-Python runtime.
+The package ships with an optional CPython C extension, `runtime_c`, that mirrors the pure-Python
+runtime for faster script execution. The compiled extension is used automatically when available;
+set the environment variable `BARESCRIPT_RUNTIME_PY=1` to force the pure-Python runtime.
+
+The extension supports CPython 3.10 and later on both the default (GIL) and free-threaded Python
+builds.
+
+The C runtime runs the BareScript include library test suite (`make test-include`) about 3.6x
+faster than the pure-Python runtime (CPython 3.14, Apple M-series):
+
+| Runtime             | Test Suite Time (ms) | Multiple |
+| ------------------- | -------------------: | -------: |
+| BareScript (C)      |                  586 |     1.0x |
+| BareScript (Python) |                 2115 |     3.6x |
+
+Compute-intensive scripts run up to roughly 30x faster - for example, the
+[Mandelbrot benchmark](https://github.com/craigahobbs/bare-script-py/blob/main/perf/test.bare)
+(`make perf`), shown here against the equivalent native Python program:
+
+| Language            | Best Time (ms) | Multiple |
+| ------------------- | -------------: | -------: |
+| Python              |            152 |     1.0x |
+| BareScript (C)      |            322 |     2.1x |
+| BareScript (Python) |          10389 |    68.5x |
 
 
 ## Using BareScript with an AI Assistant

{bare_script-4.2.5 → bare_script-4.2.7}/README.md

@@ -79,11 +79,11 @@ from bare_script import execute_script, fetch_http, parse_script
 
 # Parse the script
 script = parse_script('''\
-# Fetch the BareScript library documentation JSON
-docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script-py/library/library.json'))
+# Fetch the BareScript builtin library documentation JSON
+docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script-py/library/library-builtin.json'))
 
-# Return the number of library functions
-return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' functions'
+# Return the number of builtin functions
+return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' builtin functions'
 ''')
 
 # Execute the script
@@ -93,7 +93,7 @@ print(execute_script(script, {'fetchFn': fetch_http}))
 This outputs:
 
 ```
-The BareScript Library has 209 functions
+The BareScript Library has 108 builtin functions
 ```
 
 
@@ -168,10 +168,30 @@ markdownPrint('Hello, Markdown!')
 
 ## C Runtime
 
-The package ships with an optional CPython C extension (`runtime_c`) that mirrors the pure-Python
-runtime for faster script execution. When the compiled extension is available, it is used
-automatically; otherwise the pure-Python runtime is used as a fallback. Set the environment
-variable `BARESCRIPT_RUNTIME_PY=1` to force the pure-Python runtime.
+The package ships with an optional CPython C extension, `runtime_c`, that mirrors the pure-Python
+runtime for faster script execution. The compiled extension is used automatically when available;
+set the environment variable `BARESCRIPT_RUNTIME_PY=1` to force the pure-Python runtime.
+
+The extension supports CPython 3.10 and later on both the default (GIL) and free-threaded Python
+builds.
+
+The C runtime runs the BareScript include library test suite (`make test-include`) about 3.6x
+faster than the pure-Python runtime (CPython 3.14, Apple M-series):
+
+| Runtime             | Test Suite Time (ms) | Multiple |
+| ------------------- | -------------------: | -------: |
+| BareScript (C)      |                  586 |     1.0x |
+| BareScript (Python) |                 2115 |     3.6x |
+
+Compute-intensive scripts run up to roughly 30x faster - for example, the
+[Mandelbrot benchmark](https://github.com/craigahobbs/bare-script-py/blob/main/perf/test.bare)
+(`make perf`), shown here against the equivalent native Python program:
+
+| Language            | Best Time (ms) | Multiple |
+| ------------------- | -------------: | -------: |
+| Python              |            152 |     1.0x |
+| BareScript (C)      |            322 |     2.1x |
+| BareScript (Python) |          10389 |    68.5x |
 
 
 ## Using BareScript with an AI Assistant

{bare_script-4.2.5 → bare_script-4.2.7}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = bare-script
-version = 4.2.5
+version = 4.2.7
 url = https://github.com/craigahobbs/bare-script
 author = Craig A. Hobbs
 author_email = craigahobbs@gmail.com

bare_script-4.2.7/src/bare_script/include/baredoc.bare

@@ -0,0 +1,383 @@
+# Licensed under the MIT License
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+include <args.bare>
+include <markdown.bare>
+include <dataUtil.bare>
+include <dataTable.bare>
+include <schemaDoc.bare>
+
+
+# $function: baredocMain
+# $group: baredoc.bare
+# $doc: The BareScript library documentation application main entry point
+# $arg config: The [documentation configuration](model.html#var.vName='BaredocConfig') object or its JSON resource URL
+async function baredocMain(config):
+    # Parse arguments
+    args = argsParse(baredocArguments)
+    group = objectGet(args, 'group')
+    name = objectGet(args, 'name')
+    single = objectGet(args, 'single')
+
+    # Render the documentation model page?
+    if objectGet(args, 'doc'):
+        documentSetTitle('Library')
+        markdownPrint(schemaDocMarkdown(baredocTypes, 'BaredocLibrary'))
+        return
+    endif
+
+    # Resolve and validate the configuration
+    if systemType(config) == 'string':
+        config = jsonParse(systemFetch(config))
+    endif
+    config = schemaValidate(baredocTypes, 'BaredocConfig', config)
+    if config == null:
+        markdownPrint('**Error:** Invalid baredoc configuration')
+        return
+    endif
+    sections = objectGet(config, 'sections')
+
+    # Fetch and validate the section library documentation resources
+    sectionURLs = []
+    for section in sections:
+        arrayPush(sectionURLs, objectGet(section, 'url'))
+    endfor
+    sectionJSONs = systemFetch(sectionURLs)
+
+    # Group each section's functions by name, with the config content and description
+    groups = {}
+    sectionGroups = []
+    for section, ixSection in sections:
+        sectionJSON = arrayGet(sectionJSONs, ixSection)
+        libraryPart = if(sectionJSON != null, jsonParse(sectionJSON))
+        libraryPart = if(libraryPart != null, schemaValidate(baredocTypes, 'BaredocLibrary', libraryPart))
+        if libraryPart == null:
+            markdownPrint( \
+                '**Error:** Failed to fetch library documentation resource "' + \
+                markdownEscape(objectGet(section, 'url')) + '"' \
+            )
+            return
+        endif
+
+        # Group the section's functions
+        sectionGroupSet = {}
+        for function_ in objectGet(libraryPart, 'functions'):
+            groupName = objectGet(function_, 'group')
+            groupEntry = objectGet(groups, groupName)
+            if groupEntry == null:
+                groupEntry = {'functions': []}
+                objectSet(groups, groupName, groupEntry)
+            endif
+            arrayPush(objectGet(groupEntry, 'functions'), function_)
+            objectSet(sectionGroupSet, groupName, true)
+        endfor
+        arrayPush(sectionGroups, {'title': objectGet(section, 'title'), 'groupNames': arraySort(objectKeys(sectionGroupSet))})
+
+        # Attach the section's group content and description from the config
+        for group_ in objectGet(section, 'groups', []):
+            groupEntry = objectGet(groups, objectGet(group_, 'name'))
+            if groupEntry != null:
+                objectSet(groupEntry, 'content', objectGet(group_, 'content'))
+                objectSet(groupEntry, 'description', objectGet(group_, 'description'))
+            endif
+        endfor
+    endfor
+
+    # Sort each group's functions by name
+    for groupName in objectKeys(groups):
+        arraySort(objectGet(objectGet(groups, groupName), 'functions'), baredocFunctionCompare)
+    endfor
+
+    # Function requested by name? Redirect to its group page anchor
+    if name != null:
+        for groupName in objectKeys(groups):
+            for function_ in objectGet(objectGet(groups, groupName), 'functions'):
+                if objectGet(function_, 'name') == name:
+                    windowSetLocation(argsURL(baredocArguments, {'group': groupName, 'name': null}, false, name))
+                    return
+                endif
+            endfor
+        endfor
+        markdownPrint('', '**Error:** Unknown function "' + markdownEscape(name) + '"')
+        return
+    endif
+
+    # Render the requested page
+    if group != null:
+        baredocGroupPage(config, args, groups, group)
+    elif single:
+        baredocSinglePage(config, args, sectionGroups, groups)
+    else:
+        baredocIndexPage(config, args, sectionGroups, 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} \
+])
+
+
+# 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
+
+
+# Helper to render the title and top-level content
+async function baredocPageHeader(config):
+    title = objectGet(config, 'title')
+    documentSetTitle(title)
+    markdownPrint('# ' + markdownEscape(title))
+    topContent = objectGet(config, 'content')
+    if topContent != null:
+        topText = systemFetch(topContent)
+        markdownPrint('', if(topText != null, topText, '**Error:** Failed to load "' + markdownEscape(topContent) + '"'))
+    endif
+endfunction
+
+
+# Render the section group index tables (single uses in-page anchors, multi-page uses group pages)
+function baredocGroupTable(sectionGroups, groups, single):
+    for section in sectionGroups:
+        markdownPrint('', '## ' + markdownEscape(objectGet(section, 'title')), '')
+        markdownPrint('|  |  |', '| --- | --- |')
+        for groupName in objectGet(section, 'groupNames'):
+            groupLink = if(single, \
+                argsLink(baredocArguments, groupName, null, false, groupName), \
+                argsLink(baredocArguments, groupName, {'group': groupName}, false, argsTopHeaderId))
+            description = objectGet(objectGet(groups, groupName), 'description')
+            markdownPrint('| ' + groupLink + ' | ' + if(description != null, description, '') + ' |')
+        endfor
+    endfor
+endfunction
+
+
+# Render a library documentation index page
+async function baredocIndexPage(config, args, sectionGroups, groups):
+    # Render the title and top-level content
+    baredocPageHeader(config)
+
+    # Render the single page toggle
+    if !objectGet(args, 'publish'):
+        markdownPrint('', argsLink(baredocArguments, 'Single Page', {'single': true}))
+    endif
+
+    # Render the section group index tables
+    baredocGroupTable(sectionGroups, groups, false)
+endfunction
+
+
+# Render the single-page library documentation
+async function baredocSinglePage(config, args, sectionGroups, groups):
+    # Render the title and top-level content
+    baredocPageHeader(config)
+
+    # Render the multi page toggle
+    if !objectGet(args, 'publish'):
+        markdownPrint('', argsLink(baredocArguments, 'Multi Page', {'single': false}))
+    endif
+
+    # Render the section group index tables
+    baredocGroupTable(sectionGroups, groups, true)
+
+    # Batch-fetch all group content, keyed by group name
+    contentNames = []
+    urls = []
+    for groupName in objectKeys(groups):
+        url = objectGet(objectGet(groups, groupName), 'content')
+        if url != null:
+            arrayPush(contentNames, groupName)
+            arrayPush(urls, url)
+        endif
+    endfor
+    texts = systemFetch(urls)
+    groupContent = {}
+    for groupName, ixName in contentNames:
+        text = arrayGet(texts, ixName)
+        objectSet(groupContent, groupName, if(text != null, text, '**Error:** Failed to load "' + markdownEscape(arrayGet(urls, ixName)) + '"'))
+    endfor
+
+    # Render each group, separated by a horizontal rule
+    for section in sectionGroups:
+        for groupName in objectGet(section, 'groupNames'):
+            markdownPrint('', '---', '')
+            baredocGroup(args, objectGet(groupContent, groupName), groups, groupName, '##')
+        endfor
+    endfor
+endfunction
+
+
+# Render a library documentation group page
+async function baredocGroupPage(config, args, groups, groupName):
+    title = objectGet(config, 'title')
+
+    # Set the document title
+    documentSetTitle(title + ' - ' + groupName)
+
+    # Group exist?
+    if !objectHas(groups, groupName):
+        markdownPrint('', '**Error:** Unknown group "' + markdownEscape(groupName) + '"')
+        return
+    endif
+
+    # Fetch the group content
+    url = objectGet(objectGet(groups, groupName), 'content')
+    groupContent = null
+    if url != null:
+        text = systemFetch(url)
+        groupContent = if(text != null, text, '**Error:** Failed to load "' + markdownEscape(url) + '"')
+    endif
+
+    # Render the index link and the group
+    markdownPrint(argsLink(baredocArguments, 'Index', {'group': null}), '')
+    baredocGroup(args, groupContent, groups, groupName, '#')
+endfunction
+
+
+# Render a documentation group's content, function index, and function documentation
+function baredocGroup(args, groupContent, groups, groupName, baseHeader):
+    publish = objectGet(args, 'publish')
+    single = objectGet(args, 'single')
+    groupEntry = objectGet(groups, groupName)
+
+    # Render the group header
+    markdownPrint(baseHeader + ' ' + markdownEscape(groupName))
+    if single && !publish:
+        markdownPrint('', argsLink(baredocArguments, 'Back to top', null, false, argsTopHeaderId))
+    endif
+
+    # Render the group content (the fetched content or load error, else the description)
+    content = if(groupContent != null, groupContent, objectGet(groupEntry, 'description'))
+    if content != null:
+        markdownPrint('', content)
+    endif
+
+    # Render the group function index
+    groupFunctions = objectGet(groupEntry, 'functions')
+    markdownPrint('', baseHeader + '# Function Index', '')
+    for function_ 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( \
+    'group "baredoc.bare"', \
+    '', \
+    '', \
+    '# The baredoc documentation application configuration', \
+    'struct BaredocConfig', \
+    '', \
+    '    # The documentation title', \
+    '    string title', \
+    '', \
+    '    # The optional top-level Markdown content resource URL', \
+    '    optional string content', \
+    '', \
+    '    # The documentation sections', \
+    '    BaredocSection[] sections', \
+    '', \
+    '', \
+    '# A documentation section', \
+    'struct BaredocSection', \
+    '', \
+    '    # The section title', \
+    '    string title', \
+    '', \
+    "    # The section's library documentation JSON resource URL", \
+    '    string url', \
+    '', \
+    '    # Optional content and descriptions for the groups (groups are defined by the library functions)', \
+    '    optional BaredocGroup[] groups', \
+    '', \
+    '', \
+    "# A library function group's content and description (the group is defined by the library functions)", \
+    'struct BaredocGroup', \
+    '', \
+    '    # The group name (matches a library function group)', \
+    '    string name', \
+    '', \
+    '    # The optional group Markdown content resource URL (defaults to the description)', \
+    '    optional string content', \
+    '', \
+    '    # The optional brief group description Markdown for the index page', \
+    '    optional string description', \
+    '', \
+    '', \
+    '# A library documentation model', \
+    'struct BaredocLibrary', \
+    '', \
+    '    # The library functions', \
+    '    BaredocFunction[] functions', \
+    '', \
+    '', \
+    '# A library function', \
+    'struct BaredocFunction', \
+    '', \
+    '    # The function name', \
+    '    string name', \
+    '', \
+    '    # The function group (e.g. "Math")', \
+    '    string group', \
+    '', \
+    "    # The function's documentation Markdown lines", \
+    '    string[] doc', \
+    '', \
+    '    # The function arguments', \
+    '    optional BaredocFunctionArgument[] args', \
+    '', \
+    "    # The function return's documentation Markdown lines", \
+    '    optional string[] return', \
+    '', \
+    '    # If true, ignore the function', \
+    '    optional bool ignore', \
+    '', \
+    '', \
+    '# A function argument', \
+    'struct BaredocFunctionArgument', \
+    '', \
+    '    # The argument name', \
+    '    string name', \
+    '', \
+    "    # The argument's documentation Markdown lines", \
+    '    string[] doc' \
+)