Marslang language and API reference#

This reference describes the Rust interpreter as of rs-0.11.1, including dynamic numeric type tracking and the expanded std.math package. The source extension is .mars; earlier releases used .mrs. Use the matching source checkout for the filenames documented here. These API documents and release notes are eligible for Git tracking. Discussion notes elsewhere under docs/ remain local.

Reference#

• Language syntax: variables, functions, families, and control flow.
• Grammar: exactly what may be written, and operator precedence.
• Strings and slicing: Unicode characters, reversal, and strict bounds.
• Collections: arrays, sets, pairs, maps, and copying.
• Dates and times: date, datetime, and duration, with time zones.
• Async and await: tasks that wait without blocking each other, with async func and await.
• Built-ins and errors: input/output, conversions, and runtime errors.
• std.math: 51 math functions and six constants, written in Marslang on native float primitives.
• std.containers: stack, queue, deque, and priority queue.
• std.algorithms: sorting by a key or a comparison, binary search, and the usual collection passes.
• std.stats: mean, median, mode, quantiles, spread, and correlation.
• std.random: random numbers, choices, shuffles, samples, weights, and seeds.
• std.strings: splitting, searching, trimming, case, and padding.
• std.regex: regular expressions: checking, finding, replacing, and splitting by pattern.
• std.format: decimal places, thousands, percentages, aligned columns, and tables.
• std.testing: assertions, and marslang test, which runs every test_ function.
• std.bigint: integers of any size, the bigint kind, and gcd, factorial, and bases.
• std.encoding: base64, hex, URL encoding, query strings, and bytes.
• std.hash: SHA-256, SHA-512, SHA-1, MD5, and CRC-32 of text and files, and HMAC.
• std.http: fetching pages, calling JSON APIs, and downloading files, over HTTPS.
• std.log: leveled logging with timestamps, to standard error or a file.
• std.terminal: colours and styles, the terminal's size, and progress bars.
• std.sqlite: SQL databases in a file or in memory, with parameters and transactions.
• std.secrets: secure tokens, passwords, and choices, for anything an attacker must not guess.
• std.async: sleep, all, race, timeout, and cancelling tasks.
• std.broadcast: channels that send messages within a program, to this computer's programs, or across the network.
• std.process: running other programs with no shell, their output and exit codes.
• std.uuid: random (v4) and time-ordered (v7) UUIDs.
• std.types: a value's kind, family checks.
• std.memory: addresses, object identity, and the cycle collector.
• std.file: reading, writing, listing, copying, moving, and removing files and directories.
  • std.file.path: joining and splitting paths, names, and extensions.
  • std.file.csv: reading and writing CSV tables, with any separator.
  • std.file.env: .env files of KEY=value lines.
  • std.file.ini: INI files of [sections] and key = value lines.
  • std.file.toml: TOML files, as Cargo and Python projects use them.
• std.json: reading and writing JSON, as text and as files.
• std.os: environment variables, the working and home directories, and the platform.
• std.sys: the interpreter's version, number limits, and package directory.
• std.time: clocks, today's date, sleeping, and lengths of time.
• std.Decorator: @Decorator.docstring, and @Decorator.private and @Decorator.subclass methods.
• std.Error: the built-in error families as Error.TypeError, Error.RangeError, and so on.
• std.cli: command-line arguments, a parser for options, and exit statuses.

Install#

Released builds need no Rust toolchain and install into your home directory:

irm https://marslang.kevin-z.com/install.ps1 | iex

curl -fsSL https://marslang.kevin-z.com/install.sh | sh

Both accept --use std,ext (-Use in PowerShell) for the package sets to install; std is built into the interpreter, and ext is not published yet. marslang pkgs prints where packages you install are imported from.

For editing, vscode-marslang gives Visual Studio Code highlighting for .mars files and shows what marslang check reports as you save.

Run#

From an installed interpreter, or with Rust from the repository root:

marslang docs/api/examples/strings.mars
cargo run -- docs/api/examples/strings.mars

The runnable example prints:

CDE
EDCBA
ABCDE
3
é👨‍👩‍👧‍👦
0

Use cargo test to run the execution tests, which run programs in the interpreter and check their output. The example above is also an execution test.

Current limits#

Programs run in a Rust tree-walking interpreter. The language is not self-hosted yet. Additional standard-library packages and the remaining decorators (static, class, overload) remain unimplemented. Async has its core: tasks, async func, await, std.async's timers, and std.http, time.sleep, and std.process, which wait without blocking other tasks; reading input with in still blocks them. General named arguments are deferred; only slicing accepts reverse=. Proposed packages are not APIs.

The lex command uses a separate lexer from the parser. The REPL reruns its accumulated source rather than retaining a persistent runtime; it shows only new output.