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 occurring in Starlark programs.

Re-exports

• pub use crate::any::AnyLifetime;
• pub use crate::any::ProvidesStaticType;
• pub use crate::coerce::Coerce;
• pub use crate::values::layout::static_string::constant_string;

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.
• enumeration
  Fixed set enumerations, with runtime checking of validity.
• exported_name
  Utilities for implementing StarlarkValue::export_as.
• float
  The floating point number type (3.14, 4e2).
• function
  Function types, including native functions and object.member functions.
• int
  The integer type.
• list
  The list type, a mutable sequence of values.
• list_or_tuple
  Utility for unpacking a value of type list[T] or tuple[T, ...] into a vec.
• none
  The None type.
• range
  The range type, constructed with range().
• record
  A record type, comprising of a fixed set of fields.
• starlark_value_as_type
  Convert a value implementing StarlarkValue into a type usable in type expression.
• 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.
• type_repr
  Trait and default implementations of a trait that will show starlark type annotations for a given type.
• typing
  Typechecker-related types.

Macros

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

Structs

• AggregateHeapProfileInfo
  Aggregated heap profiling data when heap profiling is enabled.
• Demand
  Taken by StarlarkValue::provide to provide different data depending on the type.
• 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.
• 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.
• OwnedFrozenRef
  Same as a FrozenRef, but it keeps itself alive by storing a reference to the owning heap.
• 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.
• StarlarkIterator
  Iterator of starlark values.
• StarlarkStrNRepr
  A constant string that can be converted to a FrozenValue.
• 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.
• ValueOfUnchecked
  Starlark value with type annotation.
• ValueTyped
  Value wrapper which asserts contained value is of type <T>.
• ValueTypedComplex
  Value which is either a complex mutable value or a frozen value.

Enums

• 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.
• 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.
• StarlarkValue
  How to put a Rust values into Values.
• StringValueLike
  Common type for StringValue and FrozenStringValue.
• 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.

Type Aliases

• FrozenStringValue
  Convenient type alias.
• StringValue
  Convenient type alias.

Attribute Macros

• starlark_value
  Generate missing elements of StarlarkValue trait when this attribute is applied to an impl block of StarlarkValue.

Derive Macros

• Coerce
• Freeze
  Derive the Freeze trait.
• NoSerialize
  Derive the NoSerialize trait for serde.
• ProvidesStaticType
  Derive the ProvidesStaticType trait. Requires the type has no type arguments, no constant arguments, and at most one lifetime argument.
• 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.
• UnpackValue
  Derive the UnpackValue trait.