home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / sed < prev    next >
Encoding:
Text File  |  1979-01-10  |  26.5 KB  |  1,260 lines

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