doc/ref/chap-plugin.md

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

154 lines, 88 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	<!--
96	<h3 id="PS1">PS1</h3>
97	-->
98
99	### PS1
100
101	First line of the shell prompt.
102
103	### PS2
104
105	Second line of the shell prompt (unimplemented).
106
107	### PS3
108
109	For the `select` builtin (unimplemented).
110
111	### PS4
112
113	The prefix of each line of output in `set -x` aka `set -o xtrace`. The leading
114	character is special.
115
116	## Completion
117
118	### complete
119
120	The [complete][] builtin calls back into the shell evaluator to create
121	candidate strings for autocompletion:
122
123	- `-C` is an external command that's executed
124	- `-F` is the name of a shell function name that's run
125	- `-W` is a word list that's evalutaed
126
127	[complete]: chap-builtin-cmd.html#complete
128
129	## Other Plugin
130
131	### PROMPT_COMMAND
132
133	A command that's executed before each prompt.
134
135	This feature is taken from [bash]($xref).
136
137	## YSH
138
139	### renderPrompt()
140
141	Users may define this func to customize their prompt.
142
143	The func should take the global `value.IO` instance, and return a prompt string
144	(type `value.Str`).
145
146	To construct the prompt, it can make calls like
147	[`io->promptVal('$')`]($chap-type-method:promptVal).
148
149	To render the prompt, YSH first checks if this function exists. Otherwise, it
150	uses [`$PS1`]($chap-plugin:PS1) with a `ysh` prefix.
151
152	<!-- note: doctools/cmark.py turns promptVal -> promptval -->
153
154