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