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