Provided by: 9base_6-14_amd64 
NAME
sam, B, E, sam.save, samterm, samsave - screen editor with structural regular expressions
SYNOPSIS
sam [ option ... ] [ files ]
sam -r machine
sam.save
B file[:line] ...
E file
DESCRIPTION
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
-a Autoindent. In this mode, when a newline character is typed in the terminal
interface, samterm copies leading white space on the current line to the new line.
-d Do not `download' the terminal part of sam. Editing will be done with the command
language only, as in ed(1).
-r machine
Run the host part remotely on the specified machine, the terminal part locally.
-s path
Start the host part from the specified file on the remote host. Only meaningful
with the -r option.
-t path
Start the terminal part from the specified file. Useful for debugging.
Regular expressions
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.
Addresses
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.
Simple Addresses
#n The empty string after character n; #0 is the beginning of the file.
n Line n; 0 is the beginning of the file.
/regexp/
?regexp?
The substring that matches the regular expression, found by looking toward the end
(/) or beginning (?) of the file, and if necessary continuing the search from the
other end to the starting point of the search. The matched substring may straddle
the starting point. When entering a pattern containing a literal question mark for
a backward search, the question mark should be specified as a member of a class.
0 The string before the first full line. This is not necessarily the null string;
see + and - below.
$ The null string at the end of the file.
. Dot.
' The mark in the file (see the k command below).
"regexp"
Preceding a simple address (default .), refers to the address evaluated in the
unique file whose menu line matches the regular expression.
Compound Addresses
In the following, a1 and a2 are addresses.
a1+a2 The address a2 evaluated starting at the end of a1.
a1-a2 The address a2 evaluated looking in the reverse direction starting at the beginning
of a1.
a1,a2 The substring from the beginning of a1 to the end of a2. If a1 is missing, 0 is
substituted. If a2 is missing, $ is substituted.
a1;a2 Like a1,a2, but with a2 evaluated at the end of, and dot set to, a1.
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.
Commands
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).
Text commands
a/text/
or
a
lines of text
. Insert the text into the file after the range. Set dot.
c
i Same as a, but c replaces the text, while i inserts before the range.
d Delete the text in the range. Set dot.
s/regexp/text/
Substitute text for the first match to the regular expression in the range. Set
dot to the modified range. In text the character & stands for the string that
matched the expression. Backslash behaves as usual unless followed by a digit: \d
stands for the string that matched the subexpression begun by the d-th left
parenthesis. If s is followed immediately by a number n, as in s2/x/y/, the n-th
match in the range is substituted. If the command is followed by a g, as in
s/x/y/g, all matches in the range are substituted.
m a1
t a1 Move (m) or copy (t) the range to after a1. Set dot.
Display commands
p Print the text in the range. Set dot.
= Print the line address and character address of the range.
=# Print just the character address of the range.
File commands
* b file-list
Set the current file to the first file named in the list that sam also has in its
menu. The list may be expressed <Plan 9 command in which case the file names are
taken as words (in the shell sense) generated by the Plan 9 command.
* B file-list
Same as b, except that file names not in the menu are entered there, and all file
names in the list are examined.
* n Print a menu of files. The format is:
' or blank indicating the file is modified or clean,
- or + indicating the file is unread or has been read (in the terminal, * means
more than one window is open),
. or blank indicating the current file,
a blank,
and the file name.
* D file-list
Delete the named files from the menu. If no files are named, the current file is deleted.
It is an error to D a modified file, but a subsequent D will delete such a file.
I/O Commands
* e filename
Replace the file by the contents of the named external file. Set dot to the
beginning of the file.
r filename
Replace the text in the range by the contents of the named external file. Set dot.
w filename
Write the range (default 0,$) to the named external file.
* f filename
Set the file name and print the resulting menu entry.
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.
< Plan 9-command
Replace the range by the standard output of the Plan 9 command.
> Plan 9-command
Send the range to the standard input of the Plan 9 command.
| Plan 9-command
Send the range to the standard input, and replace it by the standard output, of the
Plan 9 command.
* ! Plan 9-command
Run the Plan 9 command.
* cd directory
Change working directory. If no directory is specified, $home is used.
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.
Loops and Conditionals
x/regexp/ command
For each match of the regular expression in the range, run the command with dot set
to the match. Set dot to the last match. If the regular expression and its
slashes are omitted, is assumed. Null string matches potentially occur before
every character of the range and at the end of the range.
y/regexp/ command
Like x, but run the command for each substring that lies before, between, or after
the matches that would be generated by x. There is no default regular expression.
Null substrings potentially occur before every character in the range.
* X/regexp/ command
For each file whose menu entry matches the regular expression, make that the
current file and run the command. If the expression is omitted, the command is run
in every file.
* Y/regexp/ command
Same as X, but for files that do not match the regular expression, and the
expression is required.
g/regexp/ command
v/regexp/ command
If the range contains (g) or does not contain (v) a match for the expression, set
dot to the range and run the command.
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.
Miscellany
k Set the current file's mark to the range. Does not set dot.
* q Quit. It is an error to quit with modified files, but a second q will succeed.
* u n Undo the last n (default 1) top-level commands that changed the contents or name of
the current file, and any other file whose most recent change was simultaneous with
the current file's change. Successive u's move further back in time. The only
commands for which u is ineffective are cd, u, q, w and D. If n is negative, u
`redoes,' undoing the undo, going forwards in time again.
(empty)
If the range is explicit, set dot to the range. If sam is downloaded, the
resulting dot is selected on the screen; otherwise it is printed. If no address is
specified (the command is a newline) dot is extended in either direction to line
boundaries and printed. If dot is thereby unchanged, it is set to .+1 and printed.
Grouping and multiple changes
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.
The terminal
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.
new Create a new, empty file.
zerox Create a copy of an existing window.
resize As in rio.
close Delete the window. In the last window of a file, close is equivalent to a D for
the file.
write Equivalent to a w for the file.
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.
Manipulating text
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:
cut Delete dot and save the deleted text in the snarf buffer.
paste Replace the text in dot by the contents of the snarf buffer.
snarf Save the text in dot in the snarf buffer.
plumb Send the text in the selection as a plumb message. If the selection is empty, the
white-space-delimited block of text is sent as a plumb message with a click
attribute defining where the selection lies (see plumb(7)).
look Search forward for the next occurrence of the literal text in dot. If dot is the
null string, the text in the snarf buffer is used. The snarf buffer is unaffected.
<rio> Exchange snarf buffers with rio.
/regexp
Search forward for the next match of the last regular expression typed in a
command. (Not in command window.)
send Send the text in dot, or the snarf buffer if dot is the null string, as if it were
typed to the command window. Saves the sent text in the snarf buffer. (Command
window only.)
External communication
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.
Abnormal termination
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.
FILES
$HOME/sam.save
$HOME/sam.err
/bin/samsave
the program called to unpack $HOME/sam.save.
SOURCE
/src/cmd/sam
source for sam itself
/src/cmd/samterm
source for the separate terminal part
/bin/B
/bin/E
SEE ALSO
ed(1), sed(1), grep(1), rio(1), regexp(7).
Rob Pike, ``The text editor sam''.
SAM(1plan9)