glenda.party
term% ls -F
term% pwd
$home/manuals/9front/1/sam
term% cat index.txt
SAM(1)                      General Commands Manual                     SAM(1)



NAME
       sam,  B,  sam.save, samterm - screen editor with structural regular ex‐
       pressions

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 op‐
       tions 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  termi‐
              nal 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 de‐
              bugging.

   Regular expressions
       Regular expressions are as in regexp(6) with the addition of \n to rep‐
       resent newlines.  A regular expression may never contain a literal new‐
       line  character.  The empty regular expression stands for the last com‐
       plete expression encountered.  A regular expression in sam matches  the
       longest leftmost substring formally matched by the expression.  Search‐
       ing 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, `char‐
       acter 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 start‐
              ing 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 start‐
              ing 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  substi‐
              tuted.

       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 prece‐
       dence.

       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  ef‐
       fect of the + or - is reversed.

       It  is  an  error  for a compound address to represent a malformed sub‐
       string.  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 trail‐
       ing 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 in‐
       terpreted 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 `re‐
       sult' 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 charac‐
              ter & stands for the string that matched the expression.   Back‐
              slash 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 cur‐
       rent 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  ex‐
              ternal 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 out‐
              put of the Plan 9 command to the command window.
       * ! 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 (us‐
       ing  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  as‐
              sumed.  Null string matches potentially occur before every char‐
              acter 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  poten‐
              tially 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  expres‐
              sion is omitted, the command is run in every file.
       * Y/regexp/ command
              Same  as  X, but for files that do not match the regular expres‐
              sion, 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 down‐
              loaded, 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 re‐
       quired between commands).  Semantically, an opening  brace  is  like  a
       command:  it takes an (optional) address and sets dot for each sub-com‐
       mand.  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 equiva‐
       lent 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.

       The button 3 menu controls window operations.  The top of the menu pro‐
       vides  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 com‐
       mand 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 -+* ac‐
       cording 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  ordi‐
       nary window except that text typed to it is interpreted as commands for
       the editor rather than passive text, and text printed  by  editor  com‐
       mands  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, but‐
       ton 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  se‐
              lection  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 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  in‐
       vocation  sam creates a named pipe /srv/sam.user which acts as an addi‐
       tional 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 en‐
       abled, 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).

   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), rio(1), regexp(6).

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



                                                                        SAM(1)