Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SAM(1)			    General Commands Manual			SAM(1)

NAME
       sam,  B,	 E, sam.save, samterm, samsave - screen	editor with structural
       regular expressions

SYNOPSIS
       sam [ option ...	 ] [ files ]

       sam -r machine

       sam.save

       B file[:line] ...

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

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

       E  is a shell-level command that	can be used as $EDITOR in a Unix envi-
       ronment.	 It runs B on file and	then  does  not	 exit  until  file  is
       changed,	which is taken as a signal that	file is	done being edited.

   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

       /usr/local/plan9/bin/samsave
	      the program called to unpack $HOME/sam.save.

SOURCE
       /usr/local/plan9/src/cmd/sam
	      source for sam itself

       /usr/local/plan9/src/cmd/samterm
	      source for the separate terminal part

       /usr/local/plan9/bin/B

       /usr/local/plan9/bin/E

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

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

									SAM(1)

NAME | SYNOPSIS | DESCRIPTION | FILES | SOURCE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sam&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help