4 sam, B, sam.save \- screen editor with structural regular expressions
26 is a multi-file editor.
27 It modifies a local copy of an external file.
28 The copy is here called a
30 The files are listed in a menu available through mouse button 3
34 Each file has an associated name, usually the name of the
35 external file from which it was read, and a `modified' bit that indicates whether
36 the editor's file agrees with the external file.
37 The external file is not read into
38 the editor's file until it first becomes the current file\(emthat to
39 which editing commands apply\(emwhereupon its menu entry is printed.
44 Do not `download' the terminal part of
46 Editing will be done with the command language only, as in
50 Run the host part remotely
51 on the specified machine, the terminal part locally.
54 Start the host part from the specified file on the remote host.
55 Only meaningful with the
60 Start the terminal part from the specified file. Useful
63 .SS Regular expressions
64 Regular expressions are as in
68 to represent newlines.
69 A regular expression may never contain a literal newline character.
71 regular expression stands for the last complete expression encountered.
72 A regular expression in
74 matches the longest leftmost substring formally
75 matched by the expression.
76 Searching in the reverse direction is equivalent
77 to searching backwards with the catenation operations reversed in
80 An address identifies a substring in a file.
81 In the following, `character
86 character in the file, with 1 the
87 first character in the file.
93 starting at the beginning of the file, of the regular expression
95 All files always have a current substring, called dot,
96 that is the default address.
101 The empty string after character
104 is the beginning of the file.
110 is the beginning of the file.
116 The substring that matches the regular expression,
117 found by looking toward the end
122 and if necessary continuing the search from the other end to the
123 starting point of the search.
124 The matched substring may straddle
126 When entering a pattern containing a literal question mark
127 for a backward search, the question mark should be
128 specified as a member of a class.
132 The string before the first full line.
133 This is not necessarily
141 The null string at the end of the file.
147 The mark in the file (see the
151 \fB"\f2regexp\fB"\f1\f1
152 Preceding a simple address (default
154 refers to the address evaluated in the unique file whose menu line
155 matches the regular expression.
157 .SS Compound Addresses
168 evaluated starting at the end of
174 evaluated looking in the reverse direction
175 starting at the beginning of
179 The substring from the beginning of
199 evaluated at the end of, and dot set to,
207 are high precedence, while
219 is a line or character address with a missing
220 number, the number defaults to 1.
230 are present and distinguishable,
235 expression; if it is delimited by
243 It is an error for a compound address to represent a malformed substring.
247 selects the line containing
248 the end (beginning) of a1.
250 locates the first match of the expression in the file.
253 sets dot unnecessarily.)
255 finds the second following occurrence of the expression,
260 In the following, text demarcated by slashes represents text delimited
262 character except alphanumerics.
264 trailing delimiters may be elided, with multiple elisions then representing
265 null strings, but the first delimiter must always
267 In any delimited text,
268 newline may not appear literally;
270 may be typed for newline; and
272 quotes the delimiter, here
274 Backslash is otherwise interpreted literally, except in
278 Most commands may be prefixed by an address to indicate their range
280 Those that may not are marked with a
284 an address and none is supplied, dot is used.
285 The sole exception is
288 command, which defaults to
290 In the description, `range' is used
291 to represent whatever address is supplied.
292 Many commands set the
293 value of dot as a side effect.
294 If so, it is always set to the `result'
295 of the change: the empty string for a deletion, the new text for an
296 insertion, etc. (but see the
315 Insert the text into the file after the range.
328 replaces the text, while
335 Delete the text in the range.
338 .BI s/ regexp / text /
341 for the first match to the regular expression in the range.
342 Set dot to the modified range.
347 stands for the string
348 that matched the expression.
349 Backslash behaves as usual unless followed by
352 stands for the string that matched the
353 subexpression begun by the
358 is followed immediately by a
365 match in the range is substituted.
367 command is followed by a
371 all matches in the range
390 Print the text in the range.
394 Print the line address and character address of the range.
397 Print just the character address of the range.
403 Set the current file to the first file named in the list
406 also has in its menu.
407 The list may be expressed
408 .BI < "Plan 9 command"
409 in which case the file names are taken as words (in the shell sense)
410 generated by the Plan 9 command.
415 except that file names not in the menu are entered there,
416 and all file names in the list are examined.
419 Print a menu of files.
424 indicating the file is modified or clean,
427 indicating the file is unread or has been read
430 means more than one window is open),
433 indicating the current file,
441 Delete the named files from the menu.
442 If no files are named, the current file is deleted.
445 a modified file, but a subsequent
447 will delete such a file.
453 Replace the file by the contents of the named external file.
454 Set dot to the beginning of the file.
457 Replace the text in the range by the contents of the named external file.
461 Write the range (default
463 to the named external file.
466 Set the file name and print the resulting menu entry.
468 If the file name is absent from any of these, the current file name is used.
470 always sets the file name;
474 do so if the file has no name.
476 .BI < " Plan 9-command
477 Replace the range by the standard output of the
480 .BI > " Plan 9-command
481 Send the range to the standard input of the
484 .BI | " Plan 9-command
485 Send the range to the standard input, and replace it by
486 the standard output, of the
489 .BI \*a! " Plan 9-command
493 .BI \*acd " directory
494 Change working directory.
495 If no directory is specified,
510 (of any type) is substituted.
515 (using the mouse and raster display, i.e. not using option
518 sets standard input to
528 for all) is placed in
530 and the first few lines are printed.
531 .SS Loops and Conditionals
534 .BI x/ regexp / " command
535 For each match of the regular expression in the range, run the command
536 with dot set to the match.
537 Set dot to the last match.
539 expression and its slashes are omitted,
542 Null string matches potentially occur before every character
543 of the range and at the end of the range.
545 .BI y/ regexp / " command
548 but run the command for each substring that lies before, between,
550 the matches that would be generated by
552 There is no default regular expression.
553 Null substrings potentially occur before every character
556 .BI \*aX/ regexp / " command
557 For each file whose menu entry matches the regular expression,
558 make that the current file and
560 If the expression is omitted, the command is run
563 .BI \*aY/ regexp / " command
566 but for files that do not match the regular expression,
567 and the expression is required.
569 .BI g/ regexp / " command
573 .BI v/ regexp / " command
574 If the range contains
578 a match for the expression,
579 set dot to the range and run the command.
581 These may be nested arbitrarily deeply, but only one instance of either
585 may appear in a \%single command.
586 An empty command in an
601 do not have defaults.
607 Set the current file's mark to the range. Does not set dot.
611 It is an error to quit with modified files, but a second
619 top-level commands that changed the contents or name of the
620 current file, and any other file whose most recent change was simultaneous
621 with the current file's change.
624 move further back in time.
625 The only commands for which u is ineffective are
636 `redoes,' undoing the undo, going forwards in time again.
639 If the range is explicit, set dot to the range.
642 is downloaded, the resulting dot is selected on the screen;
643 otherwise it is printed.
644 If no address is specified (the
645 command is a newline) dot is extended in either direction to
646 line boundaries and printed.
647 If dot is thereby unchanged, it is set to
651 .SS Grouping and multiple changes
652 Commands may be grouped by enclosing them in braces
654 Commands within the braces must appear on separate lines (no backslashes are
655 required between commands).
656 Semantically, an opening brace is like a command:
657 it takes an (optional) address and sets dot for each sub-command.
658 Commands within the braces are executed sequentially, but changes made
659 by one command are not visible to other commands (see the next
661 Braces may be nested arbitrarily.
663 When a command makes a number of changes to a file, as in
665 the addresses of all changes to the file are computed in the original file.
666 If the changes are in sequence,
667 they are applied to the file.
668 Successive insertions at the same address are catenated into a single
669 insertion composed of the several insertions in the order applied.
671 What follows refers to behavior of
673 when downloaded, that is, when
674 operating as a display editor on a raster display.
680 (no download) option provides access
681 to the command language only.
683 Each file may have zero or more windows open.
684 Each window is equivalent
685 and is updated simultaneously with changes in other windows on the same file.
686 Each window has an independent value of dot, indicated by a highlighted
687 substring on the display.
688 Dot may be in a region not within
690 There is usually a `current window',
691 marked with a dark border, to which typed text and editing
693 Text may be typed and edited as in
695 also the escape key (ESC) selects (sets dot to) text typed
696 since the last mouse button hit.
698 The button 3 menu controls window operations.
700 provides the following operators, each of which uses one or
703 cursors to prompt for selection of a window or sweeping
705 `Sweeping' a null rectangle gets a large window, disjoint
706 from the command window or the whole screen, depending on
707 where the null rectangle is.
711 Create a new, empty file.
714 Create a copy of an existing window.
722 In the last window of a file,
734 Below these operators is a list of available files, starting with
737 Selecting a file from the list makes the most recently
738 used window on that file current, unless it is already current, in which
739 case selections cycle through the open windows.
740 If no windows are open
741 on the file, the user is prompted to open one.
744 are marked with one of the characters
746 according as zero, one, or more windows
747 are open on the file.
750 appears on the file in the current window and
753 on a file modified since last write.
755 The command window, created automatically when
757 starts, is an ordinary window except that text typed to it
758 is interpreted as commands for the editor rather than passive text,
759 and text printed by editor commands appears in it.
762 with an `output point' that separates commands being typed from
764 Commands typed in the command window apply to the
765 current open file\(emthe file in the most recently
767 .SS Manipulating text
768 Button 1 changes selection, much like
770 Pointing to a non-current window with button 1 makes it current;
771 within the current window, button 1 selects text, thus setting dot.
772 Double-clicking selects text to the boundaries of words, lines,
773 quoted strings or bracketed strings, depending on the text at the click.
775 Button 2 provides a menu of editing commands:
779 Delete dot and save the deleted text in the snarf buffer.
782 Replace the text in dot by the contents of the snarf buffer.
785 Save the text in dot in the snarf buffer.
788 Send the text in the selection as a plumb
789 message. If the selection is empty,
790 the white-space-delimited block of text is sent as a plumb message
793 attribute defining where the selection lies (see
797 Search forward for the next occurrence of the literal text in dot.
798 If dot is the null string, the text in the snarf buffer is
800 The snarf buffer is unaffected.
803 Exchange snarf buffers with
807 Search forward for the next match of the last regular expression
809 (Not in command window.)
812 Send the text in dot, or the snarf buffer if
813 dot is the null string, as if it were typed to the command window.
814 Saves the sent text in the snarf buffer.
815 (Command window only.)
817 .SS External communication
822 If plumbing is not active,
827 which acts as an additional source of commands. Characters written to
828 the named pipe are treated as if they had been typed in the command window.
831 is a shell-level command that causes an instance of
833 running on the same terminal to load the named
836 uses either plumbing or the named pipe, whichever service is available.
837 If plumbing is not enabled,
838 the option allows a line number to be specified for
839 the initial position to display in the last named file
840 (plumbing provides a more general mechanism for this ability).
841 .SS Abnormal termination
844 terminates other than by a
846 command (by hangup, deleting its window, etc.), modified
847 files are saved in an
850 This program, when executed, asks whether to write
851 each file back to a external file.
854 causes writing; anything else skips the file.
856 .TF /usr/local/plan9/src/cmd/samterm
862 .B /usr/local/plan9/bin/samsave
863 the program called to unpack
866 .TF /usr/local/plan9/src/cmd/samterm
868 .B /usr/local/plan9/src/cmd/sam
873 .B /usr/local/plan9/src/cmd/samterm
874 source for the separate terminal part
876 .B /usr/local/plan9/bin/B
885 ``The text editor sam''.
