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.

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

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 four Array types.

You can run code with Uiua::load_str or Uiua::load_file.

use uiua::*;

let mut uiua = Uiua::with_native_sys();
uiua.load_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.load_str("+").unwrap();
let res = uiua.pop_int().unwrap();
assert_eq!(res, 3);

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

use uiua::*;

let mut uiua = Uiua::with_native_sys();

uiua.create_bind_function("MyAdd", (2, 1), |uiua| {
    let a = uiua.pop_num()?;
    let b = uiua.pop_num()?;
    uiua.push(a + b);
    Ok(())
}).unwrap();

uiua.load_str("MyAdd 2 3").unwrap();
let res = uiua.pop_num().unwrap();
assert_eq!(res, 5.0);

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 feature flags:

  • bytes: Enables a byte array type. This type is semantically equivalent to a numeric array, but takes up less space. It is returned by certain file and network functions, as well as some comparison functions.
  • audio: Enables audio features in the NativeSys backend.

Modules

  • ast
    Uiua’s abstract syntax tree
  • format
    The Uiua formatter

Structs

Enums

Constants

Statics

Traits

Functions

  • constants
    Get the list of all shadowable constants
  • example_ua
    Access the built-in example.ua file
  • is_custom_glyph
    Whether a string is a custom glyph
  • is_ident_char
    Whether a character can be part of a Uiua identifier
  • lex
    Lex a Uiua source file
  • parse
    Parse Uiua code into an AST
  • spans
    Get spans and their kinds from Uiua code

Type Aliases