acme.4 (10601B)
1 .TH ACME 4 2 .SH NAME 3 acme \- control files for text windows 4 .SH SYNOPSIS 5 .B acme 6 [ 7 .B -f 8 .I varfont 9 ] [ 10 .B -F 11 .I fixfont 12 ] 13 [ 14 .I file 15 \&... ] 16 .SH DESCRIPTION 17 The text window system 18 .MR acme (1) 19 serves a variety of files for reading, writing, and controlling 20 windows. 21 Some of them are virtual versions of system files for dealing 22 with the virtual console; others control operations 23 of 24 .I acme 25 itself. 26 When a command is run under 27 .IR acme , 28 a directory holding these files is posted as the 9P service 29 .B acme 30 (using 31 .MR 9pserve (4) ). 32 .PP 33 Some of these files supply virtual versions of services available from the underlying 34 environment, in particular the character terminal files in Plan 9's 35 .IR cons (3). 36 (Unlike in Plan 9's 37 .IR rio (1), 38 each command under 39 .I acme 40 sees the same set of files; there is not a distinct 41 .B /dev/cons 42 for each window.) 43 Other files are unique to 44 .IR acme . 45 .TP 46 .B acme 47 is a subdirectory used by 48 .B win 49 (see 50 .MR acme (1) ) 51 as a mount point for the 52 .I acme 53 files associated with the window in which 54 .B win 55 is running. 56 It has no specific function under 57 .I acme 58 itself. 59 .TP 60 .B cons 61 is the standard and diagnostic output file for all commands 62 run under 63 .IR acme . 64 (Input for commands is redirected to 65 .BR /dev/null .) 66 Text written to 67 .B cons 68 appears in a window labeled 69 .IB dir /+Errors\f1, 70 where 71 .I dir 72 is the directory in which the command 73 was run. 74 The window is created if necessary, but not until text is actually written. 75 .TP 76 .B consctl 77 is an empty unwritable file present only for compatibility; there is no way 78 to turn off `echo', for example, under 79 .IR acme . 80 .TP 81 .B index 82 holds a sequence of lines of text, one per window. Each line has 5 decimal numbers, 83 each formatted in 11 characters plus a blank\(emthe window ID; 84 number of characters (runes) in the tag; 85 number of characters in the body; 86 a 1 if the window is a directory, 0 otherwise; 87 and a 1 if the window is modified, 0 88 otherwise\(emfollowed by the tag up to a newline if present. 89 Thus at character position 5×12 starts the name of the window. 90 If a file has multiple zeroxed windows open, 91 only the most recently used will appear in the 92 .B index 93 file. 94 .TP 95 .B label 96 is an empty file, writable without effect, present only for compatibility with 97 .BR rio . 98 .TP 99 .B log 100 reports a log of window operations since the opening of the 101 .B log 102 file. 103 Each line describes a single operation using three fields separated by single spaces: 104 the decimal window ID, the operation, and the window name. 105 Reading from 106 .B log 107 blocks until there is an operation to report, so reading the file 108 can be used to monitor editor activity and react to changes. 109 The reported operations are 110 .L new 111 (window creation), 112 .L zerox 113 (window creation via zerox), 114 .LR get , 115 .LR put , 116 and 117 .LR del 118 (window deletion). 119 The window name can be the empty string; in particular it is empty in 120 .L new 121 log entries corresponding to windows created by external programs. 122 .TP 123 .B new 124 is a directory analogous to the numbered directories 125 .RI ( q.v. ). 126 Accessing any 127 file in 128 .B new 129 creates a new window. Thus to cause text to appear in a new window, 130 write it to 131 .BR /dev/new/body . 132 For more control, open 133 .BR /dev/new/ctl 134 and use the interface described below. 135 .LP 136 .PP 137 Each 138 .I acme 139 window has associated a directory numbered by its ID. 140 Window IDs are chosen sequentially and may be discovered by the 141 .B ID 142 command, by 143 reading the 144 .B ctl 145 file, or 146 indirectly through the 147 .B index 148 file. The files in the numbered directories are as follows. 149 .TP 150 .B addr 151 may be written with any textual address (line number, regular expression, etc.), 152 in the format understood by button 3 but without the initial colon, including compound addresses, 153 to set the address for text accessed through the 154 .B data 155 file. 156 When read, it returns the value of the address that would next be read 157 or written through the 158 .B data 159 file, in the format 160 .BI # m ,# n 161 where 162 .I m 163 and 164 .I n 165 are character (not byte) offsets. If 166 .I m 167 and 168 .I n 169 are identical, the format is just 170 .BI # m\f1. 171 Thus a regular expression may be evaluated by writing it to 172 .B addr 173 and reading it back. 174 The 175 .B addr 176 address has no effect on the user's selection of text. 177 .TP 178 .B body 179 holds contents of the window body. It may be read at any byte offset. 180 Text written to 181 .B body 182 is always appended; the file offset is ignored. 183 .TP 184 .B ctl 185 may be read to recover the five numbers as held in the 186 .B index 187 file, described above, plus five more fields: the width of the 188 window in pixels; the name of the font used in the window; 189 the width of a tab character in pixels; a 1 if there is undo history, 0 otherwise; 190 a 1 if there is redo history, 0 otherwise. 191 Text messages may be written to 192 .B ctl 193 to affect the window. 194 Each message is terminated by a newline and multiple 195 messages may be sent in a single write. 196 .RS .5i 197 .TF limit=addr 198 .TP 199 .B addr=dot 200 Set the 201 .B addr 202 address to that of the user's selected text in the window. 203 .TP 204 .B clean 205 Mark the window clean as though it has just been written. 206 .TP 207 .B dirty 208 Mark the window dirty, the opposite of clean. 209 .TP 210 .B cleartag 211 Remove all text in the tag after the vertical bar. 212 .TP 213 .B del 214 Equivalent to the 215 .B Del 216 interactive command. 217 .TP 218 .B delete 219 Equivalent to the 220 .B Delete 221 interactive command. 222 .TP 223 .B dot=addr 224 Set the user's selected text in the window to the text addressed by the 225 .B addr 226 address. 227 .TP 228 .BI dump " command 229 Set the command string to recreate the window from a dump file. 230 .TP 231 .BI dumpdir " directory 232 Set the directory in which to run the command to recreate the window from a dump file. 233 .TP 234 .B get 235 Equivalent to the 236 .B Get 237 interactive command with no arguments; accepts no arguments. 238 .TP 239 .BI font " path 240 Equivalent to the 241 .B Font 242 interactive command with a single (required) argument. 243 .TP 244 .B limit=addr 245 When the 246 .B ctl 247 file is first opened, regular expression context searches in 248 .B addr 249 addresses examine the whole file; this message restricts subsequent 250 searches to the current 251 .B addr 252 address. 253 .TP 254 .B mark 255 Cancel 256 .BR nomark , 257 returning the window to the usual state wherein each modification to the 258 body must be undone individually. 259 .TP 260 .BI name " name 261 Set the name of the window to 262 .IR name . 263 .TP 264 .B nomark 265 Turn off automatic `marking' of changes, so a set of related changes 266 may be undone in a single 267 .B Undo 268 interactive command. 269 .TP 270 .B put 271 Equivalent to the 272 .B Put 273 interactive command with no arguments; accepts no arguments. 274 .TP 275 .B show 276 Guarantee at least some of the selected text is visible on the display. 277 .RE 278 .PD 279 .TP 280 .B data 281 is used in conjunction with 282 .B addr 283 for random access to the contents of the body. 284 The file offset is ignored when writing the 285 .B data 286 file; instead the location of the data to be read or written is determined by the state of the 287 .B addr 288 file. 289 Text, which must contain only whole characters (no `partial runes'), 290 written to 291 .B data 292 replaces the characters addressed by the 293 .B addr 294 file and sets the address to the null string at the end of the written text. 295 A read from 296 .B data 297 returns as many whole characters as the read count will permit starting 298 at the beginning of the 299 .B addr 300 address (the end of the address has no effect) 301 and sets the address to the null string at the end of the returned 302 characters. 303 .TP 304 .B errors 305 Writing to the 306 .B errors 307 file appends to the body of the 308 .IB dir /+Errors 309 window, where 310 .I dir 311 is the directory currently named in the tag. 312 The window is created if necessary, 313 but not until text is actually written. 314 .TP 315 .B event 316 When a window's 317 .B event 318 file is open, changes to the window occur as always but the 319 actions are also reported as 320 messages to the reader of the file. Also, user actions with buttons 2 and 3 321 (other than chorded 322 .B Cut 323 and 324 .BR Paste , 325 which behave normally) have no immediate effect on the window; 326 it is expected that the program reading the 327 .B event 328 file will interpret them. 329 The messages have a fixed format: 330 a character indicating the origin or cause of the action, 331 a character indicating the type of the action, 332 four free-format blank-terminated decimal numbers, 333 optional text, and a newline. 334 The first and second numbers are the character addresses of the action, 335 the third is a flag, 336 and the final is a count of the characters in the optional text, which 337 may itself contain newlines. 338 The origin characters are 339 .B E 340 for writes to the 341 .B body 342 or 343 .B tag 344 file, 345 .B F 346 for actions through the window's other files, 347 .B K 348 for the keyboard, and 349 .B M 350 for the mouse. 351 The type characters are 352 .B D 353 for text deleted from the body, 354 .B d 355 for text deleted from the tag, 356 .B I 357 for text inserted to the body, 358 .B i 359 for text inserted to the tag, 360 .B L 361 for a button 3 action in the body, 362 .B l 363 for a button 3 action in the tag, 364 .B R 365 for a shifted button 3 action in the body, 366 .B r 367 for a shifted button 3 action in the tag, 368 .B X 369 for a button 2 action in the body, and 370 .B x 371 for a button 2 action in the tag. 372 .IP 373 If the relevant text has less than 256 characters, it is included in the message; 374 otherwise it is elided, the fourth number is 0, and the program must read 375 it from the 376 .B data 377 file if needed. No text is sent on a 378 .B D 379 or 380 .B d 381 message. 382 .IP 383 For 384 .BR D , 385 .BR d , 386 .BR I , 387 and 388 .BR i 389 the flag is always zero. 390 For 391 .BR X 392 and 393 .BR x , 394 the flag is a bitwise OR (reported decimally) of the following: 395 1 if the text indicated is recognized as an 396 .I acme 397 built-in command; 398 2 if the text indicated is a null string that has a non-null expansion; 399 if so, another complete message will follow describing the expansion 400 exactly as if it had been indicated explicitly (its flag will always be 0); 401 8 if the command has an extra (chorded) argument; if so, 402 two more complete messages will follow reporting the argument (with 403 all numbers 0 except the character count) and where it originated, in the form of 404 a fully-qualified button 3 style address. 405 .IP 406 For 407 .B L 408 and 409 .BR l , 410 the flag is the bitwise OR of the following: 411 1 if 412 .I acme 413 can interpret the action without loading a new file; 414 2 if a second (post-expansion) message follows, analogous to that with 415 .B X 416 messages; 417 4 if the text is a file or window name (perhaps with address) rather than 418 plain literal text. 419 .IP 420 For messages with the 1 bit on in the flag, 421 writing the message back to the 422 .B event 423 file, but with the flag, count, and text omitted, 424 will cause the action to be applied to the file exactly as it would 425 have been if the 426 .B event 427 file had not been open. 428 .TP 429 .B tag 430 holds contents of the window tag. It may be read at any byte offset. 431 Text written to 432 .B tag 433 is always appended; the file offset is ignored. 434 .TP 435 .B xdata 436 The 437 .B xdata 438 file like 439 .B data 440 except that reads stop at the end address. 441 .SH SOURCE 442 .B \*9/src/cmd/acme 443 .SH SEE ALSO 444 .MR rio (1) , 445 .MR acme (1)