bare-script 5.1.3__tar.gz → 5.1.6__tar.gz

{bare_script-5.1.3/src/bare_script.egg-info → bare_script-5.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bare-script
-Version: 5.1.3
+Version: 5.1.6
 Summary: BareScript; a lightweight scripting and expression language
 Author-email: "Craig A. Hobbs" <craigahobbs@gmail.com>
 License-Expression: MIT
@@ -49,7 +49,6 @@ confident that BareScript will execute the same regardless of the underlying run
 
 - [The BareScript Language](https://craigahobbs.github.io/bare-script-py/language/)
 - [The BareScript Library](https://craigahobbs.github.io/bare-script-py/library/)
-- [The BareScript Include Library Tests](https://craigahobbs.github.io/bare-script/include/test/)
 - [API Documentation](https://craigahobbs.github.io/bare-script-py/)
 - [Source code](https://github.com/craigahobbs/bare-script-py)
 
@@ -96,20 +95,22 @@ This outputs:
 ```
 
 
-### The BareScript Library
+## The BareScript Library
 
 [The BareScript Library](https://craigahobbs.github.io/bare-script-py/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
+documents the built-in functions available to every script and the include libraries loaded with
+the [include statement](https://craigahobbs.github.io/bare-script-py/language/#include-statements).
+Built-in functions cover mathematical operations, object and array manipulation, regular
+expressions, HTTP fetch, and more. Angle-bracket includes (`include <markdown.bare>`) load libraries
+bundled with the runtime. Quoted includes (`include 'util.bare'`) load a local file or URL.
+
+The following example uses the built-in
 [systemFetch](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='system'&systemfetch),
 [objectGet](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='object'&objectget), and
 [arrayLength](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='array'&arraylength)
-functions.
+functions:
 
 ```python
-import urllib.request
-
 from bare_script import barescript_parse_script, execute_script, fetch_http
 
 # Parse the script
@@ -131,44 +132,48 @@ This outputs:
 The BareScript Library has 100 builtin functions
 ```
 
-
-## Evaluating BareScript Expressions
-
-To evaluate a
-[BareScript expression](https://craigahobbs.github.io/bare-script-py/language/#expressions),
-parse the expression using the
-[barescript_parse_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#barescript-parse-expression)
-function. Then evaluate the expression using the
-[evaluate_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#evaluate-expression)
-function.
-
-Expression evaluation includes the
-[BareScript Expression Library](https://craigahobbs.github.io/bare-script-py/library/expression.html),
-a set of built-in, spreadsheet-like functions.
-
-For example:
+Include libraries are loaded before use:
 
 ```python
-from bare_script import barescript_parse_expression, evaluate_expression
+from bare_script import barescript_parse_script, execute_script
 
-# Parse the expression
-expr = barescript_parse_expression('2 * max(a, b, c)')
+# Parse the script
+script = barescript_parse_script('''\
+include <markdownParser.bare>
+include <markdown.bare>
 
-# Evaluate the expression
-variables = {'a': 1, 'b': 2, 'c': 3}
-print(evaluate_expression(expr, None, variables))
+markdown = markdownParse('# Hello, Markdown!')
+return markdownTitle(markdown)
+''')
+
+# Execute the script
+print(execute_script(script))
 ```
 
 This outputs:
 
 ```
-6
+Hello, Markdown!
 ```
 
+Quoted includes and
+[systemFetch](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='system'&systemfetch)
+calls with a non-URL path need a filesystem-aware fetch function. Pass
+[fetch_read_only](https://craigahobbs.github.io/bare-script-py/options.html#bare_script.fetch_read_only)
+or
+[fetch_read_write](https://craigahobbs.github.io/bare-script-py/options.html#bare_script.fetch_read_write):
+
+```python
+from bare_script import barescript_parse_script, execute_script, fetch_read_write
+
+script = barescript_parse_script("include 'util.bare'")
+execute_script(script, {'fetchFn': fetch_read_write})
+```
 
-## The Include Library Stub Functions
 
-BareScript include library functions are callable directly from Python using the native stub functions
+### Stub Functions
+
+Include library functions are also callable directly from Python using the native stub functions
 exported by the
 [include module](https://craigahobbs.github.io/bare-script-py/include.html) — for example,
 [data_aggregate](https://craigahobbs.github.io/bare-script-py/include.html#data-aggregate),
@@ -201,13 +206,54 @@ Hello, Markdown!
 ```
 
 
+## Evaluating BareScript Expressions
+
+To evaluate a
+[BareScript expression](https://craigahobbs.github.io/bare-script-py/language/#expressions),
+parse the expression using the
+[barescript_parse_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#barescript-parse-expression)
+function. Then evaluate the expression using the
+[evaluate_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#evaluate-expression)
+function.
+
+Expression evaluation includes the
+[BareScript Expression Library](https://craigahobbs.github.io/bare-script-py/library/expression.html),
+a set of built-in, spreadsheet-like functions.
+
+For example:
+
+```python
+from bare_script import barescript_parse_expression, evaluate_expression
+
+# Parse the expression
+expr = barescript_parse_expression('2 * max(a, b, c)')
+
+# Evaluate the expression
+variables = {'a': 1, 'b': 2, 'c': 3}
+print(evaluate_expression(expr, None, variables))
+```
+
+This outputs:
+
+```
+6
+```
+
+
 ## 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
+bare script.bare                      # run a script
+bare -c 'systemLog("Hello, World!")'  # execute inline code
+bare -v N 10 script.bare              # set the global N to 10
+bare -d script.bare                   # debug mode
+bare -m app.bare                      # MarkdownUp text output
+bare -l app.bare                      # MarkdownUp HTML output
+bare -s script.bare                   # parse and lint only
+bare -x script.bare                   # lint with execution
 ```
 
 **Note:** In the BareScript CLI, include statements and the
@@ -233,6 +279,11 @@ markdownPrint('Hello, Markdown!')
 ```
 ~~~
 
+To run a MarkdownUp script (`.bare`) from this package, use `bare -m` (Markdown text) or `bare -l`
+(HTML). To view a MarkdownUp document (`.md` with `markdown-script` blocks), install the
+[markdown-up](https://github.com/craigahobbs/markdown-up-py#readme) viewer or open the file in the
+[MarkdownUp web app](https://craigahobbs.github.io/markdown-up/).
+
 
 ## C Runtime
 
@@ -260,21 +311,21 @@ without a native Python equivalent are omitted.
 
 | Test             | Language         | Time (ms) | Multiple |
 | ---------------- | ---------------- | --------: | -------: |
-| mandelbrot       | Python           |    4720.8 |          |
-|                  | BareScript (PyC) |   10800.0 |     2.3x |
-|                  | BareScript (Py)  |  334100.0 |    70.8x |
-| schemaValidate   | Python           |      21.0 |          |
-|                  | BareScript (PyC) |     101.6 |     4.8x |
-|                  | BareScript (Py)  |    1404.8 |    67.0x |
+| mandelbrot       | Python           |    4630.9 |          |
+|                  | BareScript (PyC) |   10900.0 |     2.4x |
+|                  | BareScript (Py)  |  341300.0 |    73.7x |
+| schemaValidate   | Python           |      20.7 |          |
+|                  | BareScript (PyC) |     105.6 |     5.1x |
+|                  | BareScript (Py)  |    1433.2 |    69.2x |
 | urlEncode        | Python           |       1.1 |          |
-|                  | BareScript (PyC) |       5.6 |     5.3x |
-|                  | BareScript (Py)  |      39.1 |    37.1x |
-| schemaParse      | Python           |      17.1 |          |
-|                  | BareScript (PyC) |     120.4 |     7.1x |
-|                  | BareScript (Py)  |     882.4 |    51.7x |
+|                  | BareScript (PyC) |       5.7 |     5.4x |
+|                  | BareScript (Py)  |      39.6 |    37.5x |
+| schemaParse      | Python           |      17.2 |          |
+|                  | BareScript (PyC) |     123.6 |     7.2x |
+|                  | BareScript (Py)  |     904.8 |    52.7x |
 | urlDecode        | Python           |       1.2 |          |
-|                  | BareScript (PyC) |      13.1 |    10.8x |
-|                  | BareScript (Py)  |      68.5 |    56.6x |
+|                  | BareScript (PyC) |      13.2 |    11.2x |
+|                  | BareScript (Py)  |      68.8 |    58.3x |
 
 
 ## Using BareScript with an AI Assistant
@@ -283,7 +334,8 @@ This repository ships a
 [`SKILL.md`](https://github.com/craigahobbs/bare-script-py/blob/main/SKILL.md)
 file that teaches an AI coding assistant how to write idiomatic BareScript — language syntax, the
 built-in and include libraries, the MarkdownUp application pattern, and the unit-test conventions.
-It is plain Markdown and applies to either BareScript implementation.
+It is plain Markdown and applies to either BareScript implementation. Assistants that discover
+`SKILL.md` at the repository root can use it without copying.
 
 For [Claude Code](https://claude.com/claude-code) and other tools that follow the
 [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
@@ -304,7 +356,7 @@ claude "Build a MarkdownUp application that plays tic-tac-toe against the user,
 ```
 
 To run the resulting MarkdownUp application locally, install the
-[markdown-up](https://pypi.org/project/markdown-up/) viewer and point it at the Markdown file:
+[markdown-up](https://github.com/craigahobbs/markdown-up-py#readme) viewer and point it at the Markdown file:
 
 ```
 pip install markdown-up

{bare_script-5.1.3 → bare_script-5.1.6}/README.md

@@ -23,7 +23,6 @@ confident that BareScript will execute the same regardless of the underlying run
 
 - [The BareScript Language](https://craigahobbs.github.io/bare-script-py/language/)
 - [The BareScript Library](https://craigahobbs.github.io/bare-script-py/library/)
-- [The BareScript Include Library Tests](https://craigahobbs.github.io/bare-script/include/test/)
 - [API Documentation](https://craigahobbs.github.io/bare-script-py/)
 - [Source code](https://github.com/craigahobbs/bare-script-py)
 
@@ -70,20 +69,22 @@ This outputs:
 ```
 
 
-### The BareScript Library
+## The BareScript Library
 
 [The BareScript Library](https://craigahobbs.github.io/bare-script-py/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
+documents the built-in functions available to every script and the include libraries loaded with
+the [include statement](https://craigahobbs.github.io/bare-script-py/language/#include-statements).
+Built-in functions cover mathematical operations, object and array manipulation, regular
+expressions, HTTP fetch, and more. Angle-bracket includes (`include <markdown.bare>`) load libraries
+bundled with the runtime. Quoted includes (`include 'util.bare'`) load a local file or URL.
+
+The following example uses the built-in
 [systemFetch](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='system'&systemfetch),
 [objectGet](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='object'&objectget), and
 [arrayLength](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='array'&arraylength)
-functions.
+functions:
 
 ```python
-import urllib.request
-
 from bare_script import barescript_parse_script, execute_script, fetch_http
 
 # Parse the script
@@ -105,44 +106,48 @@ This outputs:
 The BareScript Library has 100 builtin functions
 ```
 
-
-## Evaluating BareScript Expressions
-
-To evaluate a
-[BareScript expression](https://craigahobbs.github.io/bare-script-py/language/#expressions),
-parse the expression using the
-[barescript_parse_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#barescript-parse-expression)
-function. Then evaluate the expression using the
-[evaluate_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#evaluate-expression)
-function.
-
-Expression evaluation includes the
-[BareScript Expression Library](https://craigahobbs.github.io/bare-script-py/library/expression.html),
-a set of built-in, spreadsheet-like functions.
-
-For example:
+Include libraries are loaded before use:
 
 ```python
-from bare_script import barescript_parse_expression, evaluate_expression
+from bare_script import barescript_parse_script, execute_script
 
-# Parse the expression
-expr = barescript_parse_expression('2 * max(a, b, c)')
+# Parse the script
+script = barescript_parse_script('''\
+include <markdownParser.bare>
+include <markdown.bare>
 
-# Evaluate the expression
-variables = {'a': 1, 'b': 2, 'c': 3}
-print(evaluate_expression(expr, None, variables))
+markdown = markdownParse('# Hello, Markdown!')
+return markdownTitle(markdown)
+''')
+
+# Execute the script
+print(execute_script(script))
 ```
 
 This outputs:
 
 ```
-6
+Hello, Markdown!
 ```
 
+Quoted includes and
+[systemFetch](https://craigahobbs.github.io/bare-script-py/library/#var.vGroup='system'&systemfetch)
+calls with a non-URL path need a filesystem-aware fetch function. Pass
+[fetch_read_only](https://craigahobbs.github.io/bare-script-py/options.html#bare_script.fetch_read_only)
+or
+[fetch_read_write](https://craigahobbs.github.io/bare-script-py/options.html#bare_script.fetch_read_write):
+
+```python
+from bare_script import barescript_parse_script, execute_script, fetch_read_write
+
+script = barescript_parse_script("include 'util.bare'")
+execute_script(script, {'fetchFn': fetch_read_write})
+```
 
-## The Include Library Stub Functions
 
-BareScript include library functions are callable directly from Python using the native stub functions
+### Stub Functions
+
+Include library functions are also callable directly from Python using the native stub functions
 exported by the
 [include module](https://craigahobbs.github.io/bare-script-py/include.html) — for example,
 [data_aggregate](https://craigahobbs.github.io/bare-script-py/include.html#data-aggregate),
@@ -175,13 +180,54 @@ Hello, Markdown!
 ```
 
 
+## Evaluating BareScript Expressions
+
+To evaluate a
+[BareScript expression](https://craigahobbs.github.io/bare-script-py/language/#expressions),
+parse the expression using the
+[barescript_parse_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#barescript-parse-expression)
+function. Then evaluate the expression using the
+[evaluate_expression](https://craigahobbs.github.io/bare-script-py/expressions.html#evaluate-expression)
+function.
+
+Expression evaluation includes the
+[BareScript Expression Library](https://craigahobbs.github.io/bare-script-py/library/expression.html),
+a set of built-in, spreadsheet-like functions.
+
+For example:
+
+```python
+from bare_script import barescript_parse_expression, evaluate_expression
+
+# Parse the expression
+expr = barescript_parse_expression('2 * max(a, b, c)')
+
+# Evaluate the expression
+variables = {'a': 1, 'b': 2, 'c': 3}
+print(evaluate_expression(expr, None, variables))
+```
+
+This outputs:
+
+```
+6
+```
+
+
 ## 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
+bare script.bare                      # run a script
+bare -c 'systemLog("Hello, World!")'  # execute inline code
+bare -v N 10 script.bare              # set the global N to 10
+bare -d script.bare                   # debug mode
+bare -m app.bare                      # MarkdownUp text output
+bare -l app.bare                      # MarkdownUp HTML output
+bare -s script.bare                   # parse and lint only
+bare -x script.bare                   # lint with execution
 ```
 
 **Note:** In the BareScript CLI, include statements and the
@@ -207,6 +253,11 @@ markdownPrint('Hello, Markdown!')
 ```
 ~~~
 
+To run a MarkdownUp script (`.bare`) from this package, use `bare -m` (Markdown text) or `bare -l`
+(HTML). To view a MarkdownUp document (`.md` with `markdown-script` blocks), install the
+[markdown-up](https://github.com/craigahobbs/markdown-up-py#readme) viewer or open the file in the
+[MarkdownUp web app](https://craigahobbs.github.io/markdown-up/).
+
 
 ## C Runtime
 
@@ -234,21 +285,21 @@ without a native Python equivalent are omitted.
 
 | Test             | Language         | Time (ms) | Multiple |
 | ---------------- | ---------------- | --------: | -------: |
-| mandelbrot       | Python           |    4720.8 |          |
-|                  | BareScript (PyC) |   10800.0 |     2.3x |
-|                  | BareScript (Py)  |  334100.0 |    70.8x |
-| schemaValidate   | Python           |      21.0 |          |
-|                  | BareScript (PyC) |     101.6 |     4.8x |
-|                  | BareScript (Py)  |    1404.8 |    67.0x |
+| mandelbrot       | Python           |    4630.9 |          |
+|                  | BareScript (PyC) |   10900.0 |     2.4x |
+|                  | BareScript (Py)  |  341300.0 |    73.7x |
+| schemaValidate   | Python           |      20.7 |          |
+|                  | BareScript (PyC) |     105.6 |     5.1x |
+|                  | BareScript (Py)  |    1433.2 |    69.2x |
 | urlEncode        | Python           |       1.1 |          |
-|                  | BareScript (PyC) |       5.6 |     5.3x |
-|                  | BareScript (Py)  |      39.1 |    37.1x |
-| schemaParse      | Python           |      17.1 |          |
-|                  | BareScript (PyC) |     120.4 |     7.1x |
-|                  | BareScript (Py)  |     882.4 |    51.7x |
+|                  | BareScript (PyC) |       5.7 |     5.4x |
+|                  | BareScript (Py)  |      39.6 |    37.5x |
+| schemaParse      | Python           |      17.2 |          |
+|                  | BareScript (PyC) |     123.6 |     7.2x |
+|                  | BareScript (Py)  |     904.8 |    52.7x |
 | urlDecode        | Python           |       1.2 |          |
-|                  | BareScript (PyC) |      13.1 |    10.8x |
-|                  | BareScript (Py)  |      68.5 |    56.6x |
+|                  | BareScript (PyC) |      13.2 |    11.2x |
+|                  | BareScript (Py)  |      68.8 |    58.3x |
 
 
 ## Using BareScript with an AI Assistant
@@ -257,7 +308,8 @@ This repository ships a
 [`SKILL.md`](https://github.com/craigahobbs/bare-script-py/blob/main/SKILL.md)
 file that teaches an AI coding assistant how to write idiomatic BareScript — language syntax, the
 built-in and include libraries, the MarkdownUp application pattern, and the unit-test conventions.
-It is plain Markdown and applies to either BareScript implementation.
+It is plain Markdown and applies to either BareScript implementation. Assistants that discover
+`SKILL.md` at the repository root can use it without copying.
 
 For [Claude Code](https://claude.com/claude-code) and other tools that follow the
 [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
@@ -278,7 +330,7 @@ claude "Build a MarkdownUp application that plays tic-tac-toe against the user,
 ```
 
 To run the resulting MarkdownUp application locally, install the
-[markdown-up](https://pypi.org/project/markdown-up/) viewer and point it at the Markdown file:
+[markdown-up](https://github.com/craigahobbs/markdown-up-py#readme) viewer and point it at the Markdown file:
 
 ```
 pip install markdown-up

{bare_script-5.1.3 → bare_script-5.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bare-script"
-version = "5.1.3"
+version = "5.1.6"
 description = "BareScript; a lightweight scripting and expression language"
 readme = "README.md"
 license = "MIT"

{bare_script-5.1.3 → bare_script-5.1.6}/src/bare_script/include.py

@@ -30,6 +30,7 @@ execute_script(
                 {'url': 'markdown.bare', 'system': True},
                 {'url': 'markdownElements.bare', 'system': True},
                 {'url': 'markdownParser.bare', 'system': True},
+                {'url': 'markdownString.bare', 'system': True},
                 {'url': 'qrcode.bare', 'system': True},
                 {'url': 'schema.bare', 'system': True},
                 {'url': 'schemaDoc.bare', 'system': True},
@@ -499,6 +500,28 @@ def markdown_parse(text):
     return _INCLUDE_GLOBALS['markdownParse']([text], _include_options())
 
 
+#
+# markdownString.bare
+#
+
+
+def markdown_to_string(markdown, wrap_width=None, ref_count=None):
+    """
+    Render a Markdown model as Markdown text
+
+    :param dict markdown: The Markdown model
+    :param wrap_width: The text wrap width (default is 100). If zero or less, text is not wrapped.
+    :type wrap_width: int or None, optional
+    :param ref_count: The minimum number of occurrences of a link/image URL for which a link/image
+        reference is rendered (default is 0). If zero or less, all links/images are rendered inline.
+    :type ref_count: int or None, optional
+    :return: The Markdown text
+    :rtype: str
+    """
+
+    return _INCLUDE_GLOBALS['markdownToString']([markdown, wrap_width, ref_count], _include_options())
+
+
 #
 # qrcode.bare
 #