NAME
     sam - editor with a command language

SYNOPSIS
     sam [file]

DESCRIPTION
     Sam edits text by command, like ed(1), but with the vocabulary Rob Pike
     gave the original sam at Bell Labs: addresses that name text by its
     contents, and x and y loops that run a command over every piece of the
     file that matches, or every piece that does not.  This is the useful half
     of sam for a machine with no mouse; it corresponds to the original's -d
     mode, which ran without a window system.

     If file is given it is read and its byte count printed.  Commands are
     read a line at a time; there is no prompt.  Dot, written ., is the
     current range of lines, and is the default address for commands that take
     one.

     Two things are smaller here than in the original.  Patterns are matched
     as plain substrings, not regular expressions, so /the/ finds a line
     containing those three letters and nothing cleverer.  And everything is a
     whole number of lines: dot is a line range, not a range of characters, so
     x selects matching lines rather than matching text within them.  In shape
     the x and y commands here are ed's g and v.  Typing h prints a summary.

ADDRESSES
     n    Line n.  A number past the end of the file means the last line.

     .    Dot: the current range.

     $    The last line.

     /pattern/
          The next line after dot containing pattern, wrapping at the end of
          the file.

     ?pattern?
          The same, searching backwards.

     +n

     -n   n lines forward from the end of dot, or back from its start.  The
          number may be omitted, in which case it is 1.

     a1,a2
          The range from a1 to a2.  A leading comma means the whole file, so
          ,p prints everything.  An omitted right address is the last line.

     a1;a2
          The same, but dot is set to a1 before a2 is worked out, so the two
          can chain.

COMMANDS
     An address with no command prints those lines.

     p    Print the addressed lines.

     =    Print the line number of the end of the range.

     a    Append text after the range.

     i    Insert text before it.

     c    Change: replace the range with typed text.

     All three read lines until a line containing only .  is typed.

     d    Delete the addressed lines.

     s/old/new/[g]
          Replace old with new on each addressed line; g replaces every
          occurrence rather than the first.  Any character may be used as the
          delimiter in place of /.

     x/pattern/command
          For each addressed line containing pattern, run command.  With no
          command the matching lines are printed.  The commands understood
          here are p, d, s, a and c; the last two read their text from the
          terminal once per matching line.

     y/pattern/command
          The complement: for each addressed line not containing pattern.
          Only p and d are understood, and p is the default.

     g/pattern/command
          Another name for x.

     w file
          Write the buffer, to the remembered file if none is named, and print
          the byte count.  The file is created if it does not exist.

     e file
          Discard the buffer and read file.  Refuses once if there are unsaved
          changes.

     r file
          Read file in after the addressed line.

     n    Print the filename, whether it is modified, and the line count.

     q    Quit; refuses once if there are unsaved changes.

     Q    Quit regardless.

     h    Print the summary.

EXAMPLES
     Print every line mentioning the mesh:

          sam /n/local/rc/profile
          x/aether/p

     Delete the commented-out lines, then write:

          x/#/d
          w

     Change a port number wherever it appears:

          ,s/8080/70/g
          w

     Print everything that is not blank -- though note that y matches a
     substring, so this catches lines with no space in them at all:

          y/ /p

SEE ALSO
     ed(1), se(1), vi(1), sed(1)

NOTES
     The buffer holds at most 4096 lines and lives in PSRAM, so it is
     considerably roomier than ed's.  Lines longer than 1024 characters are
     split when read.

     Character addresses -- the original's #n -- are parsed and ignored, since
     dot is a line range here.

BUGS
     There is no undo.  Write early.

     x/pattern/a and x/pattern/c prompt for text once for every matching line,
     which is rarely what a person means when the pattern matches forty lines.

FRST Computer                                                           SAM(1)
