## refdef
class Aspect
    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.

class ClassEntry(code: 'str', title: 'str') -> 'None'
    One class code with its title, the typical device of the class.

class Designation(levels: 'tuple[Level, ...]' = (), top: 'str' = '') -> 'None'
    A tuple of levels and an optional top node, built by the constructor and `child` only.

    Join two through their levels; the empty designation is the root.

class Issue(code: 'IssueCode', subject: 'str', message: 'str') -> 'None'
    One finding about a string or a designation: a code, the offending text, a short sentence.

class IssueCode
    The 21 issue codes: the first 16 come from the readers, the last 5 from check.

class Level(aspect: 'Aspect', code: 'str' = '', number: 'int | None' = None, label: 'str' = '') -> 'None'
    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.

class Parsed(value: 'T', issues: 'tuple[Issue, ...]') -> 'None'
    A value read from text together with the issues the reader found.

STANDARD: 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.

class Scheme(name: 'str', aspects: 'frozenset[Aspect]', letters: 'LetterRule', classes: 'ClassTable') -> 'None'
    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.

class Signal(of: 'Designation | None', name: 'str') -> 'None'
    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.

class Terminal(of: 'Designation', pins: 'tuple[str, ...]') -> 'None'
    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.

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.

check(designations: 'Iterable[Designation]', scheme: 'Scheme') -> 'tuple[Issue, ...]'
    Issues of the designations against `scheme`, in order; duplicates first for each one.

    Terminals and signals are not checked: pass their `of`.

lowest_free(taken: 'Collection[int]', reserved: 'Collection[int]' = (), *, first: 'int' = 1) -> 'int'
    The smallest number from `first` that is in neither `taken` nor `reserved`.

    `reserved` is never handed out; the caller stores it. `first` below 1 is a TypeError.

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.

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.

parse(text: 'str', *, bare: 'Aspect') -> 'Parsed[Designation | Terminal | Signal]'
    Read text as a designation, terminal or signal, with an issue for each repair.

    `bare` is the aspect of text before the first sign. Never raises for content.

render(d: 'Designation', *, pad: 'Mapping[str, int] | None' = None, dotted: 'Collection[Aspect]' = (), bare: 'bool' = False) -> 'str'
    Print a designation; `pad`, `dotted` and `bare` are the explicit dialects, none is `str(d)`.

    `pad={"W": 4}` gives `-W0001`; `dotted=(P,)` gives `-W25.1`; `bare=True` omits the first sign.

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.

## refdef.plc
class Address(memory: 'Memory', size: 'Size', path: 'tuple[int, ...]') -> 'None'
    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.

class ChannelTag(terminal: 'Terminal', address: 'Address | None' = None) -> 'None'
    A terminal with an optional address, printed as the terminal alone (`-KE1:DI03`).

class Memory
    The memory area of an address: input, output or marker; the value is the letter.

class Size
    The access size of an address: none, bit, byte, word, double word or long word.

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.
