1 94b5e3ff 2005-01-04 devnull .TH ACMEEVENT 1
3 94b5e3ff 2005-01-04 devnull acmeevent, acme.rc \- shell script support for acme clients
4 94b5e3ff 2005-01-04 devnull .SH SYNOPSIS
7 94b5e3ff 2005-01-04 devnull .B acme/acme/$winid/event | acmeevent
10 c3674de4 2005-01-11 devnull \&. \*9/lib/acme.rc
12 94b5e3ff 2005-01-04 devnull .B newwindow
14 94b5e3ff 2005-01-04 devnull .B winread
17 94b5e3ff 2005-01-04 devnull .B winwrite
20 94b5e3ff 2005-01-04 devnull .B winctl
23 94b5e3ff 2005-01-04 devnull .B windump
25 94b5e3ff 2005-01-04 devnull .I dumpdir
30 94b5e3ff 2005-01-04 devnull .I dumpcmd
35 94b5e3ff 2005-01-04 devnull .B winname
38 94b5e3ff 2005-01-04 devnull .B windel
43 94b5e3ff 2005-01-04 devnull .B winwriteevent
52 94b5e3ff 2005-01-04 devnull .I textlen
54 94b5e3ff 2005-01-04 devnull .I chordarg
55 94b5e3ff 2005-01-04 devnull .I chordaddr
58 94b5e3ff 2005-01-04 devnull .B wineventloop
59 94b5e3ff 2005-01-04 devnull .SH DESCRIPTION
60 94b5e3ff 2005-01-04 devnull .I Acmeevent
62 94b5e3ff 2005-01-04 devnull .I acme.rc
63 94b5e3ff 2005-01-04 devnull make it easy to write simple
65 94b5e3ff 2005-01-04 devnull client programs as shell scripts.
68 94b5e3ff 2005-01-04 devnull clients read the
72 d32deab1 2020-08-16 rsc .MR acme (4) )
73 94b5e3ff 2005-01-04 devnull for the windows they control, reacting to the events.
74 94b5e3ff 2005-01-04 devnull The events are presented in a format that is easy to read with C programs
75 94b5e3ff 2005-01-04 devnull but hard to read with shell scripts.
77 94b5e3ff 2005-01-04 devnull .I Acmeevent
80 94b5e3ff 2005-01-04 devnull event stream from standard input, printing a shell-friendly
81 94b5e3ff 2005-01-04 devnull version of the events, one per line, on standard output.
82 94b5e3ff 2005-01-04 devnull Each output line from
83 94b5e3ff 2005-01-04 devnull .I acmeevent
84 94b5e3ff 2005-01-04 devnull has the form:
94 94b5e3ff 2005-01-04 devnull .I textlen
96 94b5e3ff 2005-01-04 devnull .I chordarg
97 94b5e3ff 2005-01-04 devnull .I chordaddr
99 94b5e3ff 2005-01-04 devnull The fields are:
102 94b5e3ff 2005-01-04 devnull A character indicating the origin or cause of the action.
103 94b5e3ff 2005-01-04 devnull The possible causes are:
104 94b5e3ff 2005-01-04 devnull a write to the body or tag file
105 94b5e3ff 2005-01-04 devnull .RB ( E ),
106 94b5e3ff 2005-01-04 devnull a write to the window's other files
107 94b5e3ff 2005-01-04 devnull .RB ( F ),
108 94b5e3ff 2005-01-04 devnull input via the keyboard
109 94b5e3ff 2005-01-04 devnull .RB ( K ),
111 94b5e3ff 2005-01-04 devnull input via the mouse
112 94b5e3ff 2005-01-04 devnull .RB ( M ).
115 94b5e3ff 2005-01-04 devnull A character indicating the type of action.
116 94b5e3ff 2005-01-04 devnull The possible types are:
117 94b5e3ff 2005-01-04 devnull text deleted from the body
118 94b5e3ff 2005-01-04 devnull .RB ( D ),
119 94b5e3ff 2005-01-04 devnull text deleted from the tag
120 94b5e3ff 2005-01-04 devnull .RB ( d ),
121 94b5e3ff 2005-01-04 devnull text inserted in the body
122 94b5e3ff 2005-01-04 devnull .RB ( I ),
123 94b5e3ff 2005-01-04 devnull text inserted in the tag
124 94b5e3ff 2005-01-04 devnull .RB ( i ),
125 94b5e3ff 2005-01-04 devnull a button 3 action in the body
126 94b5e3ff 2005-01-04 devnull .RB ( L ),
127 94b5e3ff 2005-01-04 devnull a button 3 action in the tag
128 94b5e3ff 2005-01-04 devnull .RB ( l ),
129 94b5e3ff 2005-01-04 devnull a button 2 action in the body
130 94b5e3ff 2005-01-04 devnull .RB ( X ),
132 94b5e3ff 2005-01-04 devnull a button 2 action in the tag
133 94b5e3ff 2005-01-04 devnull .RB ( x ).
135 c8b6342d 2005-01-13 devnull .I q0\fR, \fPq1
136 c8b6342d 2005-01-13 devnull The character addresses of the action.
138 c8b6342d 2005-01-13 devnull .I eq0\fR, \fPq1
139 c8b6342d 2005-01-13 devnull The expanded character addresses of the action.
140 c8b6342d 2005-01-13 devnull If the text indicated by
141 c8b6342d 2005-01-13 devnull .IR q0 ,
143 c8b6342d 2005-01-13 devnull is a null string that has a non-null expansion,
144 c8b6342d 2005-01-13 devnull .IR eq0 ,
146 c8b6342d 2005-01-13 devnull are the addresses of the expansion.
147 c8b6342d 2005-01-13 devnull Otherwise they are the same as
148 c8b6342d 2005-01-13 devnull .IR q0 ,
149 c8b6342d 2005-01-13 devnull .IR q1 .
153 c8b6342d 2005-01-13 devnull is a bitwise OR (reported decimally) of the following:
154 c8b6342d 2005-01-13 devnull 1 if the text indicated is recognized as an
156 c8b6342d 2005-01-13 devnull built-in command;
157 c8b6342d 2005-01-13 devnull 2 if the text indicated is a null string that has a non-null expansion
159 c8b6342d 2005-01-13 devnull .IR eq0 ,
162 c8b6342d 2005-01-13 devnull 8 if the command has an extra (chorded) argument
164 c8b6342d 2005-01-13 devnull .I chordarg
167 c8b6342d 2005-01-13 devnull remains from the
168 d32deab1 2020-08-16 rsc .MR acme (4)
169 c8b6342d 2005-01-13 devnull event format.
171 c8b6342d 2005-01-13 devnull .IR eq0 ,
172 c8b6342d 2005-01-13 devnull .IR eq1 ,
174 c8b6342d 2005-01-13 devnull .I chordarg
175 c8b6342d 2005-01-13 devnull are explicit in each event
176 c8b6342d 2005-01-13 devnull (unlike in
177 d32deab1 2020-08-16 rsc .MR acme (4)
178 c8b6342d 2005-01-13 devnull events),
180 c8b6342d 2005-01-13 devnull can usually be ignored.
182 94b5e3ff 2005-01-04 devnull .I textlen
183 c8b6342d 2005-01-13 devnull The length of the action text (or its expansion) for button 2 and button 3 events in characters.
187 c8b6342d 2005-01-13 devnull .I textlen
188 c8b6342d 2005-01-13 devnull is less than 256 chracters,
190 c8b6342d 2005-01-13 devnull is the action text itself.
191 c8b6342d 2005-01-13 devnull Otherwise it is an empty string and must be read from the
195 94b5e3ff 2005-01-04 devnull .I chordarg
196 c8b6342d 2005-01-13 devnull The chorded argument for an action.
198 94b5e3ff 2005-01-04 devnull .I chordorigin
199 c8b6342d 2005-01-13 devnull If the chord argument is in the body of a named window,
200 c8b6342d 2005-01-13 devnull .I chordorigin
201 c8b6342d 2005-01-13 devnull specifies the full address of the argument,
203 c8b6342d 2005-01-13 devnull .BR /etc/group:#123,#234 .
206 c8b6342d 2005-01-13 devnull To experiment with
207 c8b6342d 2005-01-13 devnull .IR acmeevent ,
208 c8b6342d 2005-01-13 devnull create an empty window in
211 c8b6342d 2005-01-13 devnull .IR New ), type
214 c8b6342d 2005-01-13 devnull 9p read acme/$winid/event | acmeevent
217 c8b6342d 2005-01-13 devnull inside it, and execute it.
218 c8b6342d 2005-01-13 devnull Actions performed on the window will be printed as events in the
219 c8b6342d 2005-01-13 devnull .B +Errors
222 94b5e3ff 2005-01-04 devnull .I Acme.rc
223 94b5e3ff 2005-01-04 devnull is a library of
225 94b5e3ff 2005-01-04 devnull shell functions useful for writing acme clients.
227 94b5e3ff 2005-01-04 devnull .I Newwindow
228 94b5e3ff 2005-01-04 devnull creates a new acme window and sets
229 94b5e3ff 2005-01-04 devnull .B $winid
230 94b5e3ff 2005-01-04 devnull to the new window's id.
231 94b5e3ff 2005-01-04 devnull The other commands all use
232 94b5e3ff 2005-01-04 devnull .B $winid
233 94b5e3ff 2005-01-04 devnull to determine which window to operate on.
235 94b5e3ff 2005-01-04 devnull .I Winread
236 94b5e3ff 2005-01-04 devnull prints the current window's
238 94b5e3ff 2005-01-04 devnull to standard output.
239 94b5e3ff 2005-01-04 devnull It is equivalent to
241 94b5e3ff 2005-01-04 devnull .BI /mnt/acme/acme/$winid/ file
242 94b5e3ff 2005-01-04 devnull on Plan 9.
243 94b5e3ff 2005-01-04 devnull Similarly,
244 94b5e3ff 2005-01-04 devnull .I winwrite
245 94b5e3ff 2005-01-04 devnull writes standard input to the current window's
246 94b5e3ff 2005-01-04 devnull .IR file .
247 94b5e3ff 2005-01-04 devnull .I Winread
249 94b5e3ff 2005-01-04 devnull .I winwrite
250 94b5e3ff 2005-01-04 devnull are useful mainly in building more complex functions.
252 94b5e3ff 2005-01-04 devnull .I Winctl
255 94b5e3ff 2005-01-04 devnull to the window's
258 94b5e3ff 2005-01-04 devnull The most commonly-used command is
259 94b5e3ff 2005-01-04 devnull .BR clean ,
260 94b5e3ff 2005-01-04 devnull which marks the window as clean.
262 d32deab1 2020-08-16 rsc .MR acme (4)
263 94b5e3ff 2005-01-04 devnull for a full list of commands.
265 94b5e3ff 2005-01-04 devnull .I Windump
266 94b5e3ff 2005-01-04 devnull sets the window's dump directory
267 94b5e3ff 2005-01-04 devnull and dump command
269 d32deab1 2020-08-16 rsc .MR acme (4) ).
270 94b5e3ff 2005-01-04 devnull If either argument is omitted or is
272 94b5e3ff 2005-01-04 devnull that argument is not set.
274 94b5e3ff 2005-01-04 devnull .I Winname
275 94b5e3ff 2005-01-04 devnull sets the name displayed in the window's tag.
277 94b5e3ff 2005-01-04 devnull .I Windel
278 94b5e3ff 2005-01-04 devnull simulates the
280 94b5e3ff 2005-01-04 devnull command. If the argument
282 94b5e3ff 2005-01-04 devnull is given, it simulates the
283 94b5e3ff 2005-01-04 devnull .B Delete
284 94b5e3ff 2005-01-04 devnull command.
286 94b5e3ff 2005-01-04 devnull .I Winwriteevent
287 94b5e3ff 2005-01-04 devnull writes an event to the window's event file.
288 94b5e3ff 2005-01-04 devnull The event is in the format produced by
289 94b5e3ff 2005-01-04 devnull .IR acmeevent .
290 94b5e3ff 2005-01-04 devnull Only the first four arguments are necessary:
291 94b5e3ff 2005-01-04 devnull the rest are ignored.
292 94b5e3ff 2005-01-04 devnull Event handlers should call
293 94b5e3ff 2005-01-04 devnull .I winwriteevent
294 94b5e3ff 2005-01-04 devnull to pass unhandled button 2 or button 3 events
297 94b5e3ff 2005-01-04 devnull for processing.
299 94b5e3ff 2005-01-04 devnull .I Wineventloop
300 94b5e3ff 2005-01-04 devnull executes the current window's event file, as output by
301 94b5e3ff 2005-01-04 devnull .IR acmeevent .
302 94b5e3ff 2005-01-04 devnull It returns when the window has been deleted.
303 94b5e3ff 2005-01-04 devnull Before running
304 94b5e3ff 2005-01-04 devnull .I wineventloop ,
305 94b5e3ff 2005-01-04 devnull clients must define a shell function named
306 94b5e3ff 2005-01-04 devnull .BR event ,
307 94b5e3ff 2005-01-04 devnull which will be run for each incoming event,
310 94b5e3ff 2005-01-04 devnull executes the output of
311 94b5e3ff 2005-01-04 devnull .IR acmeevent .
312 94b5e3ff 2005-01-04 devnull A typical event function need only worry about button 2 and button 3 events.
313 94b5e3ff 2005-01-04 devnull Those events not handled should be sent back to
316 94b5e3ff 2005-01-04 devnull .IR winwriteevent .
317 94b5e3ff 2005-01-04 devnull .SH EXAMPLE
318 94b5e3ff 2005-01-04 devnull .IR Adict ,
319 94b5e3ff 2005-01-04 devnull a dictionary browser,
320 94b5e3ff 2005-01-04 devnull is implemented using
321 94b5e3ff 2005-01-04 devnull .I acmeevent
323 94b5e3ff 2005-01-04 devnull .IR acme.rc .
325 94b5e3ff 2005-01-04 devnull .I event
326 94b5e3ff 2005-01-04 devnull handler is:
329 94b5e3ff 2005-01-04 devnull .ta +4n +4n +4n +4n +4n +4n
330 94b5e3ff 2005-01-04 devnull fn event {
331 94b5e3ff 2005-01-04 devnull switch($1$2){
332 94b5e3ff 2005-01-04 devnull case Mx MX # button 2 - pass back to acme
333 94b5e3ff 2005-01-04 devnull winwriteevent $*
334 94b5e3ff 2005-01-04 devnull case Ml ML # button 3 - open new window on dictionary or entry
336 94b5e3ff 2005-01-04 devnull if(~ $dict NONE)
337 94b5e3ff 2005-01-04 devnull dictwin /adict/$7/ $7
339 94b5e3ff 2005-01-04 devnull dictwin /adict/$dict/$7 $dict $7
345 94b5e3ff 2005-01-04 devnull Note that the button 3 handler starts a subshell in which to run
346 94b5e3ff 2005-01-04 devnull .IR dictwin .
347 94b5e3ff 2005-01-04 devnull That subshell will create a new window, set its name,
348 94b5e3ff 2005-01-04 devnull possibly fill the window with a dictionary list or dictionary entry,
349 94b5e3ff 2005-01-04 devnull mark the window as clean, and run the event loop:
352 94b5e3ff 2005-01-04 devnull fn dictwin {
353 94b5e3ff 2005-01-04 devnull newwindow
354 94b5e3ff 2005-01-04 devnull winname $1
356 94b5e3ff 2005-01-04 devnull if(~ $dict NONE)
357 94b5e3ff 2005-01-04 devnull dict -d '?' >[2=1] | sed 1d | winwrite body
358 94b5e3ff 2005-01-04 devnull if(~ $#* 3)
359 94b5e3ff 2005-01-04 devnull dict -d $dict $3 >[2=1] | winwrite body
360 94b5e3ff 2005-01-04 devnull winctl clean
361 94b5e3ff 2005-01-04 devnull wineventloop
365 94b5e3ff 2005-01-04 devnull The script starts with an initial window:
368 94b5e3ff 2005-01-04 devnull dictwin /adict/ NONE
371 94b5e3ff 2005-01-04 devnull Button 3 clicking on a dictionary name in the initial window
372 94b5e3ff 2005-01-04 devnull will create a new empty window for that dictionary.
373 94b5e3ff 2005-01-04 devnull Typing and button 3 clicking on a word in that window
374 94b5e3ff 2005-01-04 devnull will create a new window with the dictionary's entry for that word.
377 c3674de4 2005-01-11 devnull .B \*9/bin/adict
378 94b5e3ff 2005-01-04 devnull for the full implementation.
379 94b5e3ff 2005-01-04 devnull .SH SOURCE
380 c3674de4 2005-01-11 devnull .B \*9/src/cmd/acmeevent.c
382 c3674de4 2005-01-11 devnull .B \*9/lib/acme.rc
383 94b5e3ff 2005-01-04 devnull .SH SEE ALSO
384 d32deab1 2020-08-16 rsc .MR acme (1) ,
385 d32deab1 2020-08-16 rsc .MR acme (4) ,
387 94b5e3ff 2005-01-04 devnull .SH BUGS
388 94b5e3ff 2005-01-04 devnull There is more that could be done to ease the writing
389 94b5e3ff 2005-01-04 devnull of complicated clients.
