@matter/model 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/models/SemanticNamespaceModel.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SemanticNamespaceElement } from "../elements/index.js";
+import { SemanticTagModel } from "../index.js";
+import { Children } from "./Children.js";
+import { Model } from "./Model.js";
+
+export class SemanticNamespaceModel extends Model<SemanticNamespaceElement> implements SemanticNamespaceElement {
+    override tag: SemanticNamespaceElement.Tag = SemanticNamespaceElement.Tag;
+    declare id: number;
+    mfgCode?: number;
+
+    override get children(): Children<SemanticTagModel> {
+        return super.children as Children<SemanticTagModel>;
+    }
+
+    override set children(children: Children.InputIterable<SemanticTagModel>) {
+        super.children = children;
+    }
+
+    get endpoints() {
+        return this.children;
+    }
+
+    static {
+        Model.types[SemanticNamespaceElement.Tag] = this;
+    }
+}

package/src/models/SemanticTagModel.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SemanticTagElement } from "../elements/index.js";
+import { Children } from "./Children.js";
+import { Model } from "./Model.js";
+
+export class SemanticTagModel extends Model<SemanticTagElement> implements SemanticTagElement {
+    override tag: SemanticTagElement.Tag = SemanticTagElement.Tag;
+    declare id: number;
+
+    override get children(): Children<never> {
+        return super.children as Children<never>;
+    }
+
+    override set children(children: Children.InputIterable<never>) {
+        super.children = children;
+    }
+
+    static {
+        Model.types[SemanticTagElement.Tag] = this;
+    }
+}

package/src/models/ValueModel.ts

@@ -0,0 +1,328 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Access, Aspect, Conformance, Constraint, Quality } from "../aspects/index.js";
+import { ElementTag, FieldValue, Metatype } from "../common/index.js";
+import { BaseElement, ValueElement } from "../elements/index.js";
+import { ModelTraversal } from "../logic/ModelTraversal.js";
+import { Aspects } from "./Aspects.js";
+import { Model } from "./Model.js";
+import { PropertyModel } from "./PropertyModel.js";
+
+// These are circular dependencies so just to be safe we only import the types.  We also need the class, though, at
+// runtime.  So we use the references in the Model.constructors factory pool.
+import { camelize } from "@matter/general";
+import { DefaultValue } from "../logic/DefaultValue.js";
+import { Children } from "./Children.js";
+import { type ClusterModel } from "./ClusterModel.js";
+import { type FieldModel } from "./FieldModel.js";
+
+const CONSTRAINT: unique symbol = Symbol("constraint");
+const CONFORMANCE: unique symbol = Symbol("conformance");
+const ACCESS: unique symbol = Symbol("access");
+const QUALITY: unique symbol = Symbol("quality");
+
+/**
+ * Each {@link ValueElement} type has a corresponding implementation that derives from this class.
+ */
+export abstract class ValueModel<T extends ValueElement = ValueElement> extends Model<T> implements ValueElement {
+    declare byteSize?: ValueElement.ByteSize;
+    declare default?: FieldValue;
+    declare metatype?: Metatype;
+    override isType? = true;
+
+    override get children(): Children<FieldModel> {
+        return super.children as Children<FieldModel>;
+    }
+
+    override set children(children: Children.InputIterable<FieldModel>) {
+        super.children = children;
+    }
+
+    get constraint(): Constraint {
+        return Aspects.getAspect(this, CONSTRAINT, Constraint);
+    }
+    set constraint(definition: Constraint | Constraint.Definition) {
+        Aspects.setAspect(this, CONSTRAINT, Constraint, definition);
+    }
+    get effectiveConstraint(): Constraint {
+        return new ModelTraversal().findConstraint(this, CONSTRAINT) || this.constraint;
+    }
+
+    get conformance(): Conformance {
+        return Aspects.getAspect(this, CONFORMANCE, Conformance);
+    }
+    set conformance(definition: Conformance | Conformance.Definition) {
+        Aspects.setAspect(this, CONFORMANCE, Conformance, definition);
+    }
+    get effectiveConformance(): Conformance {
+        return Aspects.getEffectiveAspect(this, CONFORMANCE, Conformance);
+    }
+
+    get access(): Access {
+        return Aspects.getAspect(this, ACCESS, Access);
+    }
+    set access(definition: Access | Access.Definition) {
+        Aspects.setAspect(this, ACCESS, Access, definition);
+    }
+    get effectiveAccess(): Access {
+        return new ModelTraversal().findAccess(this, ACCESS, ValueModel);
+    }
+
+    get quality(): Quality {
+        return Aspects.getAspect(this, QUALITY, Quality);
+    }
+    set quality(definition: Quality | Quality.Definition) {
+        Aspects.setAspect(this, QUALITY, Quality, definition);
+    }
+    get effectiveQuality(): Quality {
+        return Aspects.getEffectiveAspect(this, QUALITY, Quality);
+    }
+
+    /**
+     * Metatype is only present on global types with specific semantic meaning. This model is significant because it
+     * gives us information about how to manipulate the data.  This accessor retrieves this model.
+     */
+    get metabase(): ValueModel | undefined {
+        return new ModelTraversal().findMetabase(this) as ValueModel | undefined;
+    }
+
+    /**
+     * Get the primitive type for this value model.  This is an integer type for enums and bitmaps.  Otherwise it's the
+     * metabase.
+     */
+    get primitiveBase(): ValueModel | undefined {
+        const metabase = this.metabase;
+        if (!metabase) {
+            return;
+        }
+
+        // Enum is a derived type so we can just return its base
+        if (metabase.metatype === Metatype.enum) {
+            return metabase.base;
+        }
+
+        // Bitmaps are not derived types so we have to map manually
+        if (metabase.metatype === Metatype.bitmap) {
+            const primitiveName = metabase.name.replace("map", "uint");
+            return metabase.parent?.children.find(c => c.name === primitiveName) as ValueModel | undefined;
+        }
+
+        return metabase;
+    }
+
+    /**
+     * The "effective type" may be inferred from context.
+     */
+    override get effectiveType(): string | undefined {
+        const type = super.effectiveType;
+        if (type) {
+            return type;
+        }
+        return new ModelTraversal().getTypeName(this);
+    }
+
+    /**
+     * The working metatype for this object.
+     */
+    get effectiveMetatype() {
+        const metaBase = this.metabase;
+        if (metaBase) {
+            return metaBase.metatype;
+        }
+    }
+
+    /**
+     * The value to use as a default.  The "default" field has a manually supplied value but this property decodes the
+     * default and/or generates a default from subfields.
+     */
+    get effectiveDefault() {
+        return DefaultValue(this);
+    }
+
+    /**
+     * Get the first derived ancestor with children, if any.
+     */
+    get definingModel() {
+        return new ModelTraversal().findDefiningModel(this);
+    }
+
+    /**
+     * Get the entry type for lists, if any.
+     */
+    get listEntry() {
+        return this.member("entry", [ElementTag.Field]) as FieldModel | undefined;
+    }
+
+    /**
+     * ValueModels may only derive from ValueModels.
+     */
+    override get base() {
+        return super.base as ValueModel | undefined;
+    }
+
+    /**
+     * ValueModels may derive from models of the same type or from generic Datatype models.
+     */
+    override get allowedBaseTags() {
+        if (this.tag === ElementTag.Field) {
+            // Allow fields to derive from attributes.  We use this for referencing options in masks and bitmaps
+            return [ElementTag.Field, ElementTag.Datatype, ElementTag.Attribute];
+        }
+        return [this.tag, ElementTag.Datatype];
+    }
+
+    /**
+     * All {@link FieldModel} children}.
+     */
+    get members(): PropertyModel[] {
+        return new ModelTraversal().findChildren(this, [ElementTag.Field]) as PropertyModel[];
+    }
+
+    /**
+     * A subset of {@link members} with conflicts resolved by conformance.
+     */
+    get activeMembers() {
+        const cluster = this.owner(Model.types[ElementTag.Cluster]) as ClusterModel | undefined;
+        return new ModelTraversal().findActiveMembers(this, false, cluster);
+    }
+
+    /**
+     * The subset of {@link members} that are conformant.
+     */
+    get conformantMembers() {
+        const cluster = this.owner(Model.types[ElementTag.Cluster]) as ClusterModel | undefined;
+        return new ModelTraversal().findActiveMembers(this, true, cluster);
+    }
+
+    /**
+     * Active members keyed by property name.
+     */
+    get fields() {
+        const members = this.activeMembers;
+        return Object.fromEntries(members.map(member => [camelize(member.name), member]));
+    }
+
+    /**
+     * Collect constraints and conformance for this type and all base types.
+     */
+    get validationAspects() {
+        const aspects = Array<Aspect<any>>();
+
+        new ModelTraversal().visitInheritance(this, model => {
+            if (model instanceof ValueModel) {
+                if (!model.conformance.empty && model.conformance.type !== Conformance.Special.Desc) {
+                    aspects.push(model.conformance);
+                }
+                if (!model.constraint.empty && !model.constraint.desc) {
+                    aspects.push(model.constraint);
+                }
+                if (model.quality.nullable === false) {
+                    aspects.push(model.quality);
+                }
+            }
+        });
+
+        return aspects;
+    }
+
+    /**
+     * Is this model deprecated?
+     */
+    get isDeprecated() {
+        return this.effectiveConformance.type === Conformance.Flag.Deprecated;
+    }
+
+    /**
+     * Is this model disallowed?
+     */
+    get isDisallowed() {
+        return this.effectiveConformance.type === Conformance.Flag.Disallowed;
+    }
+
+    /**
+     * Can this model be omitted?
+     */
+    get nullable() {
+        return !!this.effectiveQuality.nullable;
+    }
+
+    /**
+     * Is the model mandatory?
+     */
+    get mandatory() {
+        return this.effectiveConformance.isMandatory;
+    }
+
+    /**
+     * Determine whether this element overrides key properties of its shadow.
+     */
+    get overridesShadow() {
+        const shadow = this.shadow;
+        if (!shadow || !(shadow instanceof ValueModel)) {
+            return;
+        }
+
+        if (this.type && this.type !== shadow.type) {
+            return true;
+        }
+        if (!this.conformance.empty && !this.conformance.equals(shadow.conformance)) {
+            return true;
+        }
+        if (!this.quality.empty && !this.quality.equals(shadow.quality)) {
+            return true;
+        }
+        if (!this.constraint.empty && !this.constraint.equals(shadow.constraint)) {
+            return true;
+        }
+        if (!this.access.empty && !this.access.equals(shadow.access)) {
+            return true;
+        }
+    }
+
+    /**
+     * Search the inheritance chain for a bitmap field defining a specific bit.
+     */
+    bitDefinition(bit: number) {
+        return new ModelTraversal().findBitDefinition(this, bit);
+    }
+
+    override valueOf() {
+        const result = super.valueOf() as any;
+        for (const k of ["conformance", "access", "quality", "constraint"]) {
+            const v = (this as any)[k] as Aspect<any>;
+            if (v && !v.empty) {
+                result[k] = v.valueOf();
+            }
+        }
+        if (result.default === undefined) {
+            delete result.default;
+        }
+        return result as T;
+    }
+
+    override freeze() {
+        this.constraint.freeze();
+        this.conformance.freeze();
+        this.access.freeze();
+        this.quality.freeze();
+        super.freeze();
+    }
+
+    constructor(definition: BaseElement.Properties<T>) {
+        super(definition);
+
+        const match = this.type?.match(/^list\[(.*)\]$/);
+        if (match) {
+            this.type = "list";
+            this.children.push(new Model.types.field({ name: "entry", type: match[1] }) as FieldModel);
+        }
+
+        if (definition instanceof Model) {
+            Aspects.cloneAspects(definition, this, CONSTRAINT, CONFORMANCE, ACCESS, QUALITY);
+        }
+    }
+}

package/src/models/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./AttributeModel.js";
+export * from "./ClusterModel.js";
+export * from "./CommandModel.js";
+export * from "./DatatypeModel.js";
+export * from "./DeviceTypeModel.js";
+export * from "./EndpointModel.js";
+export * from "./EventModel.js";
+export * from "./FabricModel.js";
+export * from "./FieldModel.js";
+export * from "./Globals.js";
+export * from "./MatterModel.js";
+export * from "./Model.js";
+export * from "./NodeModel.js";
+export * from "./PropertyModel.js";
+export * from "./RequirementModel.js";
+export * from "./SemanticNamespaceModel.js";
+export * from "./SemanticTagModel.js";
+export * from "./ValueModel.js";

package/src/parser/Lexer.ts

@@ -0,0 +1,275 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { FieldValue } from "../common/index.js";
+import { BasicToken, Token } from "./Token.js";
+
+function isNameChar(c: string) {
+    return (c >= "A" && c <= "Z") || (c >= "a" && c <= "z") || (c >= "0" && c <= "9") || c === "_";
+}
+
+/**
+ * DSL lexer.
+ *
+ * Tokenizes simple text dialects.  Currently sufficient for Matter conformance and constraint tokenization.
+ */
+export class Lexer<T extends BasicToken> {
+    #keywords: Set<string>;
+
+    constructor(keywords: Iterable<string> = []) {
+        if (keywords instanceof Set) {
+            this.#keywords = keywords;
+        } else {
+            this.#keywords = new Set(keywords);
+        }
+    }
+
+    lex(text: string, error: (code: string, message: string) => void) {
+        return lex(text, error, this.#keywords) as Iterator<T>;
+    }
+}
+
+export namespace Lexer {
+    export const Basic = new Lexer();
+}
+
+function* lex(
+    text: string,
+    error: (code: string, message: string) => void,
+    keywords: Set<string>,
+): Generator<Token, undefined> {
+    const i = text[Symbol.iterator]();
+
+    let current = i.next();
+    if (current.done) {
+        return;
+    }
+    let peeked = i.next();
+
+    let line = 1;
+    let char = 1;
+
+    let startLine = -1;
+    let startChar = -1;
+
+    function markStart() {
+        startLine = line;
+        startChar = char;
+    }
+
+    function next() {
+        current = peeked;
+        if (!current.done) {
+            char++;
+            peeked = i.next();
+        }
+    }
+
+    function tokenizeName(): Token | BasicToken.Word {
+        const chars = [current.value];
+        while (peeked.value !== undefined && isNameChar(peeked.value)) {
+            next();
+            chars.push(current.value);
+        }
+        const name = chars.join("");
+
+        if (keywords.has(name)) {
+            return { type: name, startLine, startChar };
+        }
+
+        return { type: "word", value: name, startLine, startChar };
+    }
+
+    function binaryValueOf(digit: string | undefined) {
+        if (digit === "0") {
+            return 0;
+        }
+        if (digit === "1") {
+            return 1;
+        }
+    }
+
+    function decimalValueOf(digit: string | undefined) {
+        if (digit === undefined) {
+            return;
+        }
+        if (digit >= "0" && digit <= "9") {
+            return digit.charCodeAt(0) - "0".charCodeAt(0);
+        }
+    }
+
+    function hexadecimalValueOf(digit: string | undefined) {
+        if (digit === undefined) {
+            return;
+        }
+        if (digit >= "0" && digit <= "9") {
+            return digit.charCodeAt(0) - "0".charCodeAt(0);
+        }
+        if (digit >= "a" && digit <= "f") {
+            return 10 + digit.charCodeAt(0) - "a".charCodeAt(0);
+        }
+        if (digit >= "A" && digit <= "F") {
+            return 10 + digit.charCodeAt(0) - "A".charCodeAt(0);
+        }
+        return;
+    }
+
+    function tokenizeNumber(sign: number) {
+        markStart();
+        if (sign === -1) {
+            // Skip "-" prefix
+            next();
+        }
+
+        if (current.value === "0") {
+            if (peeked.value === "x") {
+                next();
+                next();
+                return tokenizeDigits(16, sign, hexadecimalValueOf);
+            } else if (peeked.value === "b") {
+                next();
+                next();
+                return tokenizeDigits(2, sign, binaryValueOf);
+            }
+        }
+
+        return tokenizeDigits(10, sign, decimalValueOf);
+    }
+
+    function tokenizeDigits(
+        base: number,
+        sign: number,
+        valueOf: (digit: string[1] | undefined) => number | undefined,
+    ): BasicToken {
+        // The first digit may not actually be a digit if number is hexadecimal or binary
+        let num = valueOf(current.value);
+        if (num === undefined) {
+            error("INVALID_NUMBER", `Expected digit following numeric suffix`);
+            return { type: "value", value: 0, startLine, startChar };
+        }
+
+        // Add subsequent digits
+        while (true) {
+            const digitValue = valueOf(peeked.value);
+            if (digitValue === undefined) {
+                break;
+            }
+            next();
+            num = num * base + digitValue;
+        }
+
+        num *= sign;
+
+        // Handle specialized suffices for percents and temperatures
+        if (peeked.value === "%") {
+            next();
+            return { type: "value", value: FieldValue.Percent(num), startLine, startChar };
+        } else if (peeked.value === "°") {
+            next();
+            if (peeked.value?.toLowerCase() === "C") {
+                next();
+            }
+            return { type: "value", value: FieldValue.Celsius(num), startLine, startChar };
+        }
+
+        // No special suffix; return raw value
+        return { type: "value", value: num, startLine, startChar };
+    }
+
+    while (!current.done) {
+        switch (current.value) {
+            case "|":
+            case "^":
+            case "&":
+            case ".":
+            case ",":
+            case "[":
+            case "]":
+            case "(":
+            case ")":
+            case "+":
+            case "/":
+            case "*":
+                yield { type: current.value, startLine: line, startChar: char };
+                break;
+
+            case "-":
+                if (peeked.value !== undefined && (peeked.value >= "0" || peeked.value <= "0")) {
+                    yield tokenizeNumber(-1);
+                } else {
+                    yield { type: current.value, startLine: line, startChar: char };
+                }
+                break;
+
+            case "0":
+                yield tokenizeNumber(1);
+                break;
+
+            case "1":
+            case "2":
+            case "3":
+            case "4":
+            case "5":
+            case "6":
+            case "7":
+            case "8":
+            case "9":
+                yield tokenizeDigits(10, 1, decimalValueOf);
+                break;
+
+            case "!":
+            case ">":
+            case "<":
+                {
+                    const base = current.value;
+                    if (peeked.value === "=") {
+                        const type = `${base}${peeked.value}` as BasicToken.Operator;
+                        next();
+                        yield {
+                            type,
+                            startLine: line,
+                            startChar: char,
+                        };
+                    } else {
+                        yield { type: base, startLine: line, startChar: char };
+                    }
+                }
+                break;
+
+            case "=":
+                markStart();
+                if (peeked.value === "=") {
+                    next();
+                } else {
+                    error("BAD_EQUAL", `"=" must be followed by another "="`);
+                }
+                yield { type: "==", startLine, startChar };
+                break;
+
+            case "\n":
+                line++;
+                char = 0;
+                break;
+
+            case " ":
+            case "\t":
+            case "\r":
+            case "\v":
+            case "\f":
+                break;
+
+            default:
+                if (isNameChar(current.value)) {
+                    markStart();
+                    yield tokenizeName();
+                } else {
+                    error("GARBAGE_CHARACTER", `Unexpected character "${current.value}"`);
+                }
+                break;
+        }
+        next();
+    }
+}