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 Do not `download' the terminal part of
47 Editing will be done with the command language only, as in
51 Run the host part remotely
52 on the specified machine, the terminal part locally.
55 Start the host part from the specified file on the remote host.
56 Only meaningful with the
61 Start the terminal part from the specified file. Useful
64 .SS Regular expressions
65 Regular expressions are as in
69 to represent newlines.
70 A regular expression may never contain a literal newline character.
72 regular expression stands for the last complete expression encountered.
73 A regular expression in
75 matches the longest leftmost substring formally
76 matched by the expression.
77 Searching in the reverse direction is equivalent
78 to searching backwards with the catenation operations reversed in
81 An address identifies a substring in a file.
82 In the following, `character
87 character in the file, with 1 the
88 first character in the file.
94 starting at the beginning of the file, of the regular expression
96 All files always have a current substring, called dot,
97 that is the default address.
102 The empty string after character
105 is the beginning of the file.
111 is the beginning of the file.
117 The substring that matches the regular expression,
118 found by looking toward the end
123 and if necessary continuing the search from the other end to the
124 starting point of the search.
125 The matched substring may straddle
127 When entering a pattern containing a literal question mark
128 for a backward search, the question mark should be
129 specified as a member of a class.
133 The string before the first full line.
134 This is not necessarily
142 The null string at the end of the file.
148 The mark in the file (see the
152 \fB"\f2regexp\fB"\f1\f1
153 Preceding a simple address (default
155 refers to the address evaluated in the unique file whose menu line
156 matches the regular expression.
158 .SS Compound Addresses
169 evaluated starting at the end of
175 evaluated looking in the reverse direction
176 starting at the beginning of
180 The substring from the beginning of
200 evaluated at the end of, and dot set to,
208 are high precedence, while
220 is a line or character address with a missing
221 number, the number defaults to 1.
231 are present and distinguishable,
236 expression; if it is delimited by
244 It is an error for a compound address to represent a malformed substring.
248 selects the line containing
249 the end (beginning) of a1.
251 locates the first match of the expression in the file.
254 sets dot unnecessarily.)
256 finds the second following occurrence of the expression,
261 In the following, text demarcated by slashes represents text delimited
263 character except alphanumerics.
265 trailing delimiters may be elided, with multiple elisions then representing
266 null strings, but the first delimiter must always
268 In any delimited text,
269 newline may not appear literally;
271 may be typed for newline; and
273 quotes the delimiter, here
275 Backslash is otherwise interpreted literally, except in
279 Most commands may be prefixed by an address to indicate their range
281 Those that may not are marked with a
285 an address and none is supplied, dot is used.
286 The sole exception is
289 command, which defaults to
291 In the description, `range' is used
292 to represent whatever address is supplied.
293 Many commands set the
294 value of dot as a side effect.
295 If so, it is always set to the `result'
296 of the change: the empty string for a deletion, the new text for an
297 insertion, etc. (but see the
316 Insert the text into the file after the range.
329 replaces the text, while
336 Delete the text in the range.
339 .BI s/ regexp / text /
342 for the first match to the regular expression in the range.
343 Set dot to the modified range.
348 stands for the string
349 that matched the expression.
350 Backslash behaves as usual unless followed by
353 stands for the string that matched the
354 subexpression begun by the
359 is followed immediately by a
366 match in the range is substituted.
368 command is followed by a
372 all matches in the range
391 Print the text in the range.
395 Print the line address and character address of the range.
398 Print just the character address of the range.
404 Set the current file to the first file named in the list
407 also has in its menu.
408 The list may be expressed
409 .BI < "Plan 9 command"
410 in which case the file names are taken as words (in the shell sense)
411 generated by the Plan 9 command.
416 except that file names not in the menu are entered there,
417 and all file names in the list are examined.
420 Print a menu of files.
425 indicating the file is modified or clean,
428 indicating the file is unread or has been read
431 means more than one window is open),
434 indicating the current file,
442 Delete the named files from the menu.
443 If no files are named, the current file is deleted.
446 a modified file, but a subsequent
448 will delete such a file.
454 Replace the file by the contents of the named external file.
455 Set dot to the beginning of the file.
458 Replace the text in the range by the contents of the named external file.
462 Write the range (default
464 to the named external file.
467 Set the file name and print the resulting menu entry.
469 If the file name is absent from any of these, the current file name is used.
471 always sets the file name;
475 do so if the file has no name.
477 .BI < " Plan 9-command
478 Replace the range by the standard output of the
481 .BI > " Plan 9-command
482 Send the range to the standard input of the
485 .BI | " Plan 9-command
486 Send the range to the standard input, and replace it by
487 the standard output, of the
490 .BI \*a! " Plan 9-command
494 .BI \*acd " directory
495 Change working directory.
496 If no directory is specified,
511 (of any type) is substituted.
516 (using the mouse and raster display, i.e. not using option
519 sets standard input to
529 for all) is placed in
531 and the first few lines are printed.
532 .SS Loops and Conditionals
535 .BI x/ regexp / " command
536 For each match of the regular expression in the range, run the command
537 with dot set to the match.
538 Set dot to the last match.
540 expression and its slashes are omitted,
543 Null string matches potentially occur before every character
544 of the range and at the end of the range.
546 .BI y/ regexp / " command
549 but run the command for each substring that lies before, between,
551 the matches that would be generated by
553 There is no default regular expression.
554 Null substrings potentially occur before every character
557 .BI \*aX/ regexp / " command
558 For each file whose menu entry matches the regular expression,
559 make that the current file and
561 If the expression is omitted, the command is run
564 .BI \*aY/ regexp / " command
567 but for files that do not match the regular expression,
568 and the expression is required.
570 .BI g/ regexp / " command
574 .BI v/ regexp / " command
575 If the range contains
579 a match for the expression,
580 set dot to the range and run the command.
582 These may be nested arbitrarily deeply, but only one instance of either
586 may appear in a \%single command.
587 An empty command in an
602 do not have defaults.
608 Set the current file's mark to the range. Does not set dot.
612 It is an error to quit with modified files, but a second
620 top-level commands that changed the contents or name of the
621 current file, and any other file whose most recent change was simultaneous
622 with the current file's change.
625 move further back in time.
626 The only commands for which u is ineffective are
637 `redoes,' undoing the undo, going forwards in time again.
640 If the range is explicit, set dot to the range.
643 is downloaded, the resulting dot is selected on the screen;
644 otherwise it is printed.
645 If no address is specified (the
646 command is a newline) dot is extended in either direction to
647 line boundaries and printed.
648 If dot is thereby unchanged, it is set to
652 .SS Grouping and multiple changes
653 Commands may be grouped by enclosing them in braces
655 Commands within the braces must appear on separate lines (no backslashes are
656 required between commands).
657 Semantically, an opening brace is like a command:
658 it takes an (optional) address and sets dot for each sub-command.
659 Commands within the braces are executed sequentially, but changes made
660 by one command are not visible to other commands (see the next
662 Braces may be nested arbitrarily.
664 When a command makes a number of changes to a file, as in
666 the addresses of all changes to the file are computed in the original file.
667 If the changes are in sequence,
668 they are applied to the file.
669 Successive insertions at the same address are catenated into a single
670 insertion composed of the several insertions in the order applied.
672 What follows refers to behavior of
674 when downloaded, that is, when
675 operating as a display editor on a raster display.
681 (no download) option provides access
682 to the command language only.
684 Each file may have zero or more windows open.
685 Each window is equivalent
686 and is updated simultaneously with changes in other windows on the same file.
687 Each window has an independent value of dot, indicated by a highlighted
688 substring on the display.
689 Dot may be in a region not within
691 There is usually a `current window',
692 marked with a dark border, to which typed text and editing
694 Text may be typed and edited as in
696 also the escape key (ESC) selects (sets dot to) text typed
697 since the last mouse button hit.
699 The button 3 menu controls window operations.
701 provides the following operators, each of which uses one or
704 cursors to prompt for selection of a window or sweeping
706 `Sweeping' a null rectangle gets a large window, disjoint
707 from the command window or the whole screen, depending on
708 where the null rectangle is.
712 Create a new, empty file.
715 Create a copy of an existing window.
723 In the last window of a file,
735 Below these operators is a list of available files, starting with
738 Selecting a file from the list makes the most recently
739 used window on that file current, unless it is already current, in which
740 case selections cycle through the open windows.
741 If no windows are open
742 on the file, the user is prompted to open one.
745 are marked with one of the characters
747 according as zero, one, or more windows
748 are open on the file.
751 appears on the file in the current window and
754 on a file modified since last write.
756 The command window, created automatically when
758 starts, is an ordinary window except that text typed to it
759 is interpreted as commands for the editor rather than passive text,
760 and text printed by editor commands appears in it.
763 with an `output point' that separates commands being typed from
765 Commands typed in the command window apply to the
766 current open file\(emthe file in the most recently
768 .SS Manipulating text
769 Button 1 changes selection, much like
771 Pointing to a non-current window with button 1 makes it current;
772 within the current window, button 1 selects text, thus setting dot.
773 Double-clicking selects text to the boundaries of words, lines,
774 quoted strings or bracketed strings, depending on the text at the click.
776 Button 2 provides a menu of editing commands:
780 Delete dot and save the deleted text in the snarf buffer.
783 Replace the text in dot by the contents of the snarf buffer.
786 Save the text in dot in the snarf buffer.
789 Send the text in the selection as a plumb
790 message. If the selection is empty,
791 the white-space-delimited block of text is sent as a plumb message
794 attribute defining where the selection lies (see
798 Search forward for the next occurrence of the literal text in dot.
799 If dot is the null string, the text in the snarf buffer is
801 The snarf buffer is unaffected.
804 Exchange snarf buffers with
808 Search forward for the next match of the last regular expression
810 (Not in command window.)
813 Send the text in dot, or the snarf buffer if
814 dot is the null string, as if it were typed to the command window.
815 Saves the sent text in the snarf buffer.
816 (Command window only.)
818 .SS External communication
823 If plumbing is not active,
828 which acts as an additional source of commands. Characters written to
829 the named pipe are treated as if they had been typed in the command window.
832 is a shell-level command that causes an instance of
834 running on the same terminal to load the named
837 uses either plumbing or the named pipe, whichever service is available.
838 If plumbing is not enabled,
839 the option allows a line number to be specified for
840 the initial position to display in the last named file
841 (plumbing provides a more general mechanism for this ability).
844 is a shell-level command that can be used as
846 in a Unix environment.
851 and then does not exit until
853 is changed, which is taken as a signal that
855 is done being edited.
856 .SS Abnormal termination
859 terminates other than by a
861 command (by hangup, deleting its window, etc.), modified
862 files are saved in an
865 This program, when executed, asks whether to write
866 each file back to a external file.
869 causes writing; anything else skips the file.
878 the program called to unpack
881 .TF \*9/src/cmd/samterm
888 .B \*9/src/cmd/samterm
889 source for the separate terminal part
902 ``The text editor sam''.
