sam man page on Plan9

Printed from http://www.polarhome.com/service/man/?qf=sam&af=0&tf=2&of=Plan9

SAM(1)									SAM(1)

NAME
       sam,  B,	 sam.save,  samterm  -	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

       -a     Autoindent.  In this mode, when a newline character is typed  in
	      the  terminal  interface,	 samterm copies leading white space on
	      the current line to the new line.

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

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

   Regular expressions
       Regular expressions are as in regexp(6) with the addition of \n to rep‐
       resent newlines.	 A regular expression may never contain a literal new‐
       line character.	The empty regular expression stands for the last  com‐
       plete  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 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; 0 is the beginning of the file.
       /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 character except alphanumerics.	 Any number of	trail‐
       ing  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  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 (m) or copy (t) the range to after a1.  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  <Plan  9
	      command  in which case the file names are taken as words (in the
	      shell sense) generated by the Plan 9 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.
       < Plan 9-command
	      Replace the range by the standard output of the Plan 9 command.
       > Plan 9-command
	      Send the range to the standard input of the Plan 9 command.
       | Plan 9-command
	      Send the range to the standard input,  and  replace  it  by  the
	      standard output, of the Plan 9 command.
       * ! Plan 9-command
	      Run the Plan 9 command.
       * cd directory
	      Change  working  directory.  If no directory is specified, $home
	      is used.

       In any of <, >, | or !, if the Plan 9 command is omitted the last  Plan
       9  command  (of	any type) is substituted.  If sam is downloaded (using
       the mouse and raster display, i.e. not using option -d), !  sets	 stan‐
       dard  input to /dev/null, and otherwise unassigned output (stdout for !
       and >, stderr for all) is placed in  /tmp/sam.err  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 regular expression.	Null substrings poten‐
	      tially 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.  If n
	      is  negative,  u	`redoes,'  undoing the undo, going forwards in
	      time again.

       (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 raster 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.  Text may
       be typed and edited as in rio(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 pro‐
       vides the following operators, each of which uses one or more  rio-like
       cursors to prompt for selection of a window or sweeping of a rectangle.
       `Sweeping' a null rectangle gets a large window, disjoint from the com‐
       mand  window or the whole screen, depending on where the null rectangle
       is.

       new    Create a new, empty file.

       zerox  Create a copy of an existing window.

       resize As in rio.

       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.  The behavior is like rio, with 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
       Button  1  changes selection, much like rio.  Pointing to a non-current
       window with button 1 makes it current; within the current window,  but‐
       ton  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.

       plumb  Send  the	 text  in  the	selection  as a plumb message.	If the
	      selection is empty, the white-space-delimited block of  text  is
	      sent  as	a  plumb message with a click attribute defining where
	      the selection lies (see plumb(6)).

       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.

       <rio>  Exchange snarf buffers with rio.

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

   External communication
       Sam  listens  to	 the  edit  plumb port.	 If plumbing is not active, on
       invocation sam creates a named pipe  /srv/sam.user  which  acts	as  an
       additional  source  of  commands.  Characters written to the named pipe
       are treated as if they had been typed in the command window.

       B is a shell-level command that causes an instance of  sam  running  on
       the  same  terminal to load the named files.  B uses either plumbing or
       the named pipe, whichever service is available.	 If  plumbing  is  not
       enabled,	 the  option allows a line number to be specified for the ini‐
       tial position to display in the last named file	(plumbing  provides  a
       more general mechanism for this ability).

   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,
       $home/sam.save.	 This  program,	 when  executed, asks whether to write
       each file back to a external file.  The answer causes writing; anything
       else skips the file.

FILES
       $home/sam.save

       $home/sam.err

       /sys/lib/samsave
	      the program called to unpack $home/sam.save.

SOURCE
       /sys/src/cmd/sam
	      source for sam itself

       /sys/src/cmd/samterm
	      source for the separate terminal part

       /rc/bin/B

SEE ALSO
       ed(1), sed(1), grep(1), rio(1), regexp(6).

       Rob Pike, ``The text editor sam''.

									SAM(1)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net