acmeevent.1 (6729B)
1 .TH ACMEEVENT 1 2 .SH NAME 3 acmeevent, acme.rc \- shell script support for acme clients 4 .SH SYNOPSIS 5 .B 9p 6 .B read 7 .B acme/acme/$winid/event | acmeevent 8 .PP 9 .B 10 \&. \*9/lib/acme.rc 11 .PP 12 .B newwindow 13 .PP 14 .B winread 15 .I file 16 .PP 17 .B winwrite 18 .I file 19 .PP 20 .B winctl 21 .I cmd 22 .PP 23 .B windump 24 [ 25 .I dumpdir 26 | 27 .B - 28 ] 29 [ 30 .I dumpcmd 31 | 32 .B - 33 ] 34 .PP 35 .B winname 36 .I name 37 .PP 38 .B windel 39 [ 40 .B sure 41 ] 42 .PP 43 .B winwriteevent 44 .I c1 45 .I c2 46 .I q0 47 .I q1 48 [ 49 .I eq0 50 .I eq1 51 .I flag 52 .I textlen 53 .I text 54 .I chordarg 55 .I chordaddr 56 ] 57 .PP 58 .B wineventloop 59 .SH DESCRIPTION 60 .I Acmeevent 61 and 62 .I acme.rc 63 make it easy to write simple 64 .MR acme (1) 65 client programs as shell scripts. 66 .PP 67 .I Acme 68 clients read the 69 .B event 70 files 71 (see 72 .MR acme (4) ) 73 for the windows they control, reacting to the events. 74 The events are presented in a format that is easy to read with C programs 75 but hard to read with shell scripts. 76 .PP 77 .I Acmeevent 78 reads an 79 .MR acme (4) 80 event stream from standard input, printing a shell-friendly 81 version of the events, one per line, on standard output. 82 Each output line from 83 .I acmeevent 84 has the form: 85 .IP 86 .B event 87 .I c1 88 .I c2 89 .I q0 90 .I q1 91 .I eq0 92 .I eq1 93 .I flag 94 .I textlen 95 .I text 96 .I chordarg 97 .I chordaddr 98 .PP 99 The fields are: 100 .TP 101 .I c1 102 A character indicating the origin or cause of the action. 103 The possible causes are: 104 a write to the body or tag file 105 .RB ( E ), 106 a write to the window's other files 107 .RB ( F ), 108 input via the keyboard 109 .RB ( K ), 110 and 111 input via the mouse 112 .RB ( M ). 113 .TP 114 .I c2 115 A character indicating the type of action. 116 The possible types are: 117 text deleted from the body 118 .RB ( D ), 119 text deleted from the tag 120 .RB ( d ), 121 text inserted in the body 122 .RB ( I ), 123 text inserted in the tag 124 .RB ( i ), 125 a button 3 action in the body 126 .RB ( L ), 127 a button 3 action in the tag 128 .RB ( l ), 129 a button 2 action in the body 130 .RB ( X ), 131 and 132 a button 2 action in the tag 133 .RB ( x ). 134 .TP 135 .I q0\fR, \fPq1 136 The character addresses of the action. 137 .TP 138 .I eq0\fR, \fPq1 139 The expanded character addresses of the action. 140 If the text indicated by 141 .IR q0 , 142 .I q1 143 is a null string that has a non-null expansion, 144 .IR eq0 , 145 .I eq1 146 are the addresses of the expansion. 147 Otherwise they are the same as 148 .IR q0 , 149 .IR q1 . 150 .TP 151 .I flag 152 .I Flag 153 is a bitwise OR (reported decimally) of the following: 154 1 if the text indicated is recognized as an 155 .I acme 156 built-in command; 157 2 if the text indicated is a null string that has a non-null expansion 158 (see 159 .IR eq0 , 160 .I eq1 161 above); 162 8 if the command has an extra (chorded) argument 163 (see 164 .I chordarg 165 below). 166 .I Flag 167 remains from the 168 .MR acme (4) 169 event format. 170 Because 171 .IR eq0 , 172 .IR eq1 , 173 and 174 .I chordarg 175 are explicit in each event 176 (unlike in 177 .MR acme (4) 178 events), 179 .I flag 180 can usually be ignored. 181 .TP 182 .I textlen 183 The length of the action text (or its expansion) for button 2 and button 3 events in characters. 184 .TP 185 .I text 186 If 187 .I textlen 188 is less than 256 chracters, 189 .I text 190 is the action text itself. 191 Otherwise it is an empty string and must be read from the 192 .B data 193 file. 194 .TP 195 .I chordarg 196 The chorded argument for an action. 197 .TP 198 .I chordorigin 199 If the chord argument is in the body of a named window, 200 .I chordorigin 201 specifies the full address of the argument, 202 as in 203 .BR /etc/group:#123,#234 . 204 .PD 205 .PP 206 To experiment with 207 .IR acmeevent , 208 create an empty window in 209 .I acme 210 (using 211 .IR New ), type 212 .IP 213 .EX 214 9p read acme/$winid/event | acmeevent 215 .EE 216 .LP 217 inside it, and execute it. 218 Actions performed on the window will be printed as events in the 219 .B +Errors 220 window. 221 .PP 222 .I Acme.rc 223 is a library of 224 .MR rc (1) 225 shell functions useful for writing acme clients. 226 .PP 227 .I Newwindow 228 creates a new acme window and sets 229 .B $winid 230 to the new window's id. 231 The other commands all use 232 .B $winid 233 to determine which window to operate on. 234 .PP 235 .I Winread 236 prints the current window's 237 .I file 238 to standard output. 239 It is equivalent to 240 .B cat 241 .BI /mnt/acme/acme/$winid/ file 242 on Plan 9. 243 Similarly, 244 .I winwrite 245 writes standard input to the current window's 246 .IR file . 247 .I Winread 248 and 249 .I winwrite 250 are useful mainly in building more complex functions. 251 .PP 252 .I Winctl 253 writes 254 .I cmd 255 to the window's 256 .B ctl 257 file. 258 The most commonly-used command is 259 .BR clean , 260 which marks the window as clean. 261 See 262 .MR acme (4) 263 for a full list of commands. 264 .PP 265 .I Windump 266 sets the window's dump directory 267 and dump command 268 (see 269 .MR acme (4) ). 270 If either argument is omitted or is 271 .BR - , 272 that argument is not set. 273 .PP 274 .I Winname 275 sets the name displayed in the window's tag. 276 .PP 277 .I Windel 278 simulates the 279 .B Del 280 command. If the argument 281 .B sure 282 is given, it simulates the 283 .B Delete 284 command. 285 .PP 286 .I Winwriteevent 287 writes an event to the window's event file. 288 The event is in the format produced by 289 .IR acmeevent . 290 Only the first four arguments are necessary: 291 the rest are ignored. 292 Event handlers should call 293 .I winwriteevent 294 to pass unhandled button 2 or button 3 events 295 back to 296 .I acme 297 for processing. 298 .PP 299 .I Wineventloop 300 executes the current window's event file, as output by 301 .IR acmeevent . 302 It returns when the window has been deleted. 303 Before running 304 .I wineventloop , 305 clients must define a shell function named 306 .BR event , 307 which will be run for each incoming event, 308 as 309 .I rc 310 executes the output of 311 .IR acmeevent . 312 A typical event function need only worry about button 2 and button 3 events. 313 Those events not handled should be sent back to 314 .I acme 315 with 316 .IR winwriteevent . 317 .SH EXAMPLE 318 .IR Adict , 319 a dictionary browser, 320 is implemented using 321 .I acmeevent 322 and 323 .IR acme.rc . 324 The 325 .I event 326 handler is: 327 .IP 328 .EX 329 .ta +4n +4n +4n +4n +4n +4n 330 fn event { 331 switch($1$2){ 332 case Mx MX # button 2 - pass back to acme 333 winwriteevent $* 334 case Ml ML # button 3 - open new window on dictionary or entry 335 { 336 if(~ $dict NONE) 337 dictwin /adict/$7/ $7 338 if not 339 dictwin /adict/$dict/$7 $dict $7 340 } & 341 } 342 } 343 .EE 344 .LP 345 Note that the button 3 handler starts a subshell in which to run 346 .IR dictwin . 347 That subshell will create a new window, set its name, 348 possibly fill the window with a dictionary list or dictionary entry, 349 mark the window as clean, and run the event loop: 350 .IP 351 .EX 352 fn dictwin { 353 newwindow 354 winname $1 355 dict=$2 356 if(~ $dict NONE) 357 dict -d '?' >[2=1] | sed 1d | winwrite body 358 if(~ $#* 3) 359 dict -d $dict $3 >[2=1] | winwrite body 360 winctl clean 361 wineventloop 362 } 363 .EE 364 .LP 365 The script starts with an initial window: 366 .IP 367 .EX 368 dictwin /adict/ NONE 369 .EE 370 .LP 371 Button 3 clicking on a dictionary name in the initial window 372 will create a new empty window for that dictionary. 373 Typing and button 3 clicking on a word in that window 374 will create a new window with the dictionary's entry for that word. 375 .PP 376 See 377 .B \*9/bin/adict 378 for the full implementation. 379 .SH SOURCE 380 .B \*9/src/cmd/acmeevent.c 381 .br 382 .B \*9/lib/acme.rc 383 .SH SEE ALSO 384 .MR acme (1) , 385 .MR acme (4) , 386 .MR rc (1) 387 .SH BUGS 388 There is more that could be done to ease the writing 389 of complicated clients.