Funcs

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

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

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 Namespace. 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

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 Namespace. 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

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

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

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.

Recs displayed by navName and disMacro such as equips and points take an authored dis default as their navName, never as a dis tag which would override the macro.

Also see Namespace.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
• useSlotSpec: marker to use a named query slot qname such as Vav.points.zoneTemp as the spec tag instead of its type, so recs deployed from an equip template validate against their template slot. Auto named constraints always use their type.
• parent: parent rec such as a site, space, or equip used to add siteRef, spaceRef, equipRef, and systemRef
• 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})

// equip template under a site, ready to commit
instantiate(spec("proj::AcmeVav100"), {graph, useSlotSpec, parent: read(site)})

Compute the extended type spec by merging all meta and slots from mixins. This call can be quite expensive; so cache and reuse the result for your operation.

Examples:

specx(Site)

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

Examples:

specParent(Str)  >>  sys

Return simple name of spec.

Examples:

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

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"

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

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

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:"..."}

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:"..."}

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

Examples:

specMembersOwn(Ahu)

Get the effective children slots and globals as a dict of Specs.

Examples:

specMembers(Ahu)

Get the effective child slot or global member.

Examples:

specMember(Ahu, "equipRef")

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

Examples:

specSlotsOwn(Ahu)

Get the effective children slots as a dict of Specs.

Examples:

specSlots(Ahu)

Get the effective child slot.

Examples:

specSlot(Ahu, "equipRef")

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

Examples:

specGlobalsOwn(Ahu)

Get the effective children globals as a dict of Specs.

Examples:

specGlobals(Ahu)

Get the effective global slot.

Examples:

specGlobal(Ahu, "equipRef")

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

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

Examples:

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

Return if the value is a member of the spec. A value fits if its spec is the given spec or a subtype. A dict also fits a sugar spec if it fits the sugar's nominal anchor and has every constraint tag. Fits never checks required slots or queries; use validate() for that. Also see is() to check strictly via nominal typing.

The spec is used as given: pass the extended spec from specx() to also apply constraints added to a sugar spec by mixins.

Examples:

fits("foo", Str)                                  >>  true
fits({spec:@ph::Ahu}, Equip)                      >>  true
fits({spec:@ph.points::DuctFanRunCmd, discharge},
     DischargeFanRunCmd)                          >>  true
fits(rec, specx(MySugar))                         >> include mixins

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

Validate recs or a bare value and return a grid of the validation items. A dict, ref, grid, or list of dicts/refs is coerced to recs via toRecList() and each rec is validated against the given spec, or against its declared 'spec' tag when the spec is null; a rec missing the tag reports a 'sys::missingSpecRef' item. Any other value validates against the spec as a bare value, such as one scalar against its slot spec. Values are always checked at haystack fidelity.

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
• ignoreUnresolvedRefs: marker to skip unresolved refs, but still check the target type of refs that do resolve
• ignoreMissingSlots: marker to skip missing required slot checks

The result grid has a row per validation item:

• subject: id of the subject rec or null if not applicable
• slot: dotted slot path within the subject or null if positioned on the subject itself
• level: "err" or "warn"
• rule: ref to the 'sys::ValidateRule' instance
• msg: display message
• val: offending value when applicable

Grid meta has numErrs and numWarns.

Examples:

 readAll(equip).validate                >> validate against each rec's spec tag
 readAll(vav).validate(G36ReheatVav)    >> validate against explicit spec
 readAll(equip).validate(null, {graph}) >> also validate required points
 validate(123, Str)                     >> validate a bare value

Debug the validation rules of the current namespace. Returns a grid with a row per sys::ValidateRule instance in the order the engine runs them, which is always after the rules named by their 'unless'.

The result grid has a row per rule:

• rule: ref to the 'sys::ValidateRule' instance
• on: types the rule applies to; the engine only runs the rule where the value's spec is one of them
• unless: rules which suppress this one when they fire first
• level: "err" or "warn"
• msg: message template
• impl: Fantom type implementing the check, or null if the rule is declared without one and so never runs

Examples:

 validateRules()                                >> all rules in order
 validateRules.findAll(r => r.missing("impl"))  >> declared but unbound

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"))

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"))

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, ...}
}