Crate starlark

A Starlark interpreter library in rust.

Starlark, formerly codenamed Skylark, is a non-Turing complete language based on Python that was made for the Bazel build system to define compilation plugin.

Starlark has at least 3 implementations: a Java one for Bazel, a go one and this one.

This interpreter was made using the specification from the go version and the Python 3 documentation when things were unclear.

This interpreter does not support most of the go extensions (e.g. bitwise operator or floating point). It does not include the set() type either (the Java implementation use a custom type, depset, instead). It uses signed 64-bit integer.

Usage

The library can be used to define a dialect of Starlark (e.g. for a build system).

The methods in the eval modules can be used to evaluate Starlark code:

• General purpose eval and eval_file function evaluate Starlark code and return the result of the last statement. Those are generic purpose function to be used when rewiring load statements.
• A file loader that simply load relative path to the program is provided by the eval::simple module. This module also contains version of eval and eval_file that use this file loader.
• Interactive versions of those function are provided in the eval::interactive module. Those function are printing the result / diagnostic to the stdout / stderr instead of returning an output.

Defining a Starlark dialect

To specify a new Starlark dialect, the global Environment can be edited, adding functions or constants. The starlark_module! macro let you define new function with limited boilerplate.

Those added function or macros can however return their own type, all of them should implement the TypedValue trait. See the documentation of the values module.

Content of the default global environment

The default global environment is returned by the stdlib::global_environment function and add the True, False and None constants, as well as the functions in the stdlib module.

Provided types

The values module provide the following types:

• integer (signed 64bit), bool, and NoneType,
• string,
• dictionary,
• list,
• tuple, and
• function.

Modules

environment	The enviroment, called "Module" in this spec is the list of variable in the current scope. It can be frozen, after which all values from this environment become immutable.
eval	Evaluation environment, provide converters from Ast* element to value.
linked_hash_set
stdlib	A module with the standard function and constants that are by default in all dialect of Starlark
values	The values module define a trait TypedValue that defines the attribute of any value in Starlark and a few macro to help implementing this trait. The Value struct defines the actual structure holding a TypedValue. It is mostly used to enable mutable and Rc behavior over a TypedValue. This modules also defines this traits for the basic immutable values: int, bool and NoneType. Sub-modules implement other common types of all Starlark dialect.

Macros

check_type	A shortcut to assert the type of a value
convert_indices	Convert 2 indices according to Starlark indices convertion for function like .index.
starlark_err	Shortcut for returning an error from the code, message and label.
starlark_module	Declare a starlark module that store one or several function