Introduction

Welcome to "The Steel Book" — a guide for a dynamic and versatile programming language designed to harmonize with Rust, known as Steel. Born from the Lisp family and descended from Scheme, Steel offers a blend of dynamic expressiveness within Rust's strict environment, creating a powerful synergy.

But why choose a Lisp dialect as an extension language?

Rust provides robustness and safety, ensuring reliable and efficient software development. However, its rigidity can sometimes feel limiting when facing dynamic and evolving requirements, such as those encountered in a text editor, a crucial tool that developers tailor to their needs. Enter Lisp — a language family renowned for its extensibility and dynamic nature. It serves as the ultimate extension language, designed to be extendable itself by allowing developers to create DSLs and tweak the evaluation process to fit any domain or task, even those unforeseen or irrelevant to the original application.

In "The Steel Book," our aim is twofold: to demystify language basics for developers unfamiliar with Scheme intricacies and to teach about Steel in particular. That said, no prior Scheme experience is needed; we've got you covered.

Foundations

The ideas of Scheme are straightforward and easily combined, resulting in a minimalistic syntax that may appear excessive at first glance. While the abundance of parentheses can seem off-putting and archaic, expressions are actually nested lists and atoms, making it a recursive data structure. This inherent structure enables easy manipulation, allowing for straightforward metaprogramming and direct AST manipulations with proper editor support.

Now, let's welcome an S-expression (or sexp for short):

(+ 1 3 (- 7 4) 7)

As mentioned earlier, its structure is recursive; this particular one is comprised of a top-level expression and nested atoms, as well as one nested expression. Such a construction can be manipulated in various ways before being evaluated. Although the list of syntactic rules will be minimally supplemented later in this book, it already provides a stable foundation to fit the language in any domain area.

Evaluation

A key to understanding any Lisp is grasping the idea of how expressions should be evaluated. Roughly, the steps are:

Reader: Code as a string becomes a sexp, either an atom or an expression. Later, we'll discuss that there are forms that users can input, but they look different until processed by the reader into a proper sexp. It will be explicitly mentioned in this book if that's the case. Until then, our string inputs will match the string representation of a resulting sexp.
Macro expansion: Some sexps may become other sexps.
Eval: The final sexp is evaluated.

In subsequent chapters, we'll demystify all of it. For now, steps 1 and 2 will be transparent.

Literals

Literals are evaluated to themselves: numbers and string literals.

Let's fire up a Steel interpreter (or use the online one) to take a look at some examples.

In the following code examples, lambda precedes user input, and => indicates the evaluation result returned from the interpreter.

λ > 5
=> 5

λ > -1337
=> -1337

λ > 1.5
=> 1.5

λ > 0
=> 0

As we can see, an input text read as a sexp in a variant of an atom made of a number literal is evaluated to itself. What about string literals?

λ > "hello"
=> "hello"

λ > "steel"
=> "steel"

Nothing unexpected happens, as for characters:

λ > #\y
=> #\y

While not very fascinating by itself, it starts to become useful when built upon, as we're about to see next.

Function Calls

We're familiar with two variants of S-expressions: atoms and expressions. We've already seen how numbers and string literals, which are examples of atoms, are evaluated. Now, let's delve into the evaluation of expressions.

Let's revisit the previous expression example:

(+ 1 3 (- 7 4) 7)

Skipping the reader and macro expansion steps mentioned in the evaluation chapter, the interpreter will evaluate this expression in the following steps:

Step 1: Evaluate all items

The symbol + evaluates to the value behind it, in this case, the value of the addition function:

λ > +
=> #<function:+>

More details on symbols will follow in the symbols chapter.

As mentioned earlier, numbers evaluate to themselves.
A nested expression is evaluated, similar to the current top-level one.

At this point, the expression is represented as follows (not proper input, but a human-readable representation of the process):

(#<function:+> 1 3 (- 7 4) 7)

Step 2: Evaluate all items, level + 1

Here, we address the nested expression.

The symbol - also evaluates to a subtraction function value, just like the previous case with addition.
Numbers evaluate to themselves, again.
Function application occurs.

Expression evaluation follows a scheme where the first (0th, or more aptly, "the head") value represents a function value. This results in a function call familiar to us. With scheme, we have the freedom to instruct the interpreter not to evaluate it and leave it as is, but we'll address this case later in the book.

Thus, the expression (- 7 4) transitions from (#<function:-> 7 4) to 3 due to function application.

Step 3: Returning to level 0

After reducing the nested expression, we have:

(#<function:+> 1 3 3 7)

The evaluation of an expression eventually results in a function application unless instructed otherwise. Here, there's no exception:

=> 14

Symbols

We've previously learned that + is not merely a function, but rather a symbol representing a function. But what exactly is a symbol?

In Scheme, a symbol is a fundamental data type—a sequence of characters, distinct from a string. Entities are named using symbols rather than strings because symbols serve as identifiers and are evaluated differently.

An analogy from Rust can shed light on the concept of symbols. Consider the question "what is a in let a = 2;" from a metaprogramming perspective. In this context, a can be understood as an identifier. Similarly, when invoking a declarative macro like hello!(b) with a macro definition of macro_rules! hello { ($x:ident) => {} }, it won't raise an error if b is not defined. In this scenario, b acts akin to a symbol, the one we don't evaluate to any value behind it, but it still exists and usable, just on a different level.

Symbols can reference values depending on the context in which they are evaluated. However, in some cases, symbols are used as themselves and may be compared directly. For example, when defining a domain-specific language (DSL), certain symbols may act as "operators" or "keywords" without having a value associated with them. Instead, they impart meaning within the code that processes the DSL. We'll delve deeper into this topic later in the discussion on macros because, by default, symbols are evaluated, which may not always align with our intended usage, especially if we assign them a "keyword" meaning.

Next, we'll explore how to assign values to symbols to give them something to evaluate to.

Bindings and Scopes

How do we define symbols? And more importantly, how do we assign values to them? Let's address these questions now.

λ > a

Congratulations, we've defined our first symbol.

error[E02]: FreeIdentifier
  ┌─ :1:1
  │
1 │ a
  │ ^ a

Well, not so fast.

As mentioned earlier in the book, the interpreter evaluates S-expressions that it encounters, and the symbol a is no exception. Since symbol evaluation involves substituting it with a bound value, and there is none bound to it, we get an error.

Let's change that.

`define`

This is how we bind values to symbols, using (define symbol value):

λ > (define a 1337)
λ > a
=> 1337

Here, we've created a binding between the symbol a and a number literal. Consequently, further evaluation of a yields the elite integer. It's worth noting that regardless of whether a is bound and used across different expressions (in separate interpreter entries), it still retains its value. Why? Because the Steel session we're in introduces a scope, a context used in evaluation to resolve symbol bindings.

Another example:

λ > (define c (+ 1000 337))
λ > c
=> 1337

Although evaluation rules differ for define (symbol c is not evaluated, otherwise it would result in an error and make no sense), the value part follows standard rules.

`let` and local scope `define`

If define seems reminiscent of global variables to you, you're not alone. While it's suitable for defining function bindings (more on that later) or constants, there must be a better way for local bindings.

Coming from Scheme, Steel has two ways to do it: one is a Lisp classic, let bindings, and the other is local scope define.

`let`

Allow me to introduce let, a term familiar from our host language, Rust, with the same meaning.

let is used as follows: (let ((symbol-a value-a) (symbol-b value-b) ...) body).

λ > (let ((a (* 25 4))
          (b 3))
      (* a b))
=> 300
λ > a
=> 1337

Three points to note here:

We're dealing with an altered evaluation: the let symbol has no function bound to it, and in nested forms, only certain things get evaluated. This is the effect macros give us.
We've defined two symbols and bound values to them, which have been evaluated to these values in the latest expression inside the let expression.
a became 100, but only within the last expression nested in let, because it introduced a narrower scope. However, it didn't change the previous binding of a, but it shadowed it. And as you can probably guess, b is not defined beyond let.

Local scope `define`

For the sake of example, we'll use let once again to define a local scope. However, we won't define any symbols with it but use define within the body of let (this shall work with other ways to define a local scope, but we don't know about them yet, so this one should work just enough):

λ > (let ()
      (define a (+ 100 100))
      (define b (+ 2 3))
      (* a b))
=> 1000
λ > a
error[E02]: FreeIdentifier
  ┌─ :1:1
  │
1 │ a
  │ ^ a

λ > b
error[E02]: FreeIdentifier
  ┌─ :1:1
  │
1 │ b
  │ ^ b

As we can see, in Steel, define inside of a local scope could be used instead of let bindings, and it won't alter the outer scope.

Steel

Features

Licensing

Getting Started

Online Playground

The Steel Playground allows you to try Steel out directly from your browser. Visit the Steel Playground at:

https://mattwparas.github.io/steel-playground/dev/

The Steel Playground's environment is as follows:

Builtin modules are supported and are automatically imported.
Dylibs are not supported.

Output

The output prints the results of all expressions. Additional information can be printed out with the display and displayln functions.

Bytecode

Bytecode renders the Bytecode that Steel generates from the Steel code. The Bytecode is a low level representation of the code that is executed by the Steel interpretter.

Raw AST

Raw AST exposes the parsed AST. This expands some macros. For example:

(define (foo bar)
  (+ bar bar))

(define baz '(1 2 3))

is actually shorthand for

(define foo
  (λ (bar)
    (+ bar bar)))

(define baz (quote 1 2 3))

Expanded AST

This is similar to the Raw AST but provides more detailed information.

Using Steel on its own

Making a Steel Module in Rust

Sometimes you may want to create a Steel module by calling Rust. This can be useful to:

Optimize a performance critical codepath with Rust.
Take advantage of Rust's rich ecosystem.

Whatever the case, Steel provides facilities to create reusable modules based on Rust code. This process involves compiling Rust into a dylib.

Guide

In this guide, we'll make a dylib that will wrap the sys-info crate. There are roughly 3 steps:

Create a new Rust library of type "cdylib".
Define a module and register types and functions to it.
Build the Steel crate and install it to $STEEL_HOME/native.
Use the library from Steel with #%require-dylib.

Creating a cdylib library

To start, create a new library using cargo:

$ cargo new --lib steel-sys-info

This should create a directory structure as follows:

├── Cargo.toml
├── src
│   └── lib.rs

We'll want to make this a cdylib library for Steel, so we'll perform the following adjustments in Cargo.toml:

Set the crate-type to "cdylib".
Include steel-core with the dylibs feature as a dependency.
Include abi_stable as a dependency. This is required by some steel-core macros.

[package]
name = "steel-sys-info"
version.workspace = true
edition = "2021"

[lib]
name = "steel_sys_info"
crate-type = ["cdylib"]

[dependencies]
# I'm running this example based on the `steel-sys-info` library found in the steel repo. If you're
# running this on your own, use whichever steel version you'd like to target and pin to that.
steel-core = { workspace = true, features = ["dylibs"] }
abi_stable = "0.11.1"
sys-info = "0.9.1"

This means that when we run cargo build we'll produce a shared library (.so file). The shared library can be loaded into other programs, Steel in our case.

Creating a module

For the purposes of this example, we'll create a module that wraps the MemInfo struct, and expose the information there. Since we'll be implementing traits that are defined inside the steel crate, we'll need to create a struct to wrap the sys_info::MemInfo struct:

struct MemoryInfo {
    info: sys_info::MemInfo,
}

impl MemoryInfo {
    fn total(&self) -> isize {
        self.info.total as isize
    }

    fn avail(&self) -> isize {
        self.info.avail as isize
    }

    fn free(&self) -> isize {
        self.info.free as isize
    }

    fn buffers(&self) -> isize {
        self.info.buffers as isize
    }

    fn cached(&self) -> isize {
        self.info.cached as isize
    }

    fn swap_total(&self) -> isize {
        self.info.swap_total as isize
    }

    fn swap_free(&self) -> isize {
        self.info.swap_free as isize
    }
}

Now that we've done that, we can expose this to steel by implementing the Custom type for the struct, and declaring an FFIModule:

// Using ABI Stable types is very important
use steel::{
    declare_module,
    rvals::Custom,
    steel_vm::ffi::{FFIModule, RegisterFFIFn},
};

impl Custom for MemoryInfo {}

declare_module!(create_module);

fn create_module() -> FFIModule {
    let mut module = FFIModule::new("steel/sys-info");

    module.register_fn("mem-info", || MemoryInfo {
        info: sys_info::mem_info().unwrap(),
    });

    module
        .register_fn("MemoryInfo-total", MemoryInfo::total)
        .register_fn("MemoryInfo-avail", MemoryInfo::avail)
        .register_fn("MemoryInfo-free", MemoryInfo::free)
        .register_fn("MemoryInfo-buffers", MemoryInfo::buffers)
        .register_fn("MemoryInfo-cached", MemoryInfo::cached)
        .register_fn("MemoryInfo-swap-total", MemoryInfo::swap_total)
        .register_fn("MemoryInfo-swap-free", MemoryInfo::swap_free);

    module
}

The register_fn API will perform all of the necessary coercions necessary to make this as safe as possible. At the end of the day, this is FFI and we are loading shared libraries, so there is some unsafe Rust code, however steel uses the underlying abi_stable library in order to make interactions with the shared library as safe as possible.

Installing the library

To install the dylib in a location where the steel interpreter will find it, from the root of the library just run:

$ cargo steel-lib

This will build the crate, and copy the resulting dylib to $STEEL_HOME/native.

Using the library from Steel

To load the library, use the syntax #%require-dylib - This operates similary to a standard require, in that all of the modifiers you're used to using work, such as only-in and prefix-in. However, the argument is no longer the path to the library, but rather the name of the library without the extension. By default, the library will be named the [lib] name used in the toml, prefixed with lib.

(#%require-dylib "libsteel_sys_info"
                 (only-in mem-info
                          MemoryInfo-total
                          MemoryInfo-avail
                          MemoryInfo-free
                          MemoryInfo-buffers
                          MemoryInfo-cached
                          MemoryInfo-swap-total
                          MemoryInfo-swap-free))

(provide current-memory-usage memory-usage-as-percentage)

(define (current-memory-usage #:memory-info (memory-info (mem-info)))
  (- (MemoryInfo-total memory-info) (MemoryInfo-free memory-info) (MemoryInfo-cached memory-info)))

(define (memory-usage-as-percentage #:memory-info (memory-info (mem-info)))
  (/ (current-memory-usage #:memory-info memory-info) (MemoryInfo-total memory-info)))

This can then be installed as a library itself on the machine, and required just like any other library, using a cog.scm file for the manifest.

Using Steel as an embedded scripting engine

Steel can be used as a scripting language within a Rust program. You can achieve this by creating a Steel Engine object. The Engine object allows you to execute Scheme code and interact with it from your Rust program. For more details about Engine, see the Engine API.

Steel Engine

The Steel Virtual Machine is provided by the steel-core trait.

[dependencies]
steel-core = { git="https://github.com/mattwparas/steel.git", branch = "master" }

The following example runs a few expressions in a Steel Engine and asserts that the results are as expected.

use steel::steel_vm::engine::Engine;
use steel::SteelVal;

fn main() {
    let mut steel_engine = Engine::new();
    let answer = steel_engine.run(
        (r#"
      (+ 1 2 3 4)
      (+ 5 6 7 8)
    "#),
    );
    assert_eq!(answer, vec![SteelVal::IntV(10), SteelVal::IntV(26)])
}

Engine::new

Creates a new engine. The Engine is used to run Steel Scheme code. Note that the Engine is not Send or Sync. This means it is bound to the current thread and cannot be shared or sent across other threads.

let mut steel_engine = Engine::new();

Engine::run

Runs a Steel expression and returns the result as a Vec<SteelVal>. If any error occurs, then Err(SteelErr) is returned.

let mut steel_engine = Engine::new();
assert_eq!(steel_engine.run("(+ 1 1)"), Ok(vec![SteelVal::IntV(2)]));
assert!(steel_engine.run("(+ 1 undefined-identifier)").is_err());

Embedding The Steel REPL

Repl functionality is provided by the steel-repl crate.

[dependencies]
steel-repl = { git="https://github.com/mattwparas/steel.git", branch = "master" }

run_repl

run_repl runs the Steel repl until an IO error is encountered or the user exits the repl. The repl may be exited by:

Running the (quit) Steel Scheme function.
Pressing either ctrl+c or ctrl+d within the repl.

let steel_engine = Engine::new();
steel_repl::run_repl(steel_engine).unwrap();

The Engine API

Registering functions

Embedding values

Rust values, types, and functions are easily embedded into Steel. Using the register_fn call, you can embed functions easily:

use steel_vm::engine::Engine;
use steel_vm::register_fn::RegisterFn;

fn external_function(arg1: usize, arg2: usize) -> usize {
    arg1 + arg2
}

fn option_function(arg1: Option<String>) -> Option<String> {
    arg1
}

fn result_function(arg1: Option<String>) -> Result<String, String> {
    if let Some(inner) = arg1 {
        Ok(inner)
    } else {
        Err("Got a none".to_string())
    }
}

pub fn main() {
    let mut vm = Engine::new();

    // Here we can register functions
    // Any function can accept parameters that implement `FromSteelVal` and
    // return values that implement `IntoSteelVal`
    vm.register_fn("external-function", external_function);

    // See the docs for more information about `FromSteelVal` and `IntoSteelVal`
    // but we can see even functions that accept/return Option<T> or Result<T,E>
    // can be registered
    vm.register_fn("option-function", option_function);

    // Result values will map directly to errors in the VM and bubble back up
    vm.register_fn("result-function", result_function);

    vm.run(
        r#"
        (define foo (external-function 10 25))
        (define bar (option-function "applesauce"))
        (define baz (result-function "bananas"))
    "#,
    )
    .unwrap();

    let foo = vm.extract::<usize>("foo").unwrap();
    println!("foo: {}", foo);
    assert_eq!(35, foo);

    // Can also extract a value by specifying the type on the variable
    let bar: String = vm.extract("bar").unwrap();
    println!("bar: {}", bar);
    assert_eq!("applesauce".to_string(), bar);

    let baz: String = vm.extract("baz").unwrap();
    println!("baz: {}", baz);
    assert_eq!("bananas".to_string(), baz);
}

We can also embed structs themselves:

use steel_vm::engine::Engine;
use steel_vm::register_fn::RegisterFn;

use steel_derive::Steel;

// In order to register a type with Steel,
// it must implement Clone, Debug, and Steel
#[derive(Clone, Debug, Steel, PartialEq)]
pub struct ExternalStruct {
    foo: usize,
    bar: String,
    baz: f64,
}

impl ExternalStruct {
    pub fn new(foo: usize, bar: String, baz: f64) -> Self {
        ExternalStruct { foo, bar, baz }
    }

    // Embedding functions that take self must take by value
    pub fn method_by_value(self) -> usize {
        self.foo
    }

    // Setters should update the value and return a new instance (functional set)
    pub fn set_foo(mut self, foo: usize) -> Self {
        self.foo = foo;
        self
    }
}

pub fn main() {
    let mut vm = Engine::new();

    // Registering a type gives access to a predicate for the type
    vm.register_type::<ExternalStruct>("ExternalStruct?");

    // Structs in steel typically have a constructor that is the name of the struct
    vm.register_fn("ExternalStruct", ExternalStruct::new);

    // register_fn can be chained
    vm.register_fn("method-by-value", ExternalStruct::method_by_value)
        .register_fn("set-foo", ExternalStruct::set_foo);

    let external_struct = ExternalStruct::new(1, "foo".to_string(), 12.4);

    // Registering an external value is fallible if the conversion fails for some reason
    // For instance, registering an Err(T) is fallible. However, most implementation outside of manual
    // ones should not fail
    vm.register_external_value("external-struct", external_struct)
        .unwrap();

    let output = vm
        .run(
            r#"
            (define new-external-struct (set-foo external-struct 100))
            (define get-output (method-by-value external-struct))
            (define second-new-external-struct (ExternalStruct 50 "bananas" 72.6))
            "last-result"
        "#,
        )
        .unwrap();

    let new_external_struct = vm.extract::<ExternalStruct>("new-external-struct").unwrap();
    println!("new_external_struct: {:?}", new_external_struct);
    assert_eq!(
        ExternalStruct::new(100, "foo".to_string(), 12.4),
        new_external_struct
    );

    // Can also extract a value by specifying the type on the variable
    let get_output: usize = vm.extract("get-output").unwrap();
    println!("get_output: {}", get_output);
    assert_eq!(1, get_output);

    let second_new_external_struct: ExternalStruct =
        vm.extract("second-new-external-struct").unwrap();
    println!(
        "second_new_external_struct: {:?}",
        second_new_external_struct
    );
    assert_eq!(
        ExternalStruct::new(50, "bananas".to_string(), 72.6),
        second_new_external_struct
    );

    // We also get the output of the VM as the value of every expression run
    // we can inspect the results just by printing like so
    println!("{:?}", output);
}

IntoSteelVal and FromSteelVal

Types that implement IntoSteelVal and FromSteelVal and be returned and passed into rust functions, respectively. Take the following for example:

#![allow(unused)]

fn main() {
fn foo(value: isize) -> String {
    ...
}
    
}

This means that steel values will attempt to be coerced to the type in the function signature, and the value that this function returns will then attempt to be coerced into a that Steel understands.

There are some special case conversions that happen specifically:

`IntoSteelVal`

Vec -> Steel list
HashMap<K, V> -> Steel hashmap
HashSet -> Steel hashset
Result<T, E> -> if Ok(T) then T else (error E)
Option -> if Some(T) then T else #false

Language Reference

Keywords

Syntax

Macros

Steel contains a limited form of the syntax-rules that scheme provides. These macros build on the small primary language constructs that exist. Consider the following:

(define-syntax or
  (syntax-rules ()
    [(or) #f]
    [(or x) x]
    [(or x y) (let ([z x])
                (if z z y))]
    [(or x y ...) (or x (or y ...))]))

(or #f #f #t)

This will actually expand into something like this

((λ (__z)
     (if __z __z ((λ (__z) (if __z __z #t)) #f)))
   #f)

These macros allow for a simple extension of Steel to however you see fit - defining macros in terms of the syntax rules format is fairly straightforward.

Contracts

Inspired by Racket's higher order contracts, Steel implements* higher order contracts to enable design by contract, made easy with a define/contract macro for easier ergonomics. Racket makes use of a concept known as blame which seeks to identify the violating party - Steel does not quite have fully fleshed out blame but that is a work in progress. Here are some examples:

;; Simple flat contracts
(define/contract (test x y)
    (->/c even? even? odd?)
    (+ x y 1))

(test 2 2) ;; => 5

(define/contract (test-violation x y)
    (->/c even? even? odd?)
    (+ x y 1))

(test-violation 1 2) ;; contract violation

Contracts are implemented as values, so they are bound to functions. This enables the use of contract checking on functions themselves since functions can be passed around:

;; Higher order contracts, check on application
(define/contract (higher-order func y)
    (->/c (->/c even? odd?) even? even?)
    (+ 1 (func y)))

(higher-order (lambda (x) (+ x 1)) 2) ;; => 4

(define/contract (higher-order-violation func y)
    (->/c (->/c even? odd?) even? even?)
    (+ 1 (func y)))

(higher-order-violation (lambda (x) (+ x 2)) 2) ;; contract violation

Contracts on functions do not get checked until they are applied, so a function returning a contracted function won't cause a violation until that function is actually used:

;; More higher order contracts, get checked on application
(define/contract (output)
    (->/c (->/c string? int?))
    (lambda (x) 10))

(define/contract (accept func)
    (->/c (->/c string? int?) string?)
    "cool cool cool")

(accept (output)) ;; => "cool cool cool"

;; different contracts on the argument
(define/contract (accept-violation func)
    (->/c (->/c string? string?) string?)
    (func "applesauce")
    "cool cool cool")

(accept-violation (output)) ;; contract violation

;; generates a function
(define/contract (generate-closure)
    (->/c (->/c string? int?))
    (lambda (x) 10))

;; calls generate-closure which should result in a contract violation
(define/contract (accept-violation)
    (->/c (->/c string? string?))
    (generate-closure))

((accept-violation) "test") ;; contract violation

Perhaps a more nuanced case:

(define/contract (output)
    (->/c (->/c string? int?))
    (lambda (x) 10.2))

(define/contract (accept)
    (->/c (->/c string? number?))
    (output))


((accept) "test") ;; contract violation 10.2 satisfies number? but _not_ int?

Transducers

Inspired by clojure's transducers, Steel has a similar object that is somewhere half way in between transducers and iterators. Consider the following:


(mapping (lambda (x) (+ x 1))) ;; => <#iterator>
(filtering even?) ;; => <#iterator>
(taking 15) ;; => <#iterator>

(compose 
    (mapping add1)
    (filtering odd?)
    (taking 15)) ;; => <#iterator>

Each of these expressions emit an <#iterator> object, which means they're compatible with execute and transduce. Execute takes a transducer (i.e. <#iterator>) and a collection that can be iterated (list, vector, or stream) and applies the transducer.

;; Accepts lists
(execute (mapping (lambda (x) (+ x 1))) (list 1 2 3 4 5)) ;; => '(2 3 4 5 6)

;; Accepts vectors
(execute (mapping (lambda (x) (+ x 1))) (vector 1 2 3 4 5)) ;; '#(2 3 4 5 6)

;; Even accepts streams!
(define (integers n)
    (stream-cons n (lambda () (integers (+ 1 n)))))

(execute (taking 5) (integers 0)) ;; => '(0 1 2 3 4)

Transduce is just reduce with more bells and whistles and works similarly:

;; (-> transducer reducing-function initial-value iterable)
(transduce (mapping (lambda (x) (+ x 1))) + 0 (list 0 1 2 3)) ;; => 10

Compose just combines the iterator functions and lets us avoid intermediate allocation. The composition works left to right - it chains each value through the functions and then accumulates into the output type. See the following:

(define xf 
    (compose 
        (mapping add1)
        (filtering odd?)
        (taking 5)))

(execute xf (range 0 100)) ;; => '(1 3 5 7 9)

By default, execute outputs to the same type that was passed in. In other words, if you execute a list, it will return a list. However, if you so choose, you can pass in a symbol specifying the output type of your choosing like so:

(define xf 
    (compose 
        (mapping add1)
        (filtering odd?)
        (taking 5)))

;; Takes a list and returns a vector
(execute xf (range 0 100) 'vector) ;; => '#(1 3 5 7 9)

;; Takes a vector and returns a list
(execute xf (vector 0 1 2 3 4 5 6 7 8 9 10) 'list) ;; => '(1 3 5 7 9)

Modules

In order to support a growing codebase, Steel has module support for projects spanning multiple files. Steel files can provide values (with contracts attached) and require modules from other files:

;; main.scm
(require "provide.scm")

(even->odd 10)


;; provide.scm
(provide 
    (contract/out even->odd (->/c even? odd?))
    no-contract
    flat-value)

(define (even->odd x) 
    (+ x 1))

(define (accept-number x) (+ x 10))

(define (no-contract) "cool cool cool")
(define flat-value 15)

(displayln "Calling even->odd with some bad inputs but its okay")
(displayln (even->odd 1))

Here we can see if we were to run main that it would include the contents of provide, and only provided values would be accessible from main. The contract is attached at the contract boundary, so inside the provide module, you can violate the contract, but outside the module the contract will be applied.

A few notes on modules:

Cyclical dependencies are not allowed
Modules will be only compiled once and used across multiple files. If A requires B and C, and B requires C, C will be compiled once and shared between A and B.
Modules will be recompiled when changed, and any dependent files will also be recompiled as necessary

Modifiers for requiring


(require (prefix-in export. ;; prefix-in will prefix all of the bound identifiers with the given prefix
                    (only-in "export.scm" ;; only-in will only introduce the identifiers listed.
                             thing-should-not-escape
                             Applesauce
                             bananas
                             new-identifier
                             my-fun-contracted-function
                             contract-out-test)))

If no modifiers are given, require-ing a module will introduce all of the provided values into the top level scope.

Providing and requiring macros;

Macros defined using define-syntax can be handled just like normal values:

;; main.scm
(require "provide.scm")

(foo-bar x) ;; Will expand into (displayln "Hello world")

;; provide.scm
(provide foo-bar)

(define-syntax foo-bar 
    (syntax-rules ()
        [(foo-bar x) (displayln "Hello world!")]))

The module system will take care to keep the namespaces separate - any macros that expand into macros that exist in the originating module will be expanded, but those will not be available to the requiring module. In addition, macros can expand into private values (those that are not provided), and the will still be inaccessible from the requiring module.

Functions

keyword?


(keyword? v) -> boolean?

v: any/c

mutable-vector


(mutable-vector args ...) -> mutable-vector?

struct

Macro for creating a new struct, in the form of: (struct <struct-name> (fields ...) options ...) The options can consist of the following:

Single variable options (those which their presence indicates #true)

#:mutable
#:transparent

Other options must be presented as key value pairs, and will get stored in the struct instance. They will also be bound to the variable ___<struct-name>-options___ in the same lexical environment where the struct was defined. For example:

λ > (struct Applesauce (a b c) #:mutable #:transparent #:unrecognized-option 1234)
λ > ___Applesauce-options___
=> #<hashmap {
    '#:fields: '(a b c),
    '#:mutable: #false,
    '#:transparent: #false,
    '#:unrecognized-option: 1234,
}>

By default, structs are immutable, which means setter functions will not be generated. Also by default, structs are not transparent, which means printing them will result in an opaque struct that does not list the fields