This document specifies the Blood shell as implemented by version 0.1.0. It describes the observable behaviour of the interactive shell, its command language, its configuration system, and the Blood scripting language. It is a specification of the implementation rather than a statement of future intent. Where the implementation is deliberately permissive or incomplete, that is stated explicitly.
The implementation is written in Spectre and is built with the Spectre
toolchain version recorded in sx.mod. The current build targets Linux with a
POSIX-style C library and uses dynamic linking. Other operating systems are not
supported by this build.
Conformance and terminology
The words shall, must, should, and may are used in their conventional normative sense. A shell command is a command entered in the interactive shell or executed by the command interpreter. A script is a sequence of Blood language statements. A line is a sequence of bytes terminated by a line feed or by end of input.
The shell has two execution domains:
-
The command domain, described in [command-language].
-
The scripting domain, described in [scripting-language].
Both domains share the same process, working directory, environment, and file descriptors. A script may execute shell commands and a shell command may run a script.
System overview
Blood is a single executable. The principal source modules are:
| Module | Responsibility |
|---|---|
|
|
Entry point, argument handling, interactive loop, startup files. |
|
|
Allocation, strings, vectors, maps, files, paths, terminal I/O. |
|
|
INI configuration loading and defaults. |
|
|
Prompt layout, colours, directory formatting, Git discovery. |
|
|
Persistent history, encoding, duplicate suppression, search. |
|
|
Command, directory, path, and variable completion. |
|
|
Raw terminal mode, key decoding, line editor, menu, search. |
|
|
Fork, exec, pipes, waits, redirection primitives. |
|
|
Command scanning, parsing, pipelines, redirection, builtins. |
|
|
Lexer, AST, and parser for the scripting language. |
|
|
Script interpreter, values, builtins, shell integration. |
The build configurations in sx.mod are:
build release {
flags "-release -dynamic"
output "./blood"
}
build dev {
flags "-dynamic"
output "./blood-dev"
}
Invocation
The executable is invoked as one of:
blood
blood -c COMMAND
blood SCRIPT.blood|SCRIPT.bx [ARG...]
blood -init
blood -version
blood -help
blood with no operands starts an interactive shell when standard input is a
terminal. If standard input is not a terminal, Blood reads standard input to
end of file and executes it.
blood -c COMMAND executes COMMAND and exits. If the first non-empty
line
of COMMAND has the shape of a scripting statement, the command is executed
as a script. Otherwise it is executed as a shell command.
blood SCRIPT.blood ARG… or
blood SCRIPT.bx ARG… reads and executes the
named script. Remaining arguments are exposed to the script as the list
variable args. The script name is exposed as file.
blood -init writes a default configuration file at the configuration path
if no file exists there. Parent directories are created. If the file already
exists it is not overwritten.
blood -version and blood -v print the version line.
blood -help and blood -h print usage information.
An unrecognised flag beginning with - produces
blood: unknown flag 'OPTION' and status 2. Command-line options use the
Plan 9 single-dash form. Parsing stops at the first positional argument, so
script arguments beginning with - are passed through unchanged.
Process model
The shell does not replace itself when executing a command. External commands
are children created with fork and replaced with execvp. Pipelines
create
one child per stage. Background commands create a wrapper child. Builtins run
in the shell process unless they occur in a pipeline or a background command,
in which case they run in the child.
The shell never invokes /bin/sh for ordinary command execution. A shell
command is parsed and executed directly. /bin/sh is used only by external
programs that choose to invoke it.
Exit status
| Status | Meaning |
|---|---|
|
0 |
Success. |
|
1 |
General failure, including failed redirection, failed
|
|
2 |
Command syntax error, script syntax error, or invalid
|
|
126 |
Reserved for a non-executable command when reported by the platform. |
|
127 |
Command not found, or |
|
128+N |
Command terminated by signal N. |
|
130 |
Interrupted by SIGINT. |
A pipeline returns the status of its last stage. && and ||
use the status
of the previous segment. A background command returns 0 in the parent.
Environment
The shell inherits the process environment. Shell variables and exported environment variables are related but distinct:
-
A plain assignment such as
NAME=valuecreates or updates a shell variable. -
export NAME=valuecreates or updates a shell variable and the process environment. -
A command prefix such as
NAME=value commandsets the variable in the child environment for that command. For builtins the assignment is applied temporarily and then restored. -
unset NAMEremoves the shell variable and the environment variable.
Variable lookup first checks shell variables and then the process environment.
Signals
The interactive shell installs a SIGINT handler that sets an interrupt flag.
SIGQUIT, SIGTERM, and SIGTSTP are ignored by the shell process. External
children restore the default dispositions for SIGINT, SIGQUIT, SIGTERM,
SIGTSTP, SIGTTIN, and SIGTTOU before exec.
While the line editor is active the terminal is in raw mode and the ISIG flag is disabled, so Ctrl-C and Ctrl-Z arrive as ordinary bytes. While a command is executing the original terminal settings are restored, so Ctrl-C is delivered to the foreground child. When the child terminates, the shell resumes editing with a new prompt.
A script can be interrupted at a loop boundary or before or after a shell command. An external command interrupted by Ctrl-C normally produces status 130.
Configuration
Location and lifecycle
The configuration file is:
$XDG_CONFIG_HOME/blood/blood.ini
when XDG_CONFIG_HOME is set and non-empty, and otherwise:
$HOME/.config/blood/blood.ini
The configuration directory and the directory containing the history file are
created at startup if they do not exist. The configuration file itself is not
created automatically; use blood -init.
Configuration is loaded once at process startup. It is not reloaded while the shell is running.
A missing configuration file is not an error. Every setting has a default.
File syntax
The file uses a sectioned INI syntax:
# comment
[section]
key = value
-
Leading and trailing whitespace is removed from keys and values.
-
A line whose first non-whitespace byte is
#or;is a comment. -
Inline comments are not recognised.
-
Section headers have the form
[name]. -
Keys before the first section are interpreted as belonging to the
promptsection. -
A value may be enclosed in matching single or double quotation marks; those marks are removed.
-
Blank lines are ignored.
-
Unknown keys are ignored.
-
Unknown sections are ignored except for
aliasesandenv. -
A line without
=in a non-aliases, non-envsection produces a diagnostic and is skipped.
Boolean values are true, yes, on, and 1
for true, and false, no,
off, and 0 for false. Boolean and integer keys are case sensitive.
A malformed line, an invalid boolean, or an invalid integer produces a diagnostic on standard error and the shell continues with the default or previously assigned value.
Settings
[prompt]
| Key | Type | Default and effect |
|---|---|---|
|
|
string |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
boolean |
|
|
|
string |
|
|
|
string |
|
|
|
string |
|
|
|
string |
|
|
|
string |
|
full shows the complete directory with the home directory abbreviated to
~. short shows the final two path components.
basename shows only the
final component. An unrecognised value behaves as full.
[colors]
| Key | Default | Use |
|---|---|---|
|
|
|
Username and prompt character. |
|
|
|
Host name. |
|
|
|
Accepted for compatibility; currently not rendered. |
|
|
|
Failure status. |
|
|
|
Directory. |
|
|
|
Clean Git branch. |
|
|
|
Dirty Git branch and dirty marker. |
|
|
|
Separators, box drawing, time, duration. |
|
|
|
Background job count. |
|
|
|
Accent text in the login banner. |
Colour values may be:
-
A name:
default,black,red,green,yellow,blue,magenta,cyan,white,bright_black(alsograyandgrey),bright_red,bright_green,bright_yellow,bright_blue,bright_magenta,bright_cyan, orbright_white. -
A decimal 256-colour index.
-
A
#RRGGBBvalue, rendered as a 24-bit foreground colour.
An unrecognised colour produces no escape sequence. Styles such as bold or underline cannot be selected independently.
[history]
| Key | Type | Default and effect |
|---|---|---|
|
|
boolean |
|
|
|
string |
|
|
|
integer |
|
|
|
boolean |
|
history_max is accepted as an alias for max_entries.
[completion]
| Key | Type | Default and effect |
|---|---|---|
|
|
boolean |
|
|
|
boolean |
|
[shell]
| Key | Type | Default and effect |
|---|---|---|
|
|
string |
|
|
|
string |
Alias for |
|
|
boolean |
|
|
|
string |
Empty. A script to execute before the interactive
loop. Leading |
In addition, ~/.config/blood/init.blood is executed before the interactive
loop when it exists. If both startup_file and the default startup file
exist, both are executed in that order. Startup scripts run after
configuration and history loading.
.bloodrc
Blood creates and runs ~/.config/blood/.bloodrc for every interactive
session. When XDG_CONFIG_HOME is set, the file lives beside
blood.ini
under that directory. The file is a normal Blood script and is created with a
prelude stub when missing:
# Aliases:
# alias ll='ls -l'
# alias gs='git status'
fn prelude() {
# Session setup goes here.
}
prelude()
Aliases and functions defined in .bloodrc are available in the interactive
shell. The file runs at the start of an interactive session, before
startup_file and init.blood. :rla reloads the
file.
[aliases]
Each key is an alias name and each value is its replacement text:
[aliases]
ll = ls -l
gs = git status
Aliases defined here are installed before the interactive loop and before
startup_file is executed.
[env]
Each key is an environment variable name and each value is its value:
[env]
EDITOR = vim
PAGER = less
These variables are passed to the process environment before the shell initialises its variable table.
Default configuration file
blood -init writes the following content when the file does not exist:
# Blood shell configuration
# See `blood help config` for the available keys.
[prompt]
theme = default
show_username = true
show_hostname = true
show_directory = true
show_git = true
show_time = false
show_exit_status = true
show_duration = true
two_line = true
[colors]
primary = cyan
secondary = magenta
success = green
error = red
directory = blue
git_clean = green
git_dirty = yellow
muted = bright_black
[history]
enabled = true
file = ~/.local/share/blood/history
max_entries = 10000
ignore_duplicates = true
[completion]
enabled = true
case_sensitive = false
[shell]
default_editor = nano
login_message = true
Interactive terminal
Terminal selection
The interactive line editor is enabled only when tcgetattr succeeds on
standard input. If standard input is not a terminal, Blood reads lines without
prompt editing and without a prompt.
The terminal size is queried with TIOCGWINSZ. The fallback size is 80
columns by 24 rows.
Raw mode
When the line editor is entered, Blood saves the current terminal settings and switches to a raw-like mode:
-
ECHO,ICANON,IEXTEN, andISIGare cleared from the local flags. -
IXONandICRNLare cleared from the input flags. -
VMINis 1 andVTIMEis 0.
The original settings are restored before any command is executed and when the shell exits. This makes Ctrl-C and Ctrl-Z work normally for external programs.
The editor assumes an ANSI-compatible terminal and emits ANSI CSI sequences for clearing, cursor movement, scrolling, and menu drawing. No terminfo database is used.
Rendering model
The prompt is rendered once per command line, not once per keystroke. Each keystroke redraws the prompt text, the current line, and any open completion menu in a single buffered write. Long lines are horizontally scrolled so that the cursor remains visible.
Newline bytes stored in a recalled history entry are displayed as ⏎ in the
line editor. Cursor movement traverses UTF-8 code points. Display width is
counted in code points, not in terminal cells, so wide East Asian characters
and combining marks are not width-corrected.
The completion menu is drawn as a bordered rectangle below the prompt line. Its height is capped at ten rows and it never fills the terminal. The cursor is repositioned to the insertion point after each redraw.
Key bindings
| Key | Action |
|---|---|
|
Printable character |
Insert at the cursor. |
|
Enter |
Accept the current line. While a history search is active, accept the matched line. |
|
Ctrl-A |
Move to the beginning of the line. |
|
Ctrl-E |
Move to the end of the line. |
|
Ctrl-B |
Move one code point left. |
|
Ctrl-F |
Move one code point right. |
|
Ctrl-K |
Delete from the cursor to the end of the line. |
|
Ctrl-U |
Delete from the beginning of the line to the cursor. |
|
Ctrl-W |
Delete the previous word. |
|
Ctrl-L |
Clear the screen and redraw. |
|
Ctrl-P |
Recall the previous history entry. |
|
Ctrl-N |
Recall the next history entry. |
|
Ctrl-R |
Start or advance reverse incremental history search. |
|
Ctrl-C |
Cancel the current line. Prints |
|
Ctrl-D |
On an empty line, end the session. Otherwise delete at the cursor. |
|
Ctrl-Z |
Ignored by the editor; the signal is ignored by the shell. |
|
Backspace |
Delete the previous code point. |
|
Delete |
Delete the code point at the cursor. |
|
Left / Right |
Move by one code point. |
|
Up / Down |
Navigate history. |
|
Home / End |
Move to the beginning or end of the line. |
|
Tab |
Complete at the cursor, or advance the completion menu. |
|
Shift-Tab |
Move backwards through the completion menu. |
|
Esc |
Close the completion menu. A lone Esc is ignored. |
|
Alt-b / Alt-f |
Move one code point left or right. |
Unrecognised control bytes are ignored.
Completion menu
Completion is opened with Tab. If there is one candidate, it is inserted immediately. If there are multiple candidates and they share a longer common prefix than the current word, that prefix is inserted and the menu is opened. Otherwise the menu is opened without changing the line.
While the menu is open:
-
Tab selects the next candidate and previews it in the line.
-
Shift-Tab selects the previous candidate and previews it.
-
Enter accepts the line as previewed.
-
Any ordinary editing key closes the menu and acts on the previewed line.
-
Esc closes the menu and restores the line to the state it had when the menu opened. A lone Esc with no menu open is ignored.
The menu is drawn as a bordered rectangle with a title, in row-major order.
At most ten rows, including the border, are used; longer candidate lists
scroll as the selection moves. The selected candidate is highlighted with
reverse video. Items that are wider than the menu are clipped with ….
Escape commands
A line beginning with : at the interactive prompt is an escape command. It
is not passed to the shell or scripting language.
| Command | Effect |
|---|---|
|
|
Print the embedded Blood brand art. |
|
|
Show the current value and, for enumerated keys, all accepted
values. Enumerated keys include |
|
|
Update a configuration key in the running session
and immediately rewrite the corresponding line in |
|
|
Reload |
|
|
Recursively find files whose name contains |
|
|
List a directory as a Unicode table with permissions and human-readable sizes. Defaults to the current directory. |
|
|
Print the paths of |
|
|
Print the escape-command summary. |
Examples:
:cfg.prompt.theme
:cfg.prompt.theme = hacker
:cfg.colors.primary = red
:cfg.history.max_entries = 500
:cfg.aliases.ll = ls -l
:ft foo bar
Saving a key creates the blood.ini file and the containing section when
needed. Existing comments and unrelated lines are preserved.
Reverse incremental search
Ctrl-R enters reverse incremental search. The prompt becomes:
(reverse-i-search) `QUERY': MATCH
Characters extend the query. Ctrl-R searches for the next older match. Backspace removes a query character. Enter accepts the matched line. Ctrl-C or Esc abandons the search and restores the line that was being edited when the search started.
Search is case-insensitive and matches substrings of history entries. It searches from newest to oldest.
Multiline input
The interactive shell collects input in three situations:
-
A script line that begins a block, recognised by a trailing
{(or by the deprecated trailing:) on a line that has the shape of a scripting statement. Subsequent lines are collected until the block is balanced or, for the colon style, until an empty line. -
A line with unbalanced parentheses, brackets, braces, or quotes. Lines are collected until balance is restored.
-
A line ending in a backslash. The backslash-newline sequence is removed by the command scanner.
The continuation prompt is a dim ` … ` marker. A cancelled continuation abandons the whole pending command. A complete multiline command is recorded as one history entry.
Prompt
Default two-line layout
The default prompt has the form:
┌─ USER@HOST DIRECTORY on BRANCH *
└─ ❯
The first line begins with a muted `┌─ `. The second line begins with a muted `└─ ` followed by the prompt character in the primary colour.
Components are emitted in this order:
-
User name, when enabled.
-
@and host name, when both user name and host name are enabled, or the host name alone when only the host name is enabled. -
Directory, when enabled.
-
Git branch, when enabled and a repository is found.
-
Time, when enabled.
-
Background-job count, when enabled and non-zero.
-
Failure status, when enabled and the previous status is non-zero.
-
Previous command duration, when enabled and at least 500 ms.
Failure status is rendered as a red ✘ N. Duration is rendered as a muted
took Nms, took N.Ns, or took NmNs. Background jobs
are rendered as a
yellow ⚙ N.
Plain theme
theme = plain selects a single-line prompt of the form:
USER@HOST DIRECTORY (BRANCH) >
The plain theme always uses > and does not print a box. It honours the
username, hostname, directory, and Git settings. It does not render time,
status, duration, job count, or the configured prompt character.
Prompt presets
A preset is selected with [prompt] theme = NAME. Every preset honours the
show_* toggles and the [colors] settings. Presets define their own
glyphs
and path style.
| Theme | Layout |
|---|---|
|
|
|
|
|
Coloured powerline segments for user, host, directory, branch,
time, and indicators, followed by a second |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A compacted home path such as
|
|
|
A three-line |
|
|
|
|
|
A three-line |
The powerline preset converts the configured foreground colours into
segment backgrounds and uses `` separators. It requires a font with
Powerline glyphs.
The two right-aligned presets draw their right-hand text at the terminal edge and then return the cursor to the end of the left-hand prompt. When the terminal is too narrow for both parts, the right-hand text is omitted and the input uses the full remaining line.
Directory formatting
The home directory prefix is replaced by ~ when it matches a complete path
component. full preserves the remaining path. short keeps the last
two
components. basename keeps only the last component. When the home directory
itself is displayed, it is shown as ~.
Git information
Git discovery walks from the current directory toward the filesystem root. At
each level it checks for a .git directory. If .git is a file, a
gitdir: PATH line is followed.
The branch is read from HEAD:
-
A symbolic reference
ref: refs/heads/NAMEyieldsNAME. -
Another symbolic reference yields the text after `ref: `.
-
A detached HEAD yields the first seven characters of the commit hash.
Dirty state is obtained by running:
git -C ROOT status --porcelain --untracked-files=no
A non-empty result marks the branch dirty. Untracked files are therefore not
considered. If git is unavailable or fails, the repository is treated as
clean. Git information is cached for 1500 milliseconds for the current
directory; the prompt does not spawn git on every keystroke.
History
History is stored one entry per line. The file format is not intended to be edited by hand, although ordinary single-line commands appear verbatim.
Within an entry:
-
A backslash is encoded as
\\. -
A line feed is encoded as
\n. -
A carriage return is encoded as
\r.
History is loaded at startup, appended as commands are accepted, and rewritten
in full when the shell exits. Entries beyond max_entries are removed from the
oldest end. Consecutive duplicates are suppressed when ignore_duplicates is
true.
The history builtin prints entries with one-based indices:
1 echo one
2 echo two
history -c clears both memory and file. history -w rewrites the file.
history N prints the last N entries. A non-numeric argument is treated as a
request for all entries.
When enabled is false, the history list is neither loaded nor recorded, and
the history builtin reports an empty list.
Completion
Completion is computed for the token containing the cursor. The token starts
after whitespace or one of |, &, ;,
<, >, (, or ).
Completion is selected as follows:
-
If no earlier word occurs in the current command segment, completion is for command names. A word that contains
/or begins with.or~is completed as a path instead. -
If the command is
cd,pushd, orpopd, completion is for directories. -
If the command is
export,unset, orset, completion is for shell variable names. -
Otherwise completion is for filesystem entries.
Command completion considers:
-
Builtin command names.
-
Alias names.
-
Executables found in the directories of
PATH.
The PATH scan is performed lazily on the first command completion and cached
for the life of the process. Only entries that are not directories and that
pass the executable access check are included.
Filesystem completion splits the word at its final /. The directory portion
is expanded for ~ and listed. Entries whose names begin with . are
offered
only when the typed basename begins with .. Directories receive a trailing
/. Candidates preserve the typed directory prefix. Typing ./some/path/
and pressing Tab therefore lists the contents of that directory in the
completion menu.
Completion inside a quoted word is not attempted when the character before the
cursor is " or '.
Completion results are sorted lexicographically. Duplicate candidates are removed.
Command language
Input decomposition
A shell input is split into segments at top-level occurrences of:
-
;and line feed, which are unconditional separators. -
&&, which executes the next segment only when the previous status is zero. -
||, which executes the next segment only when the previous status is non-zero. -
&, which executes the segment in the background.
Splitting respects single quotes, double quotes, backslash escapes, backticks,
and $(…). A # that begins a word starts a comment
that extends to the end
of the line.
A segment is split into a pipeline at top-level | characters. A pipeline is
a sequence of commands. Consecutive pipelines form a command list.
Words and quoting
A word is a maximal sequence of bytes not containing unquoted whitespace or one
of the metacharacters |, &, ;, <,
>.
Within an unquoted word:
-
A backslash quotes the next byte. A backslash followed by a line feed is a line continuation and both bytes are removed.
-
Single quotes preserve every byte until the next single quote.
-
Double quotes preserve every byte until the next double quote, except that backslash escapes
",\,$, and backtick, and line continuations are removed. -
$and backtick introduce expansions. -
A leading
~introduces tilde expansion.
An empty quoted word is a valid empty argument.
Expansions
Variables
| Form | Meaning |
|---|---|
|
|
Value of shell variable or environment variable
|
|
|
Same, with explicit delimiters. |
|
|
Status of the previous command. |
|
|
Process ID of the shell. |
|
|
Process ID of the most recent background command. |
|
|
Number of script arguments. |
|
|
Program name, normally |
An undefined variable expands to the empty string. $@, $*, and
array or
positional expansion are not implemented and are left literal or partially
expanded as ordinary text.
Variable expansion is performed before field splitting. A variable whose value contains spaces expands to a single word; the shell does not perform word splitting on expansion results.
Tilde expansion
A word that begins with ~ has the ~ replaced by the value of
HOME.
~user is not resolved through the user database; any ~
followed by
characters other than / or the end of the word is left unchanged.
Command substitution
Command substitution has two forms:
$(COMMANDS)
`COMMANDS`
The commands are executed in a child process with standard output captured. Trailing line feeds and carriage returns are removed from the result. The result is inserted into the current word as a single field; it is not split on whitespace. The status of the substitution becomes the shell’s previous status.
The child runs Blood’s own command interpreter, not /bin/sh.
Globbing
An unquoted word containing *, ?, or [ is treated
as a pathname pattern.
The pattern is expanded against the filesystem. If no match exists, the word is
left unchanged.
Supported pattern elements are:
-
*matches any sequence of bytes. -
?matches one byte. -
[abc]matches one byte in the set. -
[a-z]matches one byte in the range. -
[!abc]and[^abc]match one byte not in the set.
A leading dot in a filename is matched only when the pattern component also
begins with a dot. Glob results are sorted lexicographically. Brace expansion,
recursive **, and extglob are not implemented. Assignment words are not
globbed.
Assignments
An assignment word has the form:
NAME=VALUE
where NAME begins with an ASCII letter or underscore and continues with
letters, digits, or underscores.
If assignments occur before the command name and no command name is present, the assignments update shell variables. If a command follows, the assignments are placed in the child environment for that command. For builtins, the assignments are temporarily applied and then restored.
export NAME=VALUE updates both the shell variable and the environment.
export NAME exports the current value.
Aliases
alias NAME=VALUE defines an alias. alias NAME prints one alias.
alias
with no arguments prints all aliases. unalias NAME… removes
aliases.
unalias -a removes all aliases.
Aliases are expanded by re-scanning the replacement text as a shell line with the original arguments appended and quoted. Expansion is recursive up to a depth of eight. Alias expansion is performed for single-command input. An alias used as a stage of a multi-command pipeline is currently not expanded and is looked up as an external command.
Aliases defined in configuration are loaded before startup scripts.
Redirections
| Form | Meaning |
|---|---|
|
|
Redirect standard input from |
|
|
Truncate |
|
|
Append standard output to |
|
|
Truncate |
|
|
Append standard error to |
|
|
Truncate |
|
|
Append both standard output and error to |
|
|
Duplicate file descriptor N onto standard error. |
A redirection target is a word and undergoes normal expansion. Redirections apply left to right. A failed open reports an error and the command is not run or runs with status 1. Redirections on a builtin are applied in the shell process and the original descriptors are restored afterwards.
Heredocs, here-strings, process substitution, and arbitrary N> forms other
than the listed forms are not implemented.
Pipelines and background execution
A | B creates a pipe between A and B. Commands in a pipeline run
concurrently. Builtins in a pipeline run in their stage child. The pipeline
status is the status of its last stage.
COMMAND & runs the entire pipeline in a wrapper child. The wrapper’s
process
ID is recorded as a background job. $! is set to that ID. jobs
lists
running jobs and wait waits for all recorded jobs.
An unquoted time at the beginning of a pipeline is a shell keyword. It runs
the pipeline and then writes timings to standard error in the same shape as
bash:
real 0m1.201s
user 0m1.067s
sys 0m0.133s
The pipeline’s output is not delayed or captured. Redirections on the pipeline
do not redirect the timing report. To run the external time utility, quote
the name or use its path, for example 'time' or /usr/bin/time.
Command resolution
A command name containing / is passed directly to execvp.
A command name without / is resolved by execvp using
PATH. Builtins are
checked before execvp.
If execution fails, the child writes:
blood: NAME: command not found
and exits with status 127.
Builtin commands
| Command | Behaviour |
|---|---|
|
|
Change directory. With no argument, use |
|
|
Print the current working directory. |
|
|
Terminate the shell with |
|
|
Alias for |
|
|
Show or manage history as described above. |
|
|
Write the ANSI clear-screen sequence. |
|
|
Alias for |
|
|
Export variables. With no arguments, print shell variables. |
|
|
Remove shell and environment variables. |
|
|
Define or print aliases. |
|
|
Remove aliases. |
|
|
Print help. Topics: |
|
|
Execute a Blood script in the current shell state. |
|
|
Alias for |
|
|
Print arguments separated by spaces. |
|
|
Print arguments separated by spaces and a newline. |
|
|
With no arguments, print shell variables. Otherwise assign values. |
|
|
Resolve a shell keyword, builtin, alias, or |
|
|
Same as |
|
|
Reap finished jobs and print running background jobs. |
|
|
Wait for all recorded background jobs and clear the job list. |
|
|
Return 0. |
|
|
Return 1. |
|
|
Return 0. |
type checks shell keywords first, then builtins, then aliases, then
PATH.
It does not verify that a PATH candidate is executable. Only the first
argument is used.
source and cd use only their first argument.
Shell grammar
The following grammar describes the command language accepted by the
implementation. WORD is a word after quoting and expansion; SEP is
a
top-level separator.
shell-input = { shell-list } ;
shell-list = segment { connector segment } ;
connector = ";" | NEWLINE | "&&" | "||" | "&" ;
segment = pipeline ;
pipeline = [ "time" ] command { "|" command } ;
command = { assignment } { WORD | redirection } ;
assignment = NAME "=" WORD ;
redirection = "<" WORD
| ">" WORD
| ">>" WORD
| "2>" WORD
| "2>>" WORD
| "&>" WORD
| "&>>" WORD
| "2>&" DIGITS ;
NAME = ( letter | "_" ) { letter | digit | "_" } ;
DIGITS = digit { digit } ;
The scanner removes comments beginning with # at a word boundary, performs
quote removal, variable expansion, tilde expansion, command substitution, and
globbing, and then yields WORD tokens plus operator tokens. The parser groups
these tokens into the structures above.
Scripting language
Source files
A Blood script is a sequence of bytes. The conventional extensions are
.blood and .bx. Extensions are not enforced. A leading shebang
line is
treated as a comment because it begins with #.
Scripts are executed by blood SCRIPT.blood or blood SCRIPT.bx, by
the
source shell builtin, by the script source function, by
startup_file,
and by the interactive shell when a submitted line has the shape of a script
statement.
Interactive submissions retain their global variables and function definitions
for the lifetime of the shell. source and script files executed from the
shell share the same global environment.
Lexical structure
Encoding and identifiers
Source is a byte sequence. Identifiers are ASCII:
IDENT = ( letter | "_" ) { letter | digit | "_" } ;
letter = "A".."Z" | "a".."z" ;
digit = "0".."9" ;
Identifiers are case sensitive. Keyword matching is case sensitive.
Whitespace and comments
Spaces and tabs separate tokens. A # outside a string begins a comment that
extends to the next line feed. Blank lines and comment-only lines do not affect
block structure.
Numeric literals
INT = digit { digit } ;
FLOAT = digit { digit } ( "." digit { digit } [ exponent ] | exponent ) ;
exponent = ( "e" | "E" ) [ "+" | "-" ] digit { digit } ;
Integer literals are decimal signed 64-bit values. Floating-point literals use
the platform double representation. Hexadecimal, binary, octal, digit
separators, and suffixes are not implemented. A leading decimal point is not
part of a numeric literal; .5 is not a float.
String literals
Strings are delimited by either single or double quotation marks. Both forms behave identically: escape processing and interpolation apply to both.
Recognised escapes are:
| Escape | Meaning |
|---|---|
|
|
Line feed. |
|
|
Horizontal tab. |
|
|
Carriage return. |
|
|
NUL byte. |
|
|
Byte with hexadecimal value HH. |
|
|
Double quote. |
|
|
Single quote. |
|
|
Backslash. |
A backslash before any other byte yields that byte. A literal line feed is accepted inside a string.
String interpolation occurs for both quote forms. { begins an interpolation
field. The field ends at the matching }. Braces and quotes inside the field
are balanced by the interpolation scanner. {{ produces a literal
{ and
}} produces a literal }. The text between the braces is parsed
as a Blood
expression and evaluated in the current environment; its value is converted to
a string and inserted.
Interpolation errors use the location information of the inner expression and may not reflect the outer source line.
Command substitution literals
Outside strings, and COMMANDS $(COMMANDS) denote
command
substitution. They are lexed as a single expression token. The commands are
executed by the shell in a child process, trailing newlines are removed, and
the result is a string value. The completion status becomes the value of the
script variable status.
Blocks
Blocks are introduced by braces. The opening brace follows the header of a compound statement and the matching closing brace ends its body:
if CONDITION {
BLOCK
}
Newlines and indentation are ignored inside unmatched ( and [
delimiters
and inside dictionary literals. This permits multiline lists, dictionaries,
and call arguments.
A semicolon ; may separate simple statements on one line. A single-line
suite may also follow the opening brace.
The older Python-like style, which introduced blocks with a trailing colon and indentation, is deprecated. It remains accepted for compatibility, but new scripts should use braces. A single source file must use one style consistently.
Keywords
The following identifiers are treated as keywords at the start of a statement or in expression position:
if elif else while for in fn return break continue pass try catch except raise throw say true false null none not and or
none is accepted as an alias for null.
Values
The runtime value types are:
| Type | Representation and behaviour |
|---|---|
|
null |
The absence of a value. Written |
|
bool |
|
|
int |
Signed 64-bit integer. |
|
float |
IEEE 754 double. |
|
string |
Byte string. Strings are immutable; operations produce new strings. |
|
list |
Ordered, mutable sequence of values. |
|
dict |
Mutable string-keyed map. Iteration order is unspecified. |
|
function |
User-defined or native callable. |
Lists and dictionaries are reference values. Assigning a list or dictionary to another variable aliases the same object; there is no implicit copy.
Expressions
Precedence
From lowest to highest:
| Level | Operators |
|---|---|
|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
|
|
6 |
|
|
7 |
unary |
|
8 |
call |
Only one comparison operator is accepted at a given level; chained
comparisons such as a < b < c are not supported. Parentheses override
precedence.
Primary expressions
-
Integer, float, and string literals.
-
true,false,null, andnone. -
Variable references.
-
Parenthesised expressions.
-
List literals:
[e1, e2, …]. -
Dictionary literals:
key1: value1, key2: value2, …inside braces. -
Command substitutions.
Calls, indexing, and attributes
Calls have the form callee(arg1, arg2, …). A trailing comma is
permitted.
Missing arguments are bound as null; extra arguments are ignored by
user-defined functions.
Indexing has the form container[index]. Lists accept integers, including
negative indices from the end. Dictionaries accept string keys; non-string
keys are converted to strings. Strings accept a byte offset, including negative
offsets, and return the UTF-8 sequence beginning at that offset.
Attribute access has the form container.name. On a dictionary it reads the
value for key name; a missing key yields null. On other values, plain
attribute access yields null. Attribute assignment dict.name = value is
supported for dictionaries.
Operators
| Operator | Semantics |
|---|---|
|
|
Numeric addition. If either operand is a string, concatenate their string representations. If both operands are lists, produce a new concatenated list. |
|
|
Numeric subtraction. |
|
|
Numeric multiplication. |
|
|
Division. Integer division truncates when both operands are non-float. Division by zero raises a catchable error. |
|
|
Integer remainder. Division by zero raises a catchable error. |
|
|
Equality. Nulls are equal. Numeric values compare across int, float, and bool. Strings compare by content. Lists compare deeply. Dictionaries and functions compare by identity. |
|
|
If either operand is a string, compare string representations lexicographically. Otherwise compare numerically. |
|
|
Short-circuit conjunction. Returns the left operand when it is falsy; otherwise returns the right operand. |
|
|
Short-circuit disjunction. Returns the left operand when it is truthy; otherwise returns the right operand. |
|
|
Logical negation, producing a bool. |
|
|
Membership. Lists use equality. Dictionaries test keys. Strings test substrings. |
|
|
Negated membership. |
Unary - negates numerically. Unary + is accepted and has no
effect.
Truthiness
null and false are false. Numeric zero is false. The empty
string, empty
list, and empty dictionary are false. All other values are true.
Interpolation
String interpolation is equivalent to evaluating each {…} field
and
concatenating its string representation. The current lexical environment is
used, including function parameters and local variables.
Statements
Assignment
NAME = expression
PLACE += expression
PLACE -= expression
PLACE *= expression
PLACE /= expression
PLACE %= expression
PLACE may be a variable, an index expression, or a dictionary attribute.
Assignments are statements, not expressions. Chained assignment is not
supported.
If the target variable does not exist in the current environment chain, it is created in the current scope. If it exists in an enclosing scope, that binding is updated.
say
say [expression {, expression}]
Evaluates each expression, converts each to a string, joins them with a single space, and writes the result followed by a newline to standard output. With no expressions, writes a newline.
say is a statement, not a function.
Conditionals
if CONDITION {
BLOCK
} elif CONDITION {
BLOCK
} else {
BLOCK
}
The first true branch is executed. elif is the only spelling for an
additional condition; else if is not part of the language. A single-line
suite after the opening brace is accepted.
Loops
while CONDITION {
BLOCK
}
for NAME in EXPRESSION {
BLOCK
}
while reevaluates its condition before each iteration. for
iterates over
the elements of a list, the UTF-8 code points of a string, or the keys of a
dictionary. break and continue affect the innermost loop.
There is no C-style for, no do, and no loop
statement.
Parallel loops
para for NAME in EXPRESSION {
BLOCK
}
para for evaluates EXPRESSION once and runs the body for each
element in a
separate child process. Iterations run concurrently. Each child starts from a
copy of the parent’s variables, with NAME bound to its element and
status
reset to 0; assignments made inside the body are visible only within that
child and do not propagate back to the parent. Output from iterations may
interleave.
After every iteration has finished, the loop waits for all children and
assigns the first non-zero iteration status to status. An iteration’s
status
is its final status value, or the argument passed to exit. An
uncaught
error in an iteration reports the error and makes that iteration fail without
aborting the remaining iterations. para for does not support
break or
continue. On platforms without fork, the statement reports an
error.
Functions
fn NAME(PARAM1, PARAM2, ...) {
BLOCK
}
Parameters are positional. Type annotations may be written after a parameter name and are ignored. A function body uses the global environment as its parent, not the environment of its definition; Blood has no closures. Functions may be recursive. The recursion depth is limited to 200 nested user-function calls.
return with no value returns null. A function that reaches the end of its
body returns null. Extra arguments are ignored; missing arguments are null.
Exceptions
try {
BLOCK
} catch NAME {
BLOCK
}
except may be used in place of catch. The catch variable is
optional and
receives the error message as a string. A caught error clears the error state
and execution continues after the try statement.
raise EXPRESSION
throw EXPRESSION
Both spellings raise a runtime error whose message is the string
representation of the expression. If the expression is omitted, the message is
the string representation of null, namely null.
Other statements
-
passdoes nothing. -
breakexits the innermost loop. -
continuebegins the next iteration of the innermost loop. -
Shell command statements execute the command line in the shell and assign the resulting status to
status.
Shell command statements
A statement that does not match a scripting statement is treated as a shell command when it has a command-like shape. The current implementation uses a lookahead heuristic:
-
A leading identifier followed by an opening parenthesis, bracket, dot, or an assignment operator is an expression or assignment.
-
A leading identifier followed by another identifier, literal, or most operators is a shell command.
-
A statement beginning with
/,., or~is a shell command. -
Lines beginning with
if,while,for,fn,try,catch,except,raise,throw,say,return,break,continue, orpassare scripting statements.
The entire remaining source line is passed to the shell command interpreter. This permits pipelines, redirections, and command substitution without a wrapper.
Scoping and environment
Each function call creates a new environment. The global environment is the shared script state. A name lookup proceeds from the current environment through parent environments. Because function environments have the global environment as their parent, a function can read and update global variables but cannot capture local variables of a caller.
A binding created by for is assigned in the current environment and is
visible after the loop.
Error handling and diagnostics
Syntax errors are detected before execution. A syntax error prints:
blood: LABEL:LINE:COL: MESSAGE
where LABEL is the script path, stdin, or -c, and
execution of the script
aborts with status 2.
Runtime errors print the same form and abort the script with status 1 unless
caught by try. An interactive script interrupted by SIGINT is reported as
status 130 without printing the message interrupted.
Runtime error messages include, among others:
-
undefined variable 'NAME' -
attempt to call a non-function value -
list index out of range -
string index out of range -
value is not indexable -
value does not support attribute assignment -
division by zero -
unknown method 'NAME' -
recursion limit exceeded -
interrupted
Standard variables
| Name | Meaning |
|---|---|
|
|
Status of the most recent shell command, command substitution, or shell-valued operation in the script. Initialised to 0. |
|
|
List of command-line arguments passed after the script name. |
|
|
Path of the currently executing script, set by script file execution. |
|
|
The null value. |
|
|
Boolean values. |
status is also updated after a command substitution and after a shell
command statement. A failed shell command does not raise a script error; it
sets status.
Builtin functions
The following names are predefined in the global environment. They are ordinary function values and may be shadowed.
| Function | Arity | Behaviour |
|---|---|---|
|
|
1 |
Length of a list, dictionary, or string. String length is bytes. For other values, length of the string representation. |
|
|
1 |
String representation. |
|
|
1 |
Convert to integer. |
|
|
1 |
Convert to float. |
|
|
1 |
Truthiness as a boolean. |
|
|
1 or 2 |
List of integers from |
|
|
variadic |
Join arguments with spaces, append newline, write to standard output. Returns null. |
|
|
0 or 1 |
Write prompt if supplied, read one line from standard input. Returns a string, or null on end of input. |
|
|
1 |
Sleep for the given number of milliseconds. |
|
|
0 or 1 |
Request shell exit with the given status. Default 0. |
|
|
1 |
Execute a shell command line and return its status. |
|
|
1 |
Execute a shell command line and return its captured standard output. |
|
|
1 |
Execute a Blood script file and return its status. |
|
|
1 |
Absolute numeric value, returned as a float. |
|
|
1 or 2 |
Minimum of a list, or of two values. With a list, returns the smallest element. |
|
|
1 or 2 |
Maximum of a list, or of two values. |
|
|
1 |
Sum of numeric elements, returned as a float. |
|
|
1 |
Type name: |
|
|
1 |
List of dictionary keys. |
|
|
1 |
List of dictionary values. |
|
|
1 |
List of |
|
|
1 |
Expand a pathname pattern and return a sorted list of
matching paths. An unmatched pattern yields an empty list. A leading
|
|
|
2 |
Rename or move a path. Returns a boolean. A leading
|
|
|
1 |
Read a file. Returns a string or null. |
|
|
2 |
Write a file. Returns a boolean. |
|
|
2 |
Append to a file. Returns a boolean. |
|
|
1 |
Read an environment variable. Returns a string or null. |
|
|
0 |
Milliseconds since the Unix epoch. |
|
|
1 |
One-byte string containing the low byte of |
|
|
1 |
Integer value of the first byte of |
keys, values, and items return empty lists when
applied to a non-dict
value. read_file and write_file expand a leading ~ in
the path.
Methods
Method calls use the attribute syntax value.name(arguments).
List methods
| Method | Arity | Behaviour |
|---|---|---|
|
|
1 |
Append x. Returns null. |
|
|
0 |
Remove and return the last element, or null when empty. |
|
|
0 |
Number of elements. |
|
|
2 |
Insert x at index i. |
|
|
1 |
Remove the element at index i. |
|
|
1 |
Membership by equality. |
|
|
1 |
Join string representations with separator
|
|
|
0 |
Sort in place by string representation. |
Dictionary methods
| Method | Arity | Behaviour |
|---|---|---|
|
|
1 or 2 |
Value for key, or default/null. |
|
|
2 |
Set a key. |
|
|
1 |
Key membership. |
|
|
0 |
List of keys. |
|
|
0 |
List of values. |
|
|
0 |
List of |
|
|
0 |
Number of keys. |
|
|
1 |
Remove a key. |
Any other method call on a dictionary inserts the first argument as the value for the method name and returns null. This is an implementation quirk; named keys should normally be accessed with indexing or assignment.
String methods
| Method | Arity | Behaviour |
|---|---|---|
|
|
0 |
ASCII uppercase. |
|
|
0 |
ASCII lowercase. |
|
|
0 |
Remove leading and trailing ASCII whitespace. |
|
|
1 |
Split on |
|
|
1 |
Prefix test. |
|
|
1 |
Suffix test. |
|
|
1 |
Substring test. |
|
|
2 |
Replace all occurrences. |
|
|
0 |
Byte length. |
|
|
0 |
List of UTF-8 code points as strings. |
|
|
1 |
Join a list with the receiver as separator. |
Numeric methods
Integers and floats provide abs(), returning a float.
Script grammar
The following grammar describes the scripting language accepted by the
implementation. Indentation terminals INDENT, DEDENT,
NEWLINE, and EOF
are produced by the lexer as described above. SHELL is a statement produced
by the heuristic described in [shell-command-statements]. STRING is
a
string literal, including interpolation text. CMDSUB is a command
substitution token.
Lexical grammar
letter = "A".."Z" | "a".."z" ;
digit = "0".."9" ;
IDENT = ( letter | "_" ) { letter | digit | "_" } ;
INT = digit { digit } ;
FLOAT = digit { digit }
( "." digit { digit } [ exponent ] | exponent ) ;
exponent = ( "e" | "E" ) [ "+" | "-" ] digit { digit } ;
STRING = "'" { string-byte } "'"
| '"' { string-byte } '"' ;
CMDSUB = "`" { any-byte } "`"
| "$(" { any-byte } ")" ;
The lexer emits NEWLINE, INDENT, and DEDENT
according to the indentation
rules. In the deprecated colon style it ignores newlines and indentation while
the delimiter depth is greater than zero. In the brace style it emits no
INDENT or DEDENT tokens and newlines separate statements
inside braces.
Syntactic grammar
program = { NEWLINE | INDENT | DEDENT | statement } EOF ;
statement = say-stmt
| return-stmt
| break-stmt
| continue-stmt
| pass-stmt
| raise-stmt
| if-stmt
| while-stmt
| for-stmt
| para-for-stmt
| fn-stmt
| try-stmt
| assignment
| expression-stmt
| SHELL ;
suite = "{" { NEWLINE | INDENT | DEDENT | ";" | statement } "}"
| ":" ( NEWLINE INDENT { statement } DEDENT
| inline-stmt { ";" inline-stmt } [ NEWLINE ] ) ;
inline-stmt = say-stmt | return-stmt | break-stmt | continue-stmt
| pass-stmt | raise-stmt | assignment | expression-stmt ;
say-stmt = "say" [ expression { "," expression } ] [ NEWLINE ] ;
return-stmt = "return" [ expression ] [ NEWLINE ] ;
break-stmt = "break" [ NEWLINE ] ;
continue-stmt= "continue" [ NEWLINE ] ;
pass-stmt = "pass" [ NEWLINE ] ;
raise-stmt = ( "raise" | "throw" ) [ expression ] [ NEWLINE ] ;
if-stmt = "if" expression suite
{ "elif" expression suite }
[ "else" suite ] ;
while-stmt = "while" expression suite ;
for-stmt = "for" IDENT "in" expression suite ;
para-for-stmt = "para" "for" IDENT "in" expression suite ;
fn-stmt = "fn" IDENT "(" [ param { "," param } [ "," ] ] ")" suite ;
param = IDENT [ ":" type-text ] ;
try-stmt = "try" suite ( "catch" | "except" ) [ IDENT ] suite ;
assignment = expression assign-op expression [ NEWLINE ] ;
assign-op = "=" | "+=" | "-=" | "*=" | "/=" ;
expression-stmt = expression [ NEWLINE ] ;
expression = or-expr ;
or-expr = and-expr { "or" and-expr } ;
and-expr = not-expr { "and" not-expr } ;
not-expr = "not" not-expr | comparison ;
comparison = additive
[ ( "==" | "!=" | "<" | ">" | "<=" | ">="
| "in" | "not" "in" ) additive ] ;
additive = multiplicative { ( "+" | "-" ) multiplicative } ;
multiplicative = unary { ( "*" | "/" | "%" ) unary } ;
unary = ( "-" | "+" ) unary | postfix ;
postfix = primary { call | index | attribute } ;
call = "(" [ expression { "," expression } [ "," ] ] ")" ;
index = "[" expression "]" ;
attribute = "." IDENT ;
primary = INT
| FLOAT
| STRING
| CMDSUB
| "true"
| "false"
| "null"
| "none"
| IDENT
| "(" expression ")"
| list-literal
| dict-literal ;
list-literal = "[" [ expression { "," expression } [ "," ] ] "]" ;
dict-literal = "{" [ expression ":" expression
{ "," expression ":" expression } [ "," ] ] "}" ;
type-text is accepted and skipped by the parser; type annotations have no
runtime effect. A SHELL statement is recognised by the statement-start
heuristic and consumes the remainder of the source line.
Evaluation order
Expressions are evaluated left to right except where short-circuit operators skip the right operand. Function arguments are evaluated left to right. Dictionary literal entries are evaluated in source order; iteration order after construction is unspecified.
A runtime error sets the error state and stops normal evaluation. try catches
the error at the nearest enclosing try statement. A return,
break,
continue, or exit is not an error and is not caught by
try.
Limits
-
Maximum user-function recursion depth: 200.
-
Maximum displayed completion candidates: 200.
-
History maximum: controlled by configuration.
-
Integer arithmetic is signed 64-bit and is not overflow checked.
-
Floating-point arithmetic follows the platform double implementation.
-
Strings are byte strings; UTF-8 is handled specially only by code-point iteration, string indexing boundaries, and the line editor.
Diagnostics
Configuration diagnostics
Configuration diagnostics are written to standard error and do not stop the shell:
blood: config: /path/to/blood.ini
line N: expected key = value
blood: config: invalid boolean 'VALUE'
blood: config: invalid integer for KEY
Shell diagnostics
Shell diagnostics are written to standard error:
blood: NAME: command not found
blood: PATH: cannot open for reading
blood: PATH: cannot open for writing
blood: cd: PATH: no such directory
blood: source: PATH: no such file
blood: alias: NAME: not found
blood: fork failed
Syntax errors in the command language produce status 2. Unknown commands produce status 127. Failed redirections and failed builtins produce status 1.
Script diagnostics
Script syntax and runtime diagnostics have the form:
blood: LABEL:LINE:COL: MESSAGE
For interactive submissions the label is empty, yielding:
blood: LINE:COL: MESSAGE
Interactive messages
Ctrl-C while editing prints ^C and returns to a new prompt. Ctrl-D on an
empty line ends the session. A cancelled completion menu or search does not
execute a command.
Performance characteristics
The implementation is designed to avoid unnecessary process creation:
-
Builtins execute in the shell process outside pipelines.
-
Simple external commands fork and exec directly;
/bin/shis not used as an intermediary. -
Pipelines fork only the stages that are required.
-
Command substitution uses the Blood parser in a child process.
-
Prompt Git information is cached for 1500 milliseconds.
-
The
PATHexecutable index used by completion is built lazily and cached. -
Prompt text is rendered once per command, not once per keystroke.
-
The line editor is byte-oriented and redraws only the prompt line and menu.
-
History appends one entry per command and rewrites the file on exit.
The implementation does not use an arena for shell command parsing. Temporary command structures and script values are allocated from the C heap and are not generally reclaimed during the lifetime of the process. This is a known limitation of version 0.1.0.
Known limitations and deviations
The following behaviours are intentional or currently unimplemented and are part of the implemented contract:
-
The build targets Linux with a POSIX-style C library. The directory-entry layout and terminal handling are Linux-oriented.
-
The prompt has two effective layouts: the default box layout and the
plainlayout. Otherthemevalues are treated as default. -
show_mode,separator,color_success, anddefault_editorare parsed and stored but have no current rendering or builtin effect. -
$@,$*, positional parameters beyond$0, arrays, and associative shell arrays are not implemented. -
~useris not resolved. -
Glob expansion does not support brace expansion, recursive
**, or extglob. -
Aliases are expanded for single-command input and not as stages of a multi-command pipeline.
-
There are no heredocs, here-strings, process substitution,
|&, or arbitrary descriptor redirections beyond2>&N. -
The scripting language has no classes, modules, imports, closures, comprehensions, generators, decorators, lambdas, slicing, keyword arguments, default parameters, varargs,
with,assert,del,global, oris. -
Type annotations on function parameters are syntactically accepted but ignored.
-
Single-quoted and double-quoted strings both interpolate.
-
Integer division truncates toward zero. There is no floor-division operator.
-
Dictionaries are unordered. Dictionary and function equality is identity equality.
-
List and dictionary assignment aliases the object; there is no copy-on-write or deep copy.
-
String length and
ord/chrare byte-oriented. String indexing advances by UTF-8 code points only at index boundaries. -
The line editor counts display width in code points, not terminal cells.
-
The shell does not attempt to free most per-command allocations.
Examples
Interactive shell
$ blood
╭─ blood 0.1.0 — type help for commands, help script for the language.
┌─ user@host ~/src (main *)
└─ ❯ echo hello | tr a-z A-Z
HELLO
┌─ user@host ~/src (main *)
└─ ❯ for item in ["one", "two"] {
… say item
… }
Command language
# Pipelines
ls -l | grep '\.sx$'
# Redirection
echo hello > out.txt
cat out.txt >> all.txt
command 2> errors.txt
# Command substitution
echo "time is $(date +%H:%M)"
# Background execution
sleep 5 &
jobs
# Environment assignment
EDITOR=vim command
export EDITOR=vim
unset EDITOR
Scripting language
name = "Blood"
version = 1
say "Welcome to {name} {version}"
for item in ["one", "two", "three"] {
say item
}
fn greet(person) {
return "Hello, " + person
}
say greet("world")
if version > 0 {
say "positive"
} elif version == 0 {
say "zero"
} else {
say "negative"
}
try {
raise "example failure"
} catch message {
say "caught: {message}"
}
output = `printf "a\nb\n"`
say output
say "status is {status}"
shell("true")
Appendix: default settings
| Section | Key | Default |
|---|---|---|
|
prompt |
theme |
|
|
prompt |
show_username |
|
|
prompt |
show_hostname |
|
|
prompt |
show_directory |
|
|
prompt |
show_git |
|
|
prompt |
show_time |
|
|
prompt |
show_exit_status |
|
|
prompt |
show_duration |
|
|
prompt |
show_jobs |
|
|
prompt |
show_mode |
|
|
prompt |
two_line |
|
|
prompt |
directory_style |
|
|
prompt |
prompt_symbol |
|
|
prompt |
prompt_char |
|
|
prompt |
separator |
|
|
colors |
primary |
|
|
colors |
secondary |
|
|
colors |
success |
|
|
colors |
error |
|
|
colors |
directory |
|
|
colors |
git_clean |
|
|
colors |
git_dirty |
|
|
colors |
muted |
|
|
colors |
warning |
|
|
colors |
accent |
|
|
history |
enabled |
|
|
history |
file |
|
|
history |
max_entries |
|
|
history |
ignore_duplicates |
|
|
completion |
enabled |
|
|
completion |
case_sensitive |
|
|
shell |
default_editor |
|
|
shell |
login_message |
|
|
shell |
startup_file |
empty |