4 sam, B, sam.save, samterm \- 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 Autoindent. In this mode, when a newline character is typed
45 in the terminal interface,
47 copies leading white space on the current line to the new line.
51 In this mode, when a tab character is typed
52 in the terminal interface,
54 will insert spaces until the next tabstop.
55 Backspace will delete spaces until the previous tabstop
56 or another character is encountered.
59 Do not `download' the terminal part of
61 Editing will be done with the command language only, as in
65 Run the host part remotely
66 on the specified machine, the terminal part locally.
69 Start the host part from the specified file on the remote host.
70 Only meaningful with the
75 Start the terminal part from the specified file. Useful
78 .SS Regular expressions
79 Regular expressions are as in
83 to represent newlines.
84 A regular expression may never contain a literal newline character.
86 regular expression stands for the last complete expression encountered.
87 A regular expression in
89 matches the longest leftmost substring formally
90 matched by the expression.
91 Searching in the reverse direction is equivalent
92 to searching backwards with the catenation operations reversed in
95 An address identifies a substring in a file.
96 In the following, `character
101 character in the file, with 1 the
102 first character in the file.
108 starting at the beginning of the file, of the regular expression
110 All files always have a current substring, called dot,
111 that is the default address.
116 The empty string after character
119 is the beginning of the file.
125 is the beginning of the file.
131 The substring that matches the regular expression,
132 found by looking toward the end
137 and if necessary continuing the search from the other end to the
138 starting point of the search.
139 The matched substring may straddle
141 When entering a pattern containing a literal question mark
142 for a backward search, the question mark should be
143 specified as a member of a class.
147 The string before the first full line.
148 This is not necessarily
156 The null string at the end of the file.
162 The mark in the file (see the
166 \fB"\f2regexp\fB"\f1\f1
167 Preceding a simple address (default
169 refers to the address evaluated in the unique file whose menu line
170 matches the regular expression.
172 .SS Compound Addresses
183 evaluated starting at the end of
189 evaluated looking in the reverse direction
190 starting at the beginning of
194 The substring from the beginning of
214 evaluated at the end of, and dot set to,
222 are high precedence, while
234 is a line or character address with a missing
235 number, the number defaults to 1.
245 are present and distinguishable,
250 expression; if it is delimited by
258 It is an error for a compound address to represent a malformed substring.
262 selects the line containing
263 the end (beginning) of a1.
265 locates the first match of the expression in the file.
268 sets dot unnecessarily.)
270 finds the second following occurrence of the expression,
275 In the following, text demarcated by slashes represents text delimited
277 character except alphanumerics.
279 trailing delimiters may be elided, with multiple elisions then representing
280 null strings, but the first delimiter must always
282 In any delimited text,
283 newline may not appear literally;
285 may be typed for newline; and
287 quotes the delimiter, here
289 Backslash is otherwise interpreted literally, except in
293 Most commands may be prefixed by an address to indicate their range
295 Those that may not are marked with a
299 an address and none is supplied, dot is used.
300 The sole exception is
303 command, which defaults to
305 In the description, `range' is used
306 to represent whatever address is supplied.
307 Many commands set the
308 value of dot as a side effect.
309 If so, it is always set to the `result'
310 of the change: the empty string for a deletion, the new text for an
311 insertion, etc. (but see the
330 Insert the text into the file after the range.
343 replaces the text, while
350 Delete the text in the range.
353 .BI s/ regexp / text /
356 for the first match to the regular expression in the range.
357 Set dot to the modified range.
362 stands for the string
363 that matched the expression.
364 Backslash behaves as usual unless followed by
367 stands for the string that matched the
368 subexpression begun by the
373 is followed immediately by a
380 match in the range is substituted.
382 command is followed by a
386 all matches in the range
405 Print the text in the range.
409 Print the line address and character address of the range.
412 Print just the character address of the range.
418 Set the current file to the first file named in the list
421 also has in its menu.
422 The list may be expressed
423 .BI < "Plan 9 command"
424 in which case the file names are taken as words (in the shell sense)
425 generated by the Plan 9 command.
430 except that file names not in the menu are entered there,
431 and all file names in the list are examined.
434 Print a menu of files.
439 indicating the file is modified or clean,
442 indicating the file is unread or has been read
445 means more than one window is open),
448 indicating the current file,
456 Delete the named files from the menu.
457 If no files are named, the current file is deleted.
460 a modified file, but a subsequent
462 will delete such a file.
468 Replace the file by the contents of the named external file.
469 Set dot to the beginning of the file.
472 Replace the text in the range by the contents of the named external file.
476 Write the range (default
478 to the named external file.
481 Set the file name and print the resulting menu entry.
483 If the file name is absent from any of these, the current file name is used.
485 always sets the file name;
489 do so if the file has no name.
491 .BI < " Plan 9-command
492 Replace the range by the standard output of the
495 .BI > " Plan 9-command
496 Send the range to the standard input of the
499 .BI | " Plan 9-command
500 Send the range to the standard input, and replace it by
501 the standard output, of the
504 .BI \*a! " Plan 9-command
508 .BI \*acd " directory
509 Change working directory.
510 If no directory is specified,
525 (of any type) is substituted.
530 (using the mouse and raster display, i.e. not using option
533 sets standard input to
543 for all) is placed in
545 and the first few lines are printed.
546 .SS Loops and Conditionals
549 .BI x/ regexp / " command
550 For each match of the regular expression in the range, run the command
551 with dot set to the match.
552 Set dot to the last match.
554 expression and its slashes are omitted,
557 Null string matches potentially occur before every character
558 of the range and at the end of the range.
560 .BI y/ regexp / " command
563 but run the command for each substring that lies before, between,
565 the matches that would be generated by
567 There is no default regular expression.
568 Null substrings potentially occur before every character
571 .BI \*aX/ regexp / " command
572 For each file whose menu entry matches the regular expression,
573 make that the current file and
575 If the expression is omitted, the command is run
578 .BI \*aY/ regexp / " command
581 but for files that do not match the regular expression,
582 and the expression is required.
584 .BI g/ regexp / " command
588 .BI v/ regexp / " command
589 If the range contains
593 a match for the expression,
594 set dot to the range and run the command.
596 These may be nested arbitrarily deeply, but only one instance of either
600 may appear in a \%single command.
601 An empty command in an
616 do not have defaults.
622 Set the current file's mark to the range. Does not set dot.
626 It is an error to quit with modified files, but a second
634 top-level commands that changed the contents or name of the
635 current file, and any other file whose most recent change was simultaneous
636 with the current file's change.
639 move further back in time.
640 The only commands for which u is ineffective are
651 `redoes,' undoing the undo, going forwards in time again.
654 If the range is explicit, set dot to the range.
657 is downloaded, the resulting dot is selected on the screen;
658 otherwise it is printed.
659 If no address is specified (the
660 command is a newline) dot is extended in either direction to
661 line boundaries and printed.
662 If dot is thereby unchanged, it is set to
666 .SS Grouping and multiple changes
667 Commands may be grouped by enclosing them in braces
669 Commands within the braces must appear on separate lines (no backslashes are
670 required between commands).
671 Semantically, an opening brace is like a command:
672 it takes an (optional) address and sets dot for each sub-command.
673 Commands within the braces are executed sequentially, but changes made
674 by one command are not visible to other commands (see the next
676 Braces may be nested arbitrarily.
678 When a command makes a number of changes to a file, as in
680 the addresses of all changes to the file are computed in the original file.
681 If the changes are in sequence,
682 they are applied to the file.
683 Successive insertions at the same address are catenated into a single
684 insertion composed of the several insertions in the order applied.
686 What follows refers to behavior of
688 when downloaded, that is, when
689 operating as a display editor on a raster display.
695 (no download) option provides access
696 to the command language only.
698 Each file may have zero or more windows open.
699 Each window is equivalent
700 and is updated simultaneously with changes in other windows on the same file.
701 Each window has an independent value of dot, indicated by a highlighted
702 substring on the display.
703 Dot may be in a region not within
705 There is usually a `current window',
706 marked with a dark border, to which typed text and editing
708 Text may be typed and edited as in
710 also the escape key (ESC) selects (sets dot to) text typed
711 since the last mouse button hit.
713 The button 3 menu controls window operations.
715 provides the following operators, each of which uses one or
718 cursors to prompt for selection of a window or sweeping
720 `Sweeping' a null rectangle gets a large window, disjoint
721 from the command window or the whole screen, depending on
722 where the null rectangle is.
726 Create a new, empty file.
729 Create a copy of an existing window.
737 In the last window of a file,
749 Below these operators is a list of available files, starting with
752 Selecting a file from the list makes the most recently
753 used window on that file current, unless it is already current, in which
754 case selections cycle through the open windows.
755 If no windows are open
756 on the file, the user is prompted to open one.
759 are marked with one of the characters
761 according as zero, one, or more windows
762 are open on the file.
765 appears on the file in the current window and
768 on a file modified since last write.
770 The command window, created automatically when
772 starts, is an ordinary window except that text typed to it
773 is interpreted as commands for the editor rather than passive text,
774 and text printed by editor commands appears in it.
777 with an `output point' that separates commands being typed from
779 Commands typed in the command window apply to the
780 current open file\(emthe file in the most recently
782 .SS Manipulating text
783 Button 1 changes selection, much like
785 Pointing to a non-current window with button 1 makes it current;
786 within the current window, button 1 selects text, thus setting dot.
787 Double-clicking selects text to the boundaries of words, lines,
788 quoted strings or bracketed strings, depending on the text at the click.
790 Button 2 provides a menu of editing commands:
794 Delete dot and save the deleted text in the snarf buffer.
797 Replace the text in dot by the contents of the snarf buffer.
800 Save the text in dot in the snarf buffer.
803 Send the text in the selection as a plumb
804 message. If the selection is empty,
805 the white-space-delimited block of text is sent as a plumb message
808 attribute defining where the selection lies (see
812 Search forward for the next occurrence of the literal text in dot.
813 If dot is the null string, the text in the snarf buffer is
815 The snarf buffer is unaffected.
818 Exchange snarf buffers with
822 Search forward for the next match of the last regular expression
824 (Not in command window.)
827 Send the text in dot, or the snarf buffer if
828 dot is the null string, as if it were typed to the command window.
829 Saves the sent text in the snarf buffer.
830 (Command window only.)
832 .SS External communication
837 If plumbing is not active,
842 which acts as an additional source of commands. Characters written to
843 the named pipe are treated as if they had been typed in the command window.
846 is a shell-level command that causes an instance of
848 running on the same terminal to load the named
851 uses either plumbing or the named pipe, whichever service is available.
852 If plumbing is not enabled,
853 the option allows a line number to be specified for
854 the initial position to display in the last named file
855 (plumbing provides a more general mechanism for this ability).
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.
871 .TF /sys/src/cmd/samterm
878 the program called to unpack
881 .TF /sys/src/cmd/samterm
888 .B /sys/src/cmd/samterm
889 source for the separate terminal part
900 ``The text editor sam''.