3 acme \- control files for text windows
28 The text window system
30 serves a variety of files for reading, writing, and controlling
32 Some of them are virtual versions of system files for dealing
33 with the virtual console; others control operations
37 When a command is run under
39 a directory holding these files is mounted on
45 the files mentioned here
46 appear in both those directories.
48 Some of these files supply virtual versions of services available from the underlying
49 environment, in particular the character terminal files
55 sees the same set of files; there is not a distinct
58 Other files are unique to
62 is a subdirectory used by
66 as a mount point for the
68 files associated with the window in which
71 It has no specific function under
76 is the standard and diagnostic output file for all commands
79 (Input for commands is redirected to
83 appears in a window labeled
87 is the directory in which the command
89 The window is created if necessary, but not until text is actually written.
92 is an empty unwritable file present only for compatibility; there is no way
93 to turn off `echo', for example, under
97 holds a sequence of lines of text, one per window. Each line has 5 decimal numbers,
98 each formatted in 11 characters plus a blank\(emthe window ID;
99 number of characters (runes) in the tag;
100 number of characters in the body;
101 a 1 if the window is a directory, 0 otherwise;
102 and a 1 if the window is modified, 0
103 otherwise\(emfollowed by the tag up to a newline if present.
104 Thus at character position 5×12 starts the name of the window.
105 If a file has multiple zeroxed windows open,
106 only the most recently used will appear in the
111 is an empty file, writable without effect, present only for compatibility with
115 reports a log of window operations since the opening of the
118 Each line describes a single operation using three fields separated by single spaces:
119 the decimal window ID, the operation, and the window name.
122 blocks until there is an operation to report, so reading the file
123 can be used to monitor editor activity and react to changes.
124 The reported operations are
128 (window creation via zerox),
132 (window deletion), and
134 (window focus change).
135 The window name can be the empty string; in particular it is empty in
137 log entries corresponding to windows created by external programs.
140 is a directory analogous to the numbered directories
145 creates a new window. Thus to cause text to appear in a new window,
148 For more control, open
150 and use the interface described below.
155 window has associated a directory numbered by its ID.
156 Window IDs are chosen sequentially and may be discovered by the
162 indirectly through the
164 file. The files in the numbered directories are as follows.
167 may be written with any textual address (line number, regular expression, etc.),
168 in the format understood by button 3 but without the initial colon, including compound addresses,
169 to set the address for text accessed through the
172 When read, it returns the value of the address that would next be read
173 or written through the
175 file, formatted as 2 decimal numbers
179 each formatted in 11 characters plus a blank.
183 are the character (not byte) offsets of the
184 beginning and end of the address,
185 which would be expressed in
189 Thus a regular expression may be evaluated by writing it to
194 address has no effect on the user's selection of text.
197 holds contents of the window body. It may be read at any byte offset.
200 is always appended; the file offset is ignored.
203 may be read to recover the five numbers as held in the
205 file, described above, plus three more fields: the width of the
206 window in pixels, the name of the font used in the window,
207 and the width of a tab character in pixels.
208 Text messages may be written to
210 to affect the window.
211 Each message is terminated by a newline and multiple
212 messages may be sent in a single write.
219 address to that of the user's selected text in the window.
222 Mark the window clean as though it has just been written.
225 Mark the window dirty, the opposite of clean.
228 Remove all text in the tag after the vertical bar.
241 Set the user's selected text in the window to the text addressed by the
246 Set the command string to recreate the window from a dump file.
248 .BI dumpdir " directory
249 Set the directory in which to run the command to recreate the window from a dump file.
254 interactive command with no arguments; accepts no arguments.
259 file is first opened, regular expression context searches in
261 addresses examine the whole file; this message restricts subsequent
262 searches to the current
269 returning the window to the usual state wherein each modification to the
270 body must be undone individually.
278 in the left half of the tag.
279 (This is the default for file windows.)
282 Set the name of the window to
286 Turn off automatic `marking' of changes, so a set of related changes
287 may be undone in a single
297 in the left half of the tag.
298 (This is the default for directory and error windows.)
301 Turn off automatic `scrolling' of the window to show text written to the body.
306 interactive command with no arguments; accepts no arguments.
309 Turn off tracking the `dirty' status, the window stays clean.
314 message, returning the window to the default state wherein each write
317 file causes the window to `scroll' to display the new text.
320 Guarantee at least some of the selected text is visible on the display.
325 is used in conjunction with
327 for random access to the contents of the body.
328 The file offset is ignored when writing the
330 file; instead the location of the data to be read or written is determined by the state of the
333 Text, which must contain only whole characters (no `partial runes'),
336 replaces the characters addressed by the
338 file and sets the address to the null string at the end of the written text.
341 returns as many whole characters as the read count will permit starting
342 at the beginning of the
344 address (the end of the address has no effect)
345 and sets the address to the null string at the end of the returned
351 file appends to the body of the
355 is the directory currently named in the tag.
356 The window is created if necessary,
357 but not until text is actually written.
362 file is open, changes to the window occur as always but the
363 actions are also reported as
364 messages to the reader of the file. Also, user actions with buttons 2 and 3
369 which behave normally) have no immediate effect on the window;
370 it is expected that the program reading the
372 file will interpret them.
373 The messages have a fixed format:
374 a character indicating the origin or cause of the action,
375 a character indicating the type of the action,
376 four free-format blank-terminated decimal numbers,
377 optional text, and a newline.
378 The first and second numbers are the character addresses of the action,
380 and the final is a count of the characters in the optional text, which
381 may itself contain newlines.
382 The origin characters are
390 for actions through the window's other files,
392 for the keyboard, and
395 The type characters are
397 for text deleted from the body,
399 for text deleted from the tag,
401 for text inserted to the body,
403 for text inserted to the tag,
405 for a button 3 action in the body,
407 for a button 3 action in the tag,
409 for a button 2 action in the body, and
411 for a button 2 action in the tag.
413 If the relevant text has less than 256 characters, it is included in the message;
414 otherwise it is elided, the fourth number is 0, and the program must read
417 file if needed. No text is sent on a
429 the flag is always zero.
434 the flag is a bitwise OR (reported decimally) of the following:
435 1 if the text indicated is recognized as an
438 2 if the text indicated is a null string that has a non-null expansion;
439 if so, another complete message will follow describing the expansion
440 exactly as if it had been indicated explicitly (its flag will always be 0);
441 8 if the command has an extra (chorded) argument; if so,
442 two more complete messages will follow reporting the argument (with
443 all numbers 0 except the character count) and where it originated, in the form of
444 a fully-qualified button 3 style address.
450 the flag is the bitwise OR of the following:
453 can interpret the action without loading a new file;
454 2 if a second (post-expansion) message follows, analogous to that with
457 4 if the text is a file or window name (perhaps with address) rather than
460 For messages with the 1 bit on in the flag,
461 writing the message back to the
463 file, but with the flag, count, and text omitted,
464 will cause the action to be applied to the file exactly as it would
467 file had not been open.
470 holds contents of the window tag. It may be read at any byte offset.
473 is always appended; the file offset is ignored.
476 holds the contents of the current selection. It may be read at any byte offset.
481 file modifies the text in the selection. Text written always
482 replaces the text selected; the file offset is ignored.
489 except that reads stop at the end address.
projects / plan9front.git / blob