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