doc/ref/chap-plugin.md

OILS / doc / ref / chap-plugin.md View on Github | oils.pub

157 lines, 90 significant

1	---
2	title: Plugins and Hooks (Oils Reference)
3	all_docs_url: ..
4	body_css_class: width40
5	default_highlighter: oils-sh
6	preserve_anchor_case: yes
7	---
8
9	<div class="doc-ref-header">
10
11	[Oils Reference](index.html) —
12	Chapter Plugins and Hooks
13
14	</div>
15
16	This chapter describes extension points for OSH and YSH.
17
18	<span class="in-progress">(in progress)</span>
19
20	<div id="dense-toc">
21	</div>
22
23	## Signals
24
25	### SIGTERM
26
27	SIGTERM is the default signal sent by `kill`. It asks a process to terminate.
28
29	You can register a SIGTERM handler with the [trap][] builtin.
30
31	[trap]: chap-builtin-cmd.html#trap
32
33	### SIGINT
34
35	SIGINT is usually generated by Ctrl-C. It interrupts what the shell is doing
36	and returns to the prompt.
37
38	You can register a SIGINT handler with the [trap][] builtin.
39
40	### SIGQUIT
41
42	SIGQUIT is usually generated by Ctrl-\.
43
44	### SIGTTIN
45
46	Used by the job control implementation.
47
48	### SIGTTOU
49
50	Used by the job control implementation.
51
52	### SIGWINCH
53
54	Oils receives this signal when the terminal window size changes.
55
56	## Traps
57
58	### DEBUG
59
60	Runs code before "leaf" commands, like
61
62	echo hi
63	a=b
64	[[ x -eq y ]]
65	(( a = 42 ))
66
67	But not before `{`:
68
69	{ echo one; echo two; }
70
71	---
72
73	See the [Quirks doc](../quirks.html) for an interaction between the `DEBUG`
74	trap, pipelines, and interactive shells.
75
76	### ERR
77
78	The `ERR` trap runs when a command fails, i.e. in the situations where `set -o
79	errexit` aka `set -e` exits the shell.
80
81	To enable it in functions and subshells, use `set -o errtrace`, aka `set -E`.
82
83	It's designed to be compatible with bash.
84
85	### EXIT
86
87	TODO
88
89	### RETURN
90
91	TODO
92
93	## Words
94
95	### PS1
96
97	The `PS1` variable controls the first line of the shell prompt. It is designed
98	to be bash-compatible.
99
100	See the [Bash Manual > Controlling the Prompt][bash-prompt].
101
102	[bash-prompt]: https://www.gnu.org/software/bash/manual/html_node/Controlling-the-Prompt.html
103
104	Note that the general `\D{format}` is implemented, but some of the more
105	specific time formats are not implemented.
106
107	### PS2
108
109	Second line of the shell prompt (unimplemented).
110
111	### PS3
112
113	For the `select` builtin (unimplemented).
114
115	### PS4
116
117	The prefix of each line of output in `set -x` aka `set -o xtrace`. The leading
118	character is special.
119
120	## Completion
121
122	### complete
123
124	The [complete][] builtin calls back into the shell evaluator to create
125	candidate strings for autocompletion:
126
127	- `-C` is an external command that's executed
128	- `-F` is the name of a shell function name that's run
129	- `-W` is a word list that's evalutaed
130
131	[complete]: chap-builtin-cmd.html#complete
132
133	## Other Plugin
134
135	### PROMPT_COMMAND
136
137	A command that's executed before each prompt.
138
139	This feature is taken from [bash]($xref).
140
141	## YSH
142
143	### renderPrompt()
144
145	Users may define this func to customize their prompt.
146
147	The func should take the global `value.IO` instance, and return a prompt string
148	(type `value.Str`).
149
150	To construct the prompt, it can make calls like
151	[`io->promptVal('$')`]($chap-type-method:promptVal).
152
153	To render the prompt, YSH first checks if this function exists. Otherwise, it
154	uses [`$PS1`]($chap-plugin:PS1) with a `ysh` prefix.
155
156	<!-- note: doctools/cmark.py turns promptVal -> promptval -->
157