4 sam, B, E, sam.save, samterm, samsave \- screen editor with structural regular expressions
20 .IB file \fR[\fP: line \fR]
24 is a multi-file editor.
25 It modifies a local copy of an external file.
26 The copy is here called a
28 The files are listed in a menu available through mouse button 3
32 Each file has an associated name, usually the name of the
33 external file from which it was read, and a `modified' bit that indicates whether
34 the editor's file agrees with the external file.
35 The external file is not read into
36 the editor's file until it first becomes the current file\(emthat to
37 which editing commands apply\(emwhereupon its menu entry is printed.
42 Do not `download' the terminal part of
44 Editing will be done with the command language only, as in
48 Run the host part remotely
49 on the specified machine, the terminal part locally.
52 Start the host part from the specified file on the remote host.
53 Only meaningful with the
58 Start the terminal part from the specified file. Useful
61 .SS Regular expressions
62 Regular expressions are as in
66 to represent newlines.
67 A regular expression may never contain a literal newline character.
69 regular expression stands for the last complete expression encountered.
70 A regular expression in
72 matches the longest leftmost substring formally
73 matched by the expression.
74 Searching in the reverse direction is equivalent
75 to searching backwards with the catenation operations reversed in
78 An address identifies a substring in a file.
79 In the following, `character
84 character in the file, with 1 the
85 first character in the file.
91 starting at the beginning of the file, of the regular expression
93 All files always have a current substring, called dot,
94 that is the default address.
99 The empty string after character
102 is the beginning of the file.
108 is the beginning of the file.
114 The substring that matches the regular expression,
115 found by looking toward the end
120 and if necessary continuing the search from the other end to the
121 starting point of the search.
122 The matched substring may straddle
124 When entering a pattern containing a literal question mark
125 for a backward search, the question mark should be
126 specified as a member of a class.
130 The string before the first full line.
131 This is not necessarily
139 The null string at the end of the file.
145 The mark in the file (see the
149 \fB"\f2regexp\fB"\f1\f1
150 Preceding a simple address (default
152 refers to the address evaluated in the unique file whose menu line
153 matches the regular expression.
155 .SS Compound Addresses
166 evaluated starting at the end of
172 evaluated looking in the reverse direction
173 starting at the beginning of
177 The substring from the beginning of
197 evaluated at the end of, and dot set to,
205 are high precedence, while
217 is a line or character address with a missing
218 number, the number defaults to 1.
228 are present and distinguishable,
233 expression; if it is delimited by
241 It is an error for a compound address to represent a malformed substring.
245 selects the line containing
246 the end (beginning) of a1.
248 locates the first match of the expression in the file.
251 sets dot unnecessarily.)
253 finds the second following occurrence of the expression,
258 In the following, text demarcated by slashes represents text delimited
260 character except alphanumerics.
262 trailing delimiters may be elided, with multiple elisions then representing
263 null strings, but the first delimiter must always
265 In any delimited text,
266 newline may not appear literally;
268 may be typed for newline; and
270 quotes the delimiter, here
272 Backslash is otherwise interpreted literally, except in
276 Most commands may be prefixed by an address to indicate their range
278 Those that may not are marked with a
282 an address and none is supplied, dot is used.
283 The sole exception is
286 command, which defaults to
288 In the description, `range' is used
289 to represent whatever address is supplied.
290 Many commands set the
291 value of dot as a side effect.
292 If so, it is always set to the `result'
293 of the change: the empty string for a deletion, the new text for an
294 insertion, etc. (but see the
313 Insert the text into the file after the range.
326 replaces the text, while
333 Delete the text in the range.
336 .BI s/ regexp / text /
339 for the first match to the regular expression in the range.
340 Set dot to the modified range.
345 stands for the string
346 that matched the expression.
347 Backslash behaves as usual unless followed by
350 stands for the string that matched the
351 subexpression begun by the
356 is followed immediately by a
363 match in the range is substituted.
365 command is followed by a
369 all matches in the range
388 Print the text in the range.
392 Print the line address and character address of the range.
395 Print just the character address of the range.
401 Set the current file to the first file named in the list
404 also has in its menu.
405 The list may be expressed
406 .BI < "Plan 9 command"
407 in which case the file names are taken as words (in the shell sense)
408 generated by the Plan 9 command.
413 except that file names not in the menu are entered there,
414 and all file names in the list are examined.
417 Print a menu of files.
422 indicating the file is modified or clean,
425 indicating the file is unread or has been read
428 means more than one window is open),
431 indicating the current file,
439 Delete the named files from the menu.
440 If no files are named, the current file is deleted.
443 a modified file, but a subsequent
445 will delete such a file.
451 Replace the file by the contents of the named external file.
452 Set dot to the beginning of the file.
455 Replace the text in the range by the contents of the named external file.
459 Write the range (default
461 to the named external file.
464 Set the file name and print the resulting menu entry.
466 If the file name is absent from any of these, the current file name is used.
468 always sets the file name;
472 do so if the file has no name.
474 .BI < " Plan 9-command
475 Replace the range by the standard output of the
478 .BI > " Plan 9-command
479 Send the range to the standard input of the
482 .BI | " Plan 9-command
483 Send the range to the standard input, and replace it by
484 the standard output, of the
487 .BI \*a! " Plan 9-command
491 .BI \*acd " directory
492 Change working directory.
493 If no directory is specified,
508 (of any type) is substituted.
513 (using the mouse and raster display, i.e. not using option
516 sets standard input to
526 for all) is placed in
528 and the first few lines are printed.
529 .SS Loops and Conditionals
532 .BI x/ regexp / " command
533 For each match of the regular expression in the range, run the command
534 with dot set to the match.
535 Set dot to the last match.
537 expression and its slashes are omitted,
540 Null string matches potentially occur before every character
541 of the range and at the end of the range.
543 .BI y/ regexp / " command
546 but run the command for each substring that lies before, between,
548 the matches that would be generated by
550 There is no default regular expression.
551 Null substrings potentially occur before every character
554 .BI \*aX/ regexp / " command
555 For each file whose menu entry matches the regular expression,
556 make that the current file and
558 If the expression is omitted, the command is run
561 .BI \*aY/ regexp / " command
564 but for files that do not match the regular expression,
565 and the expression is required.
567 .BI g/ regexp / " command
571 .BI v/ regexp / " command
572 If the range contains
576 a match for the expression,
577 set dot to the range and run the command.
579 These may be nested arbitrarily deeply, but only one instance of either
583 may appear in a \%single command.
584 An empty command in an
599 do not have defaults.
605 Set the current file's mark to the range. Does not set dot.
609 It is an error to quit with modified files, but a second
617 top-level commands that changed the contents or name of the
618 current file, and any other file whose most recent change was simultaneous
619 with the current file's change.
622 move further back in time.
623 The only commands for which u is ineffective are
634 `redoes,' undoing the undo, going forwards in time again.
637 If the range is explicit, set dot to the range.
640 is downloaded, the resulting dot is selected on the screen;
641 otherwise it is printed.
642 If no address is specified (the
643 command is a newline) dot is extended in either direction to
644 line boundaries and printed.
645 If dot is thereby unchanged, it is set to
649 .SS Grouping and multiple changes
650 Commands may be grouped by enclosing them in braces
652 Commands within the braces must appear on separate lines (no backslashes are
653 required between commands).
654 Semantically, an opening brace is like a command:
655 it takes an (optional) address and sets dot for each sub-command.
656 Commands within the braces are executed sequentially, but changes made
657 by one command are not visible to other commands (see the next
659 Braces may be nested arbitrarily.
661 When a command makes a number of changes to a file, as in
663 the addresses of all changes to the file are computed in the original file.
664 If the changes are in sequence,
665 they are applied to the file.
666 Successive insertions at the same address are catenated into a single
667 insertion composed of the several insertions in the order applied.
669 What follows refers to behavior of
671 when downloaded, that is, when
672 operating as a display editor on a raster display.
678 (no download) option provides access
679 to the command language only.
681 Each file may have zero or more windows open.
682 Each window is equivalent
683 and is updated simultaneously with changes in other windows on the same file.
684 Each window has an independent value of dot, indicated by a highlighted
685 substring on the display.
686 Dot may be in a region not within
688 There is usually a `current window',
689 marked with a dark border, to which typed text and editing
691 Text may be typed and edited as in
693 also the escape key (ESC) selects (sets dot to) text typed
694 since the last mouse button hit.
696 The button 3 menu controls window operations.
698 provides the following operators, each of which uses one or
701 cursors to prompt for selection of a window or sweeping
703 `Sweeping' a null rectangle gets a large window, disjoint
704 from the command window or the whole screen, depending on
705 where the null rectangle is.
709 Create a new, empty file.
712 Create a copy of an existing window.
720 In the last window of a file,
732 Below these operators is a list of available files, starting with
735 Selecting a file from the list makes the most recently
736 used window on that file current, unless it is already current, in which
737 case selections cycle through the open windows.
738 If no windows are open
739 on the file, the user is prompted to open one.
742 are marked with one of the characters
744 according as zero, one, or more windows
745 are open on the file.
748 appears on the file in the current window and
751 on a file modified since last write.
753 The command window, created automatically when
755 starts, is an ordinary window except that text typed to it
756 is interpreted as commands for the editor rather than passive text,
757 and text printed by editor commands appears in it.
760 with an `output point' that separates commands being typed from
762 Commands typed in the command window apply to the
763 current open file\(emthe file in the most recently
765 .SS Manipulating text
766 Button 1 changes selection, much like
768 Pointing to a non-current window with button 1 makes it current;
769 within the current window, button 1 selects text, thus setting dot.
770 Double-clicking selects text to the boundaries of words, lines,
771 quoted strings or bracketed strings, depending on the text at the click.
773 Button 2 provides a menu of editing commands:
777 Delete dot and save the deleted text in the snarf buffer.
780 Replace the text in dot by the contents of the snarf buffer.
783 Save the text in dot in the snarf buffer.
786 Send the text in the selection as a plumb
787 message. If the selection is empty,
788 the white-space-delimited block of text is sent as a plumb message
791 attribute defining where the selection lies (see
795 Search forward for the next occurrence of the literal text in dot.
796 If dot is the null string, the text in the snarf buffer is
798 The snarf buffer is unaffected.
801 Exchange snarf buffers with
805 Search forward for the next match of the last regular expression
807 (Not in command window.)
810 Send the text in dot, or the snarf buffer if
811 dot is the null string, as if it were typed to the command window.
812 Saves the sent text in the snarf buffer.
813 (Command window only.)
815 .SS External communication
820 If plumbing is not active,
825 which acts as an additional source of commands. Characters written to
826 the named pipe are treated as if they had been typed in the command window.
829 is a shell-level command that causes an instance of
831 running on the same terminal to load the named
834 uses either plumbing or the named pipe, whichever service is available.
835 If plumbing is not enabled,
836 the option allows a line number to be specified for
837 the initial position to display in the last named file
838 (plumbing provides a more general mechanism for this ability).
841 is a shell-level command that can be used as
843 in a Unix environment.
848 and then waits to exit until
850 is changed, which is taken as a signal that
852 is done being edited.
853 .SS Abnormal termination
856 terminates other than by a
858 command (by hangup, deleting its window, etc.), modified
859 files are saved in an
862 This program, when executed, asks whether to write
863 each file back to a external file.
866 causes writing; anything else skips the file.
868 .TF /usr/local/plan9/src/cmd/samterm
874 .B /usr/local/plan9/bin/samsave
875 the program called to unpack
878 .TF /usr/local/plan9/src/cmd/samterm
880 .B /usr/local/plan9/src/cmd/sam
885 .B /usr/local/plan9/src/cmd/samterm
886 source for the separate terminal part
888 .B /usr/local/plan9/bin/B
897 ``The text editor sam''.
