Commit 43f2bf68 authored by Per Bothner's avatar Per Bothner

Update specification and add scripts.

parent f19a6c1a
......@@ -14,7 +14,7 @@ where each _command_ is a sequence of _user input_ (one or more lines typed by t
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
This protocol defines a way for an application to specify to a terminal
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);
......@@ -28,11 +28,6 @@ Other similar prior art is known for
[XMLterm](www.xml.com/pub/2000/06/07/xmlterm/index.html),
and [GraphTerm](https://github.com/mitotic/graphterm).
**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
......@@ -55,9 +50,10 @@ application; if that is unavailable, the name of the application.
> First do a _fresh-line_.
> 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.
> (until a `OSC "133;B"` or `OSC "133;I"` command) is a prompt string
> (as if followed by `OSC 133;P;k=i\007`).
> Applicable options: `aid`, `click-move`, `repaint`.
> Applicable options: `aid`, `cl`.
`OSC "133;N"` _options_ `"\007"`
......@@ -67,18 +63,20 @@ application; if that is unavailable, the name of the application.
> (as well as any other commands nested more deeply).
> If no `aid` is specified, treat as an `aid` whose value is the empty string.
> Applicable options: `aid`, `click-move`, `repaint`.
> Applicable options: `aid`, `cl`.
`OSC "133;P"` _options_ `"\007"`
> Start of secondary prompt. This is used for multi-line prompts,
> right-side prompts, and prompts for continuation lines.
> Explicit start of prompt. Optional after an `A` or `N` command.
> The `k` (kind) option specifies the type of prompt:
> regular primary prompt (`k=i` or default),
> right-side prompts (`k=r`), or prompts for continuation lines (`k=c`).
> Applicable options: `kind`.
> Applicable options: `k` (kind).
`OSC "133;B"` _options_ `"\007"`
> End of prompt and start of user input, terminated
> by a `OSC "133;C"`.
> by a `OSC "133;C"` or another prompt (`OSC "133;P"`).
`OSC "133;I"` _options_ `"\007"`
> End of prompt and start of user input, terminated
......@@ -95,7 +93,9 @@ application; if that is unavailable, the name of the application.
> Applicable options: `aid`, `cancel`.
`OSC "133;D"` [`";"` _exit-code_]`"\007"`
> Same as `OSC "133;Z"` [`";exitcode="` _exit-code_]`"\007"`.
> Same as `OSC "133;Z"` [`";err="` _exit-code_]`"\007"`
> (except that a zero _exit-code_ is equivalet to `OSC "133;Z\007"`
> without the _exit-code_).
> For backward compatibility with Iterm2/FinalTerm.
## General options syntax
......@@ -123,13 +123,18 @@ A terminal must ignore an _option_ whose _option-name_ it doesn't recognize.
> A command was cancelled before execution started, for example by
> typing ctrl-c on Unix-like systems (sending `SIGINT`) during input editing.
`exitcode=` _value_
`err=` _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.
> Specifies a string value that reports an error code from the command.
> Note that any non-empty _value_ should be displayed as an error, even 0.
> A non-error is indicated by a missing `err` option or en empty _value_.
> This generality is to support command processors that don't
> follow the standard Unix convention of 0 for success.
> For a Unix-like shells, on success (zero exit code) there should be
> no `err` option or an empty `err` option;
> on failure (non-zero exit code), _value) should be the exit code.
`click-move=` _value_
`cl=` _value_
> This option is defined for `A` or `N` commands.
......@@ -142,23 +147,23 @@ A terminal must ignore an _option_ whose _option-name_ it doesn't recognize.
> especially for beginners, who are often surprised when a mouse
> click doesn't move the cursor.
> The _value_ can be one of `line`, `multi`, `vmove`, or `vmove+`,
> The _value_ can be one of `line`, `m`, `v`, or `w`,
> specifying what kind of cursor key sequences are handled by the application.
> The value `line` allows motion within single input line, using
> using standard left/right arrow escape sequences
> (or overridden by `'move-keys`). Only a single left/right sequence
> should be emitted for double-width characters.
> The value `multi` allows movement between different lines
> The value `m` (for "multiple") allows movement between different lines
> (in the same group), but only using left/right arrow escape sequences.
> The values `vmove` or `vmove+` is like `multi` but cursor up/down should
> The values `v` or `w` is like `m` but cursor up/down should
> be used.
> Using `vmove+` specifies that that there are no spurious spaces
> Using `w` specifies that that there are no spurious spaces
> (written by the application though not typed by the user)
> at the end of the line, _and_ that the application editor handles
> "smart vertical movement". (This means that moving 2 lines up from
> character position 20, where the intermediate line is 15 characters wide
> and the destination line is 18 characters wide, ends at position 18.)
> If `vmode` is specified instead of `vmode+` then the terminal
> If `v` is specified instead of `w` then the terminal
> should be more conservative when moving between lines:
> It should move the cursor left to the start of line, then emit the needed
> up or down sequences, then move the cursor right to the clicked destination.
......@@ -171,15 +176,13 @@ A terminal must ignore an _option_ whose _option-name_ it doesn't recognize.
> The defaults are the standard arrow-key sequences: `CSI D` etc.
> (_Note:_ this is an example where allowing quoted strings would be useful.)
`repaint`
> Used before repainting the active input line(s): Clear the
> input area of data and re-use it.
`kind=` _prompt_kind_
`k=` _prompt_kind_
> Specify the kind of prompt sequence.
> Currently `right` is the only specified _prompt_kind_.
> When reflowing lines with a `right` prompt, a terminal may optionally
> adjust spacing so the `right` prompt stays at the right end of the line.
> A normal left first-line prompt has kind `i` (initial), which is the default.
> Continuation prompts have kind `c` (continuation).
> A right-aligned prompt has kind `r` (right).
> When reflowing lines with a `r` prompt, a terminal may optionally
> adjust spacing so the right prompt stays at the right end of the line.
## Input lines
......@@ -246,7 +249,7 @@ line-wrap indicators to be correct.
Many terminals re-flow long (wrapped) lines when the containing
window changes size. It is recommended that terminal should _not_
re-flow the current input area when the cursor is in the area.
The reason is that most input editors will repaing the input area
The reason is that most input editors will repaint the input area
on windows resize, and inconsistencies are possible if both
terminal and application try to re-flow, as there is no easy synchronization.
......@@ -284,6 +287,32 @@ 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`).
## Omitted-newline sequence
Both fish and zsh emit after a command finishes special strings
to deal with output that does not end with a newline.
These strings have no effect for output that (correctly) ends with a newline,
but otherwise they append a special marker, and add the missing newline.
Such "omitted-newline" sequences can be emitted before or after the
end-of-commmand sequence (`D` or `Z`), but must be emitted before
the next start-of-command seuqnec (`A` or `N`).
Note that re-flow due to making the window narrower may
cause an extra undesired blank line.
A _fresh-line_ sequence (`L`) does not have that downside, but
it doesn't have a way to specify a marker.
# Resources
## Bash
[Initialization script for bash (the Bourne-Again SHell)](./shell-integration.bash)
## DomTerm
[DomTerm](https://domterm.org) implements the latest version of this specification.
# Open Questions
See the paragraphs starting with **Issue:**.
#source /home/bothner/DomTerm/tools/bash-preexec.sh
thisfile="$BASH_SOURCE"
case "$thisfile" in
"") echo "installation error - can't find path to $0"; exit -1 ;;
/*) ;;
*) thisfile="$PWD/$thisfile" ;;
esac
while test -L "$thisfile"; do thisfile=$(readlink -f "$thisfile"); done
source `dirname "$thisfile"`/bash-preexec.sh
#PS1='\[\e]133;P\a\]'$PS1'\[\e]133;B\a\e]122;> \a\]'
#PS1='\[\e]133]A;repaint;aid='"$BASHPID"'\a\e]133;P\a\]'$PS1'\[\e]133;B\a\e]122;> \a\]'
function __prompt_precmd() {
local ret="$?"
local err=`if test "$ret" != "0"; then echo ";err=$ret"; fi`
_PROMPT_SAVE_PS1="$PS1"
_PROMPT_SAVE_PS2="$PS2"
PS1='\[\e]133;P;k=i\a\]'$PS1'\[\e]133;B\a\e]122;> \a\]'
PS2='\[\e]133;P;k=c\a\]'$PS2'\[\e]133;B\a\]'
if test "$_prompt_executing" = "1"
then
printf "\033]133;Z%s;aid=%s\007" "$err" "$BASHPID"
fi
printf "\033]133;A;cl=m;aid=%s\007" "$BASHPID"
_prompt_executing=0
}
function __prompt_preexec() {
PS1="$_PROMPT_SAVE_PS1"
PS2="$_PROMPT_SAVE_PS2"
printf "\033]133;C;\007"
_prompt_executing=1
}
preexec_functions+=(__prompt_preexec)
precmd_functions+=(__prompt_precmd)
if status --is-interactive
set _fishprompt_aid "fish"$fish_pid
set _fishprompt_started 0
# empty if running; or a numeric exit code; or CANCEL
set _fishprompt_postexec ""
functions -c fish_prompt _fishprompt_saved_prompt
set _fishprompt_prompt_count 0
set _fishprompt_disp_count 0
function _fishprompt_start --on-event fish_prompt
set _fishprompt_prompt_count (math $_fishprompt_prompt_count + 1)
# don't use post-exec, because it is called *before* omitted-newline output
if [ -n "$_fishprompt_postexec" ]
set ret (if test "$_fishprompt_postexec" != "0"; echo ";err=$_fishprompt_postexec"; end)
printf "\033]133;Z%s;aid=%s\007" "$ret" $_fishprompt_aid
end
printf "\033]133;A;aid=%s;cl=m\007" $_fishprompt_aid
end
function fish_prompt
set _fishprompt_disp_count (math $_fishprompt_disp_count + 1)
printf "\033]133;P;k=i\007%b\033]133;B\007" (string join "\n" (_fishprompt_saved_prompt))
set _fishprompt_started 1
set _fishprompt_postexec ""
end
function _fishprompt_preexec --on-event fish_preexec
if [ "$_fishprompt_started" = "1" ]
printf "\033]133;C;\007"
end
set _fishprompt_started 0
end
function _fishprompt_postexec --on-event fish_postexec
set _fishprompt_postexec $status
end
function __fishprompt_cancel --on-event fish_cancel
set _fishprompt_postexec CANCEL
_fishprompt_start
end
function _fishprompt_exit --on-process %self
if [ "$_fishprompt_started" = "1" ]
printf "\033]133;Z;aid=%s\007" $_fishprompt_aid
end
end
if functions -q fish_right_prompt
functions -c fish_right_prompt _fishprompt_saved_right_prompt
function fish_right_prompt
printf "\033]133;P;k=r\007%b\033]133;B\007" (string join "\n" (_fishprompt_saved_right_prompt))
end
end
end
#PS1='\[\e]133;P\a\]'$PS1'\[\e]133;B\a\e]122;> \a\]'
#PS1='\[\e]133]A;repaint;aid='"$BASHPID"'\a\e]133;P\a\]'$PS1'\[\e]133;B\a\e]122;> \a\]'
function __prompt_precmd() {
local ret="$?"
local err=`if test "$ret" != "0"; then echo ";err=$ret"; fi`
_PROMPT_SAVE_PS1="$PS1"
_PROMPT_SAVE_PS2="$PS2"
PS1=$'%{\e]133;P;k=i\a%}'$PS1$'%{\e]133;B\a\e]122;> \a%}'
PS2=$'%{\e]133;P;k=c\a%}'$PS2$'%{\e]133;B\a%}'
if test "$_prompt_executing" = "1"
then
printf "\033]133;Z%s;aid=%s\007" "$err" "$$"
fi
printf "\033]133;A;cl=m;aid=%s\007" "$$"
_prompt_executing=0
}
function __prompt_preexec() {
PS1="$_PROMPT_SAVE_PS1"
PS2="$_PROMPT_SAVE_PS2"
printf "\033]133;C;\007"
_prompt_executing=1
}
preexec_functions+=(__prompt_preexec)
precmd_functions+=(__prompt_precmd)
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