man(1) Manual page archive


     SAM(9.1)                                                 SAM(9.1)

     NAME
          sam - screen editor with structural regular expressions

     SYNOPSIS
          sam [ option ... ] [ files ]

          sam -r machine

          sam.save

     DESCRIPTION
          Sam is a multi-file editor.  It modifies a local copy of a
          Unix file.  The copy is here called a file; a Unix file is
          distinguished by the trademarked adjective.  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 Unix file from which it was read, and a `modified'
          bit that indicates whether the editor's file agrees with the
          Unix file.  The Unix file is not read into the editor's file
          until it first becomes the current file-that to which edit-
          ing 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.  This extends graphic edit-
               ing to files on machines that don't ordinarily support
               it or across non-nfs(8) connections.

        Regular expressions
          Regular expressions are as in egrep (see gre(1)), with the
          addition of @ and \n.  A regular expression may never con-
          tain 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).

          @    Match any character.

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

     SAM(9.1)                                                 SAM(9.1)

          [^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 cate-
          nation, then | is lowest.  The empty regular expression
          stands for the last complete expression encountered.  A reg-
          ular expression in sam matches the longest leftmost sub-
          string 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 follow-
          ing, `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 begin-
          ning of the file, of the regular expression `.*\n? .'  (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 (?)

     SAM(9.1)                                                 SAM(9.1)

               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.

          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 direc-
               tion 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 miss-
               ing, $ 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 `?''s, the effect of the +
          or - is reversed.

          It is an error for a compound address to represent a mal-
          formed 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

     SAM(9.1)                                                 SAM(9.1)

          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 alphanu-
          merics.  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 delim-
          ited text, newline may not appear literally; \n may be typed
          for newline; and \/ quotes the delimiter, here `/'.  Back-
          slash is otherwise interpreted literally, except in s com-
          mands.

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

     SAM(9.1)                                                 SAM(9.1)

          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
          In these commands a file-list may be expressed <Unix-command
          in which case the file names are taken as words (in the
          shell sense) generated by the Unix command.

          * b file-list
               Set the current file to the first file named in the
               list that sam also has in its menu.

          * 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 exam-
               ined.

          * n  Print a menu of files.  The format is:
               504336.if 600.sp40u
               ' or blank
                    indicating the file is modified or clean,

               - or +
                    indicating the 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 Unix
               file.  Set dot to the beginning of the file.

          r filename
               Replace the text in the range by the contents of the
               named Unix file.  Set dot.

     SAM(9.1)                                                 SAM(9.1)

          w filename
               Write the range (default 0,$) to the named Unix 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.

          < Unix-command
               Replace the range by the standard output of the Unix
               command.

          > Unix-command
               Sends the range to the standard input of the Unix com-
               mand.

          | Unix-command
               Send the range to the standard input, and replace it by
               the standard output, of the Unix command.

          * ! Unix-command
               Run the Unix command.

          * cd directory
               Change working directory.  If no directory is speci-
               fied, $HOME is used.

          In any of <, >, | or !, if the Unix command is omitted the
          last Unix command (of any type) is substituted.  If sam is
          downloaded, ! sets standard input to and otherwise unas-
          signed 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, `/.*\n/' 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

     SAM(9.1)                                                 SAM(9.1)

               For each file whose menu entry matches the regular
               expression, 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 com-
          mand 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 simultane-
               ous 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
          section of this manual).  Braces may be nested arbitrarily.

     SAM(9.1)                                                 SAM(9.1)

          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 inser-
          tions at the same address are catenated into a single inser-
          tion 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 indepen-
          dent 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 bor-
          der, to which typed text and editing commands apply.  Text
          may be typed and edited as in mux(9.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
          prompts with one or more mux-like cursors to prompt for
          selection of a window or sweeping of a rectangle.  `Sweep-
          ing' 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.
          xerox    Create a copy of an existing window.
          reshape  As in mux.
          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 cur-
          rent, 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 cur-
          rent window and a single quote, ', on a file modified since
          last write.

     SAM(9.1)                                                 SAM(9.1)

          Nothing can be done without a command window, for which sam
          prompts initially.  The command window 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 mux,
          with a `command 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 mux. 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 unaf-
               fected.
          <mux>
               Exchange snarf buffers with mux.
          /regexp
               Search forward for the next match of the last regular
               expression typed in a command.  (Not in command win-
               dow.)
          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 win-
               dow only.)
          scroll
          noscroll
               Select whether to reveal automatically text that
               appears off the end of the command window.  (Command
               window only.)

        Abnormal termination
          If sam terminates other than by a q command (by hangup,
          deleting its layer, etc.), modified files are saved in an
          executable file, This program, when executed, asks whether
          to write each file back to a Unix file.  The answer `y'
          causes writing; anything else skips the file.

     SAM(9.1)                                                 SAM(9.1)

     FILES
     SEE ALSO
          ed(1), sed(1), vi(1), gre(1)

     BUGS
          The u command undoes characters-and backspaces-typed
          directly into a file window in unpredictable increments.