![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to sed CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 18.sed|
Return to sed CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 18.sed |
1.1 root 1: .\" @(#)sed 6.1 (Berkeley) 5/22/86
2: .\"
3: .EH 'USD:18-%''SED \(em A Non-interactive Text Editor'
4: .OH 'SED \(em A Non-interactive Text Editor''USD:18-%'
5: .hw de-limit
6: .hw de-limit-ing
7: .\".RP
8: ....TM 78-1270-1 39199 39199-11
9: .ND August 15, 1978
10: .TL
11: SED \(em A Non-interactive Text Editor
12: .AU "MH 2C-555" 3302
13: Lee E. McMahon
14: .AI
15: .MH
16: .OK
17: \"Context search
18: \"Editing
19: .AB
20: .ul
21: Sed
22: is a non-interactive context editor
23: that runs on the
24: .UX
25: operating system.
26: .ul
27: Sed
28: is
29: designed to be especially useful in
30: three cases:
31: .in +1i
32: .LP
33: .ti -.5i
34: 1)
35: To edit files too large for comfortable
36: interactive editing;
37: .ti -.5i
38: 2)
39: To edit any size file when the sequence
40: of editing commands is too complicated to be comfortably
41: typed in interactive mode.
42: .ti -.5i
43: 3)
44: To perform multiple `global' editing functions
45: efficiently in one pass through the input.
46: .in -1i
47: .LP
48: This memorandum constitutes a manual for users of
49: .ul
50: sed.
51: .AE
52: .CS 10 0 10 0 0 1
53: .SH
54: Introduction
55: .LP
56: .ul
57: Sed
58: is a non-interactive context editor designed to be especially useful in
59: three cases:
60: .in +1i
61: .LP
62: .ti -.5i
63: 1)
64: To edit files too large for comfortable
65: interactive editing;
66: .ti -.5i
67: 2)
68: To edit any size file when the sequence
69: of editing commands is too complicated to be comfortably
70: typed in interactive mode;
71: .ti -.5i
72: 3)
73: To perform multiple `global' editing functions
74: efficiently in one pass through the input.
75: .in -1i
76: .LP
77: Since only a few lines of the input reside in core
78: at one time, and no temporary files are used,
79: the effective size of file that can be edited is limited only
80: by the requirement that the input and output fit simultaneously
81: into available secondary storage.
82: .LP
83: Complicated editing scripts can be created separately and given
84: to
85: .ul
86: sed
87: as a command file.
88: For complex edits, this saves considerable typing, and its
89: attendant errors.
90: .ul
91: Sed
92: running from a command file is much more efficient than any interactive
93: editor known to the author, even if that editor
94: can be driven by a pre-written script.
95: .LP
96: The principal loss of functions compared to an interactive editor
97: are lack of relative addressing (because of the line-at-a-time
98: operation), and lack of immediate verification that a command has
99: done what was intended.
100: .LP
101: .ul
102: Sed
103: is a lineal descendant of the UNIX editor,
104: .ul
105: ed.
106: Because of the differences between interactive and non-interactive
107: operation, considerable changes have been made between
108: .ul
109: ed
110: and
111: .ul
112: sed;
113: even confirmed users of
114: .ul
115: ed
116: will frequently be surprised (and probably chagrined),
117: if they rashly use
118: .ul
119: sed
120: without reading Sections 2 and 3 of this document.
121: The most striking family resemblance between the two
122: editors is in the class of patterns (`regular expressions') they
123: recognize;
124: the code for matching patterns is copied almost
125: verbatim from the code for
126: .ul
127: ed,
128: and the description of regular expressions in Section 2
129: is copied almost verbatim from the UNIX Programmer's
130: Manual[1]. (Both code and description were written by Dennis
131: M. Ritchie.)
132: .LP
133: .SH
134: 1. Overall Operation
135: .LP
136: .ul
137: Sed
138: by default copies the standard input to the standard output,
139: perhaps performing one or more editing commands on each
140: line before writing it to the output.
141: This behavior may be modified by flags on the command line;
142: see Section 1.1 below.
143: .LP
144: The general format of an editing command is:
145: .LP
146: .in +1i
147: [address1,address2][function][arguments]
148: .LP
149: .in -1i
150: One or both addresses may be omitted; the format of addresses is
151: given in Section 2.
152: Any number of blanks or tabs may separate the addresses
153: from the function.
154: The function must be present; the available commands are discussed
155: in Section 3.
156: The arguments may be required or optional, according to which function
157: is given; again, they are discussed in Section 3 under each individual
158: function.
159: .LP
160: Tab characters and spaces at the beginning of lines are ignored.
161: .LP
162: .SH
163: 1.1. Command-line Flags
164: .LP
165: Three flags are recognized on the command line:
166: .in +1i
167: .ti -.5i
168: .B
169: -n:
170: .R
171: tells
172: .ul
173: sed
174: not to copy all lines, but only those specified by
175: .ul
176: p
177: functions or
178: .ul
179: p
180: flags after
181: .ul
182: s
183: functions (see Section 3.3);
184: .ti -.5i
185: .B
186: -e:
187: .R
188: tells
189: .ul
190: sed
191: to take the next argument as an editing command;
192: .ti -.5i
193: .B
194: -f:
195: .R
196: tells
197: .ul
198: sed
199: to take the next argument as a file name;
200: the file should contain editing commands, one to a line.
201: .in -1i
202: .SH
203: 1.2. Order of Application of Editing Commands
204: .LP
205: Before any editing is done (in fact, before any input file is
206: even opened), all the editing commands are compiled into
207: a form which will be moderately efficient during
208: the execution phase (when the commands are actually applied to
209: lines of the input file).
210: The commands are compiled in the order in which they are
211: encountered; this is generally the order in which they will
212: be attempted at execution time.
213: The commands are applied one at a time; the input to each command
214: is the output of all preceding commands.
215: .LP
216: The default linear order of application of editing commands can
217: be changed by the flow-of-control commands,
218: .ul
219: t
220: and
221: .ul
222: b
223: (see Section 3).
224: Even when the order of application is changed
225: by these commands, it is still true that the input line to any
226: command is the output of any previously applied command.
227: .SH
228: 1.3. Pattern-space
229: .LP
230: The range of pattern matches is called the pattern space.
231: Ordinarily, the pattern space is one line of the input text,
232: but more than one line can be read into the pattern space
233: by using the
234: .ul
235: N
236: command (Section 3.6.).
237: .LP
238: .SH
239: 1.4. Examples
240: .LP
241: Examples are scattered throughout the text.
242: Except where otherwise noted,
243: the examples all assume the following input text:
244: .LP
245: .in +.5i
246: .nf
247: In Xanadu did Kubla Khan
248: A stately pleasure dome decree:
249: Where Alph, the sacred river, ran
250: Through caverns measureless to man
251: Down to a sunless sea.
252: .in -.5i
253: .fi
254: .LP
255: (In no case is the output of the
256: .ul
257: sed
258: commands to be considered an improvement
259: on Coleridge.)
260: .LP
261: .SH
262: Example:
263: .LP
264: The command
265: .in +.5i
266: .LP
267: 2q
268: .in -.5i
269: .LP
270: will quit after copying the first two lines of the input.
271: The output will be:
272: .LP
273: .in +.5i
274: .nf
275: In Xanadu did Kubla Khan
276: A stately pleasure dome decree:
277: .in -.5i
278: .fi
279: .LP
280: .SH
281: 2. ADDRESSES: Selecting lines for editing
282: .LP
283: Lines in the input file(s) to which editing commands are
284: to be applied can be selected by addresses.
285: Addresses may be either line numbers or context addresses.
286: .LP
287: The application of a group of commands can be controlled by
288: one address (or address-pair) by grouping
289: the commands with curly braces (`{ }')(Sec. 3.6.).
290: .SH
291: 2.1. Line-number Addresses
292: .LP
293: A line number is a decimal integer.
294: As each line is read from the input, a line-number counter
295: is incremented;
296: a line-number address matches (selects) the input
297: line which causes the internal counter to equal the
298: address line-number.
299: The counter runs cumulatively through multiple input files;
300: it is not reset when a new input file is opened.
301: .LP
302: As a special case, the character
303: $
304: matches the last line of the last input file.
305: .SH
306: 2.2. Context Addresses
307: .LP
308: A context address is a pattern (`regular expression') enclosed in slashes (`/').
309: The regular expressions recognized by
310: .ul
311: sed
312: are constructed as follows:
313: .in +1i
314: .LP
315: .ti -.5i
316: 1)
317: An ordinary character (not one of those discussed below)
318: is a regular expression, and matches that character.
319: .LP
320: .ti -.5i
321: 2)
322: A circumflex `^' at the beginning of a regular expression
323: matches the null character at the beginning of a line.
324: .ti -.5i
325: 3)
326: A dollar-sign `$' at the end of a regular expression
327: matches the null character at the end of a line.
328: .ti -.5i
329: 4)
330: The characters `\en' match an imbedded newline character,
331: but not the newline at the end of the pattern space.
332: .ti -.5i
333: 5)
334: A period `.' matches any character except the terminal newline
335: of the pattern space.
336: .ti -.5i
337: 6)
338: A regular expression followed by an asterisk `*' matches any
339: number (including 0) of adjacent occurrences of the regular
340: expression it follows.
341: .ti -.5i
342: 7)
343: A string of characters in square brackets `[ ]' matches any character
344: in the string, and no others.
345: If, however, the first character of the string is circumflex `^',
346: the regular expression matches any character
347: .ul
348: except
349: the characters in the string and the terminal newline of the pattern space.
350: .ti -.5i
351: 8)
352: A concatenation of regular expressions is a regular expression
353: which matches the concatenation of strings matched by the
354: components of the regular expression.
355: .ti -.5i
356: 9)
357: A regular expression between the sequences `\e(' and `\e)' is
358: identical in effect to the unadorned regular expression, but has
359: side-effects which are described under the
360: .ul
361: s
362: command below and specification 10) immediately below.
363: .ti -.5i
364: 10)
365: The expression
366: .ul
367: `\|\ed'
368: means the same string of characters matched
369: by an expression enclosed in `\e(' and `\e)'
370: earlier in the same pattern.
371: Here
372: .ul
373: d
374: is a single digit;
375: the string specified is that beginning with the
376: \fId\|\fRth
377: occurrence of `\e(' counting from the left.
378: For example, the expression
379: `^\e(.*\e)\e1' matches a line beginning with
380: two repeated occurrences of the same string.
381: .ti -.5i
382: 11)
383: The null regular expression standing alone (e.g., `//') is
384: equivalent to the last regular expression compiled.
385: .in -1i
386: .LP
387: To use one of the special characters (^ $ . * [ ] \e /) as a literal
388: (to match an occurrence of itself in the input), precede the
389: special character by a backslash `\e'.
390: .LP
391: For a context address to `match' the input requires that
392: the whole pattern within the address match some
393: portion of the pattern space.
394: .SH
395: 2.3. Number of Addresses
396: .LP
397: The commands in the next section can have 0, 1, or 2 addresses.
398: Under each command the maximum number of allowed addresses is
399: given.
400: For a command to have more addresses than the maximum allowed
401: is considered an error.
402: .LP
403: If a command has no addresses, it is applied to every line
404: in the input.
405: .LP
406: If a command has one address, it is applied to all
407: lines which match that address.
408: .LP
409: If a command has two addresses, it is applied to the first
410: line which matches the first address, and to all subsequent lines
411: until (and including) the first subsequent line which matches
412: the second address.
413: Then an attempt is made on subsequent lines to again match the first
414: address, and the process is repeated.
415: .LP
416: Two addresses are separated by a comma.
417: .SH
418: Examples:
419: .LP
420: .nf
421: .in +.5i
422: .ta 1i 2i
423: /an/ matches lines 1, 3, 4 in our sample text
424: /an.*an/ matches line 1
425: /^an/ matches no lines
426: /./ matches all lines
427: /\e./ matches line 5
428: /r*an/ matches lines 1,3, 4 (number = zero!)
429: /\e(an\e).*\e1/ matches line 1
430: .fi
431: .in 0
432: .LP
433: .SH
434: 3. FUNCTIONS
435: .LP
436: All functions are named by a single character.
437: In the following summary, the maximum number of allowable addresses
438: is given enclosed in parentheses, then the single character
439: function name, possible arguments enclosed in angles (< >),
440: an expanded English translation of the single-character name,
441: and finally a description of what each function does.
442: The angles around the arguments are
443: .ul
444: not
445: part of the argument, and should not be typed
446: in actual editing commands.
447: .SH
448: 3.1. Whole-line Oriented Functions
449: .LP
450: .in +1i
451: .ti -.5i
452: (2)d -- delete lines
453: .if t .sp .5
454: The
455: .ul
456: d
457: function deletes from the file (does not write to the output)
458: all those lines matched by its address(es).
459: .if t .sp .5
460: It also has the side effect that no further commands are attempted
461: on the corpse of a deleted line;
462: as soon as the
463: .ul
464: d
465: function is executed, a new line is read from the input, and
466: the list of editing commands is re-started from the beginning
467: on the new line.
468: .ti -.5i
469: .if t .sp .5
470: (2)n -- next line
471: .if t .sp .5
472: The
473: .ul
474: n
475: function reads the next line from the input, replacing
476: the current line.
477: The current line is written to the output if it should
478: be.
479: The list of editing commands is continued
480: following the
481: .ul
482: n
483: command.
484: .if t .sp .5
485: .nf
486: .in -.5i
487: (1)a\e
488: <text> -- append lines
489: .in +.5i
490: .fi
491: .if t .sp .5
492: The
493: .ul
494: a
495: function causes the argument <text> to be written to the
496: output after the line matched by its address.
497: The
498: .ul
499: a
500: command is inherently multi-line;
501: .ul
502: a
503: must appear at the end of a line, and <text> may contain
504: any number of lines.
505: To preserve the one-command-to-a-line fiction,
506: the interior newlines must be hidden by a
507: backslash character (`\e') immediately preceding the
508: newline.
509: The <text> argument is terminated by the first unhidden
510: newline (the first one not immediately preceded
511: by backslash).
512: .if t .sp .5
513: Once an
514: .ul
515: a
516: function is successfully executed, <text> will be
517: written to the output regardless of what later commands do to
518: the line which triggered it.
519: The triggering line may be
520: deleted entirely; <text> will still be written to the output.
521: .if t .sp .5
522: The <text> is not scanned for address matches, and no editing
523: commands are attempted on it.
524: It does not cause any change in the line-number counter.
525: .if t .sp .5
526: .nf
527: .in -.5i
528: (1)i\e
529: <text> -- insert lines
530: .in +.5i
531: .fi
532: .if t .sp .5
533: The
534: .ul
535: i
536: function behaves identically to the
537: .ul
538: a
539: function, except that <text> is written to the output
540: .ul
541: before
542: the matched line.
543: All other comments about the
544: .ul
545: a
546: function apply to the
547: .ul
548: i
549: function as well.
550: .if t .sp .5
551: .nf
552: .in -.5i
553: (2)c\e
554: <text> -- change lines
555: .in +.5i
556: .fi
557: .if t .sp .5
558: The
559: .ul
560: c
561: function deletes the lines selected by its address(es),
562: and replaces them with the lines in <text>.
563: Like
564: .ul
565: a
566: and
567: .ul
568: i,
569: .ul
570: c
571: must be followed by a newline hidden by a backslash;
572: and interior new lines in <text> must be hidden by
573: backslashes.
574: .if t .sp .5
575: The
576: .ul
577: c
578: command may have two addresses, and therefore select a range
579: of lines.
580: If it does, all the lines in the range are deleted, but only
581: one copy of <text> is written to the output,
582: .ul
583: not
584: one copy per line deleted.
585: As with
586: .ul
587: a
588: and
589: .ul
590: i,
591: <text> is not scanned for address matches, and no
592: editing commands are attempted on it.
593: It does not change the line-number counter.
594: .if t .sp .5
595: After a line has been deleted by a
596: .ul
597: c
598: function, no further commands are attempted on the corpse.
599: .if t .sp .5
600: If text is appended after a line by
601: .ul
602: a
603: or
604: .ul
605: r
606: functions, and the line is subsequently changed, the text
607: inserted by the
608: .ul
609: c
610: function will be placed
611: .ul
612: before
613: the text of the
614: .ul
615: a
616: or
617: .ul
618: r
619: functions.
620: (The
621: .ul
622: r
623: function is described in Section 3.4.)
624: .if t .sp .5
625: .in -1i
626: .ul
627: Note:
628: Within the text put in the output by these functions,
629: leading blanks and tabs will disappear, as always in
630: .ul
631: sed
632: commands.
633: To get leading blanks and tabs into the output, precede the first
634: desired blank or tab by a backslash; the backslash will not
635: appear in the output.
636: .SH
637: Example:
638: .LP
639: The list of editing commands:
640: .LP
641: .in +.5i
642: .nf
643: n
644: a\e
645: XXXX
646: d
647: .in -.5i
648: .fi
649: .LP
650: applied to our standard input, produces:
651: .LP
652: .in +.5i
653: .nf
654: In Xanadu did Kubhla Khan
655: XXXX
656: Where Alph, the sacred river, ran
657: XXXX
658: Down to a sunless sea.
659: .in -.5i
660: .fi
661: .LP
662: In this particular case,
663: the same effect would be produced by either
664: of the two following command lists:
665: .LP
666: .in +.5i
667: .nf
668: n n
669: i\e c\e
670: XXXX XXXX
671: d
672: .in -.5i
673: .fi
674: .LP
675: .in 0
676: .SH
677: 3.2. Substitute Function
678: .LP
679: One very important function changes parts of lines selected by
680: a context search within the line.
681: .if t .sp .5
682: .in +1i
683: .ti -.5i
684: (2)s<pattern><replacement><flags> -- substitute
685: .if t .sp .5
686: The
687: .ul
688: s
689: function replaces
690: .ul
691: part
692: of a line (selected by <pattern>) with <replacement>.
693: It can best be read:
694: .if t .sp .5
695: .ti +1i
696: Substitute for <pattern>, <replacement>
697: .if t .sp .5
698: The <pattern> argument contains a pattern,
699: exactly like the patterns in addresses (see 2.2 above).
700: The only difference between <pattern> and a context address is
701: that the context address must be delimited by slash (`/') characters;
702: <pattern> may be delimited by any character other than space or
703: newline.
704: .if t .sp .5
705: By default, only the first string matched by <pattern> is replaced,
706: but see the
707: .ul
708: g
709: flag below.
710: .if t .sp .5
711: The
712: <replacement> argument begins immediately after the
713: second delimiting character of <pattern>, and must be followed
714: immediately by another instance of the delimiting character.
715: (Thus there are exactly
716: .ul
717: three
718: instances of the delimiting character.)
719: .if t .sp .5
720: The <replacement> is not a pattern,
721: and the characters which are special in patterns
722: do not have special meaning in <replacement>.
723: Instead, other characters are special:
724: .if t .sp .5
725: .in +1i
726: .ti -.5i
727: & is replaced by the string matched by <pattern>
728: .if t .sp .5
729: .ti -.5i
730: .ul
731: \ed
732: (where
733: .ul
734: d
735: is a single digit) is replaced by the \fId\fRth substring
736: matched by parts of <pattern> enclosed in `\e(' and `\e)'.
737: If nested substrings occur in <pattern>, the \fId\fRth
738: is determined by counting opening delimiters (`\e(').
739: .if t .sp .5
740: As in patterns, special characters may be made
741: literal by preceding them with backslash (`\e').
742: .if t .sp .5
743: .in -1i
744: The <flags> argument may contain the following flags:
745: .if t .sp .5
746: .in +1i
747: .ti -.5i
748: g -- substitute <replacement> for all (non-overlapping)
749: instances of <pattern> in the line.
750: After a successful substitution, the scan for the next
751: instance of <pattern> begins just after the end of the
752: inserted characters; characters put into the line from
753: <replacement> are not rescanned.
754: .if t .sp .5
755: .ti -.5i
756: p -- print the line if a successful replacement was done.
757: The
758: .ul
759: p
760: flag causes the line to be written to the output if and only
761: if a substitution was actually made by the
762: .ul
763: s
764: function.
765: Notice that if several
766: .ul
767: s
768: functions, each followed by a
769: .ul
770: p
771: flag, successfully substitute in the same input line,
772: multiple copies of the line will be written to the
773: output: one for each successful substitution.
774: .if t .sp .5
775: .ti -.5i
776: w <filename> -- write the line to a file if a successful
777: replacement was done.
778: The
779: .ul
780: w
781: flag causes lines which are actually substituted by the
782: .ul
783: s
784: function to be written to a file named by <filename>.
785: If <filename> exists before
786: .ul
787: sed
788: is run, it is overwritten;
789: if not, it is created.
790: .if t .sp .5
791: A single space must separate
792: .ul
793: w
794: and <filename>.
795: .if t .sp .5
796: The possibilities of multiple, somewhat different copies of
797: one input line being written are the same as for
798: .ul
799: p.
800: .if t .sp .5
801: A maximum of 10 different file names may be mentioned after
802: .ul
803: w
804: flags and
805: .ul
806: w
807: functions (see below), combined.
808: .in 0
809: .SH
810: Examples:
811: .LP
812: The following command, applied to our standard input,
813: .LP
814: .in +.5i
815: s/to/by/w changes
816: .in -.5i
817: .LP
818: produces, on the standard output:
819: .LP
820: .in +.5i
821: .nf
822: In Xanadu did Kubhla Khan
823: A stately pleasure dome decree:
824: Where Alph, the sacred river, ran
825: Through caverns measureless by man
826: Down by a sunless sea.
827: .fi
828: .in -.5i
829: .LP
830: and, on the file `changes':
831: .LP
832: .in +.5i
833: .nf
834: Through caverns measureless by man
835: Down by a sunless sea.
836: .fi
837: .in -.5i
838: .LP
839: If the nocopy option is in effect, the command:
840: .LP
841: .in +.5i
842: .nf
843: s/[.,;?:]/*P&*/gp
844: .fi
845: .in -.5i
846: .LP
847: produces:
848: .LP
849: .in +.5i
850: .nf
851: A stately pleasure dome decree*P:*
852: Where Alph*P,* the sacred river*P,* ran
853: Down to a sunless sea*P.*
854: .LP
855: .in -.5i
856: .fi
857: Finally, to illustrate the effect of the
858: .ul
859: g
860: flag,
861: the command:
862: .LP
863: .in +.5i
864: .nf
865: /X/s/an/AN/p
866: .in -.5i
867: .fi
868: .LP
869: produces (assuming nocopy mode):
870: .in +.5i
871: .LP
872: .nf
873: In XANadu did Kubhla Khan
874: .fi
875: .in -.5i
876: .LP
877: and the command:
878: .LP
879: .in +.5i
880: .nf
881: /X/s/an/AN/gp
882: .in -.5i
883: .fi
884: .LP
885: produces:
886: .LP
887: .in +.5i
888: .nf
889: In XANadu did Kubhla KhAN
890: .in -.5i
891: .fi
892: .LP
893: .in 0
894: .SH
895: 3.3. Input-output Functions
896: .LP
897: .in +1i
898: .ti -.5i
899: (2)p -- print
900: .if t .sp .5
901: The print function writes the addressed lines to the standard output file.
902: They are written at the time the
903: .ul
904: p
905: function is encountered, regardless of what succeeding
906: editing commands may do to the lines.
907: .if t .sp .5
908: .ti -.5i
909: (2)w <filename> -- write on <filename>
910: .if t .sp .5
911: The write function writes the addressed lines to the file named
912: by <filename>.
913: If the file previously existed, it is overwritten; if not, it is created.
914: The lines are written exactly as they exist when the write function
915: is encountered for each line, regardless of what subsequent
916: editing commands may do to them.
917: .if t .sp .5
918: Exactly one space must separate the
919: .ul
920: w
921: and <filename>.
922: .if t .sp .5
923: A maximum of ten different files may be mentioned in write
924: functions and
925: .ul
926: w
927: flags after
928: .ul
929: s
930: functions, combined.
931: .if t .sp .5
932: .ti -.5i
933: (1)r <filename> -- read the contents of a file
934: .if t .sp .5
935: The read function reads the contents of <filename>, and appends
936: them after the line matched by the address.
937: The file is read and appended regardless of what subsequent
938: editing commands do to the line which matched its address.
939: If
940: .ul
941: r
942: and
943: .ul
944: a
945: functions are executed on the same line,
946: the text from the
947: .ul
948: a
949: functions and the
950: .ul
951: r
952: functions is written to the output in the order that
953: the functions are executed.
954: .if t .sp .5
955: Exactly one space must separate the
956: .ul
957: r
958: and <filename>.
959: If a file mentioned by a
960: .ul
961: r
962: function cannot be opened, it is considered a null file,
963: not an error, and no diagnostic is given.
964: .if t .sp .5
965: .in -1i
966: NOTE:
967: Since there is a limit to the number of files that can be opened
968: simultaneously, care should be taken that no more than ten
969: files be mentioned in
970: .ul
971: w
972: functions or flags; that number is reduced by one if any
973: .ul
974: r
975: functions are present.
976: (Only one read file is open at one time.)
977: .in 0
978: .SH
979: Examples
980: .LP
981: Assume that the file `note1'
982: has the following contents:
983: .LP
984: .in +1i
985: Note: Kubla Khan (more properly Kublai Khan; 1216-1294)
986: was the grandson and most eminent successor of Genghiz
987: (Chingiz) Khan, and founder of the Mongol dynasty in China.
988: .LP
989: .in 0
990: Then the following command:
991: .LP
992: .nf
993: .in +.5i
994: /Kubla/r note1
995: .in -.5i
996: .fi
997: .LP
998: produces:
999: .LP
1000: .nf
1001: .in +.5i
1002: In Xanadu did Kubla Khan
1003: .in +.5i
1004: .fi
1005: Note: Kubla Khan (more properly Kublai Khan; 1216-1294)
1006: was the grandson and most eminent successor of Genghiz
1007: (Chingiz) Khan, and founder of the Mongol dynasty in China.
1008: .in -.5i
1009: .nf
1010: A stately pleasure dome decree:
1011: Where Alph, the sacred river, ran
1012: Through caverns measureless to man
1013: Down to a sunless sea.
1014: .in -.5i
1015: .fi
1016: .LP
1017: .in 0
1018: .SH
1019: 3.4.
1020: Multiple Input-line Functions
1021: .LP
1022: Three functions, all spelled with capital letters, deal
1023: specially with pattern spaces containing imbedded newlines;
1024: they are intended principally to provide pattern matches across
1025: lines in the input.
1026: .if t .sp .5
1027: .in +1i
1028: .ti -.5i
1029: (2)N -- Next line
1030: .if t .sp .5
1031: The next input line is appended to the current line in the
1032: pattern space; the two input lines are separated by an imbedded
1033: newline.
1034: Pattern matches may extend across the imbedded newline(s).
1035: .if t .sp .5
1036: .ti -.5i
1037: (2)D -- Delete first part of the pattern space
1038: .if t .sp .5
1039: Delete up to and including the first newline character
1040: in the current pattern space.
1041: If the pattern space becomes empty (the only newline
1042: was the terminal newline),
1043: read another line from the input.
1044: In any case, begin the list of editing commands again
1045: from its beginning.
1046: .if t .sp .5
1047: .ti -.5i
1048: (2)P -- Print first part of the pattern space
1049: .if t .sp .5
1050: Print up to and including the first newline in the pattern space.
1051: .if t .sp .5
1052: .in 0
1053: The
1054: .ul
1055: P
1056: and
1057: .ul
1058: D
1059: functions are equivalent to their lower-case counterparts
1060: if there are no imbedded newlines in the pattern space.
1061: .in 0
1062: .SH
1063: 3.5. Hold and Get Functions
1064: .LP
1065: Four functions save and retrieve part of the input for possible later
1066: use.
1067: .if t .sp .5
1068: .in 1i
1069: .ti -.5i
1070: (2)h -- hold pattern space
1071: .if t .sp .5
1072: The
1073: .ul
1074: h
1075: functions copies the contents of the pattern space
1076: into a hold area (destroying the previous contents of the
1077: hold area).
1078: .if t .sp .5
1079: .ti -.5i
1080: (2)H -- Hold pattern space
1081: .if t .sp .5
1082: The
1083: .ul
1084: H
1085: function appends the contents of the pattern space
1086: to the contents of the hold area; the former and new contents
1087: are separated by a newline.
1088: .if t .sp .5
1089: .ti -.5i
1090: (2)g -- get contents of hold area
1091: .if t .sp .5
1092: The
1093: .ul
1094: g
1095: function copies the contents of the hold area into
1096: the pattern space (destroying the previous contents of the
1097: pattern space).
1098: .if t .sp .5
1099: .ti -.5i
1100: (2)G -- Get contents of hold area
1101: .if t .sp .5
1102: The
1103: .ul
1104: G
1105: function appends the contents of the hold area to the
1106: contents of the pattern space; the former and new contents are separated by
1107: a newline.
1108: .if t .sp .5
1109: .ti -.5i
1110: (2)x -- exchange
1111: .if t .sp .5
1112: The exchange command interchanges the contents
1113: of the pattern space and the hold area.
1114: .in 0
1115: .SH
1116: Example
1117: .LP
1118: The commands
1119: .nf
1120: .if t .sp .5
1121: 1h
1122: 1s/ did.*//
1123: 1x
1124: G
1125: s/\en/ :/
1126: .if t .sp .5
1127: .fi
1128: applied to our standard example, produce:
1129: .nf
1130: .if t .sp .5
1131: In Xanadu did Kubla Khan :In Xanadu
1132: A stately pleasure dome decree: :In Xanadu
1133: Where Alph, the sacred river, ran :In Xanadu
1134: Through caverns measureless to man :In Xanadu
1135: Down to a sunless sea. :In Xanadu
1136: .if t .sp .5
1137: .fi
1138: .SH
1139: 3.6. Flow-of-Control Functions
1140: .LP
1141: These functions do no editing on the input
1142: lines, but control the application of functions
1143: to the lines selected by the address part.
1144: .if t .sp .5
1145: .in +1i
1146: .ti -.5i
1147: (2)! -- Don't
1148: .if t .sp .5
1149: The
1150: .ul
1151: Don't
1152: command causes the next command
1153: (written on the same line), to be applied to all and only those input lines
1154: .ul
1155: not
1156: selected by the adress part.
1157: .if t .sp .5
1158: .ti -.5i
1159: (2){ -- Grouping
1160: .if t .sp .5
1161: The grouping command `{' causes the
1162: next set of commands to be applied
1163: (or not applied) as a block to the
1164: input lines selected by the addresses
1165: of the grouping command.
1166: The first of the commands under control of the grouping
1167: may appear on the same line as the
1168: `{' or on the next line.
1169: .LP
1170: The group of commands is terminated by a
1171: matching `}' standing on a line by itself.
1172: .LP
1173: Groups can be nested.
1174: .ti -.5i
1175: .if t .sp .5
1176: (0):<label> -- place a label
1177: .if t .sp .5
1178: The label function marks a place in the list
1179: of editing commands which may be referred to by
1180: .ul
1181: b
1182: and
1183: .ul
1184: t
1185: functions.
1186: The <label> may be any sequence of eight or fewer characters;
1187: if two different colon functions have identical labels,
1188: a compile time diagnostic will be generated, and
1189: no execution attempted.
1190: .if t .sp .5
1191: .ti -.5i
1192: (2)b<label> -- branch to label
1193: .if t .sp .5
1194: The branch function causes the sequence of editing commands being
1195: applied to the current input line to be restarted immediately
1196: after the place where a colon function with the same <label>
1197: was encountered.
1198: If no colon function with the same label can be found after
1199: all the editing commands have been compiled, a compile time diagnostic
1200: is produced, and no execution is attempted.
1201: .if t .sp .5
1202: A
1203: .ul
1204: b
1205: function with no <label> is taken to be a branch to the end of the
1206: list of editing commands;
1207: whatever should be done with the current input line is done, and
1208: another input line is read; the list of editing commands is restarted from the
1209: beginning on the new line.
1210: .if t .sp .5
1211: .ti -.5i
1212: (2)t<label> -- test substitutions
1213: .if t .sp .5
1214: The
1215: .ul
1216: t
1217: function tests whether
1218: .ul
1219: any
1220: successful substitutions have been made on the current input
1221: line;
1222: if so, it branches to <label>;
1223: if not, it does nothing.
1224: The flag which indicates that a successful substitution has
1225: been executed is reset by:
1226: .if t .sp .5
1227: .in +1i
1228: 1) reading a new input line, or
1229: .br
1230: 2) executing a
1231: .ul
1232: t
1233: function.
1234: .if t .sp .5
1235: .in 0
1236: .SH
1237: 3.7. Miscellaneous Functions
1238: .LP
1239: .in +1i
1240: .ti -.5i
1241: (1)= -- equals
1242: .if t .sp .5
1243: The = function writes to the standard output the line number of the
1244: line matched by its address.
1245: .if t .sp .5
1246: .ti -.5i
1247: (1)q -- quit
1248: .if t .sp .5
1249: The
1250: .ul
1251: q
1252: function causes the current line to be written to the
1253: output (if it should be), any appended or read text to be written, and
1254: execution to be terminated.
1255: .in 0
1256: .SH
1257: .SH
1258: Reference
1259: .IP [1]
1260: Ken Thompson and Dennis M. Ritchie,
1261: .ul
1262: The UNIX Programmer's Manual.
1263: Bell Laboratories, 1978.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.