Facets
Overview
Facets are a mechanism to annotate pods, types, and slots with arbitrary meta-data. Facets are similar to Java annotations or C# attributes. A facet is simply a name/value pair where the name is keyed by a symbol an the value is a serializable object.
Syntax
Facets are defined as "@symbolName=value" prefixed before a pod, type, or slot definition:
@serializable @sys::js // using qualified symbol @icon=`/icons/account.png` @version=Version("1.2") @table=Table { name="Accounts"; autoCreate=true } @todo=["fix it", "really fix it"] class Account { }
The symbol can be qualified or unqualified (see Symbols) The symbol type defines the valid type of a facet. For example @sys::uriScheme
if defined as a Str
, therefore all facets which use this symbol must have a Str
value.
If the value is omitted as it is for serializable
, then the value is assumed to be true
. The other facets illustrate various value types: icon
is a Uri
literal, version
is a simple, table
is a complex, and todo
is a list. You can create arbitrarily complex facet values through the serialization syntax.
API
Facets are available at runtime via the following methods:
Always prefer the facet
method over facets
since it is much more efficient. Some examples:
// get a description string Type.of(obj).facet(@description) // check if an object implements the simple facet Type.of(obj).facet(@simple, false) == true
If querying type facets, you can use the inherited
parameter to search facets in the inheritance chain:
// check if an object or any of its super-types has the obsolete facet Type.of(obj).facet(@obsolete, null, true)
Facet Indexing
Type facets can be indexed in the type database to allow efficient queries on the installed types. See Facet Indexing for details.