Home

bare-script

npm GitHub

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

Executing BareScript Scripts

To execute a BareScript script, parse the script using the parseScript function. Then execute the script using the executeScript function or the executeScriptAsync function. For example:

import {executeScript} from 'bare-script/lib/runtime.js';
import {parseScript} from 'bare-script/lib/parser.js';

// Parse the script
const script = parseScript(`\
# 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 {executeScriptAsync} from 'bare-script/lib/runtimeAsync.js';
import {parseScript} from 'bare-script/lib/parser.js';

// Parse the script
const script = parseScript(`\
# Fetch the BareScript library documentation JSON
docs = jsonParse(systemFetch('https://craigahobbs.github.io/bare-script/library/library.json'))

# Return the number of library functions
return 'The BareScript Library has ' + arrayLength(objectGet(docs, 'functions')) + ' functions'
`);

// Execute the script
console.log(await executeScriptAsync(script, {'fetchFn': fetch}));

This outputs:

The BareScript Library has 209 functions

Evaluating BareScript Expressions

To evaluate a BareScript expression, parse the expression using the parseExpression 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 {evaluateExpression} from 'bare-script/lib/runtime.js';
import {parseExpression} from 'bare-script/lib/parser.js';

// Parse the expression
const expr = parseExpression('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

Note: In the BareScript CLI, import 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!')
```

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 library is also documented as single-page Markdown, which can be fetched directly into an assistant's context alongside SKILL.md:

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