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  termi‐
               nal 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  men‐
               tioned.
 
        [^abc] Match any character not in the square brackets, but never a new‐
               line.  Both these forms accept a range of ASCII characters indi‐
               cated 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.  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 (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 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
        effect 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 ASCII character except alphanumerics.  Any number of
        trailing delimiters may be elided, with multiple elisions  then  repre‐
        senting  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 oth‐
        erwise 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 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 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 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
               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  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.
        (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
        required 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 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 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.   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 pro‐
        vides  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 fur‐
        ther 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.  There is an ‘output point’  that  separates  com‐
        mands  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 but‐
        ton 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.
        ed(1), regexp(7g)
 

BUGS

        When  a  sam  window  is resized, the command window may have the wrong
        size.
 
                                                                         SAM(1)