refdef 0.1.0__py3-none-any.whl

refdef/level.py

@@ -0,0 +1,111 @@
+"""One step of a reference designation: its aspect, class letters, number or label."""
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+MAX_NUMBER = 999_999_999
+_NOT_IN_LABEL = frozenset("=-+%#:;&<>.")
+_CODED = re.compile(r"([A-Za-z]*)([0-9]+)")
+_LETTERS = re.compile(r"[A-Z]*")
+
+
+class Aspect(Enum):
+    """The tree a level belongs to; the value is its sign.
+
+    The first three are on in the shipped scheme; declaration order is the rank tie-break.
+    """
+
+    FUNCTION = "="
+    PRODUCT = "-"
+    LOCATION = "+"
+    TYPE = "%"
+    OTHER = "#"
+    ASSIGNMENT = "=="
+    SITE = "++"
+
+
+def coded_split(body: str) -> tuple[str, str] | None:
+    """Split `body` into letters and digits when it is shaped like a code, else None.
+
+    The digits must be worth 1 to 999_999_999; `K0` and `K1234567890` are not codes.
+    """
+    hit = _CODED.fullmatch(body)
+    if hit is None:
+        return None
+    letters, digits = hit.groups()
+    significant = digits.lstrip("0")  # int() of a 4300-digit run of zeros raises ValueError
+    if len(significant) > len(str(MAX_NUMBER)) or not 1 <= int(significant or "0") <= MAX_NUMBER:
+        return None
+    return letters, digits
+
+
+def _check_types(aspect: object, code: object, label: object) -> None:
+    if not isinstance(aspect, Aspect):
+        msg = "aspect must be an Aspect"
+        raise TypeError(msg)
+    if not isinstance(code, str) or not isinstance(label, str):
+        msg = "code and label must be str"
+        raise TypeError(msg)
+
+
+def _check_number(number: object) -> None:
+    if number is None:
+        return
+    if not isinstance(number, int) or isinstance(number, bool):
+        msg = "number must be an int or None"
+        raise TypeError(msg)
+    if not 1 <= number <= MAX_NUMBER:
+        msg = f"number must be 1..{MAX_NUMBER}"
+        raise TypeError(msg)
+
+
+def _check_label(label: str) -> None:
+    if label != label.strip():
+        msg = "label must not have outer whitespace"
+        raise TypeError(msg)
+    if _NOT_IN_LABEL & set(label):
+        msg = "label must not hold any of = - + % # : ; & < > ."
+        raise TypeError(msg)
+    if coded_split(label) is not None:
+        msg = "label must not be shaped like a code (letters and a number)"
+        raise TypeError(msg)
+
+
+@dataclass(frozen=True)
+class Level:
+    """One step in a tree: letters and a number (`-K2`), a number alone (`+3`) or a label (`+ER`).
+
+    Letters are upper case and need a number; a label is never code-shaped. Else TypeError.
+    """
+
+    aspect: Aspect
+    code: str = ""
+    number: int | None = None
+    label: str = ""
+
+    def __post_init__(self) -> None:
+        """Validate the shape; every violation raises TypeError naming the field."""
+        _check_types(self.aspect, self.code, self.label)
+        _check_number(self.number)
+        coded = bool(self.code) or self.number is not None
+        if coded == bool(self.label):
+            msg = "a level is letters and a number, a number alone, or a label"
+            raise TypeError(msg)
+        if coded:
+            self._check_coded()
+        else:
+            _check_label(self.label)
+
+    def _check_coded(self) -> None:
+        if _LETTERS.fullmatch(self.code) is None:
+            msg = "code must be upper-case ASCII letters A-Z only"
+            raise TypeError(msg)
+        if self.number is None:
+            msg = "code letters need a number"
+            raise TypeError(msg)
+
+    @property
+    def text(self) -> str:
+        """The level without its sign: the label, or the letters and the number."""
+        return self.label or f"{self.code}{self.number}"

refdef/numbering.py

@@ -0,0 +1,42 @@
+"""Numbering: the lowest free number for a class, and a group of them in order."""
+
+from collections.abc import Collection, Sequence
+
+from refdef.level import Aspect, Level
+
+
+def allocate(
+    aspect: Aspect,
+    code: str,
+    taken: Collection[Level],
+    reserved: Collection[Level] = (),
+    *,
+    first: int = 1,
+) -> int:
+    """The smallest number from `first` for which `Level(aspect, code, n)` is in neither collection.
+
+    `first` below 1 is a TypeError. Nothing is stored: the caller passes what is taken.
+    """
+    if not isinstance(first, int) or isinstance(first, bool) or first < 1:
+        msg = "first must be an int of at least 1"
+        raise TypeError(msg)
+    number = first
+    while Level(aspect, code, number) in taken or Level(aspect, code, number) in reserved:
+        number += 1
+    return number
+
+
+def number_group(
+    aspect: Aspect,
+    codes: Sequence[str],
+    taken: Collection[Level] = (),
+    reserved: Collection[Level] = (),
+) -> tuple[Level, ...]:
+    """One level per code, each numbered after the earlier ones; `taken` is not changed."""
+    used = set(taken)
+    out: list[Level] = []
+    for code in codes:
+        level = Level(aspect, code, allocate(aspect, code, used, reserved))
+        used.add(level)
+        out.append(level)
+    return tuple(out)

refdef/order.py

@@ -0,0 +1,44 @@
+"""The natural order of designations: numbers by value, text as text."""
+
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from refdef.designation import Designation
+from refdef.level import Aspect
+
+_RUNS = re.compile(r"[0-9]+|[^0-9]+")
+
+
+def _run_key(run: str, *, case_sensitive: bool) -> tuple[Any, ...]:
+    if run.isascii() and run.isdigit():
+        significant = run.lstrip("0")
+        # (length, digits) orders like int(run) and never hits the int-from-text digit limit
+        return (0, len(significant), significant)
+    return (1, run if case_sensitive else run.lower())
+
+
+def natural_key(text: str, *, case_sensitive: bool = True) -> tuple[Any, ...]:
+    """A sort key: digit runs by value, text runs as text, numbers first, then the raw text."""
+    if not isinstance(text, str):
+        msg = "text must be str"
+        raise TypeError(msg)
+    runs = tuple(_run_key(run, case_sensitive=case_sensitive) for run in _RUNS.findall(text))
+    return (runs, text)
+
+
+def sort_key(
+    d: Designation, *, aspects: Sequence[Aspect], case_sensitive: bool = True
+) -> tuple[Any, ...]:
+    """A sort key: per level the rank of its aspect in `aspects` and its natural key.
+
+    Aspects not listed rank after the listed ones, in enum order. The top is not in the key.
+    """
+    if not isinstance(aspects, Sequence) or not all(isinstance(a, Aspect) for a in aspects):
+        msg = "aspects must be a sequence of Aspect"
+        raise TypeError(msg)
+    order = [*aspects, *(a for a in Aspect if a not in aspects)]
+    return tuple(
+        (order.index(level.aspect), natural_key(level.text, case_sensitive=case_sensitive))
+        for level in d.levels
+    )

refdef/plc.py

@@ -0,0 +1,121 @@
+"""The direct address of a PLC program (`%IX0.0`, `%QW4`, `%I*`) and a channel tag that pairs it."""
+
+import re
+from dataclasses import dataclass, replace
+from enum import Enum
+
+from refdef.issues import Issue, IssueCode, Parsed
+from refdef.terminal import Terminal
+
+__all__ = ["Address", "ChannelTag", "Memory", "Size", "parse_address"]
+
+_MAX = 999_999_999
+_DIGITS = 9
+_ADDRESS = re.compile(r"%([IQM])([XBWDL]?)(\*|[0-9]+(?:\.[0-9]+)*)")
+
+
+class Memory(Enum):
+    """The memory area of an address: input, output or marker; the value is the letter."""
+
+    INPUT = "I"
+    OUTPUT = "Q"
+    MARKER = "M"
+
+
+class Size(Enum):
+    """The access size of an address: none, bit, byte, word, double word or long word."""
+
+    NONE = ""
+    BIT = "X"
+    BYTE = "B"
+    WORD = "W"
+    DWORD = "D"
+    LWORD = "L"
+
+
+def _is_index(value: object) -> bool:
+    """True for an int (not a bool) from 0 to 999_999_999."""
+    return isinstance(value, int) and not isinstance(value, bool) and 0 <= value <= _MAX
+
+
+@dataclass(frozen=True)
+class Address:
+    """A direct address printed `%` memory size path; an empty path is the incomplete `%I*`.
+
+    A path index is an int from 0 to 999_999_999; any other shape raises TypeError.
+    """
+
+    memory: Memory
+    size: Size
+    path: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        """Validate the fields; every violation raises TypeError."""
+        if not isinstance(self.memory, Memory) or not isinstance(self.size, Size):
+            msg = "memory must be a Memory and size a Size"
+            raise TypeError(msg)
+        if not isinstance(self.path, tuple) or not all(map(_is_index, self.path)):
+            msg = "path must be a tuple of ints from 0 to 999_999_999"
+            raise TypeError(msg)
+
+    def __str__(self) -> str:
+        """The strict printed form."""
+        return f"%{self.memory.value}{self.size.value}" + (".".join(map(str, self.path)) or "*")
+
+    def as_bit(self) -> Address:
+        """The one normalisation: a size-less dotted address gets the bit size; others are kept."""
+        if self.size is Size.NONE and len(self.path) > 1:
+            return replace(self, size=Size.BIT)
+        return self
+
+
+def _element(part: str, issues: list[Issue]) -> str:
+    """One path element without its leading zeros; the repair is an issue naming the element."""
+    stripped = part.lstrip("0") or "0"
+    if len(part) > 1 and part.startswith("0"):
+        issues.append(Issue(IssueCode.LEADING_ZERO, part, "leading zero dropped"))
+    return stripped
+
+
+def parse_address(text: str) -> Parsed[Address | None]:
+    """Read a direct address; repairs (outer whitespace, leading zeros) are issues.
+
+    Text that is not an address gives `None` and a NOT_ADDRESS issue.
+    """
+    if not isinstance(text, str):
+        msg = "text must be a str"
+        raise TypeError(msg)
+    body = text.strip()
+    match = _ADDRESS.fullmatch(body)
+    if match is None:
+        return Parsed(None, (Issue(IssueCode.NOT_ADDRESS, text, "not a direct address"),))
+    issues: list[Issue] = []
+    if body != text:
+        issues.append(Issue(IssueCode.WHITESPACE, text, "outer whitespace of the address removed"))
+    memory, size, rest = match.groups()
+    parts = [] if rest == "*" else [_element(part, issues) for part in rest.split(".")]
+    if any(len(part) > _DIGITS for part in parts):
+        return Parsed(None, (Issue(IssueCode.NOT_ADDRESS, text, "an index of over nine digits"),))
+    path = tuple(map(int, parts))
+    return Parsed(Address(Memory(memory), Size(size), path), tuple(issues))
+
+
+@dataclass(frozen=True)
+class ChannelTag:
+    """A terminal with an optional address, printed as the terminal alone (`-KE1:DI03`)."""
+
+    terminal: Terminal
+    address: Address | None = None
+
+    def __post_init__(self) -> None:
+        """Validate the fields; every violation raises TypeError."""
+        if not isinstance(self.terminal, Terminal):
+            msg = "terminal must be a Terminal"
+            raise TypeError(msg)
+        if self.address is not None and not isinstance(self.address, Address):
+            msg = "address must be None or an Address"
+            raise TypeError(msg)
+
+    def __str__(self) -> str:
+        """The terminal text only."""
+        return str(self.terminal)

refdef/scheme.py

@@ -0,0 +1,77 @@
+"""The scheme a check reads: aspects that are on, a letter rule and a class table."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass, replace
+from functools import cached_property
+
+from refdef.level import Aspect
+from refdef.tables import standard as _standard
+
+
+@dataclass(frozen=True)
+class LetterRule:
+    """How many letters a code has and which letters never appear."""
+
+    min_count: int = 1
+    max_count: int = 3
+    never: frozenset[str] = frozenset("IO")
+
+
+@dataclass(frozen=True)
+class ClassEntry:
+    """One class code with its title, the typical device of the class."""
+
+    code: str
+    title: str
+
+
+@dataclass(frozen=True)
+class ClassTable:
+    """Versioned class entries; `depth` is how many leading letters of a code are looked up."""
+
+    name: str
+    version: str
+    depth: int
+    entries: tuple[ClassEntry, ...]
+
+    @cached_property
+    def index(self) -> dict[str, ClassEntry]:
+        """The entries by code, built once."""
+        return {entry.code: entry for entry in self.entries}
+
+    def get(self, code: str) -> ClassEntry | None:
+        """The entry for the first `depth` letters of `code`, or None; no shorter fallback."""
+        return self.index.get(code[: self.depth])
+
+
+@dataclass(frozen=True)
+class Scheme:
+    """What `check` tests against: aspects on, a letter rule and a class table.
+
+    `STANDARD` is the shipped scheme: `= - +` on, 1-3 letters without I and O, a versioned table.
+    """
+
+    name: str
+    aspects: frozenset[Aspect]
+    letters: LetterRule
+    classes: ClassTable
+
+    def extend(self, *entries: ClassEntry, aspects: Iterable[Aspect] = ()) -> Scheme:
+        """A new scheme with `entries` overlaid by code (later wins) and `aspects` turned on."""
+        merged = {entry.code: entry for entry in (*self.classes.entries, *entries)}
+        table = replace(self.classes, entries=tuple(merged.values()))
+        return replace(self, aspects=self.aspects | frozenset(aspects), classes=table)
+
+
+_TABLE = ClassTable(
+    _standard.NAME,
+    _standard.VERSION,
+    _standard.DEPTH,
+    tuple(ClassEntry(code, title) for code, title in _standard.ENTRIES),
+)
+STANDARD = Scheme(
+    "standard",
+    frozenset({Aspect.FUNCTION, Aspect.PRODUCT, Aspect.LOCATION}),
+    LetterRule(),
+    _TABLE,
+)

refdef/tables/__init__.py

@@ -0,0 +1 @@
+"""Generated class tables."""

refdef/tables/standard.py

@@ -0,0 +1,192 @@
+# Generated by scripts/gen_table.py; do not edit.
+"""The generated class table."""
+
+NAME = "standard"
+VERSION = "1"
+DEPTH = 2
+ENTRIES: tuple[tuple[str, str], ...] = (
+    ("B", "Sensors"),
+    ("BA", "Voltage sensor"),
+    ("BB", "Resistivity sensor"),
+    ("BC", "Current sensor"),
+    ("BD", "Density sensor"),
+    ("BE", "Field sensor"),
+    ("BF", "Flow sensor"),
+    ("BG", "Position and distance sensors"),
+    ("BH", "Energy meter"),
+    ("BJ", "Power meter"),
+    ("BK", "Timer"),
+    ("BL", "Level sensor"),
+    ("BM", "Humidity sensor"),
+    ("BP", "Pressure sensor"),
+    ("BQ", "Concentration sensors"),
+    ("BR", "Light and radiation sensors"),
+    ("BS", "Speed and rate sensors"),
+    ("BT", "Temperature sensor"),
+    ("BU", "Multi-quantity sensors"),
+    ("BW", "Force and weight sensors"),
+    ("BX", "Acoustic and image sensors"),
+    ("BY", "Card and code readers"),
+    ("BZ", "Counters and detectors"),
+    ("C", "Storage devices"),
+    ("CA", "Capacitor"),
+    ("CB", "Inductor"),
+    ("CC", "Battery"),
+    ("CF", "Data storage"),
+    ("CL", "Open storage"),
+    ("CM", "Tanks and boxes"),
+    ("CN", "Containers"),
+    ("CP", "Heat storage"),
+    ("CQ", "Flywheels and springs"),
+    ("E", "Emitters"),
+    ("EA", "Lamp"),
+    ("EB", "Electric heater"),
+    ("EC", "Electric cooler"),
+    ("EE", "Wireless power source"),
+    ("EG", "Heat pumps and exchangers"),
+    ("EM", "Boilers and burners"),
+    ("EP", "Radiators and heating coils"),
+    ("EQ", "Chillers and coolers"),
+    ("ET", "Nuclear reactor"),
+    ("EU", "Particle sources"),
+    ("EV", "Acoustic wave emitter"),
+    ("F", "Protective devices"),
+    ("FA", "Surge protectors"),
+    ("FB", "Earth fault protectors"),
+    ("FC", "Fuses and circuit breakers"),
+    ("FE", "Field shields"),
+    ("FL", "Pressure relief devices"),
+    ("FM", "Fire protection devices"),
+    ("FN", "Mechanical protectors"),
+    ("FQ", "Guards and barriers"),
+    ("FR", "Lubricants and wear pads"),
+    ("FS", "Coatings and shelters"),
+    ("G", "Generating devices"),
+    ("GA", "Generator"),
+    ("GB", "Batteries and fuel cells"),
+    ("GC", "Photovoltaic module"),
+    ("GF", "Signal generator"),
+    ("GL", "Conveyors"),
+    ("GM", "Cranes, lifts and wagons"),
+    ("GP", "Pump"),
+    ("GQ", "Fans and compressors"),
+    ("GR", "Solar collector"),
+    ("H", "Process machines"),
+    ("HJ", "Casting and printing machines"),
+    ("HK", "Surface treatment machines"),
+    ("HL", "Assembly and joining machines"),
+    ("HM", "Centrifuges and cyclones"),
+    ("HP", "Dryers and distillers"),
+    ("HQ", "Filters and screens"),
+    ("HR", "Electromagnetic separators"),
+    ("HS", "Ion exchangers and absorbers"),
+    ("HU", "Mills and crushers"),
+    ("HV", "Pelletizers and flocculators"),
+    ("HW", "Mixers"),
+    ("HX", "Reactors"),
+    ("K", "Signal processing devices"),
+    ("KE", "Computers and controllers"),
+    ("KF", "Signal relay"),
+    ("KG", "Optical network devices"),
+    ("KH", "Fluid controllers"),
+    ("KJ", "Mechanical regulators"),
+    ("KZ", "Multi-signal devices"),
+    ("M", "Drives"),
+    ("MA", "Electric motor"),
+    ("MB", "Linear actuators"),
+    ("MC", "Permanent magnet"),
+    ("MD", "Piezo actuator"),
+    ("ML", "Turbines and spring drives"),
+    ("MM", "Hydraulic and pneumatic drives"),
+    ("MS", "Internal combustion engine"),
+    ("MT", "Steam and Stirling engines"),
+    ("N", "Covers"),
+    ("NA", "Panels and seals"),
+    ("NB", "Door leaves and hatch covers"),
+    ("NC", "Surface finishes"),
+    ("ND", "Edge trim"),
+    ("NE", "Trim and flashing"),
+    ("P", "Indicators and displays"),
+    ("PF", "Signal lamp"),
+    ("PG", "Meters and gauges"),
+    ("PH", "Displays and signs"),
+    ("PJ", "Loudspeakers and bells"),
+    ("PK", "Tactile devices"),
+    ("PL", "Ornaments"),
+    ("PZ", "Audio-visual alarms"),
+    ("Q", "Switching and control devices"),
+    ("QA", "Switching device for power"),
+    ("QB", "Disconnector"),
+    ("QC", "Earthing switch"),
+    ("QM", "Shutoff valves"),
+    ("QN", "Control valves"),
+    ("QP", "Open flow controllers"),
+    ("QQ", "Doors, windows and gates"),
+    ("QR", "Dosing valves"),
+    ("QS", "Locks and latches"),
+    ("QZ", "Earthing disconnector"),
+    ("R", "Restrictors"),
+    ("RA", "Resistors and diodes"),
+    ("RB", "UPS and power filters"),
+    ("RF", "Signal filters"),
+    ("RL", "Brakes and shock absorbers"),
+    ("RM", "Non-return valves"),
+    ("RN", "Regulating valves and dampers"),
+    ("RQ", "Insulation and screens"),
+    ("RU", "Fences and barriers"),
+    ("S", "Operator controls"),
+    ("SF", "Eye and face readers"),
+    ("SG", "Handles and hand switches"),
+    ("SH", "Pedal switch"),
+    ("SJ", "Pushbuttons and switches"),
+    ("SK", "Joysticks and pointing devices"),
+    ("SZ", "Operating panels"),
+    ("T", "Converters"),
+    ("TA", "Transformers and frequency converters"),
+    ("TB", "Rectifiers and inverters"),
+    ("TC", "AC/DC power supply"),
+    ("TF", "Amplifiers and signal converters"),
+    ("TL", "Gears and levers"),
+    ("TM", "Cutting and drilling machines"),
+    ("TP", "Forging and rolling machines"),
+    ("TR", "Plants"),
+    ("U", "Holders"),
+    ("UA", "Mounting fixtures"),
+    ("UB", "Cable trays and supports"),
+    ("UC", "Cabinets and enclosures"),
+    ("UL", "Structural members"),
+    ("UM", "Reinforcement"),
+    ("UN", "Frames"),
+    ("UP", "Bearings and hinges"),
+    ("UQ", "Fasteners"),
+    ("UT", "Fill and excavation"),
+    ("UU", "Soil and rock"),
+    ("W", "Conductors and guides"),
+    ("WB", "High voltage cables"),
+    ("WD", "Low voltage cables"),
+    ("WE", "Earthing conductors"),
+    ("WG", "Signal cables"),
+    ("WH", "Optical fibres and mirrors"),
+    ("WJ", "Sound reflector"),
+    ("WL", "Chutes and roller tables"),
+    ("WM", "Gutters and drains"),
+    ("WP", "Pipes and ducts"),
+    ("WQ", "Shafts and drive belts"),
+    ("WR", "Rail track"),
+    ("WV", "Heat sinks"),
+    ("WZ", "Umbilical cables"),
+    ("X", "Connectors"),
+    ("XB", "High voltage terminals and sockets"),
+    ("XD", "Low voltage terminals and sockets"),
+    ("XE", "Earthing terminals"),
+    ("XG", "Signal sockets and patch panels"),
+    ("XH", "Optical connectors"),
+    ("XK", "Sinks and drains"),
+    ("XM", "Pipe fittings and flanges"),
+    ("XN", "Fixed couplings"),
+    ("XP", "Clutches"),
+    ("XS", "Stairs and ladders"),
+    ("XT", "Openings"),
+    ("XZ", "Multi-connector"),
+)
+ENTRIES_SHA256 = "dfe380f087194b2f27565793153c2d3c96f1e9161b68d23e942a7b27a69a51d6"

refdef/terminal.py

@@ -0,0 +1,76 @@
+"""A terminal (`-K1:13`) and a signal (`-K1;SYSTEM_CAN_L`) of a designation."""
+
+from dataclasses import dataclass
+
+from refdef.designation import Designation
+
+
+def _stripped(text: object, banned: str) -> bool:
+    """True when `text` is a non-empty str without outer whitespace and without `banned`."""
+    if not isinstance(text, str) or not text or text != text.strip():
+        return False
+    return not any(char in text for char in banned)
+
+
+@dataclass(frozen=True)
+class Terminal:
+    """A designation and the pins on it, printed `of:pin:pin`.
+
+    At least one pin; each is stripped, non-empty and without `:`. Pins are opaque text.
+    """
+
+    of: Designation
+    pins: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        """Validate the designation and the pins; every violation raises TypeError."""
+        if not isinstance(self.of, Designation):
+            msg = "of must be a Designation"
+            raise TypeError(msg)
+        if not isinstance(self.pins, tuple) or not self.pins:
+            msg = "pins must be a non-empty tuple of str"
+            raise TypeError(msg)
+        if not all(_stripped(pin, ":") for pin in self.pins):
+            msg = "each pin must be stripped, non-empty and without ':'"
+            raise TypeError(msg)
+
+    def __str__(self) -> str:
+        """The strict printed form."""
+        return ":".join((str(self.of), *self.pins))
+
+    def relative_to(self, root: Designation) -> Terminal:
+        """The terminal with its designation made relative to `root`; the pins are kept."""
+        return Terminal(self.of.relative_to(root), self.pins)
+
+
+@dataclass(frozen=True)
+class Signal:
+    """A signal name on a designation, printed `of;name`; `of` is None for a bare name.
+
+    The name is stripped and non-empty and may hold `: ; &`. It is opaque text.
+    """
+
+    of: Designation | None
+    name: str
+
+    def __post_init__(self) -> None:
+        """Validate the designation and the name; every violation raises TypeError."""
+        if self.of is not None and (
+            not isinstance(self.of, Designation) or not (self.of.levels or self.of.top)
+        ):
+            msg = "of must be None or a Designation with a level or a top"
+            raise TypeError(msg)
+        if not _stripped(self.name, ""):
+            msg = "name must be a stripped, non-empty str"
+            raise TypeError(msg)
+
+    def __str__(self) -> str:
+        """The strict printed form."""
+        return (str(self.of) if self.of is not None else "") + ";" + self.name
+
+    def relative_to(self, root: Designation) -> Signal:
+        """The signal with its designation made relative to `root`; None if nothing is left."""
+        if self.of is None:
+            return self
+        rest = self.of.relative_to(root)
+        return Signal(rest if rest.levels or rest.top else None, self.name)