Morphir Scheme

An embeddable Scheme dialect for writing Morphir transforms and executing Morphir IR. It runs on MoonBit's wasm, wasm-gc, js and native targets. This chapter is the index and the reference for the core language and its embedding. The other chapters cover compiling Scheme to Morphir IR, running Morphir IR, transform scripts and the specification notation.

Chapters: index (this page) · next: Writing models

Chapter Covers
Morphir Scheme The language, its limits and embedding a runtime
Writing models Compiling Scheme to Morphir IR
Running Morphir IR Evaluating and emitting IR, externals, linking, the symbols sidecar
Transform scripts Scripts as IRFile -> IRFile procedures
Specification notation Package specifications as data

Overview

Morphir Scheme has two jobs. Transform scripts written in it read and rewrite Morphir IR. Morphir IR compiled to it runs in the same interpreter.

The separation of reader, evaluator and runtime takes inspiration from bobzhang/scheme-r6rs and its MoonBit implementation. This is an independent implementation of a specialized subset, not an R6RS implementation. This chapter describes what the language does today, and says where a form or procedure differs from R6RS. A difference that is a known deviation names bead morphir-ukvn.5.48, which tracks its fix; the others are by design.

Declare finos/morphir-scheme@0.1.0 in your module and import the packages you need. The MoonBit examples in these chapters use the aliases scheme, frontend, backend, pipeline and ir.

Import Responsibility
finos/morphir-scheme Reader, runtime values, lexical evaluation and host procedures
finos/morphir-scheme/frontend Scheme expressions and files → current Morphir IR
finos/morphir-scheme/backend Morphir IR → executable Scheme; runtime support
finos/morphir-scheme/pipeline Scripted IR transforms, JSON bridge and bottom-up traversal
finos/morphir-scheme/spec The specification notation (see the chapter) ↔ @ir.PackageSpecification

morphir-engine provides file discovery, manifests, configuration, frontend/backend registration, artifacts and diagnostics.

Compiling Scheme to Morphir IR is described in Writing models, running it in Running Morphir IR, and scripted IR transforms in Transform scripts.

Every scheme block in this chapter is a checked example. Each block runs in a fresh Runtime and its last value is printed with value_to_string. A ;; => line states the printed result. A ;; error: line states the start of the error message.

(define (inc x) (+ x 1))
(inc 41)
;; => 42

Lexical syntax

The reader turns source text into data before anything is evaluated. A program is a sequence of data, separated by whitespace and comments.

Datum Written as Notes
List (a b c) or [a b c] A list closes with the delimiter that opened it
Dotted pair (a . b), (a b . c) The dot needs at least one datum before it and exactly one after it
Quotation 'datum Reads as (quote datum)
Vector #(a b c)
String "text" Escapes: \n, \r, \t, \\, \", and a backslash before a vertical bar
Character #\a, #\space, #\newline, #\tab, #\return A delimiter such as ( can follow #\ directly
Escaped identifier a name between vertical bars Can hold spaces, delimiters and the same escapes as a string
Boolean #t, #true, #f, #false
Exact integer 42, -7, +5 Any size
Exact rational 6/4 Normalized: 6/4 reads as 3/2, and 4/2 reads as 2
Inexact real 1.5, -0.25, 1e3, 2.5E-3 JSON number syntax with an optional leading +; the literal must be finite
Symbol any other token

Line comments start with ; and run to the end of the line. Block comments sit between #| and |#, and they nest. A datum comment #; skips the next datum.

#| outer #| inner |# |# #; (+ 9 9) '(1 . 2)
;; => (1 . 2)

Brackets read the same as parentheses.

(let ([x 1] [y 2]) (+ x y))
;; => 3

Integers have arbitrary precision.

(+ 18446744073709551616 1)
;; => 18446744073709551617

Rationals are exact and stay normalized.

(+ 1/3 1/6)
;; => 1/2

An inexact real needs a digit before its point. .5 reads as a symbol, not a number. This is a known deviation from R6RS, tracked by bead morphir-ukvn.5.48.

(list 0.5 1e3 (symbol? '.5))
;; => (0.5 1000.0 #t)

Strings print with their escapes.

"say \"hi\"\tthen go"
;; => "say \"hi\"\tthen go"

Characters print with their names.

(list #\a #\( #\space #\newline)
;; => (#\a #\( #\space #\newline)

An escaped identifier reads as one symbol.

(symbol->string '|two words|)
;; => "two words"

Refused input

The table lists every Syntax error the reader raises. Its message names the character offset where the reader stopped, counted from 0.

Refused input Message
The text ends inside a list Unclosed list
A closing delimiter with no open list, or one that does not match the opening delimiter Unexpected closing delimiter
A dot with nothing before it Dot requires a head
More than one datum after a dot Expected closing delimiter after tail
A vector written with a dot, such as #(1 . 2) Invalid vector
The text ends inside a string or escaped identifier Unclosed quoted text
The text ends right after a backslash inside a string or escaped identifier Unclosed escape
An escape other than the six listed above Unsupported escape
The text ends inside a block comment Unclosed block comment
The text ends where a datum must follow: after a quotation, a datum comment or a dot Expected datum
The text ends right after #\ Expected character
A character name other than the four listed above Expected one character
A # token that is not a boolean, vector, character or comment, such as #x10 Unknown reader token: #x10
A token that starts with a digit but is not a number, such as 1abc or 1. Invalid numeric token
Lists nested more than 256 deep Reader nesting limit

The rows about text that ends too early cannot be scheme examples. An example's ;; error: line is part of its text, so the text never ends where the row needs it to. This test reads each such input directly.

///|
test "the reader refuses text that ends too early" {
  for
    refusal in [
      ("(1 2", "Syntax at character 4: Unclosed list"),
      ("\"abc", "Syntax at character 4: Unclosed quoted text"),
      ("\"a\\", "Syntax at character 3: Unclosed escape"),
      ("#| open", "Syntax at character 7: Unclosed block comment"),
      ("'", "Syntax at character 1: Expected datum"),
      ("#;", "Syntax at character 2: Expected datum"),
      ("(1 .", "Syntax at character 4: Expected datum"),
      ("#\\", "Syntax at character 2: Expected character"),
    ] {
    let (source, expected) = refusal
    let message = try {
      ignore(@scheme.parse_program(source))
      ""
    } catch {
      e => @scheme.error_message(e)
    }
    assert_eq(message, expected)
  }
}
#(1 . 2)
;; error: Syntax at character 8: Invalid vector
(1 . 2 3)
;; error: Syntax at character 7: Expected closing delimiter after tail
#x10
;; error: Syntax at character 4: Unknown reader token: #x10
"a\q"
;; error: Syntax at character 4: Unsupported escape

A backquote or a comma raises an Unsupported error, because quasiquotation is outside the language. A number literal can also fail with an Invalid error: 1/0 raises Division by zero, and 1e400 raises Nonfinite number.

1/0
;; error: Division by zero
1e400
;; error: Nonfinite number

Values

Value Printed form Example
Exact integer decimal digits 42
Exact rational numerator / denominator 1/2
Inexact real digits with a point or exponent 2.5, 1000.0
Inexact real that is not finite NaN.0, Infinity.0 or -Infinity.0 made only by a host or by evaluate
Boolean #t or #f #t
Character #\ and the character or its name #\a, #\space
String between double quotes, with escapes "hi"
Symbol its name, between vertical bars when it needs escaping abc
Empty list () ()
Pair a list, or a dotted list when the last tail is not the empty list (1 2), (1 . 2)
Vector #( elements ) #(1 2)
Record #<record key=value ... > #<record x=1>
Tagged value #< tag elements > made by the backend for Morphir constructors
Unit #<unit> #<unit>
Procedure #<procedure> closures and host procedures
Morphir IR value, type or file #<morphir-value>, #<morphir-type>, #<morphir-file> made by host procedures

Pairs, strings, records and vectors are immutable. Values nested more than 256 deep cannot be printed: value_to_string raises Limit exceeded: value printing depth.

The reader, string->number and arithmetic never produce a real that is not finite. A host procedure can return one, and so can the backend's evaluate, as listed in Two ways to run IR. Arithmetic on such a value raises Nonfinite arithmetic result.

///|
test "a host can return a real that is not finite" {
  let runtime = @scheme.Runtime::new()
  runtime.define_native("infinity", fn(_rt, _args) {
    @scheme.Value::Number(@scheme.Number::Real(1.0 / 0.0))
  })
  inspect(
    @scheme.value_to_string(runtime.eval("(infinity)")),
    content="Infinity.0",
  )
  let below = @scheme.Value::Number(@scheme.Number::Real(-1.0 / 0.0))
  inspect(@scheme.value_to_string(below), content="-Infinity.0")
  let nan = @scheme.Value::Number(@scheme.Number::Real(0.0 / 0.0))
  inspect(@scheme.value_to_string(nan), content="NaN.0")
  let message = try {
    ignore(runtime.eval("(+ (infinity) 1)"))
    ""
  } catch {
    e => @scheme.error_message(e)
  }
  inspect(message, content="Nonfinite arithmetic result")
}

Truthiness

Only #f is false in the interpreter. Every other value, including 0, () and the empty string, is true.

(if 0 'zero-is-true 'false)
;; => zero-is-true

Equality

equal? compares two values by structure.

Values Equal when
Numbers They have the same numeric value, whatever their exactness
Booleans, characters, strings, symbols They have the same content
Empty lists, units Always
Pairs, vectors Their elements are equal, in order
Records They have the same keys with equal values, in any order
Tagged values They have the same tag and equal elements
Morphir IR values, types and files They are equal as IR
Procedures Never, not even a procedure and itself
Values of different kinds Never

Numbers compare by value, so 1 and 1.0 are equal; R6RS equal? says they are not. Procedures are never equal; R6RS equal? says a procedure equals itself. Both are known deviations, tracked by bead morphir-ukvn.5.48. The language has no eq? or eqv?.

(list (equal? 1 1.0) (equal? car car) (equal? '(1 #(2)) (list 1 (vector 2))))
;; => (#t #f #t)

Special forms

A list whose head is one of these names is a special form, not a procedure call.

Form Syntax
define (define name expression), (define (name parameter ...) body ...)
set! (set! name expression)
lambda (lambda (parameter ...) body ...), (lambda (parameter ... . rest) body ...), (lambda rest body ...)
if (if test consequent alternative)
begin (begin form ...)
and (and form ...)
or (or form ...)
let (let ((name expression) ...) body ...)
let* (let* ((name expression) ...) body ...)
letrec (letrec ((name expression) ...) body ...)
named let (let loop ((name expression) ...) body ...)
quote (quote datum) or 'datum

The evaluator recognizes a special form by its name before it looks up any binding. A local binding named if therefore cannot be called as (if ...).

(let ((if (lambda (x) x))) (if 1))
;; error: if expects condition, consequent and alternative

Evaluation and application

A symbol evaluates to its binding in the innermost scope that has one. Numbers, strings, characters, booleans and vectors evaluate to themselves. The elements of a vector literal are not evaluated.

#(x (+ 1 2))
;; => #(x (+ 1 2))

Any other list is an application. The evaluator evaluates the head, then the arguments from left to right, then calls the head with the arguments.

Error Message
A symbol has no binding Unbound identifier: name
The list is empty Empty application
The list is dotted Cannot evaluate an improper application
The head is not a procedure Attempt to call a non-procedure
(1 2)
;; error: Attempt to call a non-procedure

define

(define name expression) evaluates the expression and binds the name in the current scope. At the top level, the current scope is the session. Inside a procedure or let body, it is that body's scope. A second define of the same name in the same scope replaces the binding. (define (name parameter ...) body ...) is short for (define name (lambda (parameter ...) body ...)), and a dotted parameter list makes a variadic procedure. The value of a define form is unit.

Error Message
Fewer than two parts after define define expects name and value
More than one expression after a name define expects one value
A target that is neither a symbol nor a non-empty list Invalid definition
A procedure name that is not a symbol Expected identifier
(define (square x) (* x x))
(square 7)
;; => 49
(define answer 42)
;; => #<unit>

set!

(set! name expression) evaluates the expression and assigns it to the innermost existing binding of the name. The value of a set! form is unit.

Error Message
No binding of the name exists Unbound identifier: name
The name is a letrec binding that is not yet initialized Uninitialized recursive binding: name
Anything other than a name and one expression set! expects name and value
(define count 0)
(set! count (+ count 1))
count
;; => 1
(set! missing 1)
;; error: Unbound identifier: missing

lambda

lambda makes a closure that captures the scope where it is evaluated. A call binds the parameters to the arguments in a new scope, then evaluates the body forms in order. The value of the call is the value of the last body form. With a dotted parameter list, the rest parameter receives a list of the extra arguments. With a single symbol instead of a list, that symbol receives a list of all the arguments.

Error Message
No body lambda expects parameters and body
A repeated parameter Duplicate parameter: name
A rest parameter that repeats a parameter Duplicate rest parameter: name
Parameters that are neither a symbol nor a list Invalid lambda formals
A parameter that is not a symbol Expected identifier
A call with the wrong number of arguments Procedure argument count mismatch
A call from another session Closure belongs to another runtime
(define (make-adder x) (lambda (y) (+ x y)))
((make-adder 10) 32)
;; => 42
((lambda (a . rest) rest) 1 2 3)
;; => (2 3)
((lambda args args) 1 2)
;; => (1 2)
((lambda (x) x))
;; error: Procedure argument count mismatch

if

(if test consequent alternative) evaluates the test. If the test is true, the form's value is the consequent's value; otherwise it is the alternative's value. The alternative is required: R6RS allows if without one, and this language does not.

Error Message
Anything other than three parts after if if expects condition, consequent and alternative
(if (< 1 2) 'yes 'no)
;; => yes
(if #t 1)
;; error: if expects condition, consequent and alternative

begin

(begin form ...) evaluates the forms in order, and its value is the last form's value. (begin) has the value unit. begin does not open a scope, so a define inside it binds in the enclosing scope. It raises no error of its own.

(begin (define x 1) (+ x 1))
;; => 2
(begin)
;; => #<unit>

and and or

and evaluates its forms from left to right and stops at the first false value, which is its value. If no form is false, the value of and is the last form's value, and (and) is #t. or evaluates its forms from left to right and stops at the first true value, which is its value. If no form is true, the value of or is #f, and (or) is #f. Neither raises an error of its own.

(list (and 1 2 3) (and 1 #f 3) (or #f 'b) (and) (or))
;; => (3 #f b #t #f)

let, let* and letrec

let evaluates every expression in the enclosing scope, from left to right. It then binds the names in a new scope and evaluates the body there.

(let ((x 1)) (let ((x 2) (y x)) y))
;; => 1

let* evaluates each expression in a scope that holds the bindings before it. A name can repeat, and the later binding shadows the earlier one.

(let* ((x 1) (x (+ x 1))) x)
;; => 2

letrec puts every name in scope for every expression, so its procedures can call each other.

(letrec ((even? (lambda (n) (if (= n 0) #t (odd? (- n 1)))))
         (odd? (lambda (n) (if (= n 0) #f (even? (- n 1))))))
  (even? 10))
;; => #t

A letrec name cannot be read until every expression of the form has been evaluated. Reading or assigning it earlier raises an error. This applies to a binding whose own expression has already finished too: (letrec ((a 1) (b a)) b) fails.

(letrec ((a b) (b 1)) a)
;; error: Uninitialized recursive binding: b
Error Message
No body let expects bindings and body
Bindings that are not a list Expected proper syntax list
A binding that is not a name and one expression Binding expects name and expression
A binding name that is not a symbol Expected identifier
A repeated name in let or letrec Duplicate binding: name
An early read of a letrec name Uninitialized recursive binding: name
(let ((x 1) (x 2)) x)
;; error: Duplicate binding: x

Named let

(let loop ((name expression) ...) body ...) binds loop to a procedure with the given parameters, visible in its own body. It then calls that procedure with the values of the expressions, which are evaluated in the enclosing scope. A call to loop in tail position runs in constant host stack. The errors are those of let, and a named let without a body raises Named let expects body.

(let loop ((n 10000) (sum 0))
  (if (= n 0) sum (loop (- n 1) (+ sum 1))))
;; => 10000

quote

(quote datum) and 'datum have the datum itself as their value, without evaluating it. A quoted list becomes pairs, and a quoted symbol becomes a symbol.

Error Message
Anything other than one datum after quote quote expects one datum
(list '(a b . c) (quote (+ 1 2)))
;; => ((a b . c) (+ 1 2))

Built-in procedures

Every session starts with the procedures in these tables. Each row gives the arguments, the result and an example. The block after each table runs the table's examples and prints their results as one list. A procedure with a fixed number of arguments raises name: expected N arguments when it receives another number, for example car: expected 1 arguments. The plural for one argument is a known defect, tracked by bead morphir-ukvn.5.48.

Arithmetic

A result is exact when every argument is exact. A result is inexact when any argument is inexact. An exact rational result is normalized, and a rational with denominator 1 becomes an integer.

Procedure Arguments Result Example
+ zero or more numbers their sum; 0 with no arguments (+ 1 2 3) → 6
- one or more numbers the first minus the rest; the negation of a single argument (- 10 4 1) → 5
* zero or more numbers their product; 1 with no arguments (* 2 3 4) → 24
/ one or more numbers the first divided by the rest; the reciprocal of a single argument (/ 1 3) → 1/3
quotient two exact integers the quotient, truncated toward zero (quotient -7 2) → -3
remainder two exact integers the remainder, with the sign of the first argument (remainder -7 2) → -1
number? one value #t for any number (number? 1/2) → #t
integer? one value #t for an exact integer (integer? 2.0) → #f
(list (+ 1 2 3) (- 10 4 1) (* 2 3 4) (/ 1 3) (quotient -7 2) (remainder -7 2) (number? 1/2) (integer? 2.0))
;; => (6 5 24 1/3 -3 -1 #t #f)
(list (+ 1 0.5) (* 2 1.0) (- 5) (/ 6 4))
;; => (1.5 2.0 -5 3/2)

integer? is #f for an inexact real with an integral value, such as 2.0; R6RS says it is #t. This is a known deviation, tracked by bead morphir-ukvn.5.48.

Raised when Message
An argument is not a number Expected number
A call to - or / has no arguments - needs an operand, / needs an operand
A divisor is zero, exact or inexact Division by zero
An inexact result overflows Nonfinite arithmetic result
An exact integer is too large to convert to an inexact real Inexact conversion overflow
An argument of quotient or remainder is a rational or a real Expected exact integers
(/ 1 0)
;; error: Division by zero

Comparison

Procedure Arguments Result Example
= two or more numbers #t when all are equal (= 1 1.0) → #t
< two or more numbers #t when each is less than the next (< 1 2 3) → #t
> two or more numbers #t when each is greater than the next (> 3 2 2) → #f
<= two or more numbers #t when each is at most the next (<= 1 1 2) → #t
>= two or more numbers #t when each is at least the next (>= 3 1 2) → #f
equal? two values #t when they are equal by structure (see Equality) (equal? '(1 (2)) '(1 (2))) → #t
(list (= 1 1.0) (< 1 2 3) (> 3 2 2) (<= 1 1 2) (>= 3 1 2) (equal? '(1 (2)) '(1 (2))))
;; => (#t #t #f #t #f #t)

A comparison checks every argument, even after it has found a false result.

Raised when Message
A numeric comparison has fewer than two arguments Comparison needs at least two operands
An argument of a numeric comparison is not a number Expected number
(< 2 1 'x)
;; error: Expected number

Lists

Procedure Arguments Result Example
cons two values a pair of them (cons 1 2) → (1 . 2)
car a pair its first part (car '(1 2)) → 1
cdr a pair its second part (cdr '(1 2)) → (2)
list zero or more values a list of them (list 1 2) → (1 2)
null? one value #t for the empty list (null? '()) → #t
pair? one value #t for a pair (pair? '()) → #f
list? one value #t for a proper list (list? '(1 . 2)) → #f
length a proper list its number of elements (length '(1 2 3)) → 3
append zero or more proper lists, then any value the lists joined, ending in the last argument (append '(1) '(2 3)) → (1 2 3)
reverse a proper list its elements in reverse order (reverse '(1 2 3)) → (3 2 1)
(list (cons 1 2) (car '(1 2)) (cdr '(1 2)) (list 1 2) (null? '()) (pair? '()) (list? '(1 . 2)) (length '(1 2 3)) (append '(1) '(2 3)) (reverse '(1 2 3)))
;; => ((1 . 2) 1 (2) (1 2) #t #f #f 3 (1 2 3) (3 2 1))

append shares its last argument as the tail of the result, so the last argument does not have to be a list.

(list (append) (append '(1) 2))
;; => (() (1 . 2))
Raised when Message
The argument of car or cdr is not a pair Expected pair
The argument of length or reverse, or an argument of append before the last, is not a proper list Expected proper list
(car '())
;; error: Expected pair

Higher-order

Procedure Arguments Result Example
map a procedure and one proper list a list of the procedure's results for each element, in order (map (lambda (x) (* x x)) '(1 2 3)) → (1 4 9)
fold-left a procedure, an initial value and a proper list the procedure applied from the left: (f (f init a) b) (fold-left - 0 '(1 2 3)) → -6
apply a procedure, zero or more values, then a proper list the procedure's result for the values followed by the list's elements (apply + 1 '(2 3)) → 6
procedure? one value #t for a closure or a host procedure (procedure? car) → #t
(list (map (lambda (x) (* x x)) '(1 2 3)) (fold-left - 0 '(1 2 3)) (apply + 1 '(2 3)) (procedure? car))
;; => ((1 4 9) -6 6 #t)

map takes exactly one list; R6RS map takes one or more.

Raised when Message
A call to map has more than one list map: expected 2 arguments
The procedure argument is not a procedure Expected procedure
The list argument is not a proper list Expected proper list
A call to apply has fewer than two arguments apply needs a procedure and list
(map (lambda (x y) x) '(1 2) '(3 4))
;; error: map: expected 2 arguments

Strings

Procedure Arguments Result Example
string-append zero or more strings the strings joined (string-append "ab" "cd") → "abcd"
string=? two strings #t when they are the same (string=? "a" "a") → #t
string? one value #t for a string (string? 'a) → #f
(list (string-append "ab" "cd") (string=? "a" "a") (string? 'a))
;; => ("abcd" #t #f)
Raised when Message
An argument of string-append or string=? is not a string Expected string
(string-append "a" 1)
;; error: Expected string

Symbols and conversion

Procedure Arguments Result Example
symbol? one value #t for a symbol (symbol? 'a) → #t
symbol->string a symbol its name (symbol->string 'abc) → "abc"
string->symbol a string the symbol with that name (string->symbol "abc") → abc
number->string a number its printed form (number->string 1/3) → "1/3"
string->number a string the number the reader reads from it, or #f (string->number "2.5") → 2.5
(list (symbol? 'a) (symbol->string 'abc) (string->symbol "abc") (number->string 1/3) (string->number "2.5"))
;; => (#t "abc" abc "1/3" 2.5)

string->symbol accepts any string, and the result prints escaped when it needs to be.

(string->symbol "two words")
;; => |two words|

string->number gives #f for text that is not a number.

(string->number "ten")
;; => #f
Raised when Message
The argument of symbol->string is not a symbol Expected symbol
The argument of string->symbol or string->number is not a string Expected string
The argument of number->string is not a number Expected number
The text given to string->number is a real that is not finite Nonfinite number
The text given to string->number is a rational with denominator zero Division by zero

string->number raises an error for "1e400" and "1/0" instead of giving #f. This is a known deviation from R6RS, tracked by bead morphir-ukvn.5.48.

(string->number "1/0")
;; error: Division by zero

Records

A record maps string keys to values. Records are immutable: record-set makes a new record. A record keeps its keys in the order they were added.

Procedure Arguments Result Example
record zero or more pairs, each with a string key a record of those fields (record (cons "x" 1)) → #<record x=1>
record-ref a record and a key the field's value (record-ref (record (cons "x" 1)) "x") → 1
record-set a record, a key and a value a new record with the field set, or added at the end (record-set (record (cons "x" 1)) "x" 2) → #<record x=2>
record-keys a record a list of its keys (record-keys (record (cons "x" 1) (cons "y" 2))) → ("x" "y")
(list (record (cons "x" 1)) (record-ref (record (cons "x" 1)) "x") (record-set (record (cons "x" 1)) "x" 2) (record-keys (record (cons "x" 1) (cons "y" 2))))
;; => (#<record x=1> 1 #<record x=2> ("x" "y"))
(define point (record (cons "x" 1)))
(define moved (record-set point "y" 2))
(list point moved)
;; => (#<record x=1> #<record x=1 y=2>)
Raised when Message
An argument of record is not a pair with a string key record expects pairs with string keys
Two arguments of record have the same key Duplicate record field: key
The first argument of record-ref, record-set or record-keys is not a record Expected record
The key is not a string Expected string
The key given to record-ref is not in the record Missing record field
(record-ref (record (cons "x" 1)) "y")
;; error: Missing record field

Vectors

Vectors are immutable, and indexes start at 0.

Procedure Arguments Result Example
vector zero or more values a vector of them (vector 1 2) → #(1 2)
vector-ref a vector and an exact integer index the element at the index (vector-ref #(a b c) 1) → b
vector-length a vector its number of elements (vector-length #(a b c)) → 3
(list (vector 1 2) (vector-ref #(a b c) 1) (vector-length #(a b c)))
;; => (#(1 2) b 3)
Raised when Message
The arguments of vector-ref are not a vector and an exact integer Expected vector and integer
The index is negative or not less than the length Vector index out of range
The argument of vector-length is not a vector Expected vector
(vector-ref #(a b c) 3)
;; error: Vector index out of range

Other

Procedure Arguments Result Example
not one value #t for #f, and #f for any other value (not 0) → #f
boolean? one value #t for a boolean (boolean? #f) → #t
unit none the unit value (unit) → #<unit>
error zero or more values raises an Invalid error and never returns (error "Not found:" 'key) raises "Not found:" key
(list (not 0) (boolean? #f) (unit))
;; => (#f #t #<unit>)

The message of error is its arguments printed with value_to_string and joined by spaces. A string argument keeps its quotes in the message; R6RS error shows the message string without quotes. This is a known deviation, tracked by bead morphir-ukvn.5.48.

(error "Not found:" 'key)
;; error: "Not found:" key

Errors

Every failure raises a SchemeError. The reader raises on bad text before any form of the program runs. The evaluator raises while it runs, and definitions made before the error stay in the session. The language has no way to catch an error, so it always reaches the host. error_message(error) turns an error into the message shown in this chapter.

Kind Raised for error_message gives
Syntax(message, offset) Text the reader refuses Syntax at character offset: message
Unbound(name) A name with no binding Unbound identifier: name
Invalid(message) A wrong form, a wrong argument or the error procedure message
Unsupported(message) A feature outside the language Unsupported: message
Limit(resource) An exhausted limit or a cancelled run Limit exceeded: resource
Domain(domain, message) A domain failure raised by another package message
Stage(stage, message) A failure in a named pipeline stage, raised by another package stage: message
(define x 1) (car x))
;; error: Syntax at character 20: Unexpected closing delimiter
undefined-name
;; error: Unbound identifier: undefined-name
(car 1)
;; error: Expected pair
`(1 ,x)
;; error: Unsupported: Quasiquotation is not in the Morphir Scheme core
(define (deep n) (+ 1 (deep n)))
(deep 0)
;; error: Limit exceeded: evaluation depth

Limits

Limits bounds evaluation steps, recursive evaluation depth and allocated lexical frames. Defaults are 1,000,000 steps, depth 256 and 100,000 frames. Each public evaluation/call starts a step budget; nested host callbacks share it. Direct tail calls use a trampoline and constant host stack, but allocate frames in a session-owned arena. Frames are retained until the session is released; create fresh sessions for independent jobs. Calls through apply and host callbacks are depth-bounded rather than trampoline tail calls.

Limit Default Bounds Message
steps 1,000,000 Evaluation steps in one public eval, call or with_budget Limit exceeded: evaluation steps
depth 256 Nested evaluations, such as arguments inside arguments and calls that are not in tail position Limit exceeded: evaluation depth
frames 100,000 Lexical scopes allocated in the session so far Limit exceeded: environment frames

A cancelled run raises Limit exceeded: cancelled (see Embedding). The reader and the printer have a fixed nesting limit of 256 of their own.

Every closure call allocates a frame, including a tail call, and so does every let, let* and letrec. A loop of 100,000 iterations therefore exceeds the default frame limit, even though it runs in constant host stack.

(let loop () (loop))
;; error: Limit exceeded: environment frames
///|
test "limits bound a session and leave it usable" {
  let runtime = @scheme.Runtime::new(limits={
    steps: 100,
    depth: 32,
    frames: 100,
  })
  let message = try {
    ignore(runtime.eval("(let loop () (loop))"))
    ""
  } catch {
    e => @scheme.error_message(e)
  }
  inspect(message, content="Limit exceeded: evaluation steps")
  inspect(@scheme.value_to_string(runtime.eval("(+ 1 2)")), content="3")
  assert_eq(@scheme.Limits::default(), {
    steps: 1000000,
    depth: 256,
    frames: 100000,
  })
}

The language has no filesystem or network procedures. Host extensions are trusted capabilities. These limits are execution controls, not an OS sandbox or a complete memory/time bound: parsing, large exact arithmetic, serialization and host I/O also consume resources. IR lowering, rewriting and pattern matching impose depth limits. Errors propagate through the embedding API.

Embedding

A Runtime is one session. Runtime::eval reads and evaluates source text and returns the last value.

///|
test "a runtime evaluates source text" {
  let runtime = @scheme.Runtime::new()
  ignore(runtime.eval("(define (inc x) (+ x 1))"))
  let answer = runtime.eval("(inc 41)")
  inspect(@scheme.value_to_string(answer), content="42")
}

Sessions retain definitions. Register host procedures explicitly with Runtime::define_native(name, (runtime, arguments) -> Value raise). Closures belong to the session that created them; calling a closure in another session raises an error. Use error_message(error) to include error details.

///|
test "a host procedure joins the session" {
  let runtime = @scheme.Runtime::new()
  runtime.define_native("shout", fn(_runtime, arguments) raise {
    @scheme.arity(arguments, 1, "shout")
    @scheme.Text(arguments[0].as_text() + "!")
  })
  inspect(
    @scheme.value_to_string(runtime.eval("(shout \"hi\")")),
    content="\"hi!\"",
  )
}

///|
test "a closure belongs to its session" {
  let first = @scheme.Runtime::new()
  let second = @scheme.Runtime::new()
  let closure = first.eval("(lambda (x) x)")
  let message = try {
    ignore(second.call(closure, [@scheme.Unit]))
    ""
  } catch {
    e => @scheme.error_message(e)
  }
  assert_true(message != "")
}

///|
test "error_message includes the error details" {
  let runtime = @scheme.Runtime::new()
  let message = try {
    ignore(runtime.eval("(letrec ((a b) (b 1)) a)"))
    ""
  } catch {
    e => @scheme.error_message(e)
  }
  inspect(message, content="Uninitialized recursive binding: b")
}
Function Purpose
Runtime::new(), Runtime::new(limits=...) A new session with the built-in procedures; raises Runtime limits must be positive for a limit of zero or less
Runtime::eval(source) Read and evaluate a program; the value of its last form
Runtime::call(procedure, arguments) Call a procedure value from the host
Runtime::define_native(name, procedure) Bind a host procedure, replacing any binding of the name, built-ins included
Runtime::register_native_binding(name, arity, procedure) Bind a host procedure with a fixed arity; raises Duplicate native binding: name if the name has one
Runtime::replace_native_binding(name, arity, procedure) Replace an existing host procedure; raises No native binding to replace: name otherwise
Runtime::has_native(name), Runtime::native_arity(name) Whether a host procedure exists, and its registered arity
Runtime::set_global(name, value), Runtime::lookup(name) Write and read a top-level binding
Runtime::set_cancelled(cancelled) A check the evaluator runs at every step; true stops the run with Limit exceeded: cancelled
Runtime::with_budget(work) Run host work and the Scheme calls it makes under one step budget
eval_program(source) Evaluate a program in a fresh session
parse_program(source), parse_program_located(source) Read a program into data, without and with source offsets
value_to_string(value) The printed form of a value
error_message(error) The message of an error
arity(arguments, count, name) Check a host procedure's argument count, raising name: expected count arguments

A procedure registered with register_native_binding checks its arity before it runs. A wrong call raises name expects N arguments.

Outside the language

These R6RS features are not part of Morphir Scheme:

Feature What happens
Macros (define-syntax, syntax-rules) The names are unbound
Quasiquotation (backquote, comma) The reader raises Unsupported
Continuations (call/cc, dynamic-wind) The names are unbound
Ports and input and output No procedures exist
Mutable pairs (set-car!, set-cdr!) The names are unbound
The full numeric tower: complex numbers, infinities, NaN, exactness conversion Only exact integers, exact rationals and inexact reals exist. No literal, string->number or arithmetic gives a real that is not finite; only a host or evaluate can, as described in Values
The library system (library, import) The names are unbound
Error handling (guard, with-exception-handler) Errors always reach the host
(call/cc (lambda (k) (k 1)))
;; error: Unbound identifier: call/cc

View source on GitHub