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 JavaScript (this package) and BareScript for Python. 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 in your project with npm:
npm install bare-script
This package is ESM-only. Import from subpaths such as bare-script/lib/runtime.js — there is no
package root export.
To use the bare command-line interface, install the package globally:
npm install -g bare-script
Executing BareScript Scripts
To execute a BareScript script, parse the script using the barescriptParseScript function. Then execute the script using the executeScript function or the executeScriptAsync function. For example:
import {barescriptParseScript, executeScript} from 'bare-script/lib/runtime.js';
// Parse the script
const script = barescriptParseScript(`\
# Double a number
function double(n):
return n * 2
endfunction
return N + ' times 2 is ' + double(N)
`);
// Execute the script
const globals = {'N': 10};
console.log(executeScript(script, {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:
import {barescriptParseScript} from 'bare-script/lib/runtime.js';
import {executeScriptAsync} from 'bare-script/lib/runtimeAsync.js';
// Parse the script
const script = barescriptParseScript(`\
# Fetch the BareScript builtin library documentation JSON
docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script/library/library-builtin.json'))
# Return the number of builtin functions
return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' builtin functions'
`);
// Execute the script
console.log(await executeScriptAsync(script, {'fetchFn': fetch}));
This outputs:
The BareScript Library has 100 builtin functions
Include libraries are loaded before use:
import {barescriptParseScript, executeScript} from 'bare-script/lib/runtime.js';
// Parse the script
const script = barescriptParseScript(`\
include <markdownParser.bare>
include <markdown.bare>
markdown = markdownParse('# Hello, Markdown!')
return markdownTitle(markdown)
`);
// Execute the script
console.log(executeScript(script));
This outputs:
Hello, Markdown!
Quoted includes and
systemFetch
calls with a non-URL path need a filesystem-aware fetch function. In Node.js, pass
fetchReadOnly
or
fetchReadWrite
from bare-script/lib/optionsNode.js to
executeScriptAsync:
import {barescriptParseScript} from 'bare-script/lib/runtime.js';
import {executeScriptAsync} from 'bare-script/lib/runtimeAsync.js';
import {fetchReadWrite} from 'bare-script/lib/optionsNode.js';
const script = barescriptParseScript("include 'util.bare'");
await executeScriptAsync(script, {'fetchFn': fetchReadWrite});
Stub Functions
Include library functions are also callable directly from JavaScript using the native stub functions exported by the include module — for example, dataAggregate, markdownParse, qrcodeMatrix, schemaParse, schemaValidate, and urlEncode. Each stub function executes its corresponding include library function using the BareScript runtime. For example:
import {markdownParse, markdownTitle} from 'bare-script/lib/include.js';
// Parse the Markdown text
const markdown = markdownParse(`\
# Hello, Markdown!
This is some text.
`);
// Print the Markdown title
console.log(markdownTitle(markdown));
This outputs:
Hello, Markdown!
Evaluating BareScript Expressions
To evaluate a BareScript expression, parse the expression using the barescriptParseExpression function. Then evaluate the expression using the evaluateExpression function or the evaluateExpressionAsync function.
Expression evaluation includes the BareScript Expression Library, a set of built-in, spreadsheet-like functions.
For example:
import {barescriptParseExpression, evaluateExpression} from 'bare-script/lib/runtime.js';
// Parse the expression
const expr = barescriptParseExpression('2 * max(a, b, c)');
// Evaluate the expression
const variables = {'a': 1, 'b': 2, 'c': 3};
console.log(evaluateExpression(expr, null, 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.
Performance
The C, JavaScript, and Python implementations share two benchmark suites: make perf (the include
library, compared with native JavaScript via
markdown-model and
schema-markdown) and make perfx (applications
ported to six languages). Results live on the
BareScript (C) Performance.
make perf
make perf PERF_MERGE= # this implementation only
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/SKILL.md, and
https://craigahobbs.github.io/bare-script/llms.txt indexes all of the fetchable documentation.
Development
This package is developed using javascript-build. It was started using javascript-template as follows:
template-specialize javascript-template/template/ bare-script/ -k package bare-script -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapp 1