|
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.
–i Indent with spaces. In this mode, when a tab character is typed
in the terminal interface, samterm will insert spaces until the
next tabstop. Backspace will delete spaces until the previous
tabstop or another character is encountered.
–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(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 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 .*\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; 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 ?'s, 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 file name and line address of the range.
=# Print the file name and 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 blankindicating 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 blankindicating 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 standard output of the Plan 9 command to the command
window.
|
| 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
| |
Send the range to the standard input, and send the standard output
of the Plan 9 command to the command window.
|
* ! 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.
Sam sets two environmental variables depending on the current
file. $% is set to the file name. $%dot is set to a list consisting
of three values that define the dot.
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 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
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.
Ctrl+b switches to the command window and moves to the end of
the text. Ctrl+g switches to the last focused window. If the focused
window is a text window, ctrl+g switches to the next zeroxed instance
of that window.
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(6)).
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 dot with snarf buffer of rio. If dot is the null string,
the text in the snarf buffer is used.
/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.
B is a shell command that sends the named files to the edit port
of the plumber.
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 y causes writing;
anything else skips the file.
|