xeto

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793554583/FIN+5.3.1+xeto 中文整理基于 FIN 5.3.1

导读： Xeto 数据和规范 API

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• mixins
• classes
• enums
• Slot Details
  • add
  • addNotNull
  • call
  • callAsync
  • child
  • dis
  • each
  • eachChild
  • eachWhile
  • get
  • has
  • hasChild
  • id
  • isAbove
  • isBelow
  • isMounted
  • links
  • missing
  • name
  • onCall
  • onCallRemove
  • onCallThis
  • onChange
  • onChangeRemove
  • onChangeThis
  • onExecute
  • onExecuteFreq
  • parent
  • remove
  • set
  • spec
  • toStr
  • trap
  • now
  • equals
  • fromStr
  • hash
  • make
  • w
  • x
  • y
  • makeForSpec
  • _id
  • isEmpty
  • map
  • isAsync
  • depends
  • files
  • global
  • globals
  • instance
  • instances
  • meta
  • metaSpec
  • metaSpecs
  • specs
  • type
  • types
  • version
  • versions
  • contains
  • fromVersion
  • wildcard
  • isSupported
  • list
  • base
  • choice
  • compileData
  • compileDicts
  • compileLib
  • digest
  • eachInstance
  • eachSubtype
  • eachType
  • eachTypeWhile
  • fits
  • hasLib
  • hasSubtypes
  • instanceAsync
  • instantiate
  • isAllLoaded
  • isOverlay
  • lib
  • libAsync
  • libErr
  • libListAsync
  • libStatus
  • libs
  • libsAllAsync
  • specAsync
  • specOf
  • validate
  • validateAll
  • writeData
  • xmeta
  • xmetaEnum
  • createNamespace
  • createOverlayNamespace
  • cur
  • latest
  • latestMatch
  • solveDepends
  • err
  • notLoaded
  • ok
  • vals
  • compare
  • doc
  • orderByDepends
  • fromRef
  • fromSlot
  • eachLink
  • isLinked
  • listOn
  • level
  • loc
• …（其余标题见英文正文）

---

API 正文（英文）

enums

LibStatus	LibStatus
ValidateLevel	ValidateLevel

---

Comp

@Js mixin Comp

Component or function block

Methods

add	Add a slot.
addNotNull	Add a slot if value is not null.
call	Call a method slot synchronously.
callAsync	Call a method slot asynchronously.
child	Lookup a child component by name
dis	Return display string for this component
each	Iterate slot name/value pairs using same semantics as get.
eachChild	Iterate children components in the tree structure
eachWhile	Iterate name/value pairs until callback returns non-null
get	Get the given slot value or null if slot name not defined.
has	Return true if this component has a slot by given name.
hasChild	Check if a child component is mapped by the given name
id	Return id that uniquely identifies this component within its space.
isAbove	Is this is an ancestor in the tree of the given component.
isBelow	Is this component is a descendant in the tree of the given component.
isMounted	Return if this component is mounted into a component space
links	Gets links slot as dict of incoming component links
missing	Return true if the component does not have a slot by given name.
name	Slot name under parent or "" if parent is null
onCall	Callback when a method is called.
onCallRemove	Remove an onCall callback
onCallThis	Callback on instance itself when a call is invoked.
onChange	Callback when a slot is modified.
onChangeRemove	Remove an onChange callback
onChangeThis	Callback on instance itself when a slot is modified.
onExecute	Callback to recompute component state.
onExecuteFreq	How often should this component have its onExecute callback invoked.
parent	Parent component or null if root/unmounted
remove	Remove a slot by name.
set	Set a slot by name.
spec	Xeto type for this component
toStr	Return debug string
trap	Get or set the slot mapped by the given name.

Slot Details

---

add

@Operator This add(Obj val, Str? name := null)

Add a slot. If name is null one is auto-generated otherwise the name must be unique.

---

addNotNull

This addNotNull(Obj? val, Str? name := null)

Add a slot if value is not null. If name is null one is auto-generated.

---

call

Obj? call(Str name, Obj? arg := null)

Call a method slot synchronously. If slot is not found then silently ignore and return null. If slot is defined but not a Function or the Function must be called asynchronously then raise exception.

---

callAsync

Void callAsync(Str name, Obj? arg, |Err?,Obj?| cb)

Call a method slot asynchronously. If slot is not found then silently ignore and return null. If slot is defined but not an Function then raise exception.

---

child

virtual Comp? child(Str name, Bool checked := true)

Lookup a child component by name

---

dis

Str dis()

Return display string for this component

---

each

Void each(|Obj,Str| f)

Iterate slot name/value pairs using same semantics as get.

---

eachChild

Void eachChild(|Comp,Str| f)

Iterate children components in the tree structure

---

eachWhile

Obj? eachWhile(|Obj,Str->Obj?| f)

Iterate name/value pairs until callback returns non-null

---

get

@Operator Obj? get(Str name)

Get the given slot value or null if slot name not defined.

---

has

Bool has(Str name)

Return true if this component has a slot by given name.

---

hasChild

Bool hasChild(Str name)

Check if a child component is mapped by the given name

---

id

Ref id()

Return id that uniquely identifies this component within its space.

---

isAbove

Bool isAbove(Comp child)

Is this is an ancestor in the tree of the given component. If the given component is this, then return true.

---

isBelow

Bool isBelow(Comp parent)

Is this component is a descendant in the tree of the given component. If the given component is this, then return true.

---

isMounted

Bool isMounted()

Return if this component is mounted into a component space

---

links

Links links()

Gets links slot as dict of incoming component links

---

missing

Bool missing(Str name)

Return true if the component does not have a slot by given name.

---

name

Str name()

Slot name under parent or "" if parent is null

---

onCall

Void onCall(Str name, |This,Obj?| cb)

Callback when a method is called. This is an observer callback only and will not determine the result value of calling a method.

---

onCallRemove

Void onCallRemove(Str name, Func cb)

Remove an onCall callback

---

onCallThis

virtual Void onCallThis(Str name, Obj? arg)

Callback on instance itself when a call is invoked.

---

onChange

Void onChange(Str name, |This,Obj?| cb)

Callback when a slot is modified. The newVal is null if the slot was removed.

---

onChangeRemove

Void onChangeRemove(Str name, Func cb)

Remove an onChange callback

---

onChangeThis

virtual Void onChangeThis(Str name, Obj? newVal)

Callback on instance itself when a slot is modified. Value is null if slot removed.

---

onExecute

virtual Void onExecute()

Callback to recompute component state. This is always called within a CompContext.

---

onExecuteFreq

virtual Duration? onExecuteFreq()

How often should this component have its onExecute callback invoked. Return null if this component has no time based computation.

---

parent

virtual Comp? parent()

Parent component or null if root/unmounted

---

remove

This remove(Str name)

Remove a slot by name. Do nothing is name isn't mapped.

---

set

@Operator This set(Str name, Obj? val)

Set a slot by name. If val is null, then this is a convenience for remove.

---

spec

Spec spec()

Xeto type for this component

---

toStr

virtual override Str toStr()

Return debug string

---

trap

override Obj? trap(Str name, Obj?[]? args := null)

Get or set the slot mapped by the given name.

---

CompContext

@Js mixin CompContext : ActorContext

Context for Comp.onExecute

Methods

now	Current DateTime to use; might be simulated

Slot Details

---

now

abstract DateTime now()

Current DateTime to use; might be simulated

---

CompLayout

@Js const class CompLayout : Obj

CompLayout models layout of a component on a logical grid coordinate system

Constructors

fromStr	Parse from string as "x,y,w"
make	Constructor

Methods

equals	Return if obj is same CompLayout value.
hash	Return hash of x, y, and h
toStr	String representation as "x,y,w"
w	Width in logical coordinate system
x	Logical x coordinate
y	Logical y coordinate

Slot Details

---

equals

virtual override Bool equals(Obj? obj)

Return if obj is same CompLayout value.

---

fromStr

static new fromStr(Str s, Bool checked := true)

Parse from string as "x,y,w"

---

hash

virtual override Int hash()

Return hash of x, y, and h

---

make

new make(Int x, Int y, Int w := 8)

Constructor

---

toStr

virtual override Str toStr()

String representation as "x,y,w"

---

w

Int w()

Width in logical coordinate system

---

x

Int x()

Logical x coordinate

---

y

Int y()

Logical y coordinate

---

CompObj

@Js class CompObj : Obj, Comp

CompObj is the base class for all Comp subclasses

Constructors

make	Constructor for subclasses
makeForSpec	Constructor for generic component with given spec

Slot Details

---

make

new make()

Constructor for subclasses

---

makeForSpec

static new makeForSpec(Spec spec)

Constructor for generic component with given spec

---

Dict

@Js const mixin Dict

Dict is an immutable map of name/value pairs.

Methods

_id
each	Iterate through the name/value pairs
eachWhile	Iterate through the name/value pairs until the given function returns non-null, then break the iteration and return resulting object.
get	Get the value for the given name or def if name not mapped
has	Return true if this dictionary contains given name
isEmpty	Return if the there are no name/value pairs
map	Create a new instance of this dict with the same names, but apply the specified closure to generate new values.
missing	Return true if this dictionary does not contain given name
trap	Get the value mapped by the given name.

Slot Details

---

_id

abstract Ref _id()

---

each

abstract Void each(|Obj,Str| f)

Iterate through the name/value pairs

---

eachWhile

abstract Obj? eachWhile(|Obj,Str->Obj?| f)

Iterate through the name/value pairs until the given function returns non-null, then break the iteration and return resulting object. Return null if function returns null for every name/value pair.

---

get

@Operator abstract Obj? get(Str name, Obj? def := null)

Get the value for the given name or def if name not mapped

---

has

abstract Bool has(Str name)

Return true if this dictionary contains given name

---

isEmpty

abstract Bool isEmpty()

Return if the there are no name/value pairs

---

map

abstract This map(|Obj,Str->Obj| f)

Create a new instance of this dict with the same names, but apply the specified closure to generate new values.

---

missing

abstract Bool missing(Str name)

Return true if this dictionary does not contain given name

---

trap

abstract override Obj? trap(Str name, Obj?[]? args := null)

Get the value mapped by the given name. If it is not mapped to a non-null value, then throw an UnknownNameErr.

---

Function

@Js mixin Function

Function is a computation modeled by the sys::Func spec.

Methods

call	Call the function with component and argument.
callAsync	Call the function with component and argument asynchronously.
isAsync	Return if this function must be called asynchronously

Slot Details

---

call

abstract Obj? call(Comp self, Obj? arg)

Call the function with component and argument. Raise exception if the function must be called async.

---

callAsync

abstract Void callAsync(Comp self, Obj? arg, |Err?,Obj?| cb)

Call the function with component and argument asynchronously. Invoke the given callback with an exception or result object.

---

isAsync

abstract Bool isAsync()

Return if this function must be called asynchronously

---

Lib

@Js const mixin Lib : Dict

Versioned library module of specs and defs.

Lib dict representation:

• id: Ref "lib:{name}"
• spec: Ref "sys::Lib"
• loaded: marker tag if loaded into memory
• meta

Methods

_id	Return "lib:{name}" as identifier This is a temp shim until we move haystack::Dict fully into Xeto.
depends	List the dependencies
files	Access all the resource files contained by this library.
global	Lookup a top level global slot spec in this library by simple name
globals	List the top level global slots
instance	Lookup an instance dict by its simple name
instances	List the instance data dicts declared in this library
meta	Meta data for library
metaSpec	Lookup a top level meta spec in this library by simple name
metaSpecs	List the top level meta specs
name	Dotted name of the library
spec	Lookup a top level spec in this library by simple name (type or global slot)
specs	List the top level specs (types and global slots)
type	Lookup a top level type spec in this library by simple name
types	List the top level types
version	Version of this library

Slot Details

---

_id

abstract override Ref _id()

Return "lib:{name}" as identifier This is a temp shim until we move haystack::Dict fully into Xeto.

---

depends

abstract LibDepend[] depends()

List the dependencies

---

files

abstract LibFiles files()

Access all the resource files contained by this library. Resources are any files included in the libs's zip file excluding xeto files. This API is only available in server environments.

---

global

abstract Spec? global(Str name, Bool checked := true)

Lookup a top level global slot spec in this library by simple name

---

globals

abstract Spec[] globals()

List the top level global slots

---

instance

abstract Dict? instance(Str name, Bool checked := true)

Lookup an instance dict by its simple name

---

instances

abstract Dict[] instances()

List the instance data dicts declared in this library

---

meta

abstract Dict meta()

Meta data for library

---

metaSpec

abstract Spec? metaSpec(Str name, Bool checked := true)

Lookup a top level meta spec in this library by simple name

---

metaSpecs

abstract Spec[] metaSpecs()

List the top level meta specs

---

name

abstract Str name()

Dotted name of the library

---

spec

abstract Spec? spec(Str name, Bool checked := true)

Lookup a top level spec in this library by simple name (type or global slot)

---

specs

abstract Spec[] specs()

List the top level specs (types and global slots)

---

type

abstract Spec? type(Str name, Bool checked := true)

Lookup a top level type spec in this library by simple name

---

types

abstract Spec[] types()

List the top level types

---

version

abstract Version version()

Version of this library

---

LibDepend

@Js const mixin LibDepend : Dict

Xeto library dependency as name and version constraints

Constructors

make	Construct with name and version constraints

Methods

name	Library dotted name
toStr	String representation is "<qname> <versions>"
versions	Version constraints that satisify this dependency

Slot Details

---

make

static new make(Str name, LibDependVersions versions := LibDependVersions.wildcard())

Construct with name and version constraints

---

name

abstract Str name()

Library dotted name

---

toStr

abstract override Str toStr()

String representation is "<qname> <versions>"

---

versions

abstract LibDependVersions versions()

Version constraints that satisify this dependency

---

LibDependVersions

@Js const mixin LibDependVersions

Xeto library dependency version constraints. The format is:

<range>    :=  <ver> "-" <ver>
<ver>      :=  <seg> "." <seg> "." <seg>
<seg>      :=  <wildcard> | <number>
<wildcard> :=  "x"
<number>   :=  <digit>+
<digit>    :=  "0" - "9"

Examples:

1.2.3         // version 1.2.3 exact
1.2.x         // any version that starts with "1.2."
3.x.x         // any version that starts with "3."
1.0.0-2.0.0   // range from 1.0.0 to 2.0.0 inclusive
1.2.0-1.3.x   // range from 1.2.0 to 1.3.* inclusive

Constructors

fromStr	Parse string representation
fromVersion	Create exact match for given version

Methods

contains	Return if the given version satisifies this instance's constraints
wildcard	Constant for "x.x.x"

Slot Details

---

contains

abstract Bool contains(Version version)

Return if the given version satisifies this instance's constraints

---

fromStr

static new fromStr(Str s, Bool checked := true)

Parse string representation

---

fromVersion

static new fromVersion(Version v)

Create exact match for given version

---

wildcard

static LibDependVersions wildcard()

Constant for "x.x.x"

---

LibFiles

@Js const mixin LibFiles

Access to file resources packaged with library.

Methods

get	Get a file in this library (treat this file as readonly)
isSupported	Return if this API is supported, will be false in browser environments.
list	List resource files in this library.

Slot Details

---

get

abstract File? get(Uri uri, Bool checked := true)

Get a file in this library (treat this file as readonly)

---

isSupported

abstract Bool isSupported()

Return if this API is supported, will be false in browser environments.

---

list

abstract Uri[] list()

List resource files in this library.

---

LibNamespace

@Js const mixin LibNamespace

Library namespace is a pinned manifest of specific library versions. Namespaces may lazily load their libs, in which case not all operations are supported. Create a new namespace via LibRepo.createNamespace.

Methods

base	Return base namespace if this namespace is an overlay.
choice	Return choice API for given spec.
compileData	Compile a Xeto data file into an in-memory value.
compileDicts	Convenience for compileData but always returns data as list of dicts.
compileLib	Compile Xeto source code into a temp library.
digest	Base64 digest for this namespace based on its lib versions
eachInstance	Iterate all the instances in libs In remote namespace this only iterates loaded libs.
eachSubtype	Iterate all the direct subtypes of given type In remote namespace this only iterates loaded libs.
eachType	Iterate all the top-level types in libs.
eachTypeWhile	Iterate all top-level types in libs until callback returns non-null.
fits	Return if the given instance fits the spec via structural typing.
hasLib	Return if this namespace contains the given lib name.
hasSubtypes	Return if given type has at least one direct subtype.
instance	Get or load instance by the given qualified name See lib for behavior if the instances's lib is not loaded.
instanceAsync	Lookup an instance async in the case the lib is not loaded yet.
instantiate	Create default instance for the given spec.
isAllLoaded	Return true if the every library in this namespace has been loaded (successfully or unsuccessfully).
isOverlay	Return true if this an overlay namespace overlaid on base.
lib	Get the given library by name synchronously.
libAsync	Get or load library asynchronously by the given dotted name.
libErr	Exception for a library with lib status of err, or null otherwise.
libListAsync	Get or load list of libraries asynchronously by the given dotted names.
libStatus	Return load status for the given library name
libs	List all libraries.
libsAllAsync	Load all libraries asynchronosly.
spec	Get or load spec by the given qualified name
specAsync	Lookup a spec async in the case the lib is not loaded yet.
specOf	Spec for Fantom Type or the typeof given object
type	Get or load type by the given qualified name.
validate	Validate a single value against a spec.
validateAll	Validate a graph of records using their configured spec tag.
version	Lookup the version info for a library name in this namespace.
versions	List the library name and versions in this namespace.
writeData	Write instance data in Xeto text format to an output stream.
xmeta	Lookup the extended meta for the given spec qname.
xmetaEnum	Lookup the extended meta for an enum spec.

Slot Details

---

base

abstract LibNamespace? base()

Return base namespace if this namespace is an overlay.

---

choice

abstract SpecChoice choice(Spec spec)

Return choice API for given spec. Callers should prefer the slot over the type since the slot determines maybe and multi-choice flags. Raise exception if Spec.isChoice is false.

---

compileData

abstract Obj? compileData(Str src, Dict? opts := null)

Compile a Xeto data file into an in-memory value. All dependencies are resolved against this namespace. Raise exception if there are any syntax or semantic errors. If the file contains a scalar value or one dict, then it is returned as the value. If the file contains two or more dicts then return a Dict[] of the instances.

Options

• externRefs: marker to allow unresolved refs to compile

---

compileDicts

abstract Dict[] compileDicts(Str src, Dict? opts := null)

Convenience for compileData but always returns data as list of dicts. If the data is not a Dict nor list of Dicts, then raise an exception.

---

compileLib

abstract Lib compileLib(Str src, Dict? opts := null)

Compile Xeto source code into a temp library. All dependencies are resolved against this namespace. Raise exception if there are any syntax or semantic errors.

---

digest

abstract Str digest()

Base64 digest for this namespace based on its lib versions

---

eachInstance

abstract Void eachInstance(|Dict| f)

Iterate all the instances in libs In remote namespace this only iterates loaded libs.

---

eachSubtype

abstract Void eachSubtype(Spec base, |Spec| f)

Iterate all the direct subtypes of given type In remote namespace this only iterates loaded libs.

---

eachType

abstract Void eachType(|Spec| f)

Iterate all the top-level types in libs. In remote namespace this only iterates loaded libs.

---

eachTypeWhile

abstract Obj? eachTypeWhile(|Spec->Obj?| f)

Iterate all top-level types in libs until callback returns non-null. In remote namespace this only iterates loaded libs.

---

fits

abstract Bool fits(Obj? val, Spec spec, Dict? opts := null)

Return if the given instance fits the spec via structural typing. Options:

• graph: marker to also check graph of references such as required points
• ignoreRefs: marker to ignore if refs resolve to valid target
• haystack: marker tag to use Haystack level data fidelity

---

hasLib

abstract Bool hasLib(Str name)

Return if this namespace contains the given lib name. This is true if version will return non-null regardless of libStatus.

---

hasSubtypes

abstract Bool hasSubtypes(Spec base)

Return if given type has at least one direct subtype. In remote namespace this only iterates loaded libs.

---

instance

abstract Dict? instance(Str qname, Bool checked := true)

Get or load instance by the given qualified name See lib for behavior if the instances's lib is not loaded.

---

instanceAsync

abstract Void instanceAsync(Str qname, |Err?,Dict?| f)

Lookup an instance async in the case the lib is not loaded yet.

---

instantiate

abstract Obj? instantiate(Spec spec, Dict? opts := null)

Create default instance for the given spec. Raise exception if spec is abstract.

Options:

• graph: marker tag to instantiate graph of recs (will auto-generate ids)
• abstract: marker to supress error if spec is abstract
• id: Ref tag to include in new instance
• haystack: marker tag to use Haystack level data fidelity

---

isAllLoaded

abstract Bool isAllLoaded()

Return true if the every library in this namespace has been loaded (successfully or unsuccessfully). This method returns false is any libs have a load status of notLoaded. Many operations require a namespace to be fully loaded.

---

isOverlay

abstract Bool isOverlay()

Return true if this an overlay namespace overlaid on base.

---

lib

abstract Lib? lib(Str name, Bool checked := true)

Get the given library by name synchronously. If this is a Java environment, then the library will be compiled on its first access. If the library cannot be compiled then an exception is always raised regardless of checked flag. If this is a JS environment then the library must already have been loaded, otherwise raise exception if checked is true. Use libAsync to load a library in JS environment.

---

libAsync

abstract Void libAsync(Str name, |Err?,Lib?| f)

Get or load library asynchronously by the given dotted name. This method automatically also loads the dependency chain. Once loaded then invoke callback with library or err.

---

libErr

abstract Err? libErr(Str name)

Exception for a library with lib status of err, or null otherwise. Raise exception is library not included in this namespace.

---

libListAsync

abstract Void libListAsync(Str[] names, |Err?,Lib[]?| f)

Get or load list of libraries asynchronously by the given dotted names. This method automatically also loads the dependency chain. Once loaded then invoke callback with libraries or err. If a lib cannot be loaded then it is excluded from the callback list (so its possible the results list is not the same size as the names list).

---

libStatus

abstract LibStatus? libStatus(Str name, Bool checked := true)

Return load status for the given library name:

• notLoaded: library is included but has not been loaded yet
• ok: library is included and loaded successfully
• err: library is included but could not be loaded
• null/exception if library not included

---

libs

abstract Lib[] libs()

List all libraries. On first call, this will force all libraries to be loaded synchronously. Any libs which cannot be compiled will log an error and be excluded from this list. If isAllLoaded is true then this call can also be in JS environments, otherwise you must use the libsAllAsync call to fully load all libraries into memory.

---

libsAllAsync

abstract Void libsAllAsync(|Err?,Lib[]?| f)

Load all libraries asynchronosly. Once this operation completes successfully the isAllLoaded method will return true and the libs method may be used even in JS environments. Note that an error is reported only if the entire load failed. Individual libs which cannot be loaded will logged on server, and be excluded from the final libs list.

---

spec

abstract Spec? spec(Str qname, Bool checked := true)

Get or load spec by the given qualified name:

• type: "foo.bar::Baz"
• global: "foo.bar::baz"
• slot: "foo.bar::Baz.qux" See lib for behavior if the spec's lib is not loaded.

---

specAsync

abstract Void specAsync(Str qname, |Err?,Spec?| f)

Lookup a spec async in the case the lib is not loaded yet.

---

specOf

abstract Spec? specOf(Obj? val, Bool checked := true)

Spec for Fantom Type or the typeof given object

---

type

abstract Spec? type(Str qname, Bool checked := true)

Get or load type by the given qualified name. If the type's lib is not loaded, it is loaded synchronously.

---

validate

abstract ValidateReport validate(Obj? val, Spec? spec := null, Dict? opts := null)

Validate a single value against a spec. If spec is null, then validate against specOf(val). Should be called within an XetoContext context to verify external refs.

---

validateAll

abstract ValidateReport validateAll(Dict[] subjects, Dict? opts := null)

Validate a graph of records using their configured spec tag. Should be called within an XetoContext context to verify external refs.

---

version

abstract LibVersion? version(Str name, Bool checked := true)

Lookup the version info for a library name in this namespace.

---

versions

abstract LibVersion[] versions()

List the library name and versions in this namespace.

---

writeData

abstract Void writeData(OutStream out, Obj val, Dict? opts := null)

Write instance data in Xeto text format to an output stream. If the value is a Dict[], then it is flattened in the output. Use compileData to read data from Xeto text format.

---

xmeta

abstract Dict? xmeta(Str qname, Bool checked := true)

Lookup the extended meta for the given spec qname. This is a merge of the spec's own meta along with any instance dicts in the namespace with a local id of "xmeta-{lib}-{spec}". Only libs currently loaded are considered for the result. If the spec is not defined then return null or raise an exception based on checked flag. For example to register extended meta data on the ph::Site spec you would create an instance dict with the local name of xmeta-ph-Site.

---

xmetaEnum

abstract SpecEnum? xmetaEnum(Str qname, Bool checked := true)

Lookup the extended meta for an enum spec. This returns a SpecEnum instance with resolved extended meta for all the enum items via a merge of all libs with instances named "xmeta-{lib}-{spec}-enum".

---

LibRepo

@Js const mixin LibRepo

Library repository is a database of Xeto libs. A repository might provide access to multiple versions per library.

Methods

createNamespace	Construct a namespace for the given set of lib versions in this repo.
createOverlayNamespace	Construct a namespace that overlays the given namespace with the given list of lib versions in this repo.
cur	Current default repository for the VM
latest	Get the latest version of the library name available.
latestMatch	Get the latest version that matches the given dependency.
libs	List the library names installed in the repository.
solveDepends	Solve the dependency graph for given list of libs and return a complete dependency graph.
version	Get the info for a specific library name and version.
versions	List the verions available for given library name.

Slot Details

---

createNamespace

abstract LibNamespace createNamespace(LibVersion[] libs)

Construct a namespace for the given set of lib versions in this repo. This method does not solve the dependency graph. The list of lib versions passed must be a complete dependency tree that satisifies all version constraints. Also see solveDepends.

---

createOverlayNamespace

abstract LibNamespace createOverlayNamespace(LibNamespace base, LibVersion[] libs)

Construct a namespace that overlays the given namespace with the given list of lib versions in this repo. This method works just like createNamespace with the exception that it reuses the libs from the the base namespace. The combination of the base libs and overlay libs must be satisfy all version constraints. The overlay libs must not duplicte any libs in the base.

---

cur

static LibRepo cur()

Current default repository for the VM

---

latest

abstract LibVersion? latest(Str name, Bool checked := true)

Get the latest version of the library name available. If no versions are available then raise exception or return null based on check flag.

---

latestMatch

abstract LibVersion? latestMatch(LibDepend depend, Bool checked := true)

Get the latest version that matches the given dependency. If no matches are available, then raise exception or return null based on check flag.

---

libs

abstract Str[] libs()

List the library names installed in the repository.

---

solveDepends

abstract LibVersion[] solveDepends(LibDepend[] libs)

Solve the dependency graph for given list of libs and return a complete dependency graph. Raise an exception is no solution can be computed based on the installed lib versions.

---

version

abstract LibVersion? version(Str name, Version version, Bool checked := true)

Get the info for a specific library name and version. If the given library or version is not available then raise exception or return null based on the checked flag.

---

versions

abstract LibVersion[]? versions(Str name, Bool checked := true)

List the verions available for given library name. If the library is not available then raise exception or return null based on check flag.

---

LibStatus

@Js @Serializable { simple=true } enum class LibStatus : Enum

LibStatus

Enum

notLoaded	The library has not been loaded into the namespace yet
ok	The library was successfully loaded into namespace
err	Load was attempted, but failed due to compiler error

Constructors

fromStr	Return the LibStatus instance for the specified name.

Fields

vals	List of LibStatus values indexed by ordinal

Slot Details

---

err

const static LibStatus err := ...

Load was attempted, but failed due to compiler error

---

fromStr

static new fromStr(Str name, Bool checked := true)

Return the LibStatus instance for the specified name. If not a valid name and checked is false return null, otherwise throw ParseErr.

---

notLoaded

const static LibStatus notLoaded := ...

The library has not been loaded into the namespace yet

---

ok

const static LibStatus ok := ...

The library was successfully loaded into namespace

---

vals

const static LibStatus[] vals := ...

List of LibStatus values indexed by ordinal

---

LibVersion

@Js const mixin LibVersion

Xeto library name, version, and dependencies

Methods

compare	Sort by name, then version
depends	Dependencies of this library
doc	Summary information or empty string if not available
name	Library dotted name
orderByDepends	Order a list of versions by their dependencies.
version	Library version

Slot Details

---

compare

override Int compare(Obj that)

Sort by name, then version

---

depends

abstract LibDepend[] depends()

Dependencies of this library

---

doc

abstract Str doc()

Summary information or empty string if not available

---

name

abstract Str name()

Library dotted name

---

orderByDepends

static LibVersion[] orderByDepends(LibVersion[] libs)

Order a list of versions by their dependencies. Raise exception if the given list does not satisify all the internal dependencies or has circular dependencies.

---

version

abstract Version version()

Library version

---

Link

@Js const mixin Link : Dict

Link models a dataflow relationship between two Comp slots

Methods

fromRef	Source component identifier
fromSlot	Soruce component slot name

Slot Details

---

fromRef

abstract Ref fromRef()

Source component identifier

---

fromSlot

abstract Str fromSlot()

Soruce component slot name

---

Links

@Js const mixin Links : Dict

Links models the incoming links of a component. It is a dict keyed by the toSlot name.

Methods

add	Add given link (if not duplicate) and return new instance of Links
eachLink	Iterate all the links as flat list
isLinked	Return if given toSlot has one or more links
listOn	List all the links with the given toSlot name
remove	Remove given link (if found) and return new instance of Links

Slot Details

---

add

abstract This add(Str toSlot, Link link)

Add given link (if not duplicate) and return new instance of Links

---

eachLink

abstract Void eachLink(|Str,Link| f)

Iterate all the links as flat list

---

isLinked

abstract Bool isLinked(Str toSlot)

Return if given toSlot has one or more links

---

listOn

abstract Link[] listOn(Str toSlot)

List all the links with the given toSlot name

---

remove

abstract This remove(Str toSlot, Link link)

Remove given link (if found) and return new instance of Links

---

MXetoLogRec

@Js const class MXetoLogRec : Obj

MXetoLogRec

Constructors

make

Fields

err
id
level
loc
msg

Methods

toStr

Slot Details

---

err

virtual const override Err? err

---

id

virtual const override Ref? id

---

level

virtual const override LogLevel level

---

loc

virtual const override FileLoc loc

---

make

new make(LogLevel level, Ref? id, Str msg, FileLoc loc, Err? err)

---

msg

virtual const override Str msg

---

toStr

virtual override Str toStr()

---

Main

class Main : Obj

Stub to xetoEnv::Main

Methods

main

Slot Details

---

main

static Int main(Str[] args)

---

Ref

@Js abstract const class Ref : Obj

Ref is used to model an entity identifier and optional display string.

Methods

dis	Return display value of target if available, otherwise id
id	Identifier that does not include leading @ nor display string

Slot Details

---

dis

abstract Str dis()

Return display value of target if available, otherwise id

---

id

abstract Str id()

Identifier that does not include leading @ nor display string

---

Scalar

@Js const class Scalar : Obj

Scalar is used to represent typed scalar values when there is no native Fantom class we can use to track their type.

Constructors

make	Construct for spec qname and string value

Fields

qname	Scalar type qualified name
val	String value

Methods

equals	Equality is base on qname and val
hash	Hash is composed of type and val
toStr	Return string value

Slot Details

---

equals

virtual override Bool equals(Obj? obj)

Equality is base on qname and val

---

hash

virtual override Int hash()

Hash is composed of type and val

---

make

new make(Str qname, Str val)

Construct for spec qname and string value

---

qname

const Str qname

Scalar type qualified name

---

toStr

virtual override Str toStr()

Return string value

---

val

const Str val

String value

---

Spec

@Js const mixin Spec : Dict

Xeto data specification.

Spec dict representation:

• id: Ref "lib:{qname}"
• spec: Ref "sys::Spec"
• base: Ref to base type (types only)
• type: Ref to slot type (slots only)
• effective meta

Methods

_id	Identifier for a spec is always its qualified name This is a temp shim until we move haystack::Dict fully into Xeto.
base	Base spec from which this spec directly inherits its meta and slots.
enum	Return enum item meta.
func	Return function specific APIs.
isChoice	Return if this is a spec that inherits from sys::Choice.
isEnum	Is the base sys::Enum
isFunc	Return if this a SpecFunc that models a function signature
isMaybe	Does meta have maybe tag
isa	Return if this spec inherits from that from a nominal type perspective.
lib	Parent library for spec
meta	Get my effective meta; this does not include synthesized tags like spec
metaOwn	Get my own declared meta-data
name	Return simple name scoped by lib or parent.
parent	Parent spec which contains this spec definition and scopes name.
qname	Return fully qualified name of this spec
slot	Convenience for slots.get
slotOwn	Convenience for slotsOwn.get
slots	Get the effective children slots including inherited
slotsOwn	Get the declared children slots
type	Type of this spec.

Slot Details

---

_id

abstract override Ref _id()

Identifier for a spec is always its qualified name This is a temp shim until we move haystack::Dict fully into Xeto.

---

base

abstract Spec? base()

Base spec from which this spec directly inherits its meta and slots. Returns null if this is sys::Obj itself.

---

enum

abstract SpecEnum enum()

Return enum item meta. Raise exception if isEnum is false.

---

func

abstract SpecFunc func()

Return function specific APIs. Raise exception if isFunc is false.

---

isChoice

abstract Bool isChoice()

Return if this is a spec that inherits from sys::Choice. If this spec inherits from a choice via a And/Or type then return false. See LibNamespace.choice to access SpecChoice API.

---

isEnum

abstract Bool isEnum()

Is the base sys::Enum

---

isFunc

abstract Bool isFunc()

Return if this a SpecFunc that models a function signature

---

isMaybe

abstract Bool isMaybe()

Does meta have maybe tag

---

isa

abstract Bool isa(Spec that)

Return if this spec inherits from that from a nominal type perspective. Nonimal typing matches any of the following conditions:

• if that matches one of this inherited specs via base
• if this is maybe and that is None
• if this is And and that matches any this.ofs
• if this is Or and that matches all this.ofs (common base)
• if that is Or and this matches any of that.ofs

---

lib

abstract Lib lib()

Parent library for spec

---

meta

abstract Dict meta()

Get my effective meta; this does not include synthesized tags like spec

---

metaOwn

abstract Dict metaOwn()

Get my own declared meta-data

---

name

abstract Str name()

Return simple name scoped by lib or parent.

---

parent

abstract Spec? parent()

Parent spec which contains this spec definition and scopes name. Returns null for top level specs in the library.

---

qname

abstract Str qname()

Return fully qualified name of this spec:

• Type specs will return "foo.bar::Baz"
• Global slots will return "foo.bar::baz"
• Type slots will return "foo.bar::Baz.qux"
• Derived specs will return "derived123::{name}"

---

slot

abstract Spec? slot(Str name, Bool checked := true)

Convenience for slots.get

---

slotOwn

abstract Spec? slotOwn(Str name, Bool checked := true)

Convenience for slotsOwn.get

---

slots

abstract SpecSlots slots()

Get the effective children slots including inherited

---

slotsOwn

abstract SpecSlots slotsOwn()

Get the declared children slots

---

type

abstract Spec type()

Type of this spec. If this spec is a top level type then return self.

---

SpecChoice

@Js const mixin SpecChoice

Choice APIs for a specific choice spec via LibNamespace.choice.

Methods

isMaybe	Return if the choice slot allows zero selections
isMultiChoice	Return if the choice slot allows multiple selections
selection	Return single choice selection considering validation rules.
selections	Return all choice selections the given instance implements.
spec	Spec for this choice - might be slot or choice type
subtypes	List the choice direct subtypes of given base (defaults to root choice).
type	Choice type for the spec

Slot Details

---

isMaybe

abstract Bool isMaybe()

Return if the choice slot allows zero selections

---

isMultiChoice

abstract Bool isMultiChoice()

Return if the choice slot allows multiple selections

---

selection

abstract Spec? selection(Dict instance, Bool checked := true)

Return single choice selection considering validation rules. This method is a semantically equivalent to:

selections(instance, checked).first

---

selections

abstract Spec[] selections(Dict instance, Bool checked := true)

Return all choice selections the given instance implements.

• one selection => return list of one
• zero selections + isMaybe is true => return empty list
• zero selections + isMaybe is false + checked is false => return empty list
• zero selections + isMaybe is false + checked is true => raise exception
• multiple selections + isMultiChoice is false + checked is false => return all
• multiple selections + isMultiChoice is false + checked is true => raise exception
• multiple selections + isMultiChoice is true + checked is true => return all

---

spec

abstract Spec spec()

Spec for this choice - might be slot or choice type

---

subtypes

abstract Spec[] subtypes(Spec base := this.spec())

List the choice direct subtypes of given base (defaults to root choice). This method can be used to efficiently build choice taxonomy tree.

---

type

abstract Spec type()

Choice type for the spec

---

SpecEnum

@Js const mixin SpecEnum

Item metadata for an Enum spec

Methods

each	Iterate the enum items by spec and string key
keys	List the string keys
spec	Lookup enum item spec by its string key
xmeta	Get the extended meta for the given enum item key.

Slot Details

---

each

abstract Void each(|Spec,Str| f)

Iterate the enum items by spec and string key

---

keys

abstract Str[] keys()

List the string keys

---

spec

abstract Spec? spec(Str key, Bool checked := true)

Lookup enum item spec by its string key

---

xmeta

abstract Dict? xmeta(Str? key := null, Bool checked := true)

Get the extended meta for the given enum item key. If key is null then get the extended meta for the enum spec itself. This method is only available if the requested by the LibNamespace.xmetaEnum otherwise an exception is raised.

---

SpecFunc

@Js const mixin SpecFunc

Function specific APIS for sys::Func specs

Methods

arity	Number of parameters
params	Parameter types in positional order
returns	Return type

Slot Details

---

arity

abstract Int arity()

Number of parameters

---

params

abstract Spec[] params()

Parameter types in positional order

---

returns

abstract Spec returns()

Return type

---

SpecSlots

@Js const mixin SpecSlots

SpecSlots is a map of named Specs

NOTE: in most cases name keys match the Spec.name of slot specs themselves. However, in cases where the slot name is an auto-name of "_0", "_1", etc its possible that the slot name keys do not match their slot names. This occurs when inheriting auto-named slots. The spec names are assigned uniquely per type, but when merged by inheritance might be assigned new unique names. This often occurs in queries such as point queries.

Methods

each	Iterate through the children using key.
eachWhile	Iterate through the children until function returns non-null NOTE: the name parameter may not match slots names
get	Get the child slot spec as keyed by this slots map NOTE: the name key may not match slot name
has	Return if the given slot name is defined.
isEmpty	Return if slots are empty
missing	Return if the given slot name is undefined.
names	Convenience to list the slots names; prefer each.

Slot Details

---

each

abstract Void each(|Spec,Str| f)

Iterate through the children using key. NOTE: the name parameter may not match slots names

---

eachWhile

abstract Obj? eachWhile(|Spec,Str->Obj?| f)

Iterate through the children until function returns non-null NOTE: the name parameter may not match slots names

---

get

abstract Spec? get(Str name, Bool checked := true)

Get the child slot spec as keyed by this slots map NOTE: the name key may not match slot name

---

has

abstract Bool has(Str name)

Return if the given slot name is defined. NOTE: the name key may not match slot name

---

isEmpty

abstract Bool isEmpty()

Return if slots are empty

---

missing

abstract Bool missing(Str name)

Return if the given slot name is undefined. NOTE: the name key may not match slot name

---

names

abstract Str[] names()

Convenience to list the slots names; prefer each. NOTE: the names may not match slots names

---

ValidateItem

@Js const mixin ValidateItem

ValidateItem models one warning or error message from validation

Methods

level	Warning or error level
msg	Free-form message for validation error
slot	Slot of subject or null if on subject itself.
subject	Subject dict.

Slot Details

---

level

abstract ValidateLevel level()

Warning or error level

---

msg

abstract Str msg()

Free-form message for validation error

---

slot

abstract Str? slot()

Slot of subject or null if on subject itself. This is dotted path if item is on a nested dict in the subject.

---

subject

abstract Dict subject()

Subject dict. If validate was called against a non-dict value then this is an empty dict.

---

ValidateLevel

@Js @Serializable { simple=true } enum class ValidateLevel : Enum

ValidateLevel

Enum

warn	Warning level
err	Error level

Constructors

fromStr	Return the ValidateLevel instance for the specified name.

Fields

vals	List of ValidateLevel values indexed by ordinal

Methods

isErr	Is this the err enum value
isWarn	Is this the warn enum value
max	Max level from items or null if items is empty

Slot Details

---

err

const static ValidateLevel err := ...

Error level

---

fromStr

static new fromStr(Str name, Bool checked := true)

Return the ValidateLevel instance for the specified name. If not a valid name and checked is false return null, otherwise throw ParseErr.

---

isErr

Bool isErr()

Is this the err enum value

---

isWarn

Bool isWarn()

Is this the warn enum value

---

max

static ValidateLevel? max(ValidateItem[] items)

Max level from items or null if items is empty

---

vals

const static ValidateLevel[] vals := ...

List of ValidateLevel values indexed by ordinal

---

warn

const static ValidateLevel warn := ...

Warning level

---

XetoContext

@Js mixin XetoContext : ActorContext

XetoContext is used to pass contextual state to XetoEnv operations.

Slot Details

---

XetoEnv

const class XetoEnv : Obj

XetoEnv models the server side file system search path.

Methods

cur	Current environment for the VM
homeDir	Home directory where xeto software is installed
installDir	Default install directory for xeto install.
path	List of paths to search for libraries in both lib and src format
workDir	Working directory - first directory in the path.

Slot Details

---

cur

static XetoEnv cur()

Current environment for the VM

---

homeDir

virtual File homeDir()

Home directory where xeto software is installed

---

installDir

virtual File installDir()

Default install directory for xeto install. Default is the workDir

---

path

File[] path()

List of paths to search for libraries in both lib and src format

---

workDir

virtual File workDir()

Working directory - first directory in the path. The workDir is used as default location for xeto init to create new libs.