CyTUI `FormattedTextElement` format spec

spec.txt

@status   DRAFT
@version
  MAJOR   1
  MINOR   0
  REV     5

all specifiers produce an escape sequence.

DEFINITIONS
  • Tag: text surrounded by brackets that signal the start of a formatted
    portion of string.
    → [bold], [fg: 255, 0, 0], ...
  • Specifier: name of the tag.
    → bold, italic, foreground, ...

FORMATS
  [{name}]
  [!{name}]
  [{name}: {arg}]

ALLOWANCES
  • tags do not need to be closed.
    → OK: "Hello [b]John!"
  • tags can intersect each other.
    → OK: "Hello [b]John [i]JD[!b] Doe[!i]"

REQUIREMENTS
  • tags must be defined in the implementation. otherwise, an error should be
    thrown (they should NOT be ignored).
    → NOT OK: "Hello [invalid_specifier]John!"
  • it is up to the implementation whether already existing escape sequences
    in the formatter input should raise an error or be stripped. the latter is
    recommended by this specification.

PROPERTIES
  • `true` is implicit(1).
    [b: true] <=> [b]
  • `false` can be expressed using `!`
    [u: false] <=> [!u]

FLAG SPECIFIERS
  LIST(2)
    • bold
      alias: b
    • italic
      alias: i
    • underlined
      alias: u
    • strikethrough
      alias: s

  SIGNATURES
    (Bool)                          [b: true]

DATA SPECIFIERS
  LIST(2)
    • foreground
      alias: fg
    • background
      alias: bg

  FOREGROUND
    SIGNATURES
      (Tuple<3; Nat8>)              [fg: 255, 0, 0]
      (Nat8)                        [fg: 1]
      (HexColor)                    [fg: #ff0000]
      (ColorName)                   [fg: red]
      (False)                       [!fg](3)

  BACKGROUND
    SIGNATURES
      (Tuple<3; Nat8>)              [bg: 0, 0, 255]
      (Nat8)                        [bg: 4]
      (HexColor)                    [bg: #0000ff]
      (ColorName)                   [bg: blue]
      (False)                       [!bg](3)

NOTES
  (1) the implementation's error system should be able to tell which one was
      used in order not to confuse the user.
    → for example: if they wrote "[fg]", the error message should be about
      a missed argument, not an incompatible type.
  (2) it may not be an exhaustive list. while all implementations are required
      to support those defined in this specification, they are free to extend
      it as they wish.
  (3) the properties still apply here: e.g. [fg: false] and [bg: false] are
      technically valid, although not recommended.