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

• The BareScript Language
• The BareScript Library
• The BareScript Include Library Tests
• API Documentation
• Source code

Installation

Install the bare-script package in your project with npm:

npm install bare-script

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 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 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

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 Include Library Stub Functions

BareScript include library functions are 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!

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

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!')
```

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 JavaScript program (using the markdown-model and schema-markdown packages).

The following results are from make perf PERF_MERGE= (Node.js 24, Apple M-series). Times are the best per-run timing in milliseconds per 1,000 runs. Multiples are relative to the native JavaScript time. Tests without a native JavaScript equivalent are omitted.

| Test | Language | Time (ms) | Multiple | | ---------------- | --------------- | --------: | -------: | | markdownParse | JavaScript | 598.0 | | | | BareScript (JS) | 2420.0 | 4.0x | | schemaParse | JavaScript | 71.3 | | | | BareScript (JS) | 1164.0 | 16.3x | | urlDecode | JavaScript | 4.9 | | | | BareScript (JS) | 85.5 | 17.5x | | urlEncode | JavaScript | 2.8 | | | | BareScript (JS) | 49.0 | 17.8x | | markdownElements | JavaScript | 29.2 | | | | BareScript (JS) | 564.0 | 19.3x | | schemaValidate | JavaScript | 57.3 | | | | BareScript (JS) | 1868.0 | 32.6x | | mandelbrot | JavaScript | 1976.1 | | | | BareScript (JS) | 293000.0 | 148.3x |

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.

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 '[email protected]' -k github 'craigahobbs' -k noapp 1