lib-xeto 库参考

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

导读： Xeto 规范和数据函数库

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

---

目录（导读）

• lib
• meta
• funcs
• def
• choiceOf(instance, choice, checked: true)
  • supertypes
• fits(val, spec, opts: null)
• fitsExplain(recs, spec, opts: null)
• fitsMatchAll(recs, specs: null, opts: null)
• instance(qname, checked: true)
• instances(scope: null, filter: null)
• instantiate(spec, opts: null)
• is(val, spec)
• query(subject, spec, checked: true)
• queryAll(subject, spec, opts: null)
• queryNamed(subject, spec, opts: null)
• spec(qname, checked: true)
• specBase(spec)
• specFits(a, b)
• specFitsExplain(a, b)
• specIs(a, b)
• specLib(name, checked: true)
• specLibs(scope: null)
• specMeta(spec)
• specMetaOwn(spec)
• specName(spec)
• specOf(val, checked: true)
• specParent(spec)
• specQName(spec)
• specSlots(spec)
• specSlotsOwn(spec)
• specType(spec)
• specs(scope: null, filter: null)

---

概述（中译）

Xeto 规范和数据函数库

---

API 正文（英文）

funcs

choiceOf	Given a choice spec, return the most specific choice subtype implemented by the instance
fits	Return if the given instance fits the spec via structural typing
fitsExplain	Return grid which explains how data fits the given spec
fitsMatchAll	Match dict recs against specs to find all the specs that fit
instance	Load or lookup a instance from a Xeto library by its string or ref qname as a Dict
instances	Lookup instances from Xeto libs as a list of dicts
instantiate	Create the default instance for a given spec
is	Return if the given instance inherits from the spec via nominal typing
query	Evaluate a relationship query and return record dict
queryAll	Evaluate a relationship query and return grid of results
queryNamed	Evaluate a relationship query and return the named constraints as a dict
spec	Load or lookup a Xeto spec by its string or ref qname
specBase	Base spec from which the given spec directly inherits
specFits	Return if spec a fits spec b based on structural typing
specFitsExplain	Return a grid explaining why spec a does not fit b
specIs	Return if spec a inherits from spec b based on nominal typing
specLib	Load or lookup a Xeto library by its string or ref name
specLibs	List Xeto libraries as a list of their dict representation
specMeta	Get the spec's effective declared meta-data as dict
specMetaOwn	Get the spec's own declared meta-data as dict
specName	Return simple name of spec
specOf	Return the Xeto spec of the given value
specParent	Parent spec which contains given spec and scopes its name
specQName	Return fully qualified name of the spec
specSlots	Get the effective children slots as a dict of Specs
specSlotsOwn	Get the spec's declared children slots as dict of Specs
specType	Data type of the spec
specs	List Xeto specs as a list of their dict representation

---

---

def

func:choiceOf

choiceOf(instance, choice, checked: true)

Given a choice spec, return the most specific choice subtype implemented by the instance. If the instance implements zero or more than one subtype of the choice, then return null or raise an exception based on the checked flag. The instance may be anything accepted by the toRec() function.

Example:

choiceOf({discharge, duct}, DuctSection)  >>  DischargeDuct
choiceOf({hot, water}, Fluid)             >>  HotWater

---

meta

def	func:choiceOf
is	func
lib	lib:xeto
name	choiceOf

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:fits

fits(val, spec, opts: null)

Return if the given instance fits the spec via structural typing. Use specFits() to check structural typing between two types. Also see is() and specIs() to check via nominal typing. Use fitsExplain() to explain why fits returns true or false.

If the val is a Dict, then the default behavior is to only check the dict's tags against the given spec. In this mode all spec query slots are ignored. Pass the {graph} option to also check queries to validate the graph of entities. For example, the graph option can be used with equip specs to validate required points.

Options:

• graph: marker to also check graph of references such as required points
• ignoreRefs: marker to not validate if refs exist or match target spec

Examples:

fits("foo", Str)               >>  true
fits(123, Str)                 >>  false
fits(equipRec, Equip)          >>  true
fits(equipRec, Site)           >>  false
fits(vav, MyVavSpec)           >> validate tags only
fits(vav, MyVavSpec, {graph})  >> validate tags and required points

---

meta

def	func:fits
is	func
lib	lib:xeto
name	fits

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:fitsExplain

fitsExplain(recs, spec, opts: null)

Return grid which explains how data fits the given spec. This function takes one or more recs and returns a grid. For each rec zero or more rows are returned with an error why the rec does not fit the given type. If a rec does fit the type, then zero rows are returned for that record.

If you pass null for the spec, then each record is fit against its declared spec tag. If a given rec is missing a spec tag then it is reported an error.

See fits() for list of options.

Example:

// validate tags on records only
readAll(vav and hotWaterHeating).fitsExplain(G36ReheatVav)

// validate tags and required points and other graph queries
readAll(vav and hotWaterHeating).fitsExplain(G36ReheatVav, {graph})

---

meta

def	func:fitsExplain
is	func
lib	lib:xeto
name	fitsExplain

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:fitsMatchAll

fitsMatchAll(recs, specs: null, opts: null)

Match dict recs against specs to find all the specs that fit. The recs argument can be anything accepted by toRecList(). Specs must be a Spec or list of Specs. If specs argument is omitted, then we match against all the non-abstract types currently in scope. Only the most specific subtype is returned.

Result is a grid for each input rec with the following columns:

• id: of the input record
• num: number of matches
• specs: list of Spec for all matching specs

See fits() for a list of supported fit options.

Example:

readAll(equip).fitsMatchAll

---

meta

def	func:fitsMatchAll
is	func
lib	lib:xeto
name	fitsMatchAll

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:instance

instance(qname, checked: true)

Load or lookup a instance from a Xeto library by its string or ref qname as a Dict. If not found raise exception or return null based on checked flag.

NOTE: this function returns the instance using Haystack level fidelity

Examples:

instance("icons::apple")             // qname string
instance(@icons::apple)              // qname Ref id
instance("icons::bad-name")          // raises exception if not found
instance("icons::bad-name", false)   // unchecked returns null

---

meta

def	func:instance
is	func
lib	lib:xeto
name	instance

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:instances

instances(scope: null, filter: null)

Lookup instances from Xeto libs as a list of dicts.

Scope may one of the following:

• null: all instances from all libs currently in the using scope
• lib: all instances declared in given library
• list of lib: all instances in given libraries

If the filter is null, then it filters the instances from the scope.

NOTE: this function returns the instances using Haystack level fidelity

Examples:

instances()                  // all instances in scope
specLib("icons").instances   // instances in a given library
instances(null, a and b)     // filter instances with filter expression

---

meta

def	func:instances
is	func
lib	lib:xeto
name	instances

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:instantiate

instantiate(spec, opts: null)

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

The default behavior for dict types is to return a single Dict. However, if the type has a constrainted query, then an entire graph can be instantiated via the {graph} option in which case a Dict[] is returned. In graph mode an id is generated for recs for cross-linking.

Also see LibNamespace.instantiate.

NOTE: this function forces the haystack option to force all non-Haystack scalars to be simple strings.

Options:

• graph: marker tag to instantiate a graph of recs
• abstract: marker to supress error if spec is abstract

Examples:

// evaluates to 2000-01-01
instantiate(Date)

// evaluates to dict {equip, vav, hotWaterHeating, ...}
instantiate(G36ReheatVav)

// evaluates to dict[] of vav + points from constrained query
instantiate(G36ReheatVav, {graph})

---

meta

def	func:instantiate
is	func
lib	lib:xeto
name	instantiate

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:is

is(val, spec)

Return if the given instance inherits from the spec via nominal typing. Use specIs() to check nominal typing between two types. Also see fits() and specFits() to check via structural typing.

Note that dict values will only match the generic sys.Dict type. Use fits() for structural type matching.

Examples:

is("hi", Str)       >>  true
is("hi", Dict)      >>  false
is({}, Dict)        >>  true
is({equip}, Equip)  >>  false
is(Str, Spec)       >>  true

---

meta

def	func:is
is	func
lib	lib:xeto
name	is

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:query

query(subject, spec, checked: true)

Evaluate a relationship query and return record dict. If no matches found throw UnknownRecErr or return null based on checked flag. If there are multiple matches it is indeterminate which one is returned. Subject must be a record id or dict in the database. Spec must be a Spec typed as a sys::Query. Also see queryAll().

Example:

read(point).query(spec("ph::Point.equips"))

---

meta

def	func:query
is	func
lib	lib:xeto
name	query

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:queryAll

queryAll(subject, spec, opts: null)

Evaluate a relationship query and return grid of results. Subject must be a record id or dict in the database. Spec must be a Spec typed as a sys::Query. Also see query().

Options:

• limit: max number of recs to return
• sort: sort by display name Example: read(ahu).queryAll(spec("ph::Equip.points"))

---

meta

def	func:queryAll
is	func
lib	lib:xeto
name	queryAll

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:queryNamed

queryNamed(subject, spec, opts: null)

Evaluate a relationship query and return the named constraints as a dict. The query slot names are the dict names and the matching record dicts are the dict values. Missing matches are silently ignored and ambiguous matches return an indeterminate record.

Example:

// spec
MyAhu: Equip {
  points: {
    dat: DischargeAirTempSensor
    rat: DischargeAirTempSensor
  }
}

// axon
myAhuPoints: read(ahu).queryNamed(spec("mylib::MyAhu.points"))

// result
{
  dat: {dis:"DAT", discharge, air, temp, sensor, ...},
  rat: {dis:"RAT", return, air, temp, sensor, ...}
}

---

meta

def	func:queryNamed
is	func
lib	lib:xeto
name	queryNamed

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:spec

spec(qname, checked: true)

Load or lookup a Xeto spec by its string or ref qname. Return the dict representation. If not found raise exception or return null based on checked flag.

NOTE: returns the same Spec instance as returned by LibNamespace. The spec meta is modeled using full fidelity and not haystack fidelity. Use specMeta() to normalize to haystack fidelity for use inside Axon.

Examples:

spec("ph::Meter")         // type string
spec(@ph::Meter)          // type id
spec("sys::Spec.of")      // slot
spec("foo::Bad")          // raises exception if not found
spec("foo::Bad", false)   // unchecked returns null

---

meta

def	func:spec
is	func
lib	lib:xeto
name	spec

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specBase

specBase(spec)

Base spec from which the given spec directly inherits. Returns null if spec is sys::Obj itself.

Examples:

specBase(Str)    >>  sys::Scalar
specBase(Meter)  >>  ph::Equip
specType(Equip)  >>  ph::Entity

---

meta

def	func:specBase
is	func
lib	lib:xeto
name	specBase

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specFits

specFits(a, b)

Return if spec a fits spec b based on structural typing. Use fits() to check if an instance fits a given type. Also see is() and specIs() to check using nominal typing.

Examples:

specFits(Meter, Equip)    >>  true
specFits(Meter, Point)    >>  false

---

meta

def	func:specFits
is	func
lib	lib:xeto
name	specFits

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specFitsExplain

specFitsExplain(a, b)

Return a grid explaining why spec a does not fit b. If a does fit b then return an empty grid.

---

meta

def	func:specFitsExplain
is	func
lib	lib:xeto
name	specFitsExplain

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specIs

specIs(a, b)

Return if spec a inherits from spec b based on nominal typing. This method checks the explicit inheritance hierarchy via specBase(). Use is() to check if an instance is of a given type. Also see fits() and specFits() to check using structural typing.

Examples:

specIs(Str, Scalar)     >>  true
specIs(Scalar, Scalar)  >>  false
specIs(Equip, Dict)     >>  true
specIs(Meter, Equip)    >>  true
specIs(Meter, Point)    >>  false

---

meta

def	func:specIs
is	func
lib	lib:xeto
name	specIs

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specLib

specLib(name, checked: true)

Load or lookup a Xeto library by its string or ref name. Return the dict representation. If not found raise exception or return null based on checked flag.

Examples:

specLib("ph.points")            // load by dotted name
specLib(@lib:ph.points)         // load by lib ref id
specLib("bad.lib.name")         // raises exception if not found
specLib("bad.lib.name", false)  // unchecked returns null

---

meta

def	func:specLib
is	func
lib	lib:xeto
name	specLib

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specLibs

specLibs(scope: null)

List Xeto libraries as a list of their dict representation. Is scope is null then return all installed libs (libs not yet loaded will not have their metadata). Otherwise scope must be a filter expression used to filter the dict representation.

Examples:

specLibs()             // all installed libs
specLibs(loaded)       // only libs loaded into memory

---

meta

def	func:specLibs
is	func
lib	lib:xeto
name	specLibs

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specMeta

specMeta(spec)

Get the spec's effective declared meta-data as dict.

NOTE: this function returns the meta using haystack level fidelity

Examples:

specMeta(Date)  >>  {sealed, val:2000-01-01, doc:"...", pattern:"..."}

---

meta

def	func:specMeta
is	func
lib	lib:xeto
name	specMeta

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specMetaOwn

specMetaOwn(spec)

Get the spec's own declared meta-data as dict.

NOTE: this function returns the meta using haystack level fidelity

Examples:

specMetaOwn(Date)  >>  {sealed, val:2000-01-01, doc:"...", pattern:"..."}

---

meta

def	func:specMetaOwn
is	func
lib	lib:xeto
name	specMetaOwn

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specName

specName(spec)

Return simple name of spec.

Examples:

specName(Dict)  >>  "Dict"
specName(Site)  >>  "Site"

---

meta

def	func:specName
is	func
lib	lib:xeto
name	specName

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specOf

specOf(val, checked: true)

Return the Xeto spec of the given value. Raise exception if value type is not mapped into the data type system. Also see is() and fits().

Examples:

specOf("hi")                 >>  sys::Str
specOf(@id)                  >>  sys::Ref
specOf({})                   >>  sys::Dict
specOf({spec:@ph::Equip})    >>  ph::Dict

---

meta

def	func:specOf
is	func
lib	lib:xeto
name	specOf

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specParent

specParent(spec)

Parent spec which contains given spec and scopes its name. Returns null for top-level specs within their library.

Examples:

specParent(Str)  >>  sys

---

meta

def	func:specParent
is	func
lib	lib:xeto
name	specParent

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specQName

specQName(spec)

Return fully qualified name of the spec:

• Top-level type will return "foo.bar::Baz"
• Slot spec will return "foo.bar::Baz.qux"
• Derived specs will return "derived123::{name}"

Examples:

specQName(Dict)  >>  "sys::Dict"
specQName(Site)  >>  "ph::Site"

---

meta

def	func:specQName
is	func
lib	lib:xeto
name	specQName

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specSlots

specSlots(spec)

Get the effective children slots as a dict of Specs.

Examples:

specSlots(Ahu)  >>  {equip: Spec, points: Spec, ahu: Spec}

---

meta

def	func:specSlots
is	func
lib	lib:xeto
name	specSlots

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specSlotsOwn

specSlotsOwn(spec)

Get the spec's declared children slots as dict of Specs.

Examples:

specSlots(Ahu)  >>  {ahu: Spec}

---

meta

def	func:specSlotsOwn
is	func
lib	lib:xeto
name	specSlotsOwn

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specType

specType(spec)

Data type of the spec. Returns the spec itself if given a top-level type.

Examples:

specType(Str)                      >>  sys:Str
spec("ph::Equip.equip").specType   >>  sys::Marker

---

meta

def	func:specType
is	func
lib	lib:xeto
name	specType

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:specs

specs(scope: null, filter: null)

List Xeto specs as a list of their dict representation. Scope may one of the following:

• null: return all the top-level specs currently in the using scope
• lib: return all the top-level specs declared in given library
• list of lib: all specs in given libraries

A filter may be specified to filter the specs found in the scope. The dict representation for filtering supports a "slots" tag on each spec with a Dict of the effective slots name. This allows filtering slots using the syntax slots->someName.

NOTE: returns the same Spec instances as returned by LibNamespace. The spec meta is modeled using full fidelity and not haystack fidelity. Use specMeta() to normalize to haystack fidelity for use inside Axon.

Examples:

specs()                  // specs in using scope
specLib("ph").specs      // specs in a given library
specs(null, abstract)    // filter specs with filter expression
specs(null, slots->ahu)  // filter specs have ahu tag

---

meta

def	func:specs
is	func
lib	lib:xeto
name	specs

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function