sam(1) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man1/sam.html | 577 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 577 insertions(+) create mode 100644 man/man1/sam.html (limited to 'man/man1/sam.html') diff --git a/man/man1/sam.html b/man/man1/sam.html new file mode 100644 index 00000000..c27afa63 --- /dev/null +++ b/man/man1/sam.html @@ -0,0 +1,577 @@ + +sam(1) - Plan 9 from User Space + + + + +

SAM(1) SAM(1) +

+
+

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
+ −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 .*\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 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 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 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, /.*\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 + +
+ + +
+ + 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 y causes writing; + anything else skips the file. + +
+

FILES
+ +
+ + $HOME/sam.save + $HOME/sam.err + /usr/local/plan9/bin/samsave + +
+ + +
+ + the program called to unpack $HOME/sam.save.
+ +
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/sam source for sam itself
+ /usr/local/plan9/src/cmd/samterm source for the separate terminal + part
+ /usr/local/plan9/bin/B + /usr/local/plan9/bin/E + +
+

SEE ALSO
+ +
+ + ed(1), sed(1), grep(1), rio(1), regexp(7). +
+ + Rob Pike, “The text editor sam”.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3