1.\" $FreeBSD$ 2.Dd May 21, 1993 3.Dt ED 1 4.Os 5.Sh NAME 6.Nm ed , 7.Nm red 8.Nd text editor 9.Sh SYNOPSIS 10.Nm 11.Op Fl 12.Op Fl sx 13.Op Fl p Ar string 14.Op Ar file 15.\" .LP 16.\" red [-] [-sx] [-p \fIstring\fR] [\fIfile\fR] 17.Sh DESCRIPTION 18The 19.Nm 20utility is a line-oriented text editor. 21It is used to create, display, modify and otherwise manipulate text 22files. 23.\" .B red 24.\" is a restricted 25.\" .BR ed : 26.\" it can only edit files in the current 27.\" directory and cannot execute shell commands. 28.Pp 29If invoked with a 30.Ar file 31argument, then a copy of 32.Ar file 33is read into the editor's buffer. 34Changes are made to this copy and not directly to 35.Ar file 36itself. 37Upon quitting 38.Nm , 39any changes not explicitly saved with a 40.Em w 41command are lost. 42.Pp 43Editing is done in two distinct modes: 44.Em command 45and 46.Em input . 47When first invoked, 48.Nm 49is in command mode. 50In this mode commands are read from the standard input and 51executed to manipulate the contents of the editor buffer. 52A typical command might look like: 53.Pp 54.Sm off 55.Cm ,s No / Em old Xo 56.No / Em new 57.No / Cm g 58.Xc 59.Sm on 60.Pp 61which replaces all occurrences of the string 62.Em old 63with 64.Em new . 65.Pp 66When an input command, such as 67.Em a 68(append), 69.Em i 70(insert) or 71.Em c 72(change), is given, 73.Nm 74enters input mode. This is the primary means 75of adding text to a file. 76In this mode, no commands are available; 77instead, the standard input is written 78directly to the editor buffer. Lines consist of text up to and 79including a 80.Em newline 81character. 82Input mode is terminated by 83entering a single period 84.Pq Em .\& 85on a line. 86.Pp 87All 88.Nm 89commands operate on whole lines or ranges of lines; e.g., 90the 91.Em d 92command deletes lines; the 93.Em m 94command moves lines, and so on. 95It is possible to modify only a portion of a line by means of replacement, 96as in the example above. However even here, the 97.Em s 98command is applied to whole lines at a time. 99.Pp 100In general, 101.Nm 102commands consist of zero or more line addresses, followed by a single 103character command and possibly additional parameters; i.e., 104commands have the structure: 105.Pp 106.Sm off 107.Xo 108.Op Ar address Op , Ar address 109.Ar command Op Ar parameters 110.Xc 111.Sm on 112.Pp 113The address(es) indicate the line or range of lines to be affected by the 114command. If fewer addresses are given than the command accepts, then 115default addresses are supplied. 116.Sh OPTIONS 117The following options are available: 118.Bl -tag -width indent 119.It Fl s 120Suppress diagnostics. 121This should be used if 122.Nm Ns 's 123standard input is from a script. 124.It Fl x 125Prompt for an encryption key to be used in subsequent reads and writes 126(see the 127.Em x 128command). 129.It Fl p Ar string 130Specify a command prompt. This may be toggled on and off with the 131.Em P 132command. 133.It Ar file 134Specify the name of a file to read. If 135.Ar file 136is prefixed with a 137bang (!), then it is interpreted as a shell command. In this case, 138what is read is 139the standard output of 140.Ar file 141executed via 142.Xr sh 1 . 143To read a file whose name begins with a bang, prefix the 144name with a backslash (\\). 145The default filename is set to 146.Ar file 147only if it is not prefixed with a bang. 148.El 149.Sh LINE ADDRESSING 150An address represents the number of a line in the buffer. 151The 152.Nm 153utility maintains a 154.Em current address 155which is 156typically supplied to commands as the default address when none is specified. 157When a file is first read, the current address is set to the last line 158of the file. In general, the current address is set to the last line 159affected by a command. 160.Pp 161A line address is 162constructed from one of the bases in the list below, optionally followed 163by a numeric offset. The offset may include any combination 164of digits, operators (i.e., 165.Em + , 166.Em - 167and 168.Em ^ ) 169and whitespace. 170Addresses are read from left to right, and their values are computed 171relative to the current address. 172.Pp 173One exception to the rule that addresses represent line numbers is the 174address 175.Em 0 176(zero). 177This means "before the first line," 178and is legal wherever it makes sense. 179.Pp 180An address range is two addresses separated either by a comma or 181semi-colon. 182The value of the first address in a range cannot exceed the 183value of the second. If only one address is given in a range, then 184the second address is set to the given address. If an 185.Em n Ns -tuple 186of addresses is given where 187.Em "n\ >\ 2" , 188then the corresponding range is determined by the last two addresses in 189the 190.Em n Ns -tuple . 191If only one address is expected, then the last address is used. 192.Pp 193Each address in a comma-delimited range is interpreted relative to the 194current address. In a semi-colon-delimited range, the first address is 195used to set the current address, and the second address is interpreted 196relative to the first. 197.Pp 198The following address symbols are recognized: 199.Bl -tag -width indent 200.It . 201The current line (address) in the buffer. 202.It $ 203The last line in the buffer. 204.It n 205The 206.Em n Ns th, 207line in the buffer 208where 209.Em n 210is a number in the range 211.Em [0,$] . 212.It - or ^ 213The previous line. 214This is equivalent to 215.Em -1 216and may be repeated with cumulative effect. 217.It -n or ^n 218The 219.Em n Ns th 220previous line, where 221.Em n 222is a non-negative number. 223.It + 224The next line. 225This is equivalent to 226.Em +1 227and may be repeated with cumulative effect. 228.It +n 229The 230.Em n Ns th 231next line, where 232.Em n 233is a non-negative number. 234.It , or % 235The first through last lines in the buffer. This is equivalent to 236the address range 237.Em 1,$ . 238.It ; 239The current through last lines in the buffer. This is equivalent to 240the address range 241.Em .,$ . 242.It /re/ 243The next line containing the regular expression 244.Em re . 245The search wraps to the beginning of the buffer and continues down to the 246current line, if necessary. 247// repeats the last search. 248.It ?re? 249The 250previous line containing the regular expression 251.Em re . 252The search wraps to the end of the buffer and continues up to the 253current line, if necessary. 254?? repeats the last search. 255.It 'lc 256The 257line previously marked by a 258.Em k 259(mark) command, where 260.Em lc 261is a lower case letter. 262.El 263.Sh REGULAR EXPRESSIONS 264Regular expressions are patterns used in selecting text. 265For example, the command: 266.Pp 267.Sm off 268.Cm g No / Em string Xo 269.No / 270.Xc 271.Sm on 272.Pp 273prints all lines containing 274.Em string . 275Regular expressions are also 276used by the 277.Em s 278command for selecting old text to be replaced with new. 279.Pp 280In addition to a specifying string literals, regular expressions can 281represent 282classes of strings. Strings thus represented are said to be matched 283by the corresponding regular expression. 284If it is possible for a regular expression 285to match several strings in a line, then the left-most longest match is 286the one selected. 287.Pp 288The following symbols are used in constructing regular expressions: 289.Bl -tag -width indent 290.It c 291Any character 292.Em c 293not listed below, including `{', '}', `(', `)', `<' and `>', 294matches itself. 295.It Pf \e c 296Any backslash-escaped character 297.Em c , 298except for `{', '}', `(', `)', `<' and `>', 299matches itself. 300.It . 301Match any single character. 302.It Op char-class 303Match any single character in 304.Em char-class . 305To include a `]' 306in 307.Em char-class , 308it must be the first character. 309A range of characters may be specified by separating the end characters 310of the range with a `-', e.g., `a-z' specifies the lower case characters. 311The following literal expressions can also be used in 312.Em char-class 313to specify sets of characters: 314.Pp 315.Bl -column "[:alnum:]" "[:cntrl:]" "[:lower:]" "[:xdigit:]" -compact 316.It [:alnum:] Ta [:cntrl:] Ta [:lower:] Ta [:space:] 317.It [:alpha:] Ta [:digit:] Ta [:print:] Ta [:upper:] 318.It [:blank:] Ta [:graph:] Ta [:punct:] Ta [:xdigit:] 319.El 320.Pp 321If `-' appears as the first or last 322character of 323.Em char-class , 324then it matches itself. 325All other characters in 326.Em char-class 327match themselves. 328.Pp 329Patterns in 330.Em char-class 331of the form: 332.Pp 333.Bl -item -compact -offset 2n 334.It 335.Op \&. Ns Ar col-elm Ns .\& 336or, 337.It 338.Op = Ns Ar col-elm Ns = 339.El 340.Pp 341where 342.Ar col-elm 343is a 344.Em collating element 345are interpreted according to 346.Xr locale 5 347(not currently supported). 348See 349.Xr regex 3 350for an explanation of these constructs. 351.It Op ^char-class 352Match any single character, other than newline, not in 353.Em char-class . 354.Em Char-class 355is defined 356as above. 357.It ^ 358If 359.Em ^ 360is the first character of a regular expression, then it 361anchors the regular expression to the beginning of a line. 362Otherwise, it matches itself. 363.It $ 364If 365.Em $ 366is the last character of a regular expression, it 367anchors the regular expression to the end of a line. 368Otherwise, it matches itself. 369.It Pf \e < 370Anchor the single character regular expression or subexpression 371immediately following it to the beginning of a word. 372(This may not be available) 373.It Pf \e > 374Anchor the single character regular expression or subexpression 375immediately following it to the end of a word. 376(This may not be available) 377.It Pf \e (re\e) 378Define a subexpression 379.Em re . 380Subexpressions may be nested. 381A subsequent backreference of the form 382.Pf \e Em n , 383where 384.Em n 385is a number in the range [1,9], expands to the text matched by the 386.Em n Ns th 387subexpression. 388For example, the regular expression `\e(.*\e)\e1' matches any string 389consisting of identical adjacent substrings. 390Subexpressions are ordered relative to 391their left delimiter. 392.It * 393Match the single character regular expression or subexpression 394immediately preceding it zero or more times. If 395.Em * 396is the first 397character of a regular expression or subexpression, then it matches 398itself. The 399.Em * 400operator sometimes yields unexpected results. 401For example, the regular expression `b*' matches the beginning of 402the string `abbb' (as opposed to the substring `bbb'), since a null match 403is the only left-most match. 404.It \e{n,m\e} or \e{n,\e} or \e{n\e} 405Match the single character regular expression or subexpression 406immediately preceding it at least 407.Em n 408and at most 409.Em m 410times. 411If 412.Em m 413is omitted, then it matches at least 414.Em n 415times. 416If the comma is also omitted, then it matches exactly 417.Em n 418times. 419.El 420.Pp 421Additional regular expression operators may be defined depending on the 422particular 423.Xr regex 3 424implementation. 425.Sh COMMANDS 426All 427.Nm 428commands are single characters, though some require additional parameters. 429If a command's parameters extend over several lines, then 430each line except for the last 431must be terminated with a backslash (\\). 432.Pp 433In general, at most one command is allowed per line. 434However, most commands accept a print suffix, which is any of 435.Em p 436(print), 437.Em l 438(list), 439or 440.Em n 441(enumerate), 442to print the last line affected by the command. 443.Pp 444An interrupt (typically ^C) has the effect of aborting the current command 445and returning the editor to command mode. 446.Pp 447The 448.Nm 449utility 450recognizes the following commands. The commands are shown together with 451the default address or address range supplied if none is 452specified (in parenthesis). 453.Bl -tag -width indent 454.It (.)a 455Append text to the buffer after the addressed line. 456Text is entered in input mode. 457The current address is set to last line entered. 458.It (.,.)c 459Change lines in the buffer. The addressed lines are deleted 460from the buffer, and text is appended in their place. 461Text is entered in input mode. 462The current address is set to last line entered. 463.It (.,.)d 464Delete the addressed lines from the buffer. 465If there is a line after the deleted range, then the current address is set 466to this line. 467Otherwise the current address is set to the line 468before the deleted range. 469.It e Ar file 470Edit 471.Ar file , 472and sets the default filename. 473If 474.Ar file 475is not specified, then the default filename is used. 476Any lines in the buffer are deleted before 477the new file is read. 478The current address is set to the last line read. 479.It e Ar !command 480Edit the standard output of 481.Ar !command , 482(see 483.Ar !command 484below). 485The default filename is unchanged. 486Any lines in the buffer are deleted before the output of 487.Ar command 488is read. 489The current address is set to the last line read. 490.It E Ar file 491Edit 492.Ar file 493unconditionally. 494This is similar to the 495.Em e 496command, 497except that unwritten changes are discarded without warning. 498The current address is set to the last line read. 499.It f Ar file 500Set the default filename to 501.Ar file . 502If 503.Ar file 504is not specified, then the default unescaped filename is printed. 505.It (1,$)g/re/command-list 506Apply 507.Ar command-list 508to each of the addressed lines matching a regular expression 509.Ar re . 510The current address is set to the 511line currently matched before 512.Ar command-list 513is executed. 514At the end of the 515.Em g 516command, the current address is set to the last line affected by 517.Ar command-list . 518.Pp 519Each command in 520.Ar command-list 521must be on a separate line, 522and every line except for the last must be terminated by a backslash 523(\\). 524Any commands are allowed, except for 525.Em g , 526.Em G , 527.Em v , 528and 529.Em V . 530A newline alone in 531.Ar command-list 532is equivalent to a 533.Em p 534command. 535.It (1,$)G/re/ 536Interactively edit the addressed lines matching a regular expression 537.Ar re . 538For each matching line, 539the line is printed, 540the current address is set, 541and the user is prompted to enter a 542.Ar command-list . 543At the end of the 544.Em G 545command, the current address 546is set to the last line affected by (the last) 547.Ar command-list . 548.Pp 549The format of 550.Ar command-list 551is the same as that of the 552.Em g 553command. A newline alone acts as a null command list. 554A single `&' repeats the last non-null command list. 555.It H 556Toggle the printing of error explanations. 557By default, explanations are not printed. 558It is recommended that ed scripts begin with this command to 559aid in debugging. 560.It h 561Print an explanation of the last error. 562.It (.)i 563Insert text in the buffer before the current line. 564Text is entered in input mode. 565The current address is set to the last line entered. 566.It (.,.+1)j 567Join the addressed lines. The addressed lines are 568deleted from the buffer and replaced by a single 569line containing their joined text. 570The current address is set to the resultant line. 571.It (.)klc 572Mark a line with a lower case letter 573.Em lc . 574The line can then be addressed as 575.Em 'lc 576(i.e., a single quote followed by 577.Em lc ) 578in subsequent commands. The mark is not cleared until the line is 579deleted or otherwise modified. 580.It (.,.)l 581Print the addressed lines unambiguously. 582If a single line fills for than one screen (as might be the case 583when viewing a binary file, for instance), a `--More--' 584prompt is printed on the last line. 585The 586.Nm 587utility waits until the RETURN key is pressed 588before displaying the next screen. 589The current address is set to the last line 590printed. 591.It (.,.)m(.) 592Move lines in the buffer. The addressed lines are moved to after the 593right-hand destination address, which may be the address 594.Em 0 595(zero). 596The current address is set to the 597last line moved. 598.It (.,.)n 599Print the addressed lines along with 600their line numbers. The current address is set to the last line 601printed. 602.It (.,.)p 603Print the addressed lines. 604The current address is set to the last line 605printed. 606.It P 607Toggle the command prompt on and off. 608Unless a prompt was specified by with command-line option 609.Fl p Ar string , 610the command prompt is by default turned off. 611.It q 612Quit 613.Nm . 614.It Q 615Quit 616.Nm 617unconditionally. 618This is similar to the 619.Em q 620command, 621except that unwritten changes are discarded without warning. 622.It ($)r Ar file 623Read 624.Ar file 625to after the addressed line. If 626.Ar file 627is not specified, then the default 628filename is used. If there was no default filename prior to the command, 629then the default filename is set to 630.Ar file . 631Otherwise, the default filename is unchanged. 632The current address is set to the last line read. 633.It ($)r Ar !command 634Read 635to after the addressed line 636the standard output of 637.Ar !command , 638(see the 639.Ar !command 640below). 641The default filename is unchanged. 642The current address is set to the last line read. 643.It (.,.)s/re/replacement/ 644.It (.,.)s/re/replacement/g 645.It (.,.)s/re/replacement/n 646Replace text in the addressed lines 647matching a regular expression 648.Ar re 649with 650.Ar replacement . 651By default, only the first match in each line is replaced. 652If the 653.Em g 654(global) suffix is given, then every match to be replaced. 655The 656.Em n 657suffix, where 658.Em n 659is a positive number, causes only the 660.Em n Ns th 661match to be replaced. 662It is an error if no substitutions are performed on any of the addressed 663lines. 664The current address is set the last line affected. 665.Pp 666.Ar Re 667and 668.Ar replacement 669may be delimited by any character other than space and newline 670(see the 671.Em s 672command below). 673If one or two of the last delimiters is omitted, then the last line 674affected is printed as though the print suffix 675.Em p 676were specified. 677.Pp 678An unescaped `&' in 679.Ar replacement 680is replaced by the currently matched text. 681The character sequence 682.Em \em , 683where 684.Em m 685is a number in the range [1,9], is replaced by the 686.Em m th 687backreference expression of the matched text. 688If 689.Ar replacement 690consists of a single `%', then 691.Ar replacement 692from the last substitution is used. 693Newlines may be embedded in 694.Ar replacement 695if they are escaped with a backslash (\\). 696.It (.,.)s 697Repeat the last substitution. 698This form of the 699.Em s 700command accepts a count suffix 701.Em n , 702or any combination of the characters 703.Em r , 704.Em g , 705and 706.Em p . 707If a count suffix 708.Em n 709is given, then only the 710.Em n Ns th 711match is replaced. 712The 713.Em r 714suffix causes 715the regular expression of the last search to be used instead of the 716that of the last substitution. 717The 718.Em g 719suffix toggles the global suffix of the last substitution. 720The 721.Em p 722suffix toggles the print suffix of the last substitution 723The current address is set to the last line affected. 724.It (.,.)t(.) 725Copy (i.e., transfer) the addressed lines to after the right-hand 726destination address, which may be the address 727.Em 0 728(zero). 729The current address is set to the last line 730copied. 731.It u 732Undo the last command and restores the current address 733to what it was before the command. 734The global commands 735.Em g , 736.Em G , 737.Em v , 738and 739.Em V . 740are treated as a single command by undo. 741.Em u 742is its own inverse. 743.It (1,$)v/re/command-list 744Apply 745.Ar command-list 746to each of the addressed lines not matching a regular expression 747.Ar re . 748This is similar to the 749.Em g 750command. 751.It (1,$)V/re/ 752Interactively edit the addressed lines not matching a regular expression 753.Ar re . 754This is similar to the 755.Em G 756command. 757.It (1,$)w Ar file 758Write the addressed lines to 759.Ar file . 760Any previous contents of 761.Ar file 762is lost without warning. 763If there is no default filename, then the default filename is set to 764.Ar file , 765otherwise it is unchanged. If no filename is specified, then the default 766filename is used. 767The current address is unchanged. 768.It (1,$)wq Ar file 769Write the addressed lines to 770.Ar file , 771and then executes a 772.Em q 773command. 774.It (1,$)w Ar !command 775Write the addressed lines to the standard input of 776.Ar !command , 777(see the 778.Em !command 779below). 780The default filename and current address are unchanged. 781.It (1,$)W Ar file 782Append the addressed lines to the end of 783.Ar file . 784This is similar to the 785.Em w 786command, expect that the previous contents of file is not clobbered. 787The current address is unchanged. 788.It x 789Prompt for an encryption key which is used in subsequent reads and 790writes. If a newline alone is entered as the key, then encryption is 791turned off. Otherwise, echoing is disabled while a key is read. 792Encryption/decryption is done using the 793.Xr bdes 1 794algorithm. 795.It Pf (.+1)z n 796Scroll 797.Ar n 798lines at a time starting at addressed line. If 799.Ar n 800is not specified, then the current window size is used. 801The current address is set to the last line printed. 802.It !command 803Execute 804.Ar command 805via 806.Xr sh 1 . 807If the first character of 808.Ar command 809is `!', then it is replaced by text of the 810previous 811.Ar !command . 812The 813.Nm 814utility does not process 815.Ar command 816for backslash (\\) escapes. 817However, an unescaped 818.Em % 819is replaced by the default filename. 820When the shell returns from execution, a `!' 821is printed to the standard output. 822The current line is unchanged. 823.It ($)= 824Print the line number of the addressed line. 825.It (.+1)newline 826Print the addressed line, and sets the current address to 827that line. 828.El 829.Sh FILES 830.Bl -tag -width /tmp/ed.* -compact 831.It /tmp/ed.* 832buffer file 833.It ed.hup 834the file to which 835.Nm 836attempts to write the buffer if the terminal hangs up 837.El 838.Sh SEE ALSO 839.Xr bdes 1 , 840.Xr sed 1 , 841.Xr sh 1 , 842.Xr vi 1 , 843.Xr regex 3 844.Pp 845USD:12-13 846.Rs 847.%A B. W. Kernighan 848.%A P. J. Plauger 849.%B Software Tools in Pascal 850.%O Addison-Wesley 851.%D 1981 852.Re 853.Sh LIMITATIONS 854The 855.Nm 856utility processes 857.Ar file 858arguments for backslash escapes, i.e., in a filename, 859any characters preceded by a backslash (\\) are 860interpreted literally. 861.Pp 862If a text (non-binary) file is not terminated by a newline character, 863then 864.Nm 865appends one on reading/writing it. In the case of a binary file, 866.Nm 867does not append a newline on reading/writing. 868.Pp 869per line overhead: 4 ints 870.Sh DIAGNOSTICS 871When an error occurs, 872.Nm 873prints a `?' and either returns to command mode 874or exits if its input is from a script. 875An explanation of the last error can be 876printed with the 877.Em h 878(help) command. 879.Pp 880Since the 881.Em g 882(global) command masks any errors from failed searches and substitutions, 883it can be used to perform conditional operations in scripts; e.g., 884.Pp 885.Sm off 886.Cm g No / Em old Xo 887.No / Cm s 888.No // Em new 889.No / 890.Xc 891.Sm on 892.Pp 893replaces any occurrences of 894.Em old 895with 896.Em new . 897If the 898.Em u 899(undo) command occurs in a global command list, then 900the command list is executed only once. 901.Pp 902If diagnostics are not disabled, attempting to quit 903.Nm 904or edit another file before writing a modified buffer 905results in an error. 906If the command is entered a second time, it succeeds, 907but any changes to the buffer are lost. 908.Sh HISTORY 909An 910.Nm 911command appeared in 912Version 1 AT&T UNIX. 913