bare-script
BareScript is a simple, lightweight, and portable programming language. Its Pythonic syntax is influenced by JavaScript, C, and the Unix Shell. BareScript also has a library of built-in functions for common programming operations. BareScript can be embedded within applications or used as a stand-alone programming language using the command-line interface.
There are two implementations of BareScript: BareScript for Python (this package) and BareScript for JavaScript. Both implementations have 100% unit test coverage with identical unit test suites, so you can be confident that BareScript will execute the same regardless of the underlying runtime environment.
Links
Installation
Install the bare-script package with pip — it includes the bare command-line interface:
pip install bare-script
Executing BareScript Scripts
To execute a BareScript script, parse the script using the barescript_parse_script function. Then execute the script using the execute_script function. For example:
from bare_script import barescript_parse_script, execute_script
# Parse the script
script = barescript_parse_script('''\
# Double a number
function double(n):
return n * 2
endfunction
return N + ' times 2 is ' + double(N)
''')
# Execute the script
globals = {'N': 10}
print(execute_script(script, {'globals': globals}))
This outputs:
10 times 2 is 20
The BareScript Library
The BareScript Library
documents the built-in functions available to every script and the include libraries loaded with
the include statement.
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, objectGet, and arrayLength functions:
from bare_script import barescript_parse_script, execute_script, fetch_http
# Parse the script
script = barescript_parse_script('''\
# 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 builtin functions
return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' builtin functions'
''')
# Execute the script
print(execute_script(script, {'fetchFn': fetch_http}))
This outputs:
The BareScript Library has 100 builtin functions
Include libraries are loaded before use:
from bare_script import barescript_parse_script, execute_script
# Parse the script
script = barescript_parse_script('''\
include <markdownParser.bare>
include <markdown.bare>
markdown = markdownParse('# Hello, Markdown!')
return markdownTitle(markdown)
''')
# Execute the script
print(execute_script(script))
This outputs:
Hello, Markdown!
Quoted includes and systemFetch calls with a non-URL path need a filesystem-aware fetch function. Pass fetch_read_only or fetch_read_write:
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})
Stub Functions
Include library functions are also callable directly from Python using the native stub functions exported by the include module — for example, data_aggregate, markdown_parse, qrcode_matrix, schema_parse, schema_validate, and url_encode. Each stub function executes its corresponding include library function using the BareScript runtime. For example:
from bare_script.include import markdown_parse, markdown_title
# Parse the Markdown text
markdown = markdown_parse('''\
# Hello, Markdown!
This is some text.
''')
# Print the Markdown title
print(markdown_title(markdown))
This outputs:
Hello, Markdown!
Evaluating BareScript Expressions
To evaluate a BareScript expression, parse the expression using the barescript_parse_expression function. Then evaluate the expression using the evaluate_expression function.
Expression evaluation includes the BareScript Expression Library, a set of built-in, spreadsheet-like functions.
For example:
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 # 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 systemFetch function read non-URL paths from the local file system. systemFetch calls with a non-URL path and a request body write the body to the path.
MarkdownUp, a Markdown Viewer with BareScript
MarkdownUp 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
This is a Markdown document with embedded BareScript:
```markdown-script
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 viewer or open the file in the
MarkdownUp web app.
C 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. See the Performance section below for benchmark results comparing the C runtime, the pure-Python runtime, and native Python.
Thread Safety
Both runtimes may be used from multiple threads, including on the free-threaded (no-GIL) Python
builds. Script models and a globals dict may be shared across threads once populated - for example,
execute a script that defines functions once, then call those functions concurrently. Each
concurrently executing thread must pass its own options dict to execute_script, since the runtime
records the running statementCount there. The parser, linter, and include library stubs initialize
lazily and are safe to call from any thread. As in Python, unsynchronized concurrent mutation of a
shared array or object from several threads has unspecified results but never crashes the runtime.
Performance
The make perf target benchmarks the BareScript runtime with a suite of compute-intensive tests —
Mandelbrot set computation, Markdown parsing and rendering, QR code generation, Schema Markdown
parsing and validation, and URL encoding and decoding — and compares each test with an equivalent
native Python program (using the
schema-markdown package).
The following results are from make perf PERF_MERGE= (CPython 3.14, Apple M-series). "BareScript
(PyC)" is the C runtime; "BareScript (Py)" is the pure-Python runtime. Times are the best per-run
timing in milliseconds per 100 runs. Multiples are relative to the native Python time. Tests
without a native Python equivalent are omitted.
| Test | Language | Time (ms) | Multiple |
|---|---|---|---|
| mandelbrot | Python | 4588.0 | |
| BareScript (PyC) | 11100.0 | 2.4x | |
| BareScript (Py) | 340300.0 | 74.2x | |
| schemaParse | Python | 17.2 | |
| BareScript (PyC) | 110.0 | 6.4x | |
| BareScript (Py) | 878.4 | 51.1x | |
| schemaValidate | Python | 20.4 | |
| BareScript (PyC) | 103.6 | 5.1x | |
| BareScript (Py) | 1421.2 | 69.6x | |
| urlDecode | Python | 1.2 | |
| BareScript (PyC) | 11.1 | 9.3x | |
| BareScript (Py) | 66.0 | 55.5x | |
| urlEncode | Python | 1.1 | |
| BareScript (PyC) | 5.2 | 4.9x | |
| BareScript (Py) | 37.4 | 35.5x |
Using BareScript with an AI Assistant
This repository ships a
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. Assistants that discover
SKILL.md at the repository root can use it without copying.
For Claude Code and other tools that follow the Agent Skills convention, install it as a project or user skill:
mkdir -p .claude/skills/bare-script
cp SKILL.md .claude/skills/bare-script/SKILL.md
Use ~/.claude/skills/bare-script/SKILL.md instead to make it available across all projects. For
other assistants, include the file's contents in your system prompt or rules file.
Once installed, prompt the assistant with a task like:
claude "Build a MarkdownUp application that plays tic-tac-toe against the user, with a reset button and a running win/loss/draw tally rendered as a bar chart. Save it as ticTacToe.md"
To run the resulting MarkdownUp application locally, install the markdown-up viewer and point it at the Markdown file:
pip install markdown-up
markdown-up ticTacToe.md
The BareScript documentation is also published as plain Markdown, which can be fetched directly
into an assistant's context alongside SKILL.md:
- The BareScript Language
- The BareScript Library
- The BareScript Library Models
- The BareScript Expression Library
- The BareScript Runtime Model
SKILL.md itself is published at https://craigahobbs.github.io/bare-script-py/SKILL.md, and
https://craigahobbs.github.io/bare-script-py/llms.txt indexes all of the fetchable documentation.
Development
This package is developed using python-build. It was started using python-template as follows:
template-specialize python-template/template/ bare-script-py/ -k package bare-script -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs'
1 maintainer
Metadata
1 maintainer
Release files for bare-script 5.1.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bare_script-5.1.9.tar.gz | 242.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bare_script-5.1.9-cp314-cp314-macosx_26_0_arm64.whl | CPython 3.14 | CPython 3.14 | macOS 26.0+ ARM64 | Details |
Total release size: 479.9 kB
Release files / bare_script-5.1.9.tar.gz
| Download URL | bare_script-5.1.9.tar.gz |
|---|---|
| Size | 242.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec8850a4e875e809e9c2f6f00f4a2bf2634ff30ecd787c0f9666c3962f263393
|
|
BLAKE2b-256 checksum How to use checksums |
cdd7599b981fd9a670ca5459a9ac00b70b2b068bb1ca583d902288c448c58499
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / bare_script-5.1.9-cp314-cp314-macosx_26_0_arm64.whl
| Download URL | bare_script-5.1.9-cp314-cp314-macosx_26_0_arm64.whl |
|---|---|
| Size | 237.3 kB |
| Tags | CPython 3.14 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
75939e9dbb841178016eb5771e555e58fc39a8ea475d2803c42e43d5f84a872e
|
|
BLAKE2b-256 checksum How to use checksums |
67d6758c61102a37700cb4b7c3b114432590d1b122c4a290f8bfe891905faa87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
