SAM(1)							      General Commands Manual							    SAM(1)

NAME

       sam, B, sam.save - screen editor with structural regular expressions

SYNOPSIS

       sam [ option ...  ] [ files ]

       sam -r machine

       sam.save

       B [ -nnnn ] 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(6) with the addition of 
 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
       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  neces-
	      sary  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  substi-
       tuted.	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.)  ./reg-
       exp/// 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; 
 may be typed for newline; and / quotes the delimiter, here Backslash is other-
       wise 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 com-
       mand 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 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 sub-
       sequent 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 bitmap 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, 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.

       (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 origi-
       nal  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  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 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 81/2(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
       81/2-like  cursors  to  prompt for selection of a window or sweeping of a rectangle.  `Sweeping' a null rectangle gets a large window, dis-
       joint 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.

       reshape
	      As in 81/2.

       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 81/2, 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 81/2.  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 unaffected.

       <81/2> Exchange snarf buffers with 81/2.

       /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
       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.  This is usually used to issue B commands from the shell.

       B is a shell-level command that causes an instance of sam running on the same terminal to load the named files.	The option allows  a  line
       number to be specified for the initial position to display in the last named file.

   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 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.

SOURCE

       /sys/src/cmd/sam
	      source for sam itself

       /sys/src/cmd/samterm
	      source for the separate terminal part

       /rc/bin/B

SEE ALSO

       ed(1), sed(1), grep(1), 81/2(1), regexp(6).

       Rob Pike, ``The text editor sam''.

																	    SAM(1)