5.1 Runtime API

Pyret exposes most of its internal operations on the runtime object; most JavaScript code that interacts with Pyret will need to know about the runtime.

The library that defines runtimes is in src/js/base/runtime-anf.js, and it is configured to be importable with js/runtime-anf via RequireJS:

Create a new Pyret runtime. The RuntimeLib value itself only exports this interface, and most other useful functions are referenced from the runtime objecs it creates. The options are:

The size of the Pyret stack is constrained to initialGas frames; most applications have little need to set this.

For applications that need control over printing, they can set stdout and stderr to get called whenever Pyret would print strings (e.g. via print). This interface may change to accept all Pyret values at some point, to allow for richer rendering interfaces.

5.1.1 The Pyret Runtime

The return value of RuntimeLib.create is a runtime object with many useful methods for programmatically interacting with Pyret.

5.1.1.1 Running Pyret Programs

Uses toLoad—the list of URIs—to evaluate modules in order. The modules are found in the modules dictionary, and the dependencies dictionary describes which modules they depend on. This structure is described in Complete Programs.

A more important feature of Runtime.runStandalone is the ability to register postLoadHooks. This dictionary, keyed on URI, contains callbacks which are invoked on completion of the corresponding module, and passed the module’s result. The most obvious candidate for a postLoadHook is the main module, or the last one in the toLoad list; this is where test results can be fetched and printed and errors reported, based on the returned [REF PyretModuleResult].

In addition, Pyret’s default standalones register several postLoadHooks. For example, after the ffi library is loaded, a number of new fields are added to runtime to manipulate lists. Other uses include:

• Substituting a different checker library by setting current-checker after loading the appropriate library.

• Logging the completion time for loading each module in the toLoad list for benchmarking.

While evaluating the modules, the runtime caches the results for each module that completed successfully, in the runtime.modules dictionary. This can be accessed later to quickly get the exported values of a module without re-running it.

5.1.1.2 Creating Values

Parses the string and creates a representation of the number that avoids float overflows and can represent very large and very small rationals exactly.

The representation of Pyret strings is JS strings, though this may change to accommodate better Unicode support in the future.

The runtime values for true and false in Pyret. Representation is JavaScript true and false.

Creates a Pyret RawArray with the given elements. Currently the identity function: Pyret raw arrays are JavaScript arrays.

Creates a Pyret object with the fields in the input object. The representation of an object is not one-to-one with JS objects.

The fields of a Pyret object go in the dict field of the JS object, and the JS object has an additional field called brands, which hold information about an object’s type information (if it has any). StringDicts, for example, are branded objects.

Returns a Pyret function backed by the provided JS function. The Pyret function will not do any arity checks on behalf of the JS function, so any arity checks need to be done explicitly (see Runtime.checkArity). The function can be accessed directly via the app field of the Pyret function, but read the section on Runtime.safeCall in order to suitably protect calls to Pyret functions.

5.1.1.3 Interacting with Objects

Gets the field with the given name from the object. If the field is a method, it is automatically curried over the object, as with dot.

Gets the field with the given name from the object. If the field is a method, no additional work is performed.

Returns all the field names of the given object.

Checks if the given object has the named field.

5.1.1.4 Assertions

Checks that the given argument list has the given arity. Throws an exception if they don’t match.

There are a number of checking functions that check that a given argument is of a particular type, and throw an exception if not:

5.1.1.5 Equality

Takes two EqualityResults and combines them. Any value paired with NotEqual produces NotEqual, any combination of Equal and Unknown produces Unknown, and two Equal values produce Equal.

5.1.1.6 FFI Helpers

The Pyret runtime instantiates an FFIHelpers object and stores in in the ffi field.