Semantics: Canonical Semantic Role Map#

Loads irix/data/semantics.yaml – the distilled house mapping of semantic theme roles to canonical hue-shade palette addresses – and classifies foreign theme keys onto those roles.

Two classifiers are provided, both deterministic and table-driven:

  • Semantics.classify_scope maps a TextMate-style scope string (comment.line.double-slash, entity.name.function, …) to a canonical role key.

  • Semantics.classify_workbench maps a workbench color key (editor.background, statusBar.errorBackground, terminal.ansiRed, …) to a canonical role key.

Role lookups (Semantics.address) use prefix fallback: keyword.control.foo resolves to keyword.control and then keyword until a table entry matches. A role’s address is either a plain hue-shade string (serves both modes) or a per-mode {dark: ..., light: ...} override for the rare role whose Radix rung is legible in one mode but not the other – see Architecture: How Irix Is Put Together for the design rationale.

Type Aliases#

irix.semantics.Mode = Mode#

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

irix.semantics.RoleAddress = RoleAddress#

A role’s address is either a plain hue-shade string (serves both modes, the common case) or a per-mode override {dark: ..., light: ...} for the rare role whose Radix rung is legible in one mode but not the other (see semantics.yaml’s header for the light-legibility overrides that introduced this shape).

class irix.semantics.Semantics(*, roles: dict[str, RoleAddress] = {})#

The canonical role -> hue-shade address table, with classifiers.

roles#

Mapping of dotted role key (comment.doc, ui.error, terminal.ansi-red) to a canonical hue-shade palette address. Addresses use shade names and therefore resolve under both irix.Palette.Palette.dark and irix.Palette.Palette.light. Most entries are a single address serving both modes; a role may instead carry a {dark: ..., light: ...} mapping when the same hue needs a different rung per mode (address’s mode param resolves it).

Type:

dict[str, RoleAddress]

I Initial Methods#

classmethod Semantics.load() → Semantics#

Load the packaged irix/data/semantics.yaml table.

II Public Methods#

Semantics.address(role: str, mode: Mode = 'dark') → str | None#

Resolve a role key to a palette address, with prefix fallback.

keyword.control.flow falls back to keyword.control, then keyword.

Parameters:

  • role – Dotted role key (e.g. from classify_scope / classify_workbench).

  • mode – Which mode’s address to return when the matched role carries a per-mode {dark: ..., light: ...} override; plain-string roles ignore this (the same address serves both modes). Defaults to 'dark' so every pre-existing call site keeps today’s behavior unchanged.

Returns:

The canonical hue-shade address, or None if no prefix matches.

Semantics.classify_scope(scope: str) → str | None#

Classify a TextMate-style scope string to a canonical role key.

Comma-separated scope lists are reduced to their first entry; compound (space-separated) scopes are reduced to their first selector. Matching is dot-boundary aware, most-specific-first, per _SCOPE_TABLE.

Parameters:

scope – A scope string such as comment.line.double-slash or string.quoted.double.python.

Returns:

The canonical role key, or None if the scope is unclassifiable.

Semantics.classify_workbench(key: str) → str | None#

Classify a workbench color key to a canonical role key.

Handles exact overrides (_WORKBENCH_EXACT), terminal.ansi* keys (mapped to the DATA-chamber terminal roles), editorBracketHighlight.foregroundN keys (rotated through the six editor.bracket-N roles, alternating SUB/META chamber hues), and then the substring pattern table (_WORKBENCH_PATTERNS: *Error* -> ui.error, *.background -> ui.background, etc.).

Parameters:

key – A workbench key such as editor.background, statusBar.errorBackground, or terminal.ansiRed.

Returns:

The canonical role key, or None if the key is unclassifiable.