Crate uiua

source ·
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, "").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.clone())?;
    uiua.call(f.clone())
}).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§

Modules§

  • ast
    Uiua’s abstract syntax tree
  • format
    The Uiua formatter
  • lsp
    Uiua’s Language Server Protocol (LSP) implementation

Structs§

Enums§

Constants§

Statics§

Traits§

Functions§

Type Aliases§