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 standard output of the Plan 9 command
501 to the command window.
503 .BI | " Plan 9-command
504 Send the range to the standard input, and replace it by
505 the standard output, of the
508 .BI _ " Plan 9-command
509 Send the range to the standard input, and send the
510 standard output of the Plan 9 command to the command
513 .BI \*a! " Plan 9-command
517 .BI \*acd " directory
518 Change working directory.
519 If no directory is specified,
536 (of any type) is substituted.
541 (using the mouse and raster display, i.e. not using option
544 sets standard input to
554 for all) is placed in
556 and the first few lines are printed.
557 .SS Loops and Conditionals
560 .BI x/ regexp / " command
561 For each match of the regular expression in the range, run the command
562 with dot set to the match.
563 Set dot to the last match.
565 expression and its slashes are omitted,
568 Null string matches potentially occur before every character
569 of the range and at the end of the range.
571 .BI y/ regexp / " command
574 but run the command for each substring that lies before, between,
576 the matches that would be generated by
578 There is no default regular expression.
579 Null substrings potentially occur before every character
582 .BI \*aX/ regexp / " command
583 For each file whose menu entry matches the regular expression,
584 make that the current file and
586 If the expression is omitted, the command is run
589 .BI \*aY/ regexp / " command
592 but for files that do not match the regular expression,
593 and the expression is required.
595 .BI g/ regexp / " command
599 .BI v/ regexp / " command
600 If the range contains
604 a match for the expression,
605 set dot to the range and run the command.
607 These may be nested arbitrarily deeply, but only one instance of either
611 may appear in a \%single command.
612 An empty command in an
627 do not have defaults.
633 Set the current file's mark to the range. Does not set dot.
637 It is an error to quit with modified files, but a second
645 top-level commands that changed the contents or name of the
646 current file, and any other file whose most recent change was simultaneous
647 with the current file's change.
650 move further back in time.
651 The only commands for which u is ineffective are
662 `redoes,' undoing the undo, going forwards in time again.
665 If the range is explicit, set dot to the range.
668 is downloaded, the resulting dot is selected on the screen;
669 otherwise it is printed.
670 If no address is specified (the
671 command is a newline) dot is extended in either direction to
672 line boundaries and printed.
673 If dot is thereby unchanged, it is set to
677 .SS Grouping and multiple changes
678 Commands may be grouped by enclosing them in braces
680 Commands within the braces must appear on separate lines (no backslashes are
681 required between commands).
682 Semantically, an opening brace is like a command:
683 it takes an (optional) address and sets dot for each sub-command.
684 Commands within the braces are executed sequentially, but changes made
685 by one command are not visible to other commands (see the next
687 Braces may be nested arbitrarily.
689 When a command makes a number of changes to a file, as in
691 the addresses of all changes to the file are computed in the original file.
692 If the changes are in sequence,
693 they are applied to the file.
694 Successive insertions at the same address are catenated into a single
695 insertion composed of the several insertions in the order applied.
697 What follows refers to behavior of
699 when downloaded, that is, when
700 operating as a display editor on a raster display.
706 (no download) option provides access
707 to the command language only.
709 Each file may have zero or more windows open.
710 Each window is equivalent
711 and is updated simultaneously with changes in other windows on the same file.
712 Each window has an independent value of dot, indicated by a highlighted
713 substring on the display.
714 Dot may be in a region not within
716 There is usually a `current window',
717 marked with a dark border, to which typed text and editing
719 Text may be typed and edited as in
721 also the escape key (ESC) selects (sets dot to) text typed
722 since the last mouse button hit.
724 Ctrl+b switches to the command window and moves to the end
727 The button 3 menu controls window operations.
729 provides the following operators, each of which uses one or
732 cursors to prompt for selection of a window or sweeping
734 `Sweeping' a null rectangle gets a large window, disjoint
735 from the command window or the whole screen, depending on
736 where the null rectangle is.
740 Create a new, empty file.
743 Create a copy of an existing window.
751 In the last window of a file,
763 Below these operators is a list of available files, starting with
766 Selecting a file from the list makes the most recently
767 used window on that file current, unless it is already current, in which
768 case selections cycle through the open windows.
769 If no windows are open
770 on the file, the user is prompted to open one.
773 are marked with one of the characters
775 according as zero, one, or more windows
776 are open on the file.
779 appears on the file in the current window and
782 on a file modified since last write.
784 The command window, created automatically when
786 starts, is an ordinary window except that text typed to it
787 is interpreted as commands for the editor rather than passive text,
788 and text printed by editor commands appears in it.
791 with an `output point' that separates commands being typed from
793 Commands typed in the command window apply to the
794 current open file\(emthe file in the most recently
796 .SS Manipulating text
797 Button 1 changes selection, much like
799 Pointing to a non-current window with button 1 makes it current;
800 within the current window, button 1 selects text, thus setting dot.
801 Double-clicking selects text to the boundaries of words, lines,
802 quoted strings or bracketed strings, depending on the text at the click.
804 Button 2 provides a menu of editing commands:
808 Delete dot and save the deleted text in the snarf buffer.
811 Replace the text in dot by the contents of the snarf buffer.
814 Save the text in dot in the snarf buffer.
817 Send the text in the selection as a plumb
818 message. If the selection is empty,
819 the white-space-delimited block of text is sent as a plumb message
822 attribute defining where the selection lies (see
826 Search forward for the next occurrence of the literal text in dot.
827 If dot is the null string, the text in the snarf buffer is
829 The snarf buffer is unaffected.
832 Exchange snarf buffers with
836 Search forward for the next match of the last regular expression
838 (Not in command window.)
841 Send the text in dot, or the snarf buffer if
842 dot is the null string, as if it were typed to the command window.
843 Saves the sent text in the snarf buffer.
844 (Command window only.)
846 .SS External communication
851 If plumbing is not active,
856 which acts as an additional source of commands. Characters written to
857 the named pipe are treated as if they had been typed in the command window.
860 is a shell-level command that causes an instance of
862 running on the same terminal to load the named
865 uses either plumbing or the named pipe, whichever service is available.
866 If plumbing is not enabled,
867 the option allows a line number to be specified for
868 the initial position to display in the last named file
869 (plumbing provides a more general mechanism for this ability).
870 .SS Abnormal termination
873 terminates other than by a
875 command (by hangup, deleting its window, etc.), modified
876 files are saved in an
879 This program, when executed, asks whether to write
880 each file back to a external file.
883 causes writing; anything else skips the file.
885 .TF /sys/src/cmd/samterm
892 the program called to unpack
895 .TF /sys/src/cmd/samterm
902 .B /sys/src/cmd/samterm
903 source for the separate terminal part
914 ``The text editor sam''.