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
- -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 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.
-
#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.
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.
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).
-
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.
- 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.
-
* 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.
-
* 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.
-
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.
- 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.
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.
- 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.
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.)
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.
- $HOME/sam.save
- $HOME/sam.err
- /bin/samsave
- the program called to unpack $HOME/sam.save.
- /src/cmd/sam
- source for sam itself
- /src/cmd/samterm
- source for the separate terminal part
- /bin/B
- /bin/E
ed(1),
sed(1),
grep(1),
rio(1),
regexp(7).
Rob Pike, ``The text editor sam''.