vtf iosys vtiinterpreter

↑ vtf-iosys

vtiinterpreter

The module contains the parser to interpreting the stdin stream.

Module contents

The MainInterpreter

class vtiinterpreter.MainInterpreter(_BaseInterpreter) ¶

This is the main interpreter object, all other interpreter types in the module are used by this one.

The input types of the framework are created character by character by this object. The interpretation starts with the first call of the interpreter's __call__ method, depending on whether the character is completed at the call, an input type or a subinterpreter is returned. Sub-interpreters obtain the following characters through __lshift__ until the sequential input is completed and an input type is returned. The query whether the return value is a complete input type is made by isdone.

>>> sequence = interpreter(char)
>>> while not interpreter.isdone(sequence):
>>>     sequence <<= char

The complete generation of final objects can be done via gen.

The class provides a close interface to the processed characters through methods with bind_ prefix.

The following code block is an example to visualize escape sequences and how the interpreter works using the bind_ methods.

>>> interpreter.bind_esc(lambda: print("\nESC   :: MAIN"))
>>> interpreter.bind_intro(lambda c: print("%-4s  :: MAIN" % repr(c)[2:-1]))
>>> interpreter.bind_to_interpreter("any", "p", lambda i, c: print("%-4s  :: ╚%s" % (repr(c)[2:-1], i.__class__.__name__)))
>>> interpreter.bind_to_interpreter("any", "f", lambda i, c: print("%-4s  :: ╚%s\n" % (repr(c)[2:-1], i.__class__.__name__)))

Since the combined input with Alt/Meta prefixes the character with an escape character, the way in which an escape sequence is to be interpreted can be determined by the ACCEPTED_META_KEYS and PROTECTED_INTRODUCERS attributes.

PROTECTED_INTRODUCERS defines code numbers of introductory characters to be interpreted as escape sequence. By default, the values (0x4f, 0x50, 0x5b, 0x5d) = ("O" (SS3), "P" (DCS), "[" (CSI), "]" (OSC)) are used, these are the components of the control characters for the regular response sequences and the inputs of the mouse or function keys of the keyboard. Inside the attribute is a collection of predefined values, and it can be modified via PROTECTED_INTRODUCERS.set().

ACCEPTED_META_KEYS defines code numbers of characters that are accepted as Metatypes. By default, all characters (which are not picked up by PROTECTED_INTRODUCERS) are accepted. Inside the attribute is a collection of predefined values, and it can be modified via ACCEPTED_META_KEYS.set().

Whether Tab, Return, Linefeed or Space is to be created as Space or Ctrl can be determined via SPACE_TARGETS. By default, only Space is created as Space. Inside the attribute is a collection of predefined values, and it can be modified via SPACE_TARGETS.set().

# Recources:

; xterm/CSI ff. ; xterm/OSC ff. ; xterm/Special-Keyboard-Keys ff. ; microsoft/console-virtual-terminal-sequences/input-sequences

_¶

ACCEPTED_META_KEYS: _AcceptedMetaKeys

PROTECTED_INTRODUCERS: _ProtectedIntroducers

SPACE_TARGETS: _SpaceTargets

bound_esc: Callable[ [], Any]

bound_esc_intro: Callable[ [bytes], Any]

esc_sequences: bool

__call__(_in) -> Ctrl | ASCII | DelIns | Space | Utf8Interpreter | MainInterpreter ¶

__init__(esc_sequences=True) ¶

esc_sequences: enable the interpretation of escape sequences.

__lshift__(_introducer) -> _BaseInterpreter | EscSegment | Key | Char | Reply ¶

bind_esc(__f=lambda *_: None) -> None ¶

Bind the execution of function __f to the occurrence of an introductory escape character.

bind_intro(__f=lambda *_: None) -> None ¶

Bind the execution of function __f to the introductory character of an escape sequence after the escape character. The function gets the character when it is executed. The introductory character after escape, is also known as the second component part of the control character, a sequence could be finalized by this.

bind_to_interpreter(interpreter, to_char, __f=lambda *_: None) -> None ¶

Bind within the sequence-interpreter-type, to the parameter characters and/or to the final character, the execution of function __f.

The interpreter is defined as type and passed to isinstance() to determine the target. Note the hierarchy of interpreter classes for this:

• BaseInterpreterFinalST

  • DevCtrlStrInterpreter
  • OSCmdInterpreter
  • AppInterpreter

• SingeShiftInterpreter

  • SingeShift3Interpreter

• CtrlSeqsInterpreter
• MouseInterpreter
• FsFpnFInterpreter
• Utf8Interpreter
• BrPasteMInterpreter

For binding to all types, "any" can be specified.

The character type to_char can be specified as "param" or "final"; or as "any" for both types.

The function __f receives at execution the active interpreter object and the character as parameterization.

gen(_in) -> EscSegment | Key | Mouse | Reply | Char ¶

Generate a complete sequence from the return values of _in.

staticmethod isdone(__o) -> bool ¶

Return whether the object is a completed sequence.

MainInterpreter Property Objects

class vtiinterpreter._AcceptedMetaKeys(_CodeNumProperty) ¶

These characters are considered to be enabled for Alt/Meta+Key interpretation (Meta).

The default values of ((0x00, 0x7f), (0xc2, 0xf4)) span the range of ASCII Control Characters, ASCII Printable Characters, ASCII Delete and the start bytes of UTF8 sequences -- so all.

ASCII = _CodeNumPredefinedValue((0x20, 0x7e), )

ASCII_CTRL = _CodeNumPredefinedValue((0x00, 0x1f), )

DELETE = _CodeNumPredefinedValue(0x7f, )

NONE = _CodeNumPredefinedValue()

UTF8 = _CodeNumPredefinedValue(0xc2, 0xf4)

set(*args) ¶

Set an unspecified number of character code points to the property. Can be passed as a single value ( <int> ), range as a tuple ( (<start>, <inclusive end>) ) and with the predefined values.

class vtiinterpreter._ProtectedIntroducers(_CodeNumProperty) ¶

Escaping sequences starting with these characters are further interpreted as escaping sequences and not as pressing Alt/Meta+Key (Meta).

The default value of (0x4f, 0x50, 0x5b, 0x5d) corresponds to ("O" (SS3), "P" (DCS), "[" (CSI), "]" (OSC)), these are regular response sequences or sequences of the keyboard or mouse.

Fe_App = _CodeNumPredefinedValue(0x58, 0x5e, 0x5f)

Fe_REPLIES = _CodeNumPredefinedValue(0x4f, 0x50, 0x5b, 0x5d) # O P [ ] (SS3, DCS, CSI, OSC)

Fe_Seqs = _CodeNumPredefinedValue(0x44, 0x45, 0x46, 0x48, (0x4d, 0x50), 0x56, 0x57, 0x58, 0x5a, (0x5b, 0x5f))

Fp_Seqs = _CodeNumPredefinedValue((0x36, 0x39), 0x3d, 0x3e)

Fs_Seqs = _CodeNumPredefinedValue(0x63, (0x6d, 0x6f), 0x7c, 0x7d, 0x7e)

HP_Keys = _CodeNumPredefinedValue((0x41, 0x44), 0x4a, 0x46, 0x51, 0x53, 0x54, 0x68)

NONE = _CodeNumPredefinedValue()

VT52_KeyPad = _CodeNumPredefinedValue(0x3f, )

VT52_Keys = _CodeNumPredefinedValue((0x41, 0x44), 0x52)

nF_Seqs = _CodeNumPredefinedValue(0x20, 0x23, 0x25, (0x28, 0x2b), 0x2d, 0x2e, 0x2f)

set(*args) ¶

Set an unspecified number of character code points to the property. Can be passed as a single value ( <int> ), range as a tuple ( (<start>, <inclusive end>) ) and with the predefined values.

class vtiinterpreter._SpaceTargets(_CodeNumProperty) ¶

Create Tab, Return, Linefeed or Space as Space instead of Ctrl.

Default:

• Space -> Space
• Tab, Return, Linefeed -> Ctrl

ANY = ENTER + SPACE + TAB

ENTER = LINEFEED + RETURN

LINEFEED = _CodeNumPredefinedValue(0x0a, )

NONE = _CodeNumPredefinedValue()

RETURN = _CodeNumPredefinedValue(0x0d, )

SPACE = _CodeNumPredefinedValue(0x20, )

TAB = _CodeNumPredefinedValue(0x09, )

set(*args) ¶

Set an unspecified number of character code points to the property. Can be passed as a single value ( <int> ), range as a tuple ( (<start>, <inclusive end>) ) and with the predefined values.

The Sub-Interpreters

class vtiinterpreter._BaseInterpreter ¶

The base class of interpreters.

Derivatives and structure:

MainInterpreter ->

• BaseInterpreterFinalST

  • DevCtrlStrInterpreter
  • OSCmdInterpreter
  • AppInterpreter

• SingeShiftInterpreter

  • SingeShift3Interpreter

• CtrlSeqsInterpreter
• MouseInterpreter
• FsFpnFInterpreter
• Utf8Interpreter
• BrPasteMInterpreter

class vtiinterpreter.AppInterpreter(BaseInterpreterFinalST) ¶

Interpreter for APP-lication defined sequences beginning with

• "X" (SOS)
• "^" (PM)
• "_" (APC)

and terminated by "ESC \" (ST).

class vtiinterpreter.BaseInterpreterFinalST(_BaseInterpreter) ¶

Base interpreter for escape sequences starting with "P" (DCS), "X" (SOS (APP)), "]" (OSC), "^" (PM (APP)) or "_" (APC (APP)) and terminated by a string terminator "ESC \" (ST).

Derivatives:

• DevCtrlStrInterpreter (DCS)
• OSCmdInterpreter (OSC)
• AppInterpreter (SOS, PM, APC)

class vtiinterpreter.BrPasteMInterpreter(_BaseInterpreter) ¶

Interpreter for bracketed Pasted mode sequences beginning with "ESC [ 200 ~" and terminated by "ESC [ 201 ~".

Sub-interpreter of CtrlSeqsInterpreter.

Activated by: (DECPrivateMode)

• [CSI ? 2004 h]

class vtiinterpreter.CtrlSeqsInterpreter(_BaseInterpreter) ¶

Interpreter for control sequences beginning with "[" (CSI).

Most keystrokes and all mouse actions are represented by them. Mouse actions are forwarded to MouseInterpreter. Bracketed paste forwarded to BrPasteMInterpreter.

class vtiinterpreter.DevCtrlStrInterpreter(BaseInterpreterFinalST) ¶

Interpreter for Device-Control-String sequences beginning with "P" (DCS) and terminated by "ESC \" (ST). Are used for some replies.

class vtiinterpreter.FsFpnFInterpreter(_BaseInterpreter) ¶

Interpreter for the less complex Fs-, Fp- and nF- Escape Sequences (FsFpnF).

class vtiinterpreter.MouseInterpreter(_BaseInterpreter) ¶

Interpreter for Mouse actions. Sub-interpreter of CtrlSeqsInterpreter.

Activated by one of: (DECPrivateMode)

• [CSI ? 9 h]
• [CSI ? 1000 h]
• [CSI ? 1002 h]
• [CSI ? 1003 h]

Modified by one of: (DECPrivateMode)

• [CSI ? 1005 h]
• [CSI ? 1006 h]

class vtiinterpreter.OSCmdInterpreter(BaseInterpreterFinalST) ¶

Interpreter for Operating-System-Command sequences beginning with "]" (OSC) and terminated by "ESC \" (ST). Used for OSC-replies.

class vtiinterpreter.SingeShift3Interpreter(SingeShiftInterpreter) ¶

Interpreter for single-shift select G3 sequences starting with "O" (SS3).

Used less frequently for the representation of keystrokes. But mostly for the unmodified representation of F1 to F4 or arrow keys.

class vtiinterpreter.SingeShiftInterpreter(_BaseInterpreter) ¶

Base class for interpreters of single-shift sequences beginning with "N" (SS2) and "O" (SS3). This is only used for SS2 and creates a Fe sequence.

Derivatives:

• SingeShift3Interpreter

class vtiinterpreter.Utf8Interpreter(_BaseInterpreter) ¶

UTF8-Sequence Interpreter.

---

Date:	11 Nov 2022
Version:	0.1
Author:	Adrian Hoefflin [srccircumflex]
Doc-Generator:	"pyiStructure-RSTGenerator" <prototype>