Provided by: 9base_6-14_amd64 bug

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

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

   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,  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  causes
       writing; anything else skips the file.

FILES

       $HOME/sam.save

       $HOME/sam.err

       /bin/samsave
              the program called to unpack $HOME/sam.save.

SOURCE

       /src/cmd/sam
              source for sam itself

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

       /bin/B

       /bin/E

SEE ALSO

       ed(1), sed(1), grep(1), rio(1), regexp(7).

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

                                                                                      SAM(1plan9)