sam

SAM(1)                      General Commands Manual                     SAM(1)



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)