| SAM(1plan9) | SAM(1plan9) |
sam, B, E, sam.save, samterm, samsave - screen editor with structural regular expressions
sam [ option ... ] [ files ]
sam -r machine
sam.save
B file[:line] ...
E file
Sam is a multi-file editor. It modifies a local copy of an external file. The copy is here called a file. The files are listed in a menu available through mouse button 3 or the n command. Each file has an associated name, usually the name of the external file from which it was read, and a `modified' bit that indicates whether the editor's file agrees with the external file. The external file is not read into the editor's file until it first becomes the current file—that to which editing commands apply—whereupon its menu entry is printed. The options are
Regular expressions are as in regexp(7) with the addition of \n to represent newlines. A regular expression may never contain a literal newline character. The empty regular expression stands for the last complete expression encountered. A regular expression in sam matches the longest leftmost substring formally matched by the expression. Searching in the reverse direction is equivalent to searching backwards with the catenation operations reversed in the expression.
An address identifies a substring in a file. In the following, `character n' means the null string after the n-th character in the file, with 1 the first character in the file. `Line n' means the n-th match, starting at the beginning of the file, of the regular expression All files always have a current substring, called dot, that is the default address.
In the following, a1 and a2 are addresses.
The operators + and - are high precedence, while , and ; are low precedence.
In both + and - forms, if a2 is a line or character address with a missing number, the number defaults to 1. If a1 is missing, is substituted. If both a1 and a2 are present and distinguishable, + may be elided. a2 may be a regular expression; if it is delimited by the effect of the + or - is reversed.
It is an error for a compound address to represent a malformed substring. Some useful idioms: a1+- (a1-+) selects the line containing the end (beginning) of a1. 0/regexp/ locates the first match of the expression in the file. (The form 0;// sets dot unnecessarily.) ./regexp/// finds the second following occurrence of the expression, and .,/regexp/ extends dot.
In the following, text demarcated by slashes represents text delimited by any printable character except alphanumerics. Any number of trailing delimiters may be elided, with multiple elisions then representing null strings, but the first delimiter must always be present. In any delimited text, newline may not appear literally; \n may be typed for newline; and \/ quotes the delimiter, here Backslash is otherwise interpreted literally, except in s commands.
Most commands may be prefixed by an address to indicate their
range of operation. Those that may not are marked with a below. If a command
takes an address and none is supplied, dot is used. The sole exception is
the w command, which defaults to 0,$. In the description,
`range' is used to represent whatever address is supplied. Many commands set
the value of dot as a side effect. If so, it is always set to the `result'
of the change: the empty string for a deletion, the new text for an
insertion, etc. (but see the s and e commands).
If the file name is absent from any of these, the current file name is used. e always sets the file name; r and w do so if the file has no name.
In any of <, >, | or !, if the Plan 9 command is omitted the last Plan 9 command (of any type) is substituted. If sam is downloaded (using the mouse and raster display, i.e. not using option -d), ! sets standard input to /dev/null, and otherwise unassigned output (stdout for ! and >, stderr for all) is placed in /tmp/sam.err and the first few lines are printed.
These may be nested arbitrarily deeply, but only one instance of either X or Y may appear in a single command. An empty command in an x or y defaults to p; an empty command in X or Y defaults to f. g and v do not have defaults.
Commands may be grouped by enclosing them in braces {}. Commands within the braces must appear on separate lines (no backslashes are required between commands). Semantically, an opening brace is like a command: it takes an (optional) address and sets dot for each sub-command. Commands within the braces are executed sequentially, but changes made by one command are not visible to other commands (see the next paragraph). Braces may be nested arbitrarily.
When a command makes a number of changes to a file, as in x/re/c/text/, the addresses of all changes to the file are computed in the original file. If the changes are in sequence, they are applied to the file. Successive insertions at the same address are catenated into a single insertion composed of the several insertions in the order applied.
What follows refers to behavior of sam when downloaded, that is, when operating as a display editor on a raster display. This is the default behavior; invoking sam with the -d (no download) option provides access to the command language only.
Each file may have zero or more windows open. Each window is equivalent and is updated simultaneously with changes in other windows on the same file. Each window has an independent value of dot, indicated by a highlighted substring on the display. Dot may be in a region not within the window. There is usually a `current window', marked with a dark border, to which typed text and editing commands apply. Text may be typed and edited as in rio(1); also the escape key (ESC) selects (sets dot to) text typed since the last mouse button hit.
The button 3 menu controls window operations. The top of the menu provides the following operators, each of which uses one or more rio-like cursors to prompt for selection of a window or sweeping of a rectangle. `Sweeping' a null rectangle gets a large window, disjoint from the command window or the whole screen, depending on where the null rectangle is.
Below these operators is a list of available files, starting with ~~sam~~, the command window. Selecting a file from the list makes the most recently used window on that file current, unless it is already current, in which case selections cycle through the open windows. If no windows are open on the file, the user is prompted to open one. Files other than ~~sam~~ are marked with one of the characters -+* according as zero, one, or more windows are open on the file. A further mark appears on the file in the current window and a single quote, ', on a file modified since last write.
The command window, created automatically when sam starts, is an ordinary window except that text typed to it is interpreted as commands for the editor rather than passive text, and text printed by editor commands appears in it. The behavior is like rio, with an `output point' that separates commands being typed from previous output. Commands typed in the command window apply to the current open file—the file in the most recently current window.
Button 1 changes selection, much like rio. Pointing to a non-current window with button 1 makes it current; within the current window, button 1 selects text, thus setting dot. Double-clicking selects text to the boundaries of words, lines, quoted strings or bracketed strings, depending on the text at the click.
Button 2 provides a menu of editing commands:
Sam listens to the edit plumb port. If plumbing is not active, on invocation sam creates a named pipe /srv/sam.user which acts as an additional source of commands. Characters written to the named pipe are treated as if they had been typed in the command window.
B is a shell-level command that causes an instance of sam running on the same terminal to load the named files. B uses either plumbing or the named pipe, whichever service is available. If plumbing is not enabled, the option allows a line number to be specified for the initial position to display in the last named file (plumbing provides a more general mechanism for this ability).
E is a shell-level command that can be used as $EDITOR in a Unix environment. It runs B on file and then does not exit until file is changed, which is taken as a signal that file is done being edited.
If sam terminates other than by a q command (by hangup, deleting its window, etc.), modified files are saved in an executable file, $HOME/sam.save. This program, when executed, asks whether to write each file back to a external file. The answer causes writing; anything else skips the file.
ed(1), sed(1), grep(1), rio(1), regexp(7).
Rob Pike, ``The text editor sam''.