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 Creator
• API Documentation
• Source code

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.

The BareScript Creator

The BareScript Creator generates a ready-to-build BareScript project from a specification you write. Choose a project type (a MarkdownUp frontend application, to start), fill in its form, and download the project as a .tar.gz archive with a Makefile, a unit test suite, and the bare-script skill. In the project directory, make run has Claude Code, in your terminal, write the code and its tests from your specification, then serves the application in your browser. The creator keeps a history of your projects so you can refine a specification and create it again.

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