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