Module starlark::values

Defines a runtime Starlark value (Value) and traits for defining custom values (StarlarkValue).

This module contains code for working with Starlark values:

• Most code dealing with Starlark will use Value, as it represents the fundamental values used in Starlark. When frozen, they become FrozenValue.
• Values are garbage-collected, so a given Value lives on a Heap.
• Rust values (e.g. String, Vec) can be added to the Heap with AllocValue, and deconstructed from a Value with UnpackValue (or specialised methods like unpack_str).
• To define your own Rust data type that can live in a Value it must implement the StarlarkValue trait.
• All the nested modules represent the built-in Starlark values. These are all defined using StarlarkValue, so may serve as interesting inspiration for writing your own values, in addition to occuring in Starlark programs.

Modules

any

A type StarlarkAny which can cheaply wrap any Rust value into a Value.

array

Array type used in implementation of List.

bool

The boolean type (False and True).

dict

The dictionary type, a mutable associative-map, which iterates in insertion order.

display

Utilities to implement Display (or repr) for Starlark values.

docs

Types supporting documentation for code written in or for Starlark.

enumeration

Fixed set enumerations, with runtime checking of validity.

float

The floating point number type (3.14, 4e2).

function

Function types, including native functions and object.member functions.

int

The integer type. Currently limited to 32 bit.

list

The list type, a mutable sequence of values.

none

The None type.

range

The range type, constructed with range().

record

A record type, comprising of a fixed set of fields.

string

The string type. All strings must be valid UTF8.

structs

The struct type, an associative-map created with struct().

tuple

The list type, an immutable sequence of values.

Macros

const_frozen_string

Create a FrozenStringValue.

starlark_attrs

Generate {has,get,dir}_attr in the StarlarkValue impl block that proxy to the ones generated by derive(StarlarkAttrs)

Structs

Freezer

Used to freeze values by Freeze::freeze.

FrozenHeap

A heap on which FrozenValues can be allocated. Can be kept alive by a FrozenHeapRef.

FrozenHeapRef

A reference to a FrozenHeap that keeps alive all values on the underlying heap. Note that the Hash is consistent for a single FrozenHeapRef, but non-deterministic across executions and distinct but observably identical FrozenHeapRef values.

FrozenRef

A FrozenRef is essentially a FrozenValue, and has the same memory and access guarantees as it. However, this keeps the type of the type T of the actual FrozenValue as a reference, allowing manipulation of the actual typed data.

FrozenStringValue

Define a &'static str that can be converted to a FrozenValue.

FrozenValue

A Value that can never be changed. Can be converted back to a Value with to_value.

FrozenValueTyped

FrozenValue wrapper which asserts contained value is of type <T>.

Heap

A heap on which Values can be allocated. The values will be annotated with the heap lifetime.

OwnedFrozenValue

A FrozenValue along with a FrozenHeapRef that ensures it is kept alive. Obtained from FrozenModule::get or OwnedFrozenValue::alloc.

OwnedFrozenValueTyped

Same as OwnedFrozenValue but it is known to contain T.

StarlarkStrNRepr

A constant string that can be converted to a FrozenValue.

StringValue

Wrapper for a Value which can only contain a StarlarkStr.

Tracer

Used to perform garbage collection by Trace::trace.

Value

A Starlark value. The lifetime argument 'v corresponds to the Heap it is stored on.

ValueIdentity

An opaque value representing the identity of a given Value. Two values have the same identity if and only if Value::ptr_eq would return true on them.

ValueOf

A wrapper that keeps the original value on the heap for use elsewhere, and also, when unpacked, unpacks the value to validate it is of the correct type. Has an UnpackValue instance, so often used as an argument to #[starlark_module] defined functions.

ValueTyped

Value wrapper which asserts contained value is of type <T>.

Enums

NoSimpleValue

Non-instantiatable type implementing a simple StarlarkValue.

ValueError

Common errors returned by Starlark evaluation.

Traits

AllocFrozenValue

Trait for things that can be allocated on a FrozenHeap producing a FrozenValue.

AllocValue

Trait for things that can be created on a Heap producing a Value.

AnyLifetime

Like Any, but while Any requires 'static, this version allows a lifetime parameter.

Coerce

A marker trait such that the existence of From: Coerce<To> implies that From can be treat as To without any data manipulation. Particularly useful for containers, e.g. Vec<From> can be treated as Vec<To> in O(1). If such an instance is available, you can use coerce and coerce_ref to perform the conversion.

ComplexValue

A trait for values which are more complex - because they are either mutable, or contain references to other values.

Freeze

Need to be implemented for non-simple StarlarkValue.

ProvidesStaticType

Provides access to the same type as Self but with all lifetimes dropped to 'static (including lifetimes of parameters).

StarlarkValue

How to put a Rust values into Values.

Trace

Called by the garbage collection, and must walk over every contained Value in the type. Marked unsafe because if you miss a nested Value, it will probably segfault.

UnpackValue

How to convert a Value to a Rust type. Required for all arguments in a #[starlark_module] definition.

ValueLike

Abstract over Value and FrozenValue.

Derive Macros

AnyLifetime

Derive the AnyLifetime trait. Requires the type has no type arguments, no constant arguments, and at most one lifetime argument.

Coerce

Freeze

Derive the Freeze trait.

NoSerialize

Derive the NoSerialize trait for serde.

StarlarkAttrs

Derive accessor methods that are designed to be used from {has,get,dir}_attr in an impl StarlarkValue block. All fields in the struct that are not marked with #[starlark(skip)] are exported to Starlark code as attributes. NOTE: Any usage must also call starlark_attrs!() in the impl block for StarlarkValue, otherwise the generated attr methods will not be used.

Trace

Derive the Trace trait.