Provided by: sam_4.3-18.2_i386 bug

NAME

       sam - 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 file
              Start  the host part from the indicated file on the remote host.
              Only meaningful with the -r option.

       -t path
              Start the terminal part from the  indicated  file.   Useful  for
              debugging.

       The standard X11 -geom toolkit option can be used to select the desired
       window geometry.

   Regular expressions
       Regular expressions are as in regexp(7g) with the  addition  of  \n  to
       represent  newlines.   A regular expression may never contain a literal
       newline character.  The elements of regular expressions are:

       .      Match any character except newline.

       \n     Match newline.

       \x     For any character except n match the character (here x).

       [abc]  Match  any  character  in  the  square  brackets.   \n  may   be
              mentioned.

       [^abc] Match  any  character  not  in  the square brackets, but never a
              newline.  Both these forms accept a range  of  ASCII  characters
              indicated by a dash, as in a-z.

       ^      Match the null string immediately after a newline.

       $      Match the null string immediately before a newline.

       Any other character except newline matches itself.

       In the following, r1 and r2 are regular expressions.

       (r1)   Match what r1 matches.

       r1|r2  Match what r1 or what r2 matches.

       r1*    Match zero or more adjacent matches of r1.

       r1+    Match one or more adjacent matches of r1.

       r1?    Match zero or one matches of r1.

       The operators *, + and ?  are highest precedence, then catenation, then
       | is lowest.  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
       (The  peculiar  properties  of  a  last  line  without  a  newline  are
       temporarily  undefined.)   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.

       /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 ASCII 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 the range to after a1 (m), or copy it (t).  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 <shell
              command in which case the file names are taken as words (in  the
              shell sense) generated by the shell 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.
       < shell-command
              Replace the range by the standard output of the shell command.
       > shell-command
              Sends the range to the standard input of the shell command.
       | shell-command
              Send  the  range  to  the  standard input, and replace it by the
              standard output, of the shell command.
       * ! shell-command
              Run the shell command.
       * cd directory
              Change working directory.  If no directory is  specified,  $HOME
              is used.
       In  any of <, >, | or !, if the shell command is omitted the last shell
       command (of any type) is substituted.  If sam is  downloaded,  !   sets
       standard input to and otherwise unassigned output (stdout for !  and >,
       stderr for all) is placed in 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 behavior.  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 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 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.  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
       cursors to prompt for selection of a window or sweeping of a rectangle.

       new    Create  a  new, empty file: Depress button 3 where one corner of
              the new rectangle should appear (box cursor), and move the mouse
              while  holding  down button 3 to the diagonally opposite corner.
              ‘Sweeping’ a null rectangle gets a large window,  disjoint  from
              the  command  window or the whole sam window, depending on where
              the null rectangle is.

       xerox  Create a copy of an existing window.  After selecting the window
              to copy with button 1, sweep out the window for the copy.

       reshape
              Change  the size and location of a window.  First click button 3
              in the window to be changed (gunsight cursor).  Then sweep out a
              window as for the new menu selection.

       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.   There  is 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
       Typed characters replace the current selection  (dot)  in  the  current
       window.   Backspace  deletes  the  previous  character.  Escape selects
       (sets dot to) everything typed since the last mouse hit.

       Button 1 changes selection.  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.

       <exch> Exchange the snarf buffer with the current selection in  another
              X11  window.  The exchange of a large amount of selected text is
              truncated to the size of Sam’s internal snarf buffer  (currently
              4K) without warning.

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

   X11 resources
       Various attributes of sam can be set by giving values to X11  resources
       for the class Sam.  There are various ways to do this; one is to have a
       file called Sam in your home directory, with entries in it like:

           Sam*width: 500
           Sam*height: 600
           Sam*font: fixed
           Sam*scrollForwardR: true

       In addition to the usual  X11  toolkit  resources,  the  scrollForwardR
       resource  says  where  the  right  button (button 3) scrolls forward or
       backward in the 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, This
       program, when executed, asks whether to  write  each  file  back  to  a
       external  file.   The  answer  causes  writing; anything else skips the
       file.  If a machine crash prevents the creation of a file, all  changes
       are  lost.  If an editing session is difficult to replicate, you should
       write your changed files often.

       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.

FILES

       <system-dependent   dirctory>/samsave  the  program  called  to  unpack
       $home/sam.save.

SEE ALSO

       ed(1), regexp(7g)

BUGS

       When a sam window is resized, the command window  may  have  the  wrong
       size.

                                                                        SAM(1)