API Reference JustBash v#0.4.0

A simulated bash environment with virtual filesystem.

Abstract Syntax Tree (AST) Types for Bash

Arithmetic array element access

Arithmetic assignment

Arithmetic binary operation

Arithmetic grouped expression: (expr)

Arithmetic number literal

Arithmetic ternary operation: cond ? then : else

Arithmetic unary operation

Arithmetic variable reference

Arithmetic command: (( expr ))

Arithmetic expansion: $((expr))

Arithmetic expression (for $((...)) and ((...)))

${VAR:=default} or ${VAR=default}

Variable assignment: VAR=value or VAR+=value

Brace expansion: {a,b,c} or {1..10}

C-style for loop: for ((init; cond; step)); do ...; done

case statement

Single case item with patterns and body

${VAR^}, ${VAR^^}, ${VAR,}, ${VAR,,}

Command substitution: $(cmd) or cmd

Conditional AND expression

Conditional binary expression

Conditional grouped expression

Conditional NOT expression

Conditional OR expression

Conditional unary expression

Conditional word (for simple string tests)

Conditional command: [[ expr ]]

${VAR:-default} or ${VAR-default}

Double-quoted string: "with $expansion"

${VAR:?error} or ${VAR?error}

Escaped character: \x

for loop: for VAR in WORDS; do ...; done

Function definition

Glob pattern part (expanded during pathname expansion)

Command group: { ...; }

Here document

if statement

Single if/elif clause with condition and body

${!VAR} - indirect expansion

${#VAR}

Literal text (no special meaning)

Parameter/variable expansion: $VAR or ${VAR...}

${VAR#pattern}, ${VAR##pattern}, ${VAR%pattern}, ${VAR%%pattern}

${VAR/pattern/replacement} or ${VAR//pattern/replacement}

A pipeline: cmd1 | cmd2 | cmd3

Process substitution: <(cmd) or >(cmd)

I/O redirection

Root node: a complete script

Simple command: name args... with optional redirections

Single-quoted string: 'literal'

A statement is a list of pipelines connected by && or ||

Subshell: ( ... )

${VAR:offset} or ${VAR:offset:length}

Tilde expansion: ~ or ~user

until loop

${VAR:+alternative} or ${VAR+alternative}

while loop

A Word is a sequence of parts that form a single shell word. After expansion, it may produce zero, one, or multiple strings.

Arithmetic expression parsing and evaluation for bash.

Evaluates arithmetic expression AST nodes.

Recursive descent parser for bash arithmetic expressions.

Detects banned remote function calls by inspecting compiled BEAM files.

Declarative, namespaced subcommand tools for JustBash.

A single node in a JustBash.CLI command tree.

Renders a whole JustBash.CLI as a document for human or agent consumption.

Renders --help text, usage lines, and usage errors for a JustBash.CLI.

The single argument passed to a JustBash.CLI command handler.

The arch command - print machine architecture.

Declarative command-line argument parser for shell commands.

The awk command - pattern scanning and processing language.

AST node constructors for AWK programs.

Evaluator for AWK programs.

Formatter for AWK printf operations.

Lexer for AWK programs.

Token-based parser for AWK programs.

The base64 command - base64 encode/decode data.

The basename command - strip directory and suffix from filenames.

The break builtin command - exit from a loop.

The cat command - concatenate files and print on stdout.

The cd command - change directory.

The chmod command - change file mode bits.

The chown command - change file owner and group.

The comm command - compare two sorted files line by line.

Behaviour for bash commands.

The command builtin - execute a command or describe it.

The continue builtin command - resume the next iteration of a loop.

The cp command - copy files and directory trees.

The curl command - transfer data from or to a server.

The cut command - remove sections from each line of files.

The date command — display the current date and time.

The diff command - compare files line by line.

The dirname command - strip last component from file name.

The du command - estimate file space usage.

The echo command - display a line of text.

The env command - print environment variables.

The eval builtin command - concatenate arguments and execute the result.

The exit command - exit the shell with a status code.

The expand command - convert tabs to spaces.

The export command - set environment variables.

The false command - do nothing, unsuccessfully.

The file command - determine file type.

The find command - search for files in a directory hierarchy.

The fold command - wrap each input line to fit in specified width.

The getopts builtin command - parse positional parameters as options.

The grep command - print lines matching a pattern.

The head command - output the first part of files.

The hostname command - show the system's host name.

The id command - print real and effective user and group IDs.

The jq command - command-line JSON processor.

Evaluator for jq AST expressions.

Output formatting functions for jq.

Built-in function implementations for jq.

Parser for jq filter expressions.

The ln command - make links between files.

The local builtin command - declare local variables within a function.

The ls command - list directory contents.

The markdown (or md) command - convert Markdown to HTML.

The md5sum command - compute MD5 message digest.

The mkdir command - make directories.

The mktemp command - create a temporary file or directory.

The mv command - move (rename) files.

The nl command - number lines of files.

The nproc command - print the number of processing units available.

The od command - dump files in octal and other formats.

The paste command - merge lines of files.

The printenv command - print all or part of environment.

The printf command - format and print data.

The pwd command - print working directory.

The read command - read a line from stdin into a variable.

The readlink command - print resolved symbolic links.

The realpath command - print the resolved absolute path.

Registry of all available bash commands.

The return builtin command - return from a function.

The rev command - reverse lines characterwise.

The rm command - remove files or directories.

The sed command - stream editor for filtering and transforming text.

Executor for SED commands.

Parser for SED scripts.

The seq command - print a sequence of numbers.

The set builtin command - set or unset shell options.

The sha256sum command - compute SHA-256 message digests.

The shasum command - compute SHA message digests (macOS-style).

The shift builtin command - shift positional parameters.

The sleep command - delay for a specified time (no-op in simulation).

The sort command - sort lines of text files.

The source and . builtin commands - execute commands from a file in the current shell.

The stat command - display file status.

The - file operand.

The tac command - concatenate and print files in reverse.

The tail command - output the last part of files.

The tee command - read from stdin and write to stdout and files.

The test and [ commands - evaluate conditional expressions.

The touch command - change file timestamps or create empty files.

The tr command - translate or delete characters.

The trap builtin command - trap signals and execute commands.

The tree command - list contents in a tree-like format.

The true and : commands - do nothing, successfully.

The type command - display information about command type.

The uname builtin - print system information.

The uniq command - report or omit repeated lines.

The unset command - unset environment variables.

The wc command - print newline, word, and byte counts.

The wget command - non-interactive network downloader.

The which command - locate a command.

The whoami command - print the current user name.

The xargs command - build and execute command lines from standard input.

The xxd command - make a hexdump.

The yes command - output a string repeatedly.

JustBash's filesystem layer: a thin facade over the vfs library.

JustBash's in-memory VFS.Mountable backend — the default backend mounted at / by JustBash.FS.new/1.

POSIX filesystem extensions that are not part of VFS.Mountable.

Device nodes the filesystem layer services itself, rather than storing them in a backend.

Content-addressing and integrity rules for the bash comparison fixture corpus.

A shared module for parsing command-line flags in bash commands.

Bash code formatter.

Behaviour for HTTP clients used by curl command.

Default HTTP client using Req library.

Executes parsed bash AST nodes.

Evaluates conditional expressions for [[ ]] and if statements.

Executes loop constructs: for, while, until.

Handles file redirections for bash commands.

Handles shell expansion: variables, command substitution, arithmetic.

Brace expansion for bash.

Glob expansion and pattern matching utilities.

Parameter expansion operations for bash variables.

Raised when accessing an unset variable with set -u

Internal interpreter state carried alongside the user-visible JustBash struct.

Production resource limits for JustBash execution.

The instant a single JustBash.exec/2 must be finished by.

Raised when a resource limit is exceeded during execution.

Shared network policy enforcement for sandbox HTTP commands (curl, wget).

Recursive Descent Parser for Bash Scripts.

Parser for compound commands in bash.

Heredoc content handling for the parser.

Hand-written lexer for bash scripts.

Brace expansion token merging for the bash lexer.

Structured error for lexer failures.

Token representation for the bash lexer.

Parse error with position information

Parser for shell redirections.

Word Parts Parser

Bracket matching utilities for word parts parsing.

Parses shell expansions: $VAR, ${VAR}, $((expr)), $(cmd), cmd.

Represents the result of executing a command or script.

Sigils for working with bash code.

Parser for Oils spec test format (.test.sh files).

Represents a single spec test case

Runs Oils spec tests against JustBash and reports results.

Result of running a spec test

Telemetry instrumentation for the JustBash interpreter.

Records what real bash does for the fixture comparison corpus.

Generates enumerated fixture matrices — the cases nobody thinks to write.

Rewrites stored content_hash values to match the current case inputs.

Checks the fixture corpus for integrity. Offline — no Docker.

Scans Elixir source for filesystem call shapes that the 0.3 → 0.4 migration broke in ways the compiler cannot catch (see UPGRADING.md). The legacy patterns still compile and then misbehave at runtime

Runs the JustBash agent eval suite.