API reference

Every public type, trait, function and method of dxn_dtcg grouped by purpose, with simplified signatures.

Every public item of dxn_dtcg, grouped by purpose. All items are exported from the crate root, except the typed value models, which live in the public dxn_dtcg::values module, and the expression types, which live in dxn_dtcg::expressions (feature expressions). Signatures are simplified (no pub). The crate is not published to docs.rs; run cargo doc --open in your project for rustdoc of the pinned version.

A selection is &[(&str, &str)], a list of (modifier, context) pairs. Types marked #[non_exhaustive] may gain fields or variants in minor releases: match enums with a wildcard arm and build structs through constructors and setters.

#DtcgRuntime

The entry point: a document catalog, a root id, RuntimeOptions and a TypeRegistry. It is Clone (cheap: documents are reference-counted), Default, Send + Sync, and its Debug output never contains document bodies.

#Construction

resource_id is impl AsRef<str> and json is impl Into<Arc<str>> (&str, String and Arc<str> work).

#Configuration

Options are fixed at construction.

#Catalog

The module methods exist in every build; only a runtime with expressions enabled reads modules. Every catalog entry has one kind: providing JSON where the catalog holds a module, or the reverse, fails with InvalidDocument and changes nothing. See Loading documents.

#Resolution

#Inspection

#Results

#Resolution

enum Resolution<T> { Ready(T), Missing(Vec<DocumentRequest>) }   // Clone, Debug, PartialEq

fn ready(self) -> Option<T>
fn map<U>(self, f: impl FnOnce(T) -> U) -> Resolution<U>
fn is_ready(&self) -> bool
fn is_missing(&self) -> bool
fn missing(&self) -> Option<&[DocumentRequest]>

#DocumentRequest

#[non_exhaustive], all fields public: resource_id: ResourceId (the normalized id to provide), referenced_from: ResourceId (the containing document or importing module), original_reference: Arc<str> (as written, fragment included), kind: DocumentKind (what to provide).

#DocumentKind

enum DocumentKind { Json, Module }   // non_exhaustive, Clone, Copy, Debug, Eq, Hash, PartialEq

Json is a token document or resolver, answered with provide_requested_json; Module is the source text of a JavaScript or TypeScript module that expressions import, answered with provide_requested_module. Without expressions, every request is Json.

#ResolvedTokens

Clone, Debug, Default, PartialEq; equality ignores the member order of object values.

#ResolvedToken

#[non_exhaustive], Clone, Debug, PartialEq, all fields public:

path: Arc<str>                     dotted token path
token_type: Option<Arc<str>>       effective DTCG type; always Some after resolution
authored_value: serde_json::Value  the $value as written (the whole object for a token-level $ref)
value: serde_json::Value           fully resolved and validated value (an expression's result when one was evaluated)
snapshot: Option<serde_json::Value>  the resolved $value an evaluated expression replaced; None for other tokens
extensions: serde_json::Value      the token's own $extensions, or Null; never inherited
description: Option<Arc<str>>      the token's own $description; never inherited
deprecated: Deprecation            own $deprecated, else the nearest group's
source: ResourceId                 document of the winning definition

fn typed(&self, extensions: &ValueExtensions) -> Result<TypedValue, DtcgError> converts value by the effective type; failure is DtcgError::Projection.

#ResolvedGroup and Deprecation

ResolvedGroup (#[non_exhaustive], public fields): path, token_type: Option<Arc<str>> (own or nearest ancestor’s), description, deprecated: Option<Deprecation> (own), extensions (merged, or Null).

Deprecation is NotDeprecated (default), Deprecated or DeprecatedWithReason(Arc<str>), with is_deprecated(), reason() -> Option<&str> and to_json() -> Value. It derives Clone, Debug, Default, Eq, Hash, PartialEq.

#AffectedResolution

Clone, Debug, Default. iter() (re-resolved tokens in the new order), removed() -> &[String], order() -> &[String], and nodes_visited() -> usize with the diagnostics feature.

#Configuration

#Documents and references

#Modifiers and selections

ModifierAxis (#[non_exhaustive]): name: String, contexts: Vec<String> (authored order), default: Option<String>. Functions:

fn selection_from_json(inputs: &serde_json::Value) -> Result<Vec<(String, String)>, DtcgError>
fn selection_refs(selection: &[(String, String)]) -> Vec<(&str, &str)>

#Projection

trait DtcgTokens: Sized {
    fn project_at(tokens: &ResolvedTokens, registry: &TypeRegistry, root: &str) -> Result<Self, DtcgError>;
    fn project(tokens: &ResolvedTokens, registry: &TypeRegistry) -> Result<Self, DtcgError>;   // root ""
}
trait DtcgComponentTokens: DtcgTokens { fn component_id() -> &'static str; }
trait FromDtcgValue: Sized + 'static { fn from_dtcg(token: &ResolvedToken) -> Result<Self, DtcgError>; }
struct TypeRegistry;   // fn convert<T: FromDtcgValue>(&self, token: &ResolvedToken) -> Result<T, DtcgError>
fn join_token_path(root: &str, path: &str) -> String

FromDtcgValue is implemented for String, f64, f32, bool, the values models and TypedValue. join_token_path joins with . and ignores empty parts. The derive macros #[derive(DtcgTokens)] and #[derive(DtcgComponentTokens)] are re-exported from dxn_dtcg_derive; attributes are in Typed projection.

#Values

fn validate_value(token_type: &str, value: &Value) -> Result<(), ValueValidationError>
fn validate_value_with(token_type: &str, value: &Value, extensions: &ValueExtensions) -> Result<(), ValueValidationError>
const BLUR_TYPE: &str = "dxn.dtcg.blur"
const EXPRESSION_EXTENSION: &str = "dxn.dtcg.expressions"
enum ValueValidationError { UnsupportedType(String), InvalidValue(String) }   // non_exhaustive, std::error::Error

The dxn_dtcg::values module holds Color, ColorSpace (14 variants, name()), Component (Number(f64) or None), Dimension, DimensionUnit, Duration, DurationUnit, FontFamily, FontWeight, CubicBezier, StrokeStyle, LineStyle, LineCap, Border, Transition, Shadow, ShadowLayer, Gradient, GradientStop, Typography, LineHeight, Blur, BlurKind and TypedValue, a #[non_exhaustive] enum with one variant per type. TypedValue::from_resolved(token_type, &value, &extensions) validates and converts. Field-by-field tables are in Value types. ColorSpace::from_name(name) -> Option<ColorSpace> is the inverse of name().

EXPRESSION_EXTENSION is the $extensions key of expressions; the constant exists in every build.

#Color operations

Methods on values::Color, available without any feature (Color conversions):

Every other value model, ShadowLayer included, also has to_json(). The twelve models of the DTCG types (Color, Dimension, Duration, CubicBezier, FontFamily, FontWeight, StrokeStyle, Border, Transition, Shadow, Gradient and Typography) implement serde’s Serialize and Deserialize with their DTCG JSON forms; deserializing validates the value as its DTCG type with every value extension.

#Inspection types

Free functions set_sources(resource, &definition) -> Result<&[Value], DtcgError> and modifier_contexts(resource, &definition) -> Result<&Map<String, Value>, DtcgError> read resolver definitions with the runtime’s checks.

#Expressions

The dxn_dtcg::expressions module exists with the expressions feature. See Expressions.

#DtcgError and diagnostics

DtcgError is documented variant by variant in Errors, including DtcgError::Expression { resource, path, message } for expressions. With the diagnostics feature, DtcgDiagnostic (from_error, code, resource, path, message) and DtcgDiagnosticCode (with Expression for expression errors) are available; see Limits and diagnostics.

Next: Conformance.