DomTerm mostly handles standard ansi/xterm escape sequences. This section documents DomTerm-specific extensions. (Future: We should also document what xterm features aren’t implemented.)
The following code sequences may change based on experience and feedback.
Notation:
Literal characters are written as quoted string literals with
escape sequences as understood by bash’s echo -e.
Specifically "\e" is an escape; "\a" is alert (bell);
"\xHH" is the 8-bit characters whose value is HH (hexadecimal).
"\e[3J"
Erase the scrollback buffer (i.e. any lines above the home line). (This is an xterm feature.)
"\e[>0c"
Request Secondary Device Attributes.
(This is a standard request for xt100style terminals, including xterm.)
DomTerm responds "\e]990;XXYYYZZ;0c",
where the number XXYYYZZ is derived from the DomTerm
version number "XXX.YYY.ZZ".
"\e]7;file://" hostname "/"directory "\a"
Specifies the current directory of the process.
(This is generated by some shells by default.
On Fedora this is done by the script /etc/profile.d/vte.sh.)
"\e]8;" options ";" url "\a" text "\e]8;;\a"
Create a link with the given url and
display text (which can contain other escape sequences for styling).
The options are ignored. The link has class="plain".
See this link.
"\e]30;" name "\a"
Sets the “session name” to name, which is shown in the window title.
Specifically sets the name attribute of the top-level
domterm <div> node to name. This can be used
to enable stylesheet rules to only apply to specfic DomTerm windows.
If an active CSS stylesheet contains:
div.domterm[name="name"] {rules}
then the rules are only active for a DomTerm element whose
session name is name.
"\e]72;" html-text "\a"
Insert HTML text (a fragment).
The html-text can be a complete html file,
but elements such as <html>, <body> or <style>
are ignored.
The HTML is sanity-checked for safety.
A <base href=" element in the base-url"/>html-text
is skipped, except that the base-url is used for subsequent
relative URLs (for src attributes for <img> elements,
and for href attributes for <a> elements) in the same
html-text.
The actual policy for allowed elements and attributes
can be changed by overwriting the elementInfo
and allowAttribute functions in terminal.js.
The default policy is a work-in-progress.
"\e]73;" keyName "\a"
"\e]74;" keyName "\a"
"\e]73;" keyName "\t" kstr "\a"
"\e]74;" keyName "\t" kstr "\a"
Simulate pressing keyName. Used by auto-line mode.
The 73 variant supresses echo.
"\e]104;" op , url "a\n"
Create a new sub-window (pane), based on the op.
This displays the url webpage in an <iframe>.
"\e]105;" op , saved-url "a\n"
Create a new sub-window (pane), based on the op.
This is displays the saved-url, a previously saved terminal session.
"\e[12u"
Start of error output.
DomTerm places the following text inside a <span> element
whose std attribute has the value "error".
The default style is to display the text in red.
"\e[11u"
End of error output.
"\e[14u"
Start of prompt.
DomTerm places the following text inside a <span> element
whose std attribute has the value "prompt".
The default style is to display the text in green.
"\e[13u"
End of prompt. The prompt is included in selections that surround it.
"\e[18u"
End of non-selectable prompt.
The prompt is not part of the text content of the document,
and is not included in selections.
The prompt string must be plain text with no styling.
You can use this for all prompts, but it is especially recommended
for continuation lines, such as the shell’s PS2 prompt.
"\e[15u"
"\e[15;" edit-mode "u"
Start of an input line.
This also implicitly ends a (selectable) prompt.
The input line is implicitly terminated by a '\n'
(carriage return).
The edit-mode specifies what kind of input-line-editing is
in effect, which affects how mouse clicks are handled.
If edit-mode is 0, it means there is no input-line-editing,
and no arrow key support by the client;
the value 1 (the default) means single-line editing (like GNU readline);
the value 2 means the first line of a multi-line editing group (as JLine3).
"\e[16u"
"\e[17u"
Delimit a hide/show "button", with "\e[16u" before
and "\e[17u" after.
The text between should be 1 or 2 characters (code points).
The first character is displayed when contents are visible (shown)
and that when clicked causes contents to be hidden.
If there is a second character, it is the character used when
contents are hidden
and that when clicked causes contents to be shown.
If the first character matches a "hide" entry in the predefined
showHideMarkers table, then the second character
defaults to the corresponding "show" entry.
"\e[83;" mode "u"
Delimit a span to be controlled by a show/hide button (previously printed).
If mode is 1 or 2 it starts a span, while mode 0 ends the span.
The span is initially visible if mode is 1, and
is hidden if mode is 2.
"\e]119;" context-id "\a"
"\e[19u" (deprecated)
Start a command group.
This command implicitly does a "fresh line" and ends any
existing command group with the same context-id.
(The "\e[19u" variant is equivalent to
an empty context-id - i.e. "\e]119;\a".)
Creates a nested command-group
if there is no existing command group with the same context-id.
You can write this string before writing an input prompt string.
The content-id is commonly the process-id of the REPL.
"\e]120;" group-id "\a"
(Experimental) Enter a new command-group without closing any current group.
"\e]121;" group-id "\a"
(Experimental) Exit the command-group with the given group-id.
"\e[20u"
Starts a "fresh line": If at the beginning of line, does nothing. Otherwise moves to the start of a new line.
"\e[80;97u"
"\e[80;99u"
"\e[80;108u"
"\e[80;112u"
Set input editing mode.
The value 99 ('c') sets character mode;
the value 108 ('l') sets line-editing mode.
The value 97 ('a') set automatic mode,
which switches between character mode and line-editing mode
based on the mode of the inferior process (when using a PTY).
The value 112 ('p' for "pipe") is like line-editing mode,
but the inferiors doesn’t echo the input, so we have to do it.
This mode is useful when the input is a pipe or some other non-tty stream.
"\e[81u\n"
Requent to send the state of the window as a WINDOW-CONTENTS response.
"\e[88;" object "\a"
Change various properties of the internal DomTerm object,
based on properties of object.
For example to change the character used hide characters
in password fields to “bullet” you can do:
echo -en '\e[88;{"passwordHideChar": "\\u2022"}\a'
Allowed properties include:
passwordHideChar, passwordShowCharTimeout,
deferredForDeletionTimeout,
historyStorageKey, historyStorageMax.
"\e[89;" settings "\a"
Internal use: Update user settings.
"\e[90;" op "u"
Create a new sub-window (pane), based on the op.
"\e[92;" op "u"
Temporarily enable auto-paging if op is 1.
Disables it if op is 2 (- only if temporarily enabled).
A simplified more program could temporarily enable auto-paging,
print some amount of output, and then revert the state.
This used by the domterm help command.
"\e[99;99u"
End-of-file on the output stream.
Calls the eofSeen method of DomTerm,
which may close the current window or other appropriate action.
"\e]103;" state "\a"
Send saved state to new window.
"\e]122;" pattern "\a"
Set continuation prompt template.
This is used for non-initial lines in a multi-line input editing area.
The template uses print-style % escapes to indicate
things to fill out.
It is similar to the one used for JLine.
"\e]123;\a"
Extend previous input line for editing. Typically used after reading an input line that is syntactically incomplete, but valid “so far“. The previous input is “re-opened” for editing, and a fresh empty line added.
"\x13" "\x15" sequence "\x14"
This is an “urgent” command sequence, which is the
same as sequence, but at higher priority.
If the terminal is in the middle of some other escape sequence
(or a multi-byte UTF-8 sequence), save the state,
evaluate sequence, and restore the state.
"\x13" sequence "\x14"
"\x13" "\x16" sequence "\x14"
These variants are reserved for the domterm backend (server).
These are similar to the previous variant,
but the sequence is not counted in the running count
(used for flow control), nor is it included if an output log
is saved (in case it is needed detach+attach).
For the second form only:
When DomTerm receives a sequence of bytes that contains
an urgent sequence, it will execute that before handling preceding bytes.
"\e]44;" options "\a"
Start of a new diagnostic - an error message or similar.
This creates and enters a node <span> element
with class="diagnostic", and info=".
The options"options should be a JSON-formatted object with the
outer { and } stripped off.
Currently the only options defined is repl: true to
indicate this was an error/warning in a previous REPL command.
"\e[44;0u"
End of current diagnostic. This exits the previously-entered
<span class="diagnostic">.
"\e[44;" parameter "u"
Furure extension, planned for marking start and/or end of specific parts of a diagnostic.
"\e]90;\a"
A request to return a list of the stylesheets in the document.
Result to client: "\x9D" stylesheets "\n"
Each stylesheet is a JSON-formatted string, separated by "\t",
suitable for printing by the list-stylesheets command.
"\e]91;" index "\a"
Disable the stylesheet that has index index in the list of
stylesheets in the document.
Result to client: "\x9D" message "\n"
where message is empty if there was no problem,
and is otherwise an error message.
"\e]92;" index "\a"
As above, but enable the specified stylesheet.
"\e]93;" index "\a"
Return the contents of the specified stylesheet.
On success the result is "\x9D" rule* "\x9D"
where each is a JSON-quoted string.
On failure, the result is a (non-quoted) error message.
"\e]94;" rule "\a"
If necessary, create a new temporary stylesheet, and add the specified JSON-quoted rule to the end of it.
"\e]95;" name "," styles "\a"
"\e]96;" name "," styles "\a"
Create or replace a stylesheet with the given name.
If there is a <style> with a name attribute equal to name,
it is replaced; otherwise a new one is created, with its name set to name.
The styles is the literal contents of the new stylesheet;
it becomes the child of the <style> element (as a single text node).
Both name and styles are strings in quoted (JSON) format.
If the code is 96, no response is sent.
If the code is 95, the result to the client is
"\x9D" index "\n" where index
is the index of the replaced or created stylesheet.
"Pretty-printing" refers to breaking a text info multiple lines in a way to minimize the number of lines needed while preserving logical structure and adding helpful indentation. DomTerm implements the features and concepts of the Common Lisp pretty-printing feature. The following uses the latter’s terminology. Doing line-breaking in DomTerm means it can dynamically adjust for varying line width.
"\e]110\a"
"\e]110;" per-line-prefix "\a"
Start a logical block, followed by sections of the output that logically belong together, and that DomTerm will try to group on the same line. If the group needs to be broken into multiple lines, continuation lines will be indented to the current horizontal position.
If there is a “prefix” before the group,
send it to DomTerm before this command.
On the other hand, if there is a per-line-prefix
(a JSON-quoted string) it will written both at the current position,
and at the same position in any continuation lines.
"\e]111\a"
End a logical block. If there is a "suffix", send it to DomTerm after this command.
"\e]112;" amount "\a"
Adjust identation of future lines (in the current block).
The amount is measured in characters, and is relative to the
current position. A negative amount is allowed, as long as you
don’t end up to the left of any per-line prefixes.
"\e]113;" amount "\a"
Similar to the 112 command, but amount
is relative to the start of the current block (after any per-line prefix).
"\e]114;" prefix "\a"
Adds an extra per-line prefix for future lines,
specified by prefix, a JSON-quoted string.
"\e]115\a"
Add a “fill”-type conditional newline.
"\e]116\a"
Add a “linear”-type conditional newline.
"\e]117\a"
Add a “miser”-type conditional newline (which is currently treated the same as a “fill” newline).
"\e]118\a"
A required newline. This should be used (rather than a plain newline) when inside a logical-block.
"\e]115;"prebreak","postbreak","nonbreak "\a"
"\e]116;"prebreak","postbreak","nonbreak "\a"
"\e]117;"prebreak","postbreak","nonbreak "\a"
"\e]118;"prebreak","postbreak","nonbreak "\a"
Line-breaks of the types given above, but with specific strings to be used.
Each string is JSON-quoted.
The nonbreak string is used if the line is not broken here.
If there is a break, the prebreak string is used before the break,
and the postbreak string is used after the break (following any indentatioon and per-line prefixes).
For example to insert a hyphenation point, you might write:
\e]115;"-","",""\a
German used to have a rule where “ck” would be hyphenated as “k-k”, as in Zucker (suger):
Zu\e]115;"-k","k","ck"\aer
"\x92" name " " data "\n"
General format for reporting events,
where name is the name of the event (an identifier).
The data can be any text not including a "\n"
(or other control character); JSON format is used in some cases.
"\x92" "WS " rows " " cols " " height " " width "\n"
Report window size from DomTerm to the back-end.
"\x92" "KEY " keyname "\t" seqno "\t" kchars "\n"
Used by auto-line mode to report a key event to back-end.
The keyName is an encoding of the key event in the
style of browserkeymap;
kchars is a string literal (JSON-formatted)
of the characters that are normally transmitted to the back-end.
The seqno is a sequence number, modulo 1024.
In auto-line mode, if the pty is in canonical mode, then keyName
is returned to DomTerm (using "\e]74;" );
otherwise keyName "\t" seqno "\t" kchars "\a"kchars are sent to the pty.
"\x92" "LINK " ref-info "\n"
Sent by the DomTerm browser when the user clicks on an <a> link.
The ref-info is a JSON-encoded object with information
about the link. The object must have at least an href property.
Typically, backend should open href
in the default browser of the user’s desktop,
though this is contomizable.
"\x92" "RECEIVED " count "\n"
This is used for flow-control.
The count is the number of bytes received and processed
by the front-end.
"\x92" "SESSION-NAME " session-name "\n"
Set session-name (a JSON-quoted string)
as the name for this session.
"\x92" "DETACH\n"
Don’t destroy the session when the last window is closed; instead detach it. (Don’t necessary detach now, if there are other windows on the session.)
"\x92" "FOCUSED\n"
The current (sub-)window has focus.
"\x92" "WINDOW-CONTENTS " rcount "," state "\n"
Report enough of the browser part of the session state so that
it can be reproduced when a window is sttached to the session.
The state is a JSON-encoded structure.
The rcount is similar to the value reported RECEIVED,
but as of the start of the most recent urgent message.
"\x92" "VERSION " version-info "\n"
Sends version-info to the back-end. Used during initialization.