tsam.1 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tsam.1 (19053B)
---
1 .TH SAM 1
2 .ds a \fR*\ \fP
3 .SH NAME
4 sam, B, E, sam.save, samterm, samsave \- screen editor with structural regular expressions
5 .SH SYNOPSIS
6 .B sam
7 [
8 .I option ...
9 ] [
10 .I files
11 ]
12 .PP
13 .B sam
14 .B -r
15 .I machine
16 .PP
17 .B sam.save
18 .PP
19 .B B
20 .IB file \fR[\fP: line \fR]
21 \&...
22 .PP
23 .B E
24 .I file
25 .SH DESCRIPTION
26 .I Sam
27 is a multi-file editor.
28 It modifies a local copy of an external file.
29 The copy is here called a
30 .IR file .
31 The files are listed in a menu available through mouse button 3
32 or the
33 .B n
34 command.
35 Each file has an associated name, usually the name of the
36 external file from which it was read, and a `modified' bit that indicates whether
37 the editor's file agrees with the external file.
38 The external file is not read into
39 the editor's file until it first becomes the current file\(emthat to
40 which editing commands apply\(emwhereupon its menu entry is printed.
41 The options are
42 .TF -rmachine
43 .TP
44 .B -a
45 Autoindent. In this mode, when a newline character is typed
46 in the terminal interface,
47 .I samterm
48 copies leading white space on the current line to the new line.
49 .TP
50 .B -d
51 Do not `download' the terminal part of
52 .IR sam .
53 Editing will be done with the command language only, as in
54 .MR ed (1) .
55 .TP
56 .BI -r " machine
57 Run the host part remotely
58 on the specified machine, the terminal part locally.
59 .TP
60 .BI -s " path
61 Start the host part from the specified file on the remote host.
62 Only meaningful with the
63 .BI -r
64 option.
65 .TP
66 .BI -t " path
67 Start the terminal part from the specified file. Useful
68 for debugging.
69 .PD
70 .SS Regular expressions
71 Regular expressions are as in
72 .MR regexp (7)
73 with the addition of
74 .BR \en
75 to represent newlines.
76 A regular expression may never contain a literal newline character.
77 The empty
78 regular expression stands for the last complete expression encountered.
79 A regular expression in
80 .I sam
81 matches the longest leftmost substring formally
82 matched by the expression.
83 Searching in the reverse direction is equivalent
84 to searching backwards with the catenation operations reversed in
85 the expression.
86 .SS Addresses
87 An address identifies a substring in a file.
88 In the following, `character
89 .IR n '
90 means the null string
91 after the
92 .IR n -th
93 character in the file, with 1 the
94 first character in the file.
95 `Line
96 .IR n '
97 means the
98 .IR n -th
99 match,
100 starting at the beginning of the file, of the regular expression
101 .LR .*\en? .
102 All files always have a current substring, called dot,
103 that is the default address.
104 .SS Simple Addresses
105 .PD 0
106 .TP
107 .BI # n
108 The empty string after character
109 .IR n ;
110 .B #0
111 is the beginning of the file.
112 .TP
113 .I n
114 Line
115 .IR n ;
116 .B 0
117 is the beginning of the file.
118 .TP
119 .BI / regexp /
120 .PD 0
121 .TP
122 .BI ? regexp ?
123 The substring that matches the regular expression,
124 found by looking toward the end
125 .RB ( / )
126 or beginning
127 .RB ( ? )
128 of the file,
129 and if necessary continuing the search from the other end to the
130 starting point of the search.
131 The matched substring may straddle
132 the starting point.
133 When entering a pattern containing a literal question mark
134 for a backward search, the question mark should be
135 specified as a member of a class.
136 .PD
137 .TP
138 .B 0
139 The string before the first full line.
140 This is not necessarily
141 the null string; see
142 .B +
143 and
144 .B -
145 below.
146 .TP
147 .B $
148 The null string at the end of the file.
149 .TP
150 .B .
151 Dot.
152 .TP
153 .B \&'
154 The mark in the file (see the
155 .B k
156 command below).
157 .TP
158 \fB"\f2regexp\fB"\f1\f1
159 Preceding a simple address (default
160 .BR . ),
161 refers to the address evaluated in the unique file whose menu line
162 matches the regular expression.
163 .PD
164 .SS Compound Addresses
165 In the following,
166 .I a1
167 and
168 .I a2
169 are addresses.
170 .TF a1+a2
171 .TP
172 .IB a1 + a2
173 The address
174 .I a2
175 evaluated starting at the end of
176 .IR a1 .
177 .TP
178 .IB a1 - a2
179 The address
180 .I a2
181 evaluated looking in the reverse direction
182 starting at the beginning of
183 .IR a1 .
184 .TP
185 .IB a1 , a2
186 The substring from the beginning of
187 .I a1
188 to the end of
189 .IR a2 .
190 If
191 .I a1
192 is missing,
193 .B 0
194 is substituted.
195 If
196 .I a2
197 is missing,
198 .B $
199 is substituted.
200 .TP
201 .IB a1 ; a2
202 Like
203 .IB a1 , a2\f1,
204 but with
205 .I a2
206 evaluated at the end of, and dot set to,
207 .IR a1 .
208 .PD
209 .PP
210 The operators
211 .B +
212 and
213 .B -
214 are high precedence, while
215 .B ,
216 and
217 .B ;
218 are low precedence.
219 .PP
220 In both
221 .B +
222 and
223 .B -
224 forms, if
225 .I a2
226 is a line or character address with a missing
227 number, the number defaults to 1.
228 If
229 .I a1
230 is missing,
231 .L .
232 is substituted.
233 If both
234 .I a1
235 and
236 .I a2
237 are present and distinguishable,
238 .B +
239 may be elided.
240 .I a2
241 may be a regular
242 expression; if it is delimited by
243 .LR ? 's,
244 the effect of the
245 .B +
246 or
247 .B -
248 is reversed.
249 .PP
250 It is an error for a compound address to represent a malformed substring.
251 Some useful idioms:
252 .IB a1 +-
253 \%(\f2a1\fB-+\f1)
254 selects the line containing
255 the end (beginning) of a1.
256 .BI 0/ regexp /
257 locates the first match of the expression in the file.
258 (The form
259 .B 0;//
260 sets dot unnecessarily.)
261 .BI ./ regexp ///
262 finds the second following occurrence of the expression,
263 and
264 .BI .,/ regexp /
265 extends dot.
266 .SS Commands
267 In the following, text demarcated by slashes represents text delimited
268 by any printable
269 character except alphanumerics.
270 Any number of
271 trailing delimiters may be elided, with multiple elisions then representing
272 null strings, but the first delimiter must always
273 be present.
274 In any delimited text,
275 newline may not appear literally;
276 .B \en
277 may be typed for newline; and
278 .B \e/
279 quotes the delimiter, here
280 .LR / .
281 Backslash is otherwise interpreted literally, except in
282 .B s
283 commands.
284 .PP
285 Most commands may be prefixed by an address to indicate their range
286 of operation.
287 Those that may not are marked with a
288 .L *
289 below.
290 If a command takes
291 an address and none is supplied, dot is used.
292 The sole exception is
293 the
294 .B w
295 command, which defaults to
296 .BR 0,$ .
297 In the description, `range' is used
298 to represent whatever address is supplied.
299 Many commands set the
300 value of dot as a side effect.
301 If so, it is always set to the `result'
302 of the change: the empty string for a deletion, the new text for an
303 insertion, etc. (but see the
304 .B s
305 and
306 .B e
307 commands).
308 .br
309 .ne 1.2i
310 .SS Text commands
311 .PD 0
312 .TP
313 .BI a/ text /
314 .TP
315 or
316 .TP
317 .B a
318 .TP
319 .I lines of text
320 .TP
321 .B .
322 Insert the text into the file after the range.
323 Set dot.
324 .PD
325 .TP
326 .B c\fP
327 .br
328 .ns
329 .TP
330 .B i\fP
331 Same as
332 .BR a ,
333 but
334 .B c
335 replaces the text, while
336 .B i
337 inserts
338 .I before
339 the range.
340 .TP
341 .B d
342 Delete the text in the range.
343 Set dot.
344 .TP
345 .BI s/ regexp / text /
346 Substitute
347 .I text
348 for the first match to the regular expression in the range.
349 Set dot to the modified range.
350 In
351 .I text
352 the character
353 .B &
354 stands for the string
355 that matched the expression.
356 Backslash behaves as usual unless followed by
357 a digit:
358 .BI \e d
359 stands for the string that matched the
360 subexpression begun by the
361 .IR d -th
362 left parenthesis.
363 If
364 .I s
365 is followed immediately by a
366 number
367 .IR n ,
368 as in
369 .BR s2/x/y/ ,
370 the
371 .IR n -th
372 match in the range is substituted.
373 If the
374 command is followed by a
375 .BR g ,
376 as in
377 .BR s/x/y/g ,
378 all matches in the range
379 are substituted.
380 .TP
381 .BI m " a1
382 .br
383 .ns
384 .TP
385 .BI t " a1
386 Move
387 .RB ( m )
388 or copy
389 .RB ( t )
390 the range to after
391 .IR a1 .
392 Set dot.
393 .SS Display commands
394 .PD 0
395 .TP
396 .B p
397 Print the text in the range.
398 Set dot.
399 .TP
400 .B =
401 Print the line address and character address of the range.
402 .TP
403 .B =#
404 Print just the character address of the range.
405 .PD
406 .SS File commands
407 .PD 0
408 .TP
409 .BI \*ab " file-list
410 Set the current file to the first file named in the list
411 that
412 .I sam
413 also has in its menu.
414 The list may be expressed
415 .BI < "Plan 9 command"
416 in which case the file names are taken as words (in the shell sense)
417 generated by the Plan 9 command.
418 .TP
419 .BI \*aB " file-list
420 Same as
421 .BR b ,
422 except that file names not in the menu are entered there,
423 and all file names in the list are examined.
424 .TP
425 .B \*an
426 Print a menu of files.
427 The format is:
428 .RS
429 .TP 11
430 .BR ' " or blank
431 indicating the file is modified or clean,
432 .TP 11
433 .BR - " or \&" +
434 indicating the file is unread or has been read
435 (in the terminal,
436 .B *
437 means more than one window is open),
438 .TP 11
439 .BR . " or blank
440 indicating the current file,
441 .TP 11
442 a blank,
443 .TP 11
444 and the file name.
445 .RE
446 .TP 0
447 .BI \*aD " file-list
448 Delete the named files from the menu.
449 If no files are named, the current file is deleted.
450 It is an error to
451 .B D
452 a modified file, but a subsequent
453 .B D
454 will delete such a file.
455 .PD
456 .SS I/O Commands
457 .PD 0
458 .TP
459 .BI \*ae " filename
460 Replace the file by the contents of the named external file.
461 Set dot to the beginning of the file.
462 .TP
463 .BI r " filename
464 Replace the text in the range by the contents of the named external file.
465 Set dot.
466 .TP
467 .BI w " filename
468 Write the range (default
469 .BR 0,$ )
470 to the named external file.
471 .TP
472 .BI \*af " filename
473 Set the file name and print the resulting menu entry.
474 .PP
475 If the file name is absent from any of these, the current file name is used.
476 .B e
477 always sets the file name;
478 .B r
479 and
480 .B w
481 do so if the file has no name.
482 .TP
483 .BI < " Plan 9-command
484 Replace the range by the standard output of the
485 Plan 9 command.
486 .TP
487 .BI > " Plan 9-command
488 Send the range to the standard input of the
489 Plan 9 command.
490 .TP
491 .BI | " Plan 9-command
492 Send the range to the standard input, and replace it by
493 the standard output, of the
494 Plan 9 command.
495 .TP
496 .BI \*a! " Plan 9-command
497 Run the
498 Plan 9 command.
499 .TP
500 .BI \*acd " directory
501 Change working directory.
502 If no directory is specified,
503 .B $HOME
504 is used.
505 .PD
506 .PP
507 In any of
508 .BR < ,
509 .BR > ,
510 .B |
511 or
512 .BR ! ,
513 if the
514 .I Plan 9 command
515 is omitted the last
516 .I Plan 9 command
517 (of any type) is substituted.
518 If
519 .I sam
520 is
521 .I downloaded
522 (using the mouse and raster display, i.e. not using option
523 .BR -d ),
524 .B !
525 sets standard input to
526 .BR /dev/null ,
527 and otherwise
528 unassigned output
529 .RB ( stdout
530 for
531 .B !
532 and
533 .BR > ,
534 .B stderr
535 for all) is placed in
536 .B /tmp/sam.err
537 and the first few lines are printed.
538 .SS Loops and Conditionals
539 .PD 0
540 .TP
541 .BI x/ regexp / " command
542 For each match of the regular expression in the range, run the command
543 with dot set to the match.
544 Set dot to the last match.
545 If the regular
546 expression and its slashes are omitted,
547 .L /.*\en/
548 is assumed.
549 Null string matches potentially occur before every character
550 of the range and at the end of the range.
551 .TP
552 .BI y/ regexp / " command
553 Like
554 .BR x ,
555 but run the command for each substring that lies before, between,
556 or after
557 the matches that would be generated by
558 .BR x .
559 There is no default regular expression.
560 Null substrings potentially occur before every character
561 in the range.
562 .TP
563 .BI \*aX/ regexp / " command
564 For each file whose menu entry matches the regular expression,
565 make that the current file and
566 run the command.
567 If the expression is omitted, the command is run
568 in every file.
569 .TP
570 .BI \*aY/ regexp / " command
571 Same as
572 .BR X ,
573 but for files that do not match the regular expression,
574 and the expression is required.
575 .TP
576 .BI g/ regexp / " command
577 .br
578 .ns
579 .TP
580 .BI v/ regexp / " command
581 If the range contains
582 .RB ( g )
583 or does not contain
584 .RB ( v )
585 a match for the expression,
586 set dot to the range and run the command.
587 .PP
588 These may be nested arbitrarily deeply, but only one instance of either
589 .B X
590 or
591 .B Y
592 may appear in a \%single command.
593 An empty command in an
594 .B x
595 or
596 .B y
597 defaults to
598 .BR p ;
599 an empty command in
600 .B X
601 or
602 .B Y
603 defaults to
604 .BR f .
605 .B g
606 and
607 .B v
608 do not have defaults.
609 .PD
610 .SS Miscellany
611 .TF (empty)
612 .TP
613 .B k
614 Set the current file's mark to the range. Does not set dot.
615 .TP
616 .B \*aq
617 Quit.
618 It is an error to quit with modified files, but a second
619 .B q
620 will succeed.
621 .TP
622 .BI \*au " n
623 Undo the last
624 .I n
625 (default 1)
626 top-level commands that changed the contents or name of the
627 current file, and any other file whose most recent change was simultaneous
628 with the current file's change.
629 Successive
630 .BR u 's
631 move further back in time.
632 The only commands for which u is ineffective are
633 .BR cd ,
634 .BR u ,
635 .BR q ,
636 .B w
637 and
638 .BR D .
639 If
640 .I n
641 is negative,
642 .B u
643 `redoes,' undoing the undo, going forwards in time again.
644 .TP
645 (empty)
646 If the range is explicit, set dot to the range.
647 If
648 .I sam
649 is downloaded, the resulting dot is selected on the screen;
650 otherwise it is printed.
651 If no address is specified (the
652 command is a newline) dot is extended in either direction to
653 line boundaries and printed.
654 If dot is thereby unchanged, it is set to
655 .B .+1
656 and printed.
657 .PD
658 .SS Grouping and multiple changes
659 Commands may be grouped by enclosing them in braces
660 .BR {} .
661 Commands within the braces must appear on separate lines (no backslashes are
662 required between commands).
663 Semantically, an opening brace is like a command:
664 it takes an (optional) address and sets dot for each sub-command.
665 Commands within the braces are executed sequentially, but changes made
666 by one command are not visible to other commands (see the next
667 paragraph).
668 Braces may be nested arbitrarily.
669 .PP
670 When a command makes a number of changes to a file, as in
671 .BR x/re/c/text/ ,
672 the addresses of all changes to the file are computed in the original file.
673 If the changes are in sequence,
674 they are applied to the file.
675 Successive insertions at the same address are catenated into a single
676 insertion composed of the several insertions in the order applied.
677 .SS The terminal
678 What follows refers to behavior of
679 .I sam
680 when downloaded, that is, when
681 operating as a display editor on a raster display.
682 This is the default
683 behavior; invoking
684 .I sam
685 with the
686 .B -d
687 (no download) option provides access
688 to the command language only.
689 .PP
690 Each file may have zero or more windows open.
691 Each window is equivalent
692 and is updated simultaneously with changes in other windows on the same file.
693 Each window has an independent value of dot, indicated by a highlighted
694 substring on the display.
695 Dot may be in a region not within
696 the window.
697 There is usually a `current window',
698 marked with a dark border, to which typed text and editing
699 commands apply.
700 Text may be typed and edited as in
701 .MR rio (1) ;
702 also the escape key (ESC) selects (sets dot to) text typed
703 since the last mouse button hit.
704 .PP
705 The button 3 menu controls window operations.
706 The top of the menu
707 provides the following operators, each of which uses one or
708 more
709 .IR rio -like
710 cursors to prompt for selection of a window or sweeping
711 of a rectangle.
712 `Sweeping' a null rectangle gets a large window, disjoint
713 from the command window or the whole screen, depending on
714 where the null rectangle is.
715 .TF resize
716 .TP
717 .B new
718 Create a new, empty file.
719 .TP
720 .B zerox
721 Create a copy of an existing window.
722 .TP
723 .B resize
724 As in
725 .IR rio .
726 .TP
727 .B close
728 Delete the window.
729 In the last window of a file,
730 .B close
731 is equivalent to a
732 .B D
733 for the file.
734 .TP
735 .B write
736 Equivalent to a
737 .B w
738 for the file.
739 .PD
740 .PP
741 Below these operators is a list of available files, starting with
742 .BR ~~sam~~ ,
743 the command window.
744 Selecting a file from the list makes the most recently
745 used window on that file current, unless it is already current, in which
746 case selections cycle through the open windows.
747 If no windows are open
748 on the file, the user is prompted to open one.
749 Files other than
750 .B ~~sam~~
751 are marked with one of the characters
752 .B -+*
753 according as zero, one, or more windows
754 are open on the file.
755 A further mark
756 .L .
757 appears on the file in the current window and
758 a single quote,
759 .BR ' ,
760 on a file modified since last write.
761 .PP
762 The command window, created automatically when
763 .B sam
764 starts, is an ordinary window except that text typed to it
765 is interpreted as commands for the editor rather than passive text,
766 and text printed by editor commands appears in it.
767 The behavior is like
768 .IR rio ,
769 with an `output point' that separates commands being typed from
770 previous output.
771 Commands typed in the command window apply to the
772 current open file\(emthe file in the most recently
773 current window.
774 .SS Manipulating text
775 Button 1 changes selection, much like
776 .IR rio .
777 Pointing to a non-current window with button 1 makes it current;
778 within the current window, button 1 selects text, thus setting dot.
779 Double-clicking selects text to the boundaries of words, lines,
780 quoted strings or bracketed strings, depending on the text at the click.
781 .PP
782 Button 2 provides a menu of editing commands:
783 .TF /regexp
784 .TP
785 .B cut
786 Delete dot and save the deleted text in the snarf buffer.
787 .TP
788 .B paste
789 Replace the text in dot by the contents of the snarf buffer.
790 .TP
791 .B snarf
792 Save the text in dot in the snarf buffer.
793 .TP
794 .B plumb
795 Send the text in the selection as a plumb
796 message. If the selection is empty,
797 the white-space-delimited block of text is sent as a plumb message
798 with a
799 .B click
800 attribute defining where the selection lies (see
801 .MR plumb (7) ).
802 .TP
803 .B look
804 Search forward for the next occurrence of the literal text in dot.
805 If dot is the null string, the text in the snarf buffer is
806 used.
807 The snarf buffer is unaffected.
808 .TP
809 .B <rio>
810 Exchange snarf buffers with
811 .IR rio .
812 .TP
813 .BI / regexp
814 Search forward for the next match of the last regular expression
815 typed in a command.
816 (Not in command window.)
817 .TP
818 .B send
819 Send the text in dot, or the snarf buffer if
820 dot is the null string, as if it were typed to the command window.
821 Saves the sent text in the snarf buffer.
822 (Command window only.)
823 .PD
824 .SS Simulated buttons
825 For systems without a three-button mouse, the keyboard modifier
826 keys can be used to modify the effect of the main mouse button.
827 On Unix systems, the Control key changes the main button to button 2,
828 and the Alt key changes it to button 3.
829 On Mac systems, the Option key changes the main button to button 2,
830 and the Command key changes it to button 3.
831 Also on Mac systems, the usual keyboard shortcuts
832 Command-C, -V, and -X invoke
833 copy, paste, and cut,
834 as in other programs.
835 .SS External communication
836 .I Sam
837 listens to the
838 .B edit
839 plumb port.
840 If plumbing is not active,
841 on invocation
842 .I sam
843 creates a named pipe
844 .BI /srv/sam. user
845 which acts as an additional source of commands. Characters written to
846 the named pipe are treated as if they had been typed in the command window.
847 .PP
848 .I B
849 is a shell-level command that causes an instance of
850 .I sam
851 running on the same terminal to load the named
852 .IR files .
853 .I B
854 uses either plumbing or the named pipe, whichever service is available.
855 If plumbing is not enabled,
856 the option allows a line number to be specified for
857 the initial position to display in the last named file
858 (plumbing provides a more general mechanism for this ability).
859 .PP
860 .I E
861 is a shell-level command that can be used as
862 .B $EDITOR
863 in a Unix environment.
864 It runs
865 .I B
866 on
867 .I file
868 and then does not exit until
869 .I file
870 is changed, which is taken as a signal that
871 .I file
872 is done being edited.
873 .SS Abnormal termination
874 If
875 .I sam
876 terminates other than by a
877 .B q
878 command (by hangup, deleting its window, etc.), modified
879 files are saved in an
880 executable file,
881 .BR $HOME/sam.save .
882 This program, when executed, asks whether to write
883 each file back to a external file.
884 The answer
885 .L y
886 causes writing; anything else skips the file.
887 .SH FILES
888 .TF $HOME/sam.save
889 .TP
890 .B $HOME/sam.save
891 .TP
892 .B $HOME/sam.err
893 .TP
894 .B \*9/bin/samsave
895 the program called to unpack
896 .BR $HOME/sam.save .
897 .SH SOURCE
898 .TF \*9/src/cmd/samterm
899 .TP
900 .B \*9/src/cmd/sam
901 source for
902 .I sam
903 itself
904 .TP
905 .B \*9/src/cmd/samterm
906 source for the separate terminal part
907 .TP
908 .B \*9/bin/B
909 .TP
910 .B \*9/bin/E
911 .SH SEE ALSO
912 .MR ed (1) ,
913 .MR sed (1) ,
914 .MR grep (1) ,
915 .MR rio (1) ,
916 .MR regexp (7) .
917 .PP
918 Rob Pike,
919 ``The text editor sam''.