Commit dfc6b256 authored by Per Bothner's avatar Per Bothner

Updates to semantic-prompts: cleanups; avoid ITerm2 conflicts

parent 21dcb94f
......@@ -15,7 +15,7 @@ The input lines will usually contain _prompt_ sections emitted
by the application, usually at the beginning of the first line.
This protocal defines a way for an application to specify to a terminal
the start and end of commands and their parts: input, promp, and output.
the start and end of commands and their parts: input, prompt, and output.
This can enable useful features like visual separation/highlighting
of commands; folding (a button to hide long command output);
searching or copying of command input or output; or indication of return status.
......@@ -26,6 +26,11 @@ then later by [iterm2](https://iterm2.com/documentation-shell-integration.html).
Other similar prior art is known for
[Extraterm](http://extraterm.org/) and [DomTerm](http://domterm.org/Wire-byte-protocol.html).
**Issue:**: The protocol needs to be tested, to see
how well it supports various shells.
Especially needing testing are handling of multi-line inputs, and right prompts.
[DomTerm](https://domterm.org) will be used for prototyping.
# Detail
A command sequence may be nested withing the output section of
......@@ -38,7 +43,7 @@ application; if that is unavailable, the name of the application.
## Commands
`OSC "133;F\007"`
`OSC "133;L\007"`
> Do a _fresh-line_: If the cursor is the initial column
> (left, assuming left-to-right writing), do nothing.
......@@ -47,15 +52,16 @@ application; if that is unavailable, the name of the application.
`OSC "133;A"` _options_ `"\007"`
> First do a _fresh-line_.
> Then start a new command, beginning with the prompt.
> Then start a new command, and enter prompt mode: Subsequent text
> (until a `OSC "133;B"` or `OSC "133;I"`command) is a prompt string.
`OSC "133;E"` _options_ `"\007"`
`OSC "133;N"` _options_ `"\007"`
> Same as `OSC "133;A"` but may first implicitly terminate a previous command:
> If the _options_ specify an `aid` and there is an active (open)
> command with matching `aid`, finish the innermost such command
> (as well as any other commands nested more deeply).
> Otherwise, treat as an `aid` whose value is the empty string.
> If no `aid` is specified, treat as an `aid` whose value is the empty string.
`OSC "133;P"` _options_ `"\007"`
......@@ -74,12 +80,13 @@ application; if that is unavailable, the name of the application.
> End of input, and start of output.
`OSC "133;D"` [`";"` _exit-code_] _options_ `"\007"`
`OSC "133;Z"`_options_ `"\007"`
> End of current command.
> The optional _exit-code_ is an integer value that reports
> an exit code from the command. This should be a non-negative integer,
> where 0 means successful completion, and non-zero for failure.
`OSC "133;D"` [`";"` _exit-code_]`"\007"`
> Same as `OSC "133;Z"` [`";exitcode="` _exit-code_]`"\007"`.
> For backward compatibility with Iterm2/FinalTerm.
## General options syntax
......@@ -102,6 +109,12 @@ A terminal must ignore an _option_ whose _option-name_ it doesn't recognize.
`aid=` _value_
> The current _application identifier_.
`exitcode=` _value
> Only applicable to a `OSC "133;Z"`command.
> Specifies an integer value that reports
> an exit code from the command. This should be a non-negative integer,
> where 0 means successful completion, and non-zero for failure.
`click-move=` _value_
> The _value_ can be `line` or other options to be determined later.
> This is a request from the application to the terminal to
......@@ -113,9 +126,11 @@ A terminal must ignore an _option_ whose _option-name_ it doesn't recognize.
> Specify key sequences to use for `click-move` mode when
> translating clicks to cursor motion.
> The defaults are the standard arrow-key sequences: `CSI D` etc.
> (_Note:_ this is an example where allowing quoted strings would be useful.)
## Input lines
Each input section consists of one or more input lines,
The structure of an input line is an optional initial prompt,
followed by a possibly-empty user input area,
followed by "background area", followed by an optional final prompt.
......@@ -125,9 +140,9 @@ followed by "background area", followed by an optional final prompt.
The `OSC "133;C"` command can be used to explicitly end
the input area and begin the output area. However, some applications
don't provide a convenient way to emit that command.
That is why we also specify an _implicit_ way to end the input area.
It is easy in the common case of a single input line, but we
can also deal with multiple lines: If the cursor is on a fresh (empty) line
That is why we also specify an _implicit_ way to end the input area
at the end of the line.
In the case of multiple input lines: If the cursor is on a fresh (empty) line
and we see either `OSC "133;P"` or `OSC "133;I"` then this is the
start of a continuation input line. If we see anything else,
it is the start of the output area (or end of command).
......@@ -147,7 +162,7 @@ from the background:
A terminal can manage this distinction using
a special logical style for text in the input area.
Input text echoed by the application should gets this style.
Input text echoed by the application should get this style.
Care must be taken when deleting characters: All deletion should be
done with either Delete Character (`CSI P`) or Erase in Line (`CSI K`),
but _not_ by overwriting with a space. If the application
......@@ -158,7 +173,7 @@ cursor in position using Cursor Forward (`CSI C`), not by writing spaces.
An application should emit each prompt string as a single
undivided sequence, not containing cursor motion
(including no carriage return or line-feed).
A prompt starts with a `'OSC 133;A'` or `'OSC 133;E'` sequence
A prompt starts with a `'OSC 133;A'` or `'OSC 133;N'` sequence
(for the initial prompt), or `'OSC 133;P'` (for subsequent prompts).
It must end with `'OSC 133;B'` or `'OSC 133;I'` or
end-of-line (only for final/right prompts).
......@@ -171,16 +186,16 @@ line wider than screen width), the prompt should be written at
the end of the final screen line, not the first. This allows
line-wrap indicators to be correct.
**Issue**: Possibly add a way to mark indentation as distict from prompts.
**Issue**: Possibly add a way to mark indentation as distinct from prompts.
## Cursor motion from mouse clicks
People new to shells and similar REPLs usually expect that they can
move the input cursor using a mouse click, and are surprised when it doesn't.
People new to shells and similar REPLs usually expect that they can move
the input cursor using a mouse click, and are surprised when it doesn't work.
Experienced shell users also sometimes want this ability,
for example making an edit to a long command. It is possible for
an application (or input library) to implement xterm-style mouse support,
but there are disadvantages:
an application (or input library) to implement this using xterm-style
mouse support, but there are disadvantages doing that:
- There is some per-application implementation effort to add mouse support.
This may be infeasible if you don't have source-code access or
......@@ -196,12 +211,13 @@ terminal to translate a mouse click to the appropriate key sequence.
Moving the cursor within the current input line is requested
by the `click-move=line` option. If the terminal supports this
feature, it is activated when the user does an unmodified
button-1 (left) click in an input line containing the cursor.
feature, it should be activated when the user clicks
in an input line containing the cursor,
using a button-1 (left) click and no modifier keys.
(If the click is in the left prompt, it is treated at the first character
of the input area; if it is to the right of input area (in the background area or right prompt) it is treated as just after the input area.)
The terminal calculates the character position of the click
minus the character position of cursor. (Character position is
minus the character position of the cursor. (Character position is
like column position, but double-width characters only count one.)
If the count is positive, that many _right_ sequences (by default `CSI C`)
are sent; if negative, that many _left_ sequences (by default `CSI D`).
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment