Unix/Linux Go Back    

Plan 9 - man page for sam (plan9 section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

SAM(1)											   SAM(1)

       sam, B, sam.save - screen editor with structural regular expressions

       sam [ option ...  ] [ files ]

       sam -r machine


       B [ -nnnn ] file ...

       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 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 represent newlines.	A
       regular expression may never contain a  literal	newline  character.   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 opera-
       tions reversed in the expression.

       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  All	files  always  have  a current substring, called dot, that is the default

   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.


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

	      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 unneces-
       sarily.)  ./regexp/// finds the second following occurrence of the expression, and .,/reg-
       exp/ extends dot.

       In  the	following,  text demarcated by slashes represents text delimited by any printable
       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 descrip-
       tion,  `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 com-

   Text commands



       lines of text

       .      Insert the text into the file after the range.  Set dot.

       i      Same as a, but c replaces the text, while i inserts before the range.

       d      Delete the text in the range.  Set dot.

	      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 paren-
	      thesis.  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 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 begin-
	      ning 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 bitmap display, i.e. not
       using option -d), !  sets standard 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 potentially occur before every character in the range.

       * X/regexp/ command
	      For  each  file whose menu entry matches the regular expression, make that the cur-
	      rent 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 expres-
	      sion 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.

       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 the range is explicit, set dot to the range.  If sam is downloaded, the  result-
	      ing dot is selected on the screen; otherwise it is printed.  If no address is spec-
	      ified (the command is a newline) dot is extended in either direction to line bound-
	      aries 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

       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 dis-
       play 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  inde-
       pendent	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 81/2(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 uses one or more 81/2-like cursors to prompt for selection  of	a
       window  or sweeping of a rectangle.  `Sweeping' a null rectangle gets a large window, dis-
       joint from the command window or the whole screen, depending on where the  null	rectangle

       new    Create a new, empty file.

       zerox  Create a copy of an existing window.

	      As in 81/2.

       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 win-
       dow 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.  The behavior is  like  81/2,  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  cur-
       rent window.

   Manipulating text
       Button  1 changes selection, much like 81/2.  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 brack-
       eted 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.

       <81/2> Exchange snarf buffers with 81/2.

	      Search  forward  for  the next match of the last regular expression typed in a com-
	      mand.  (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
       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.  This is usually used to issue B commands from the shell.

       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.

   Abnormal termination
       If sam terminates other than by a q command (by hangup, deleting its window, etc.),  modi-
       fied  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;  any-
       thing else skips the file.



	      the program called to unpack $home/sam.save.

	      source for sam itself

	      source for the separate terminal part


       ed(1), sed(1), grep(1), 81/2(1), regexp(6).

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

Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 03:52 PM.