Crate uiua

Expand description

The Uiua programming language

This is the crate so you can use Uiua as a Rust library. If you just want to write programs in Uiua, you can check out uiua.org or the GitHub repo.

§Usage

The uiua crate is set up primarily to be installed as a binary. For this reason, when using it as a library, you’ll likely want to disable default features.

This disables some of the features that many users are used to having, so to re-enable things like regex and media encoding, you can enable the batteries feature.

# Cargo.toml
[dependencies]
uiua = { version = "*", default-features = false, features = ["batteries"] }

The main entry point is the Uiua struct, which is the Uiua runtime. It must be created with a SysBackend. Uiua::with_native_sys is a convenient way to create a Uiua runtime that uses the same backend as the Uiua CLI, though keep in mind it gives full access to the filesystem and TCP sockets and so probably shouldn’t be used in a sandboxed environment.

Value is the generic value type. It wraps one of five Array types.

You can run Uiua code with Uiua::run_str or Uiua::run_file.

use uiua::*;

let mut uiua = Uiua::with_native_sys();
uiua.run_str("&p + 1 2").unwrap();

You can push values onto the stack with Uiua::push. When you’re done, you can get the results with Uiua::pop, Uiua::take_stack, or one of numerous pop+conversion convenience functions.

use uiua::*;

let mut uiua = Uiua::with_native_sys();
uiua.push(1);
uiua.push(2);
uiua.run_str("+").unwrap();
let res = uiua.pop_int().unwrap();
assert_eq!(res, 3);

Sometimes, you need to configure the compiler before running.

You can create a new compiler with Compiler::new. Strings or files can be compiled with Compiler::load_str or Compiler::load_file respectively. You can get the compiled assembly with Compiler::finish and run it with Uiua::run_asm.

use uiua::*;

let mut comp = Compiler::new();
comp.print_diagnostics(true);
let asm = comp.load_str("+ 3 5").unwrap().finish();

let mut uiua = Uiua::with_native_sys();
uiua.run_asm(asm).unwrap();
let res = uiua.pop_int().unwrap();
assert_eq!(res, 8);

This can be shortened a bit with Uiua::compile_run.

use uiua::*;

let mut uiua = Uiua::with_native_sys();
uiua.compile_run(|comp| {
    comp.print_diagnostics(true).load_str("+ 3 5")
});

You can create and bind Rust functions with Compiler::create_function, Compiler::bind_function, and Compiler::create_bind_function

use uiua::*;

let mut comp = Compiler::new();
comp.create_bind_function("MyAdd", (2, 1), |uiua| {
    let a = uiua.pop_num()?;
    let b = uiua.pop_num()?;
    uiua.push(a + b);
    Ok(())
}).unwrap();
comp.load_str("MyAdd 2 3").unwrap();
let asm = comp.finish();

let mut uiua = Uiua::with_native_sys();
uiua.run_asm(asm).unwrap();
let res = uiua.pop_num().unwrap();
assert_eq!(res, 5.0);

Bindings can be retrieved with Uiua::bound_values or Uiua::bound_functions.

use uiua::*;

let mut uiua = Uiua::with_native_sys();
uiua.run_str("
    X ← 5
    F ← +1
").unwrap();

let x = uiua.bound_values().remove("X").unwrap();
assert_eq!(x.as_int(&uiua, None).unwrap(), 5);

let f = uiua.bound_functions().remove("F").unwrap();
let mut comp = Compiler::new().with_assembly(uiua.take_asm());
comp.create_bind_function("AddTwo", (1, 1), move |uiua| {
    uiua.call(&f)?;
    uiua.call(&f)
}).unwrap();
comp.load_str("AddTwo 3").unwrap();
uiua.run_asm(comp.finish()).unwrap();
let res = uiua.pop_int().unwrap();
assert_eq!(res, 5);

You can format Uiua code with the format module.

use uiua::format::*;

let input = "resh3_4rang12";
let config = FormatConfig::default().with_trailing_newline(false);
let formatted = format_str(input, &config).unwrap().output;
assert_eq!(formatted, "↯3_4⇡12");

§Features

The uiua crate has the following noteable feature flags:

batteries: Enables the following features:
- regex: Enables the regex function
- image: Enables image encoding and decoding
- gif: Enables GIF encoding and decoding
- audio_encode: Enables audio encoding and decoding
native_sys: Enables the NativeSys backend. This is the default backend used by the interpreter.
audio: Enables audio features in the NativeSys backend.
https: Enables the &httpsw system function
invoke: Enables the &invk system function
trash: Enables the &ftr system function
raw_mode: Enables the &raw system function

Re-exports§

pub use self::lsp::SpanKind;
pub use self::lsp::Spans;

Modules§

ast: Uiua’s abstract syntax tree
encode: En/decode Uiua arrays to/from media formats
format: The Uiua formatter
lsp: Uiua’s Language Server Protocol (LSP) implementation

Macros§

val_as_arr: Operate on a value as an array

Structs§

Array: Uiua’s array type
ArrayFlags: Flags for an array
ArrayMeta: Non-shape metadata for an array
Assembly: A compiled Uiua assembly
BindingCounts: Character counts for a binding
BindingInfo: Information about a binding
BindingMeta: Metadata about a binding
Boxed: The element type for box arrays
CodeSpan: A span in a Uiua source file
Compiler: The Uiua compiler
Complex: Uiua’s complex number type
ConstantDef: The definition of a shadowable constant
CustomInverse: A custom inverse node
DefInfo: Information for a data definition
Diagnostic: A message to be displayed to the user that is not an error
DocComment: A comment that documents a binding
DocCommentArg: An argument in a doc comment signature
DocCommentSig: A signature in a doc comment
DynamicFunction: A function that executes Rust code
FormatPrimitive: A wrapper that nicely prints a Primitive
FormatShape: A formattable shape
Function: A Uiua function
Handle: A handle to an IO stream
HashLabels: A wrapper for values that hashes their labels in addition to the normal hashing
Inputs: A repository of code strings input to the compiler
Loc: A location in a Uiua source file
LocalName: The index of a named local in the bindings, and whether it is public
MetaPtr: Array pointer metadata
Module: A Uiua module
NativeSys: The default native system backend
PersistentMeta: Array metadata that can be persisted across operations
PrimDoc: Documentation for a primitive
PrimExample: An primitive code example
PrimNames: The names of a primitive
Report: A rich-text error/diagnostic report
SafeSys: A safe backend with no IO other than captured stdout and stderr
Shape: Uiua’s array shape type
SigNode: A node with a signature
Signature: A function stack signature
Sp: A span wrapping a value
TraceFrame: A frame in a trace
Uiua: The Uiua interpreter
UiuaError: An error produced when running/compiling/formatting a Uiua program

Enums§

ArrayLen: The length of an array when being constructed
AsciiToken: An ASCII lexical token
BindingKind: A kind of global binding
ConstClass: Kinds of shadowable constants
ConstantValue: The value of a shadowable constant
DiagnosticKind: Kinds of non-error diagnostics
FfiType: Types for FFI
FunctionId: A Uiua function id
GitTarget: A target for a git repository
HandleKind: The kind of a handle
InputSrc: The source of code input into the interpreter
LexError: An error that occurred while lexing
Node: A Uiua execution tree node
ParseError: An error that occurred while parsing
PreEvalMode: The mode that dictates how much code to pre-evaluate at compile time
PrimClass: Categories of primitives
PrimDocFragment: A pseudo-markdown fragment for primitive documentation
PrimDocLine: A line in a primitive’s documentation
Primitive: A built-in function
Purity: Levels of purity for an operation
ReportFragment: A text fragment of a report
ReportKind: Kinds of reports
RunMode: A mode that affects how non-binding lines are run
SemanticComment: The kinds of semantic comments
Span: A runtime span in a Uiua source file
SysOp: A system function
SysOpClass: Categories of system functions
Token: A Uiua lexical token
UiuaErrorKind: The kind of an error produced when running/compiling/formatting a Uiua program
Value: A generic array value

Constants§

EXAMPLE_TXT: The text of Uiua’s example text file
EXAMPLE_UA: The text of Uiua’s example module
SUBSCRIPT_DIGITS: Subscript digit characters
VERSION: The Uiua version
WILDCARD_CHAR: A character value used as a wildcard that will equal any character
WILDCARD_NAN: A NaN value that always compares as equal

Statics§

CONSTANTS: The list of all shadowable constants
DEFAULT_META: Default metadata for an array

Traits§

ArrayCmp: Trait for comparing array elements
ArrayValue: A trait for types that can be used as array elements
ExactDoubleIterator: A combination of ExactSizeIterator and DoubleEndedIterator
Exec: Things that can be executed
IntoInputSrc: A trait for types that can be converted into an InputSrc
IntoSysBackend: Trait for converting to a system backend
RealArrayValue: Trait for ArrayValues that are real numbers
SendSyncNative: Supertrait for Send and Sync on native targets, but not on wasm32
StackArg: A trait for types that can be used as argument specifiers for Uiua::pop
SysBackend: Trait for defining a system backend

Functions§

example_txt: Access the built-in example.txt file
example_ua: Access the built-in example.ua file
ident_modifier_args: Get the number of modifier arguments implied by an identifier
is_custom_glyph: Whether a string is a custom glyph
is_ident_char: Whether a character can be part of a Uiua identifier
is_ident_start: Whether a character can be among the first characters of a Uiua identifier
lex: Lex a Uiua source file
now: Get the current time in seconds
parse: Parse Uiua code into an AST
random: Generate a random number, equivalent to Primitive::Rand
seed_random: Seed the random number generator

Type Aliases§

AudioStreamFn: The function type passed to &ast
Ident: A Uiua identifier
ReadLinesFn: The function type passed to &rl’s returned function
ReadLinesReturnFn: The function type returned by &rl
UiuaResult: Uiua’s result type

Crate uiuaCopy item path