From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man1/sam.html | 577 ------------------------------------------------------ 1 file changed, 577 deletions(-) delete mode 100644 man/man1/sam.html (limited to 'man/man1/sam.html') diff --git a/man/man1/sam.html b/man/man1/sam.html deleted file mode 100644 index c27afa63..00000000 --- a/man/man1/sam.html +++ /dev/null @@ -1,577 +0,0 @@ - -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”.
- -
- -

 -
-
- - -
-
-
-Space Glenda -
-
- - -- cgit v1.2.3