Expand description
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 becomeFrozenValue
. - Values are garbage-collected, so a given
Value
lives on aHeap
. - Rust values (e.g.
String
,Vec
) can be added to theHeap
withAllocValue
, and deconstructed from aValue
withUnpackValue
(or specialised methods likeunpack_str
). - To define your own Rust data type that can live in a
Value
it must implement theStarlarkValue
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§
- A type
StarlarkAny
which can cheaply wrap any Rust value into aValue
. - Array type used in implementation of
List
. - The boolean type (
False
andTrue
). - The dictionary type, a mutable associative-map, which iterates in insertion order.
- Fixed set enumerations, with runtime checking of validity.
- Utilities for implementing
StarlarkValue::export_as
. - The floating point number type (3.14, 4e2).
- Function types, including native functions and
object.member
functions. - The integer type.
- The list type, a mutable sequence of values.
- Utility for unpacking a value of type
list[T]
ortuple[T, ...]
into a vec. - The
None
type. - The range type, constructed with
range()
. - A
record
type, comprising of a fixed set of fields. - Convert a value implementing
StarlarkValue
into a type usable in type expression. - The string type. All strings must be valid UTF8.
- The struct type, an associative-map created with
struct()
. - The list type, an immutable sequence of values.
- Trait and default implementations of a trait that will show starlark type annotations for a given type.
- Typechecker-related types.
Macros§
- Generate
{has,get,dir}_attr
in theStarlarkValue
impl block that proxy to the ones generated byderive(StarlarkAttrs)
Structs§
- Aggregated heap profiling data when heap profiling is enabled.
- Taken by
StarlarkValue::provide
to provide different data depending on the type. - Used to
freeze
values byFreeze::freeze
. - A heap on which
FrozenValue
s can be allocated. Can be kept alive by aFrozenHeapRef
. - A reference to a
FrozenHeap
that keeps alive all values on the underlying heap. Note that theHash
is consistent for a singleFrozenHeapRef
, but non-deterministic across executions and distinct but observably identicalFrozenHeapRef
values. - A
FrozenRef
is essentially aFrozenValue
, and has the same memory and access guarantees as it. However, this keeps the type of the typeT
of the actualFrozenValue
as a reference, allowing manipulation of the actual typed data. FrozenValue
wrapper which asserts contained value is of type<T>
.- A heap on which
Value
s can be allocated. The values will be annotated with the heap lifetime. - Same as a
FrozenRef
, but it keeps itself alive by storing a reference to the owning heap. - A
FrozenValue
along with aFrozenHeapRef
that ensures it is kept alive. Obtained fromFrozenModule::get
orOwnedFrozenValue::alloc
. - Same as
OwnedFrozenValue
but it is known to containT
. - Iterator of starlark values.
- A constant string that can be converted to a
FrozenValue
. - Used to perform garbage collection by
Trace::trace
. - A Starlark value. The lifetime argument
'v
corresponds to theHeap
it is stored on. - An opaque value representing the identity of a given Value. Two values have the same identity if and only if
Value::ptr_eq
would returntrue
on them. - 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. - Starlark value with type annotation.
Value
wrapper which asserts contained value is of type<T>
.- Value which is either a complex mutable value or a frozen value.
Enums§
- Common errors returned by Starlark evaluation.
Traits§
- Trait for things that can be allocated on a
FrozenHeap
producing aFrozenValue
. - A trait for values which are more complex - because they are either mutable, or contain references to other values.
- Need to be implemented for non-simple
StarlarkValue
. - How to put a Rust values into
Value
s. - Common type for
StringValue
andFrozenStringValue
. - Called by the garbage collection, and must walk over every contained
Value
in the type. Markedunsafe
because if you miss a nestedValue
, it will probably segfault. - How to convert a
Value
to a Rust type. Required for all arguments in a#[starlark_module]
definition. - Abstract over
Value
andFrozenValue
.
Type Aliases§
- Convenient type alias.
- Convenient type alias.
Attribute Macros§
- Generate missing elements of
StarlarkValue
trait when this attribute is applied to an impl block ofStarlarkValue
.
Derive Macros§
- Derive the
Freeze
trait. - Derive the
NoSerialize
trait for serde. - Derive the
ProvidesStaticType
trait. Requires the type has no type arguments, no constant arguments, and at most one lifetime argument. - 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 callstarlark_attrs!()
in the impl block forStarlarkValue
, otherwise the generated attr methods will not be used. - Derive the
Trace
trait. - Derive the
UnpackValue
trait.