On this page:
5.2.1 Equality
FFI.equal
FFI.unknown
FFI.not  Equal
FFI.is  Equal
FFI.is  Not  Equal
FFI.is  Unknown
FFI.is  Equality  Result
5.2.2 Exceptions
FFI.throw  Message  Exception
FFI.make  Message  Exception
5.2.3 Lists
FFI.make  List
FFI.to  Array
FFI.is  List
5.2.4 Other Data Helpers
FFI.make  Some
FFI.make  None
FFI.make  Left
FFI.make  Right
FFI.cases

5.2 FFI Helpers

There are a number of convenience functions that aren’t native to the Pyret runtime, but are often used in JavaScript code that interacts with the runtime. Some of the most commonly used ones are documented here; this list is often growing.

5.2.1 Equality

The ffi exposes several utilities related to equality.

FFI.equal :: PyretObject

The Equal value.

FFI.unknown :: PyretObject

The Unknown value.

FFI.notEqual :: PyretFunction

The NotEqual constructor.

FFI.isEqual(Any) → JSBoolean

Checks if the given value is Equal.

FFI.isNotEqual(Any) → JSBoolean

Checks if the given value is an instance of NotEqual.

FFI.isUnknown(Any) → JSBoolean

Checks if the given value is a Unknown.

FFI.isEqualityResult(Any) → JSBoolean

Checks if the given value is an instance of a EqualityResult.

5.2.2 Exceptions

FFI helpers provide the easiest way to programmatically throw Pyret exceptions from JavaScript. Most commonly, user-defined modules will simply throw MessageExceptions that contain a string describing the error.

FFI.throwMessageException(PyretString) → Undefined

Throws an exception that Pyret recognizes and reports with a stack trace, using the provided string as the message.

FFI.makeMessageException(PyretString) → Error

Sometimes its useful to create an exception without actually throwing it, like when using the error callback of the Restarter in Runtime.pauseStack. This call creates a new exception object without throwing it.

5.2.3 Lists

Pyret lists are ubiquitous in Pyret’s internals and libraries, and this library provides a few conveniences for working with them.

FFI.makeList(JSArray) → List

Turns a JavaScript array into a Pyret List with the same elements in the same order.

FFI.toArray(List) → JSArray

Turns a Pyret List with the same elements in the same order. For doing computationally heavy work, sometimes it is useful to convert a Pyret List to an array before processing it (and using JavaScript’s map/filter, etc.), since the Pyret version incurs more overhead.

FFI.isList(Any) → JSBoolean

Returns true if the value is a Pyret List and false otherwise.

5.2.4 Other Data Helpers

FFI.makeSome(Any) → Option

FFI.makeNone() → Option

Create instances of none and some from option.

FFI.makeLeft(Any) → Either

FFI.makeRight(Any) → Either

Create instances of left and right from either.

FFI.cases(
(Any -> JSBoolean)
JSString
Any
Handlers
)
→ Any

This call emulates the functionality of the cases expression in a JavaScript context. It takes a predicate to check (usually a function like is-List), a name for the predicate being checked, a data value, and an object containing handlers for its variants. For example:

function sum(l) {

  cases(runtime.getField(lists, "is-List"), "List", l, {

    empty: function() { return "Empty"; },

    link: function(f, r) { return f + sum(r); }

  });

}

sum(runtime.ffi.makeList([1,2])) // is 3

The predicate check and name are solely for error reporting.