4 sam, B, E, sam.save, samterm, samsave \- screen editor with structural regular expressions
20 .IB file \fR[\fP: line \fR]
27 is a multi-file editor.
28 It modifies a local copy of an external file.
29 The copy is here called a
31 The files are listed in a menu available through mouse button 3
35 Each file has an associated name, usually the name of the
36 external file from which it was read, and a `modified' bit that indicates whether
37 the editor's file agrees with the external file.
38 The external file is not read into
39 the editor's file until it first becomes the current file\(emthat to
40 which editing commands apply\(emwhereupon its menu entry is printed.
45 Autoindent. In this mode, when a newline character is typed
46 in the terminal interface,
48 copies leading white space on the current line to the new line.
51 Do not `download' the terminal part of
53 Editing will be done with the command language only, as in
57 Run the host part remotely
58 on the specified machine, the terminal part locally.
61 Start the host part from the specified file on the remote host.
62 Only meaningful with the
67 Start the terminal part from the specified file. Useful
70 .SS Regular expressions
71 Regular expressions are as in
75 to represent newlines.
76 A regular expression may never contain a literal newline character.
78 regular expression stands for the last complete expression encountered.
79 A regular expression in
81 matches the longest leftmost substring formally
82 matched by the expression.
83 Searching in the reverse direction is equivalent
84 to searching backwards with the catenation operations reversed in
87 An address identifies a substring in a file.
88 In the following, `character
93 character in the file, with 1 the
94 first character in the file.
100 starting at the beginning of the file, of the regular expression
102 All files always have a current substring, called dot,
103 that is the default address.
108 The empty string after character
111 is the beginning of the file.
117 is the beginning of the file.
123 The substring that matches the regular expression,
124 found by looking toward the end
129 and if necessary continuing the search from the other end to the
130 starting point of the search.
131 The matched substring may straddle
133 When entering a pattern containing a literal question mark
134 for a backward search, the question mark should be
135 specified as a member of a class.
139 The string before the first full line.
140 This is not necessarily
148 The null string at the end of the file.
154 The mark in the file (see the
158 \fB"\f2regexp\fB"\f1\f1
159 Preceding a simple address (default
161 refers to the address evaluated in the unique file whose menu line
162 matches the regular expression.
164 .SS Compound Addresses
175 evaluated starting at the end of
181 evaluated looking in the reverse direction
182 starting at the beginning of
186 The substring from the beginning of
206 evaluated at the end of, and dot set to,
214 are high precedence, while
226 is a line or character address with a missing
227 number, the number defaults to 1.
237 are present and distinguishable,
242 expression; if it is delimited by
250 It is an error for a compound address to represent a malformed substring.
254 selects the line containing
255 the end (beginning) of a1.
257 locates the first match of the expression in the file.
260 sets dot unnecessarily.)
262 finds the second following occurrence of the expression,
267 In the following, text demarcated by slashes represents text delimited
269 character except alphanumerics.
271 trailing delimiters may be elided, with multiple elisions then representing
272 null strings, but the first delimiter must always
274 In any delimited text,
275 newline may not appear literally;
277 may be typed for newline; and
279 quotes the delimiter, here
281 Backslash is otherwise interpreted literally, except in
285 Most commands may be prefixed by an address to indicate their range
287 Those that may not are marked with a
291 an address and none is supplied, dot is used.
292 The sole exception is
295 command, which defaults to
297 In the description, `range' is used
298 to represent whatever address is supplied.
299 Many commands set the
300 value of dot as a side effect.
301 If so, it is always set to the `result'
302 of the change: the empty string for a deletion, the new text for an
303 insertion, etc. (but see the
322 Insert the text into the file after the range.
335 replaces the text, while
342 Delete the text in the range.
345 .BI s/ regexp / text /
348 for the first match to the regular expression in the range.
349 Set dot to the modified range.
354 stands for the string
355 that matched the expression.
356 Backslash behaves as usual unless followed by
359 stands for the string that matched the
360 subexpression begun by the
365 is followed immediately by a
372 match in the range is substituted.
374 command is followed by a
378 all matches in the range
397 Print the text in the range.
401 Print the line address and character address of the range.
404 Print just the character address of the range.
410 Set the current file to the first file named in the list
413 also has in its menu.
414 The list may be expressed
415 .BI < "Plan 9 command"
416 in which case the file names are taken as words (in the shell sense)
417 generated by the Plan 9 command.
422 except that file names not in the menu are entered there,
423 and all file names in the list are examined.
426 Print a menu of files.
431 indicating the file is modified or clean,
434 indicating the file is unread or has been read
437 means more than one window is open),
440 indicating the current file,
448 Delete the named files from the menu.
449 If no files are named, the current file is deleted.
452 a modified file, but a subsequent
454 will delete such a file.
460 Replace the file by the contents of the named external file.
461 Set dot to the beginning of the file.
464 Replace the text in the range by the contents of the named external file.
468 Write the range (default
470 to the named external file.
473 Set the file name and print the resulting menu entry.
475 If the file name is absent from any of these, the current file name is used.
477 always sets the file name;
481 do so if the file has no name.
483 .BI < " Plan 9-command
484 Replace the range by the standard output of the
487 .BI > " Plan 9-command
488 Send the range to the standard input of the
491 .BI | " Plan 9-command
492 Send the range to the standard input, and replace it by
493 the standard output, of the
496 .BI \*a! " Plan 9-command
500 .BI \*acd " directory
501 Change working directory.
502 If no directory is specified,
517 (of any type) is substituted.
522 (using the mouse and raster display, i.e. not using option
525 sets standard input to
535 for all) is placed in
537 and the first few lines are printed.
538 .SS Loops and Conditionals
541 .BI x/ regexp / " command
542 For each match of the regular expression in the range, run the command
543 with dot set to the match.
544 Set dot to the last match.
546 expression and its slashes are omitted,
549 Null string matches potentially occur before every character
550 of the range and at the end of the range.
552 .BI y/ regexp / " command
555 but run the command for each substring that lies before, between,
557 the matches that would be generated by
559 There is no default regular expression.
560 Null substrings potentially occur before every character
563 .BI \*aX/ regexp / " command
564 For each file whose menu entry matches the regular expression,
565 make that the current file and
567 If the expression is omitted, the command is run
570 .BI \*aY/ regexp / " command
573 but for files that do not match the regular expression,
574 and the expression is required.
576 .BI g/ regexp / " command
580 .BI v/ regexp / " command
581 If the range contains
585 a match for the expression,
586 set dot to the range and run the command.
588 These may be nested arbitrarily deeply, but only one instance of either
592 may appear in a \%single command.
593 An empty command in an
608 do not have defaults.
614 Set the current file's mark to the range. Does not set dot.
618 It is an error to quit with modified files, but a second
626 top-level commands that changed the contents or name of the
627 current file, and any other file whose most recent change was simultaneous
628 with the current file's change.
631 move further back in time.
632 The only commands for which u is ineffective are
643 `redoes,' undoing the undo, going forwards in time again.
646 If the range is explicit, set dot to the range.
649 is downloaded, the resulting dot is selected on the screen;
650 otherwise it is printed.
651 If no address is specified (the
652 command is a newline) dot is extended in either direction to
653 line boundaries and printed.
654 If dot is thereby unchanged, it is set to
658 .SS Grouping and multiple changes
659 Commands may be grouped by enclosing them in braces
661 Commands within the braces must appear on separate lines (no backslashes are
662 required between commands).
663 Semantically, an opening brace is like a command:
664 it takes an (optional) address and sets dot for each sub-command.
665 Commands within the braces are executed sequentially, but changes made
666 by one command are not visible to other commands (see the next
668 Braces may be nested arbitrarily.
670 When a command makes a number of changes to a file, as in
672 the addresses of all changes to the file are computed in the original file.
673 If the changes are in sequence,
674 they are applied to the file.
675 Successive insertions at the same address are catenated into a single
676 insertion composed of the several insertions in the order applied.
678 What follows refers to behavior of
680 when downloaded, that is, when
681 operating as a display editor on a raster display.
687 (no download) option provides access
688 to the command language only.
690 Each file may have zero or more windows open.
691 Each window is equivalent
692 and is updated simultaneously with changes in other windows on the same file.
693 Each window has an independent value of dot, indicated by a highlighted
694 substring on the display.
695 Dot may be in a region not within
697 There is usually a `current window',
698 marked with a dark border, to which typed text and editing
700 Text may be typed and edited as in
702 also the escape key (ESC) selects (sets dot to) text typed
703 since the last mouse button hit.
705 The button 3 menu controls window operations.
707 provides the following operators, each of which uses one or
710 cursors to prompt for selection of a window or sweeping
712 `Sweeping' a null rectangle gets a large window, disjoint
713 from the command window or the whole screen, depending on
714 where the null rectangle is.
718 Create a new, empty file.
721 Create a copy of an existing window.
729 In the last window of a file,
741 Below these operators is a list of available files, starting with
744 Selecting a file from the list makes the most recently
745 used window on that file current, unless it is already current, in which
746 case selections cycle through the open windows.
747 If no windows are open
748 on the file, the user is prompted to open one.
751 are marked with one of the characters
753 according as zero, one, or more windows
754 are open on the file.
757 appears on the file in the current window and
760 on a file modified since last write.
762 The command window, created automatically when
764 starts, is an ordinary window except that text typed to it
765 is interpreted as commands for the editor rather than passive text,
766 and text printed by editor commands appears in it.
769 with an `output point' that separates commands being typed from
771 Commands typed in the command window apply to the
772 current open file\(emthe file in the most recently
774 .SS Manipulating text
775 Button 1 changes selection, much like
777 Pointing to a non-current window with button 1 makes it current;
778 within the current window, button 1 selects text, thus setting dot.
779 Double-clicking selects text to the boundaries of words, lines,
780 quoted strings or bracketed strings, depending on the text at the click.
782 Button 2 provides a menu of editing commands:
786 Delete dot and save the deleted text in the snarf buffer.
789 Replace the text in dot by the contents of the snarf buffer.
792 Save the text in dot in the snarf buffer.
795 Send the text in the selection as a plumb
796 message. If the selection is empty,
797 the white-space-delimited block of text is sent as a plumb message
800 attribute defining where the selection lies (see
804 Search forward for the next occurrence of the literal text in dot.
805 If dot is the null string, the text in the snarf buffer is
807 The snarf buffer is unaffected.
810 Exchange snarf buffers with
814 Search forward for the next match of the last regular expression
816 (Not in command window.)
819 Send the text in dot, or the snarf buffer if
820 dot is the null string, as if it were typed to the command window.
821 Saves the sent text in the snarf buffer.
822 (Command window only.)
824 .SS External communication
829 If plumbing is not active,
834 which acts as an additional source of commands. Characters written to
835 the named pipe are treated as if they had been typed in the command window.
838 is a shell-level command that causes an instance of
840 running on the same terminal to load the named
843 uses either plumbing or the named pipe, whichever service is available.
844 If plumbing is not enabled,
845 the option allows a line number to be specified for
846 the initial position to display in the last named file
847 (plumbing provides a more general mechanism for this ability).
850 is a shell-level command that can be used as
852 in a Unix environment.
857 and then does not exit until
859 is changed, which is taken as a signal that
861 is done being edited.
862 .SS Abnormal termination
865 terminates other than by a
867 command (by hangup, deleting its window, etc.), modified
868 files are saved in an
871 This program, when executed, asks whether to write
872 each file back to a external file.
875 causes writing; anything else skips the file.
884 the program called to unpack
887 .TF \*9/src/cmd/samterm
894 .B \*9/src/cmd/samterm
895 source for the separate terminal part
908 ``The text editor sam''.