SAM(1) SAM(1)
NAME
sam - screen editor with structural regular expressions
SYNOPSIS
sam [ option ... ] [ files ]
sam -r machine
sam.save
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 cur-
rent file-that to which editing commands apply-whereupon its
menu entry is printed. The options are
-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. Use-
ful for debugging.
Regular expressions
Regular expressions are as in regexp(6) 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 encoun-
tered. A regular expression in sam matches the longest
leftmost substring formally matched by the expression.
Searching in the reverse direction is equivalent to search-
ing backwards with the catenation operations reversed in the
expression.
Addresses
An address identifies a substring in a file. In the
Page 1 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
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 begin-
ning of the file, of the regular expression `.*\n? .' 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.
/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.
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 direc-
tion 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 miss-
ing, $ is substituted.
a1;a2
Like a1,a2, but with a2 evaluated at the end of, and
Page 2 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
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 `?''s, the effect of the +
or - is reversed.
It is an error for a compound address to represent a mal-
formed 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 multi-
ple 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 new-
line; 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.
Page 3 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
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 sub-
stituted. 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 the range to after a1 (m), or copy it (t). 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 exam-
ined.
* n Print a menu of files. The format is:
504336.if 600.sp 40u
' 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.
Page 4 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
* 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
Sends 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 speci-
fied, $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, ! sets standard input to /dev/null, and other-
wise unassigned output (stdout for ! and >, stderr for all)
is placed in /tmp/sam.err and the first few lines are
printed.
Page 5 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
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, `/.*\n/' 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 behavior. 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 com-
mand. 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 com-
mand 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 simultane-
ous 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.
Page 6 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
(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 inser-
tions at the same address are catenated into a single inser-
tion 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 bitmap 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 indepen-
dent 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 bor-
der, to which typed text and editing commands apply. Text
may be typed and edited as in 8½(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 8½-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.
Page 7 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
new Create a new, empty file.
xerox Create a copy of an existing window.
reshape As in 8½.
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 cur-
rent, 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 cur-
rent 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 inter-
preted as commands for the editor rather than passive text,
and text printed by editor commands appears in it. The
behavior is like 8½, 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 8½. 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.
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 unaf-
fected.
<8½> Exchange snarf buffers with 8½.
/regexp
Search forward for the next match of the last regular
expression typed in a command. (Not in command
Page 8 Plan 9 (printed 12/30/24)
SAM(1) SAM(1)
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 win-
dow only.)
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 exe-
cuted, asks whether to write each file back to a external
file. The answer `y' causes writing; anything else skips
the file.
FILES
$home/sam.save
$home/sam.err
/sys/lib/samsave the program called to unpack
$home/sam.save.
SEE ALSO
ed(1), sed(1), grep(1), 8½(1), regexp(6).
Page 9 Plan 9 (printed 12/30/24)