diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ed.1 | 8 | ||||
| -rw-r--r-- | doc/ed.info | 368 | ||||
| -rw-r--r-- | doc/ed.texi | 347 |
3 files changed, 424 insertions, 299 deletions
@@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.1. -.TH ED "1" "January 2016" "ed 1.13" "User Commands" +.TH ED "1" "February 2017" "ed 1.14.2" "User Commands" .SH NAME ed \- line-oriented text editor .SH SYNOPSIS @@ -28,10 +28,10 @@ use STRING as an interactive prompt run in restricted mode .TP \fB\-s\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR -suppress diagnostics +suppress diagnostics, byte counts and '!' prompt .TP \fB\-v\fR, \fB\-\-verbose\fR -be verbose +be verbose; equivalent to the 'H' command .PP Start edit by reading in 'file' if given. If 'file' begins with a '!', read output of shell command. @@ -49,7 +49,7 @@ General help using GNU software: http://www.gnu.org/gethelp .SH COPYRIGHT Copyright \(co 1994 Andrew L. Moore. .br -Copyright \(co 2016 Antonio Diaz Diaz. +Copyright \(co 2017 Antonio Diaz Diaz. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> .br This is free software: you are free to change and redistribute it. diff --git a/doc/ed.info b/doc/ed.info index a239faf..7a5575f 100644 --- a/doc/ed.info +++ b/doc/ed.info @@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY * Ed: (ed). The GNU line editor END-INFO-DIR-ENTRY - Copyright (C) 1993, 1994, 2006-2016 Free Software Foundation, Inc. + Copyright (C) 1993, 1994, 2006-2017 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -18,7 +18,7 @@ File: ed.info, Node: Top, Next: Overview, Up: (dir) The GNU ed line editor ********************** -This manual is for GNU ed (version 1.13, 24 January 2016). +This manual is for GNU ed (version 1.14.2, 22 February 2017). GNU ed is a line-oriented text editor. It is used to create, display, @@ -43,7 +43,7 @@ superseded by full-screen editors such as GNU Emacs or GNU Moe. * GNU Free Documentation License:: How you can copy and share this manual - Copyright (C) 1993, 1994, 2006-2016 Free Software Foundation, Inc. + Copyright (C) 1993, 1994, 2006-2017 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -277,8 +277,8 @@ is 's/OLD/NEW/'. # Move the title to its proper place. 5m0p Sonnet #50 - # The title is now the first line, and the current line has been - # set to this line as well. + # The title is now the first line, and the current address has been + # set to the address of this line as well. ,p Sonnet #50 No more be grieved at that which thou hast done. @@ -289,9 +289,9 @@ is 's/OLD/NEW/'. 195 $ - When 'ed' opens a file, the current line is initially set to the -last line of that file. Similarly, the move command 'm' sets the -current line to the last line moved. + When 'ed' opens a file, the current address is initially set to the +address of the last line of that file. Similarly, the move command 'm' +sets the current address to the address of the last line moved. Related programs or routines are 'vi (1)', 'sed (1)', 'regex (3)', 'sh (1)'. Relevant documents are: @@ -355,14 +355,18 @@ prefixed with a bang. '-s' '--quiet' '--silent' - Suppresses diagnostics. This should be used if 'ed''s standard - input is from a script. + Suppresses diagnostics, the printing of byte counts by 'e', 'E', + 'r' and 'w' commands, and the '!' prompt after a '!' command. This + option may be useful if 'ed''s standard input is from a script. '-v' '--verbose' - Verbose mode. This may be toggled on and off with the 'H' command. + Verbose mode; prints error explanations. This may be toggled on + and off with the 'H' command. + Exit status: 0 if no errors occurred; otherwise >0. + File: ed.info, Node: Line addressing, Next: Regular expressions, Prev: Invoking ed, Up: Top @@ -372,25 +376,30 @@ File: ed.info, Node: Line addressing, Next: Regular expressions, Prev: Invoki An address represents the number of a line in the buffer. 'ed' maintains a "current address" which is typically supplied to commands as the default address when none is specified. When a file is first -read, the current address is set to the last line of the file. In -general, the current address is set to the last line affected by a -command. +read, the current address is set to the address of the last line of the +file. In general, the current address is set to the address of the last +line affected by a command. One exception to the rule that addresses represent line numbers is the address '0' (zero). This means "before the first line", and is valid wherever it makes sense. An address range is two addresses separated either by a comma (',') -or a semicolon (';'). The value of the first address in a range cannot -exceed the value of the second. If only one address is given in a -range, then the second address is set to the given address. If an -N-tuple of addresses is given where N > 2, then the corresponding range -is determined by the last two addresses in the N-tuple. If only one -address is expected, then the last address is used. - - In a semicolon-delimited range, the current address ('.') is set to -the first address before the second address is calculated. This feature -can be used to set the starting line for searches. +or a semicolon (';'). In a semicolon-delimited range, the current +address ('.') is set to the first address before the second address is +calculated. This feature can be used to set the starting line for +searches. The value of the first address in a range cannot exceed the +value of the second. + + Addresses can be omitted on either side of the comma or semicolon +separator. If only the first address is given in a range, then the +second address is set to the given address. If only the second address +is given, the resulting address pairs are '1,addr' and '.;addr' +respectively. If a N-tuple of addresses is given where N > 2, then the +corresponding range is determined by the last two addresses in the +N-tuple. If only one address is expected, then the last address is +used. It is an error to give any number of addresses to a command that +requires zero addresses. A line address is constructed as follows: @@ -423,17 +432,17 @@ can be used to set the starting line for searches. ';' The current through last lines in the buffer. This is equivalent - to the address range '.,$'. + to the address range '.;$'. '/RE/' The next line containing the regular expression RE. The search wraps to the beginning of the buffer and continues down to the - current line, if necessary. '//' repeats the last search. + current line, if necessary. A null RE '//' repeats the last search. '?RE?' The previous line containing the regular expression RE. The search wraps to the end of the buffer and continues up to the current - line, if necessary. '??' repeats the last search. + line, if necessary. A null RE '??' repeats the last search. ''x' The apostrophe-x character pair addresses the line previously @@ -444,14 +453,20 @@ can be used to set the starting line for searches. Addresses can be followed by one or more address offsets, optionally separated by whitespace. Offsets are constructed as follows: - * A number adds the indicated number of lines to the address. - * '+' or '-' followed by a number adds or subtracts the indicated number of lines to or from the address. * '+' or '-' not followed by a number adds or subtracts 1 to or from the address. + * A number adds the indicated number of lines to the address. + + + It is not an error if an intermediate address value is negative or +greater than the address of the last line in the buffer. It is an error +if the final address value is negative or greater than the address of +the last line in the buffer. It is an error if a search for a RE fails +to find a matching line. File: ed.info, Node: Regular expressions, Next: Commands, Prev: Line addressing, Up: Top @@ -612,7 +627,9 @@ each line except for the last must be terminated with a backslash ('\'). In general, at most one command is allowed per line. However, most commands accept a print suffix, which is any of 'p' (print), 'l' (list), or 'n' (enumerate), to print the last line affected by the -command. +command. It is not portable to give more than one print suffix, but +'ed' allows any combination of non-repeated print suffixes and combines +their effects. An interrupt (typically <Control-C>) has the effect of aborting the current command and returning the editor to command mode. @@ -622,64 +639,80 @@ together with the default address or address range supplied if none is specified (in parenthesis). '(.)a' - Appends text to the buffer after the addressed line, which may be - the address '0' (zero). Text is entered in input mode. The current - address is set to last line entered. + Appends text to the buffer after the addressed line. The address + '0' (zero) is valid for this command; it places the entered text at + the beginning of the buffer. Text is entered in input mode. The + current address is set to the address of the last line entered or, + if there were none, to the addressed line. '(.,.)c' Changes lines in the buffer. The addressed lines are deleted from - the buffer, and text is appended in their place. Text is entered - in input mode. The current address is set to last line entered. + the buffer, and text is inserted in their place. Text is entered + in input mode. The current address is set to the address of the + last line entered or, if there were none, to the new address of + the line after the last line deleted; if the lines deleted were + originally at the end of the buffer, the current address is set to + the address of the new last line; if no lines remain in the + buffer, the current address is set to zero. '(.,.)d' - Deletes the addressed lines from the buffer. If there is a line - after the deleted range, then the current address is set to this - line. Otherwise the current address is set to the line before the - deleted range. + Deletes the addressed lines from the buffer. The current address + is set to the new address of the line after the last line deleted; + if the lines deleted were originally at the end of the buffer, the + current address is set to the address of the new last line; if no + lines remain in the buffer, the current address is set to zero. 'e FILE' Edits FILE, and sets the default filename. If FILE is not specified, then the default filename is used. Any lines in the buffer are deleted before the new file is read. The current - address is set to the last line read. + address is set to the address of the last line in the buffer. -'e !COMMAND' - Edits the standard output of '!COMMAND', (see the '!' command - below). The default filename is unchanged. Any lines in the buffer - are deleted before the output of COMMAND is read. The current - address is set to the last line read. + If FILE is prefixed with a bang (!), then it is interpreted as a + shell command whose output is to be read, (*note shell escape + command:: '!' below). In this case the default filename is + unchanged. + + A warning is printed if any changes have been made in the buffer + since the last 'w' command that wrote the entire buffer to a file. 'E FILE' Edits FILE unconditionally. This is similar to the 'e' command, - except that unwritten changes are discarded without warning. The - current address is set to the last line read. + except that unwritten changes are discarded without warning. 'f FILE' Sets the default filename to FILE. If FILE is not specified, then the default unescaped filename is printed. '(1,$)g/RE/COMMAND-LIST' - Global command. Applies COMMAND-LIST to each of the addressed - lines matching a regular expression RE. The current address is set - to the line currently matched before COMMAND-LIST is executed. At - the end of the 'g' command, the current address is set to the last - line affected by COMMAND-LIST. - - At least the first command of COMMAND-LIST must appear on the same - line as the 'g' command. All lines of a multi-line COMMAND-LIST - except the last line must be terminated with a backslash ('\'). - Any commands are allowed, except for 'g', 'G', 'v', and 'V'. By - default, a newline alone in COMMAND-LIST is equivalent to a 'p' - command. If 'ed' is invoked with the command-line option '-G', - then a newline in COMMAND-LIST is equivalent to a '.+1p' command. + Global command. The global command makes two passes over the file. + On the first pass, all the addressed lines matching a regular + expression RE are marked. Then, going sequentially from the + beginning of the file to the end of the file, the given + COMMAND-LIST is executed for each marked line, with the current + address set to the address of that line. Any line modified by the + COMMAND-LIST is unmarked. The final value of the current address + is the value assigned by the last command in the last COMMAND-LIST + executed. If there were no matching lines, the current address is + unchanged. + + The first command of COMMAND-LIST must appear on the same line as + the 'g' command. All lines of a multi-line COMMAND-LIST except the + last line must be terminated with a backslash ('\'). Any commands + are allowed, except for 'g', 'G', 'v', and 'V'. The '.' + terminating the input mode of commands 'a', 'c', and 'i' can be + omitted if it would be the last line of COMMAND-LIST. By default, + a newline alone in COMMAND-LIST is equivalent to a 'p' command. If + 'ed' is invoked with the command-line option '-G', then a newline + in COMMAND-LIST is equivalent to a '.+1p' command. '(1,$)G/RE/' Interactive global command. Interactively edits the addressed lines matching a regular expression RE. For each matching line, the line is printed, the current address is set, and the user is prompted to - enter a COMMAND-LIST. At the end of the 'G' command, the current - address is set to the last line affected by (the last) - COMMAND-LIST. + enter a COMMAND-LIST. The final value of the current address is + the value assigned by the last command executed. If there were no + matching lines, the current address is unchanged. The format of COMMAND-LIST is the same as that of the 'g' command. A newline alone acts as a null command list. A single '&' repeats @@ -694,41 +727,48 @@ specified (in parenthesis). begin with this command to aid in debugging. '(.)i' - Inserts text in the buffer before the current line. The address '0' - (zero) is valid for this command; it is equivalent to address '1'. - Text is entered in input mode. The current address is set to the - last line entered. + Inserts text in the buffer before the addressed line. The address + '0' (zero) is valid for this command; it is equivalent to address + '1'. Text is entered in input mode. The current address is set to + the address of the last line entered or, if there were none, to the + addressed line. '(.,.+1)j' - Joins the addressed lines. The addressed lines are deleted from the - buffer and replaced by a single line containing their joined text. - The current address is set to the resultant line. + Joins the addressed lines, replacing them by a single line + containing their joined text. If only one address is given, this + command does nothing. If lines are joined, the current address is + set to the address of the joined line. Else, the current address + is unchanged. '(.)kx' Marks a line with a lower case letter 'x'. The line can then be addressed as ''x' (i.e., a single quote followed by 'x') in subsequent commands. The mark is not cleared until the line is - deleted or otherwise modified. + deleted or otherwise modified. The current address is unchanged. '(.,.)l' - Prints the addressed lines unambiguously. The end of each line is - marked with a '$', and every '$' character within the text is - printed with a preceding backslash. The current address is set to - the last line printed. + List command. Prints the addressed lines unambiguously. The end of + each line is marked with a '$', and every '$' character within the + text is printed with a preceding backslash. Special characters are + printed as escape sequences. The current address is set to the + address of the last line printed. '(.,.)m(.)' Moves lines in the buffer. The addressed lines are moved to after - the right-hand destination address, which may be the address '0' - (zero). The current address is set to the new address of the last - line moved. + the right-hand destination address. The destination address '0' + (zero) is valid for this command; it moves the addressed lines to + the beginning of the buffer. It is an error if the destination + address falls within the range of moved lines. The current address + is set to the new address of the last line moved. '(.,.)n' - Prints the addressed lines, preceding each line by its line number - and a <tab>. The current address is set to the last line printed. + Number command. Prints the addressed lines, preceding each line by + its line number and a <tab>. The current address is set to the + address of the last line printed. '(.,.)p' - Prints the addressed lines. The current address is set to the last - line printed. + Prints the addressed lines. The current address is set to the + address of the last line printed. 'P' Toggles the command prompt on and off. Unless a prompt is @@ -736,68 +776,89 @@ specified (in parenthesis). default turned off. 'q' - Quits 'ed'. + Quits 'ed'. A warning is printed if any changes have been made in + the buffer since the last 'w' command that wrote the entire buffer + to a file. 'Q' Quits 'ed' unconditionally. This is similar to the 'q' command, except that unwritten changes are discarded without warning. '($)r FILE' - Reads FILE to after the addressed line. If FILE is not specified, - then the default filename is used. If there is no default filename - prior to the command, then the default filename is set to FILE. - Otherwise, the default filename is unchanged. The current address - is set to the last line read. - -'($)r !COMMAND' - Reads to after the addressed line the standard output of - '!command', (see the '!' command below). The default filename is - unchanged. The current address is set to the last line read. + Reads FILE and appends it after the addressed line. If FILE is not + specified, then the default filename is used. If there is no + default filename prior to the command, then the default filename + is set to FILE. Otherwise, the default filename is unchanged. The + address '0' (zero) is valid for this command; it reads the file at + the beginning of the buffer. The current address is set to the + address of the last line read or, if there were none, to the + addressed line. + + If FILE is prefixed with a bang (!), then it is interpreted as a + shell command whose output is to be read, (*note shell escape + command:: '!' below). In this case the default filename is + unchanged. '(.,.)s/RE/REPLACEMENT/' -'(.,.)s/RE/REPLACEMENT/g' -'(.,.)s/RE/REPLACEMENT/N' - Replaces text in the addressed lines matching a regular expression - RE with REPLACEMENT. By default, only the first match in each line - is replaced. If the 'g' (global) suffix is given, then every match - is replaced. The N suffix, where N is a postive number, causes - only the Nth match to be replaced. It is an error if no - substitutions are performed on any of the addressed lines. The - current address is set to the last line affected. + Substitute command. Replaces text in the addressed lines matching a + regular expression RE with REPLACEMENT. By default, only the first + match in each line is replaced. The 's' command accepts any + combination of the suffixes 'g', 'COUNT', 'l', 'n', and 'p'. If + the 'g' (global) suffix is given, then every match is replaced. + The 'COUNT' suffix, where COUNT is a positive number, causes only + the COUNTth match to be replaced. 'g' and 'COUNT' can't be + specified in the same command. 'l', 'n', and 'p' are the usual + print suffixes. It is an error if no substitutions are performed + on any of the addressed lines. The current address is set to the + address of the last line on which a substitution occurred. If a + line is split, a substitution is considered to have occurred on + each of the new lines. If no substitution is performed, the + current address is unchanged. RE and REPLACEMENT may be delimited by any character other than <space>, <newline> and the characters used by the form of the 's' - command shown below. If one or two of the last delimiters is - omitted, then the last line affected is printed as if the print - suffix 'p' were specified. + command shown below. If the last delimiter is omitted, then the + last line affected is printed as if the print suffix 'p' were + specified. The last delimiter can't be omitted if the 's' command + is part of a 'g' or 'v' COMMAND-LIST and is not the last command + in the list, because the meaning of the following escaped newline + becomes ambiguous. An unescaped '&' in REPLACEMENT is replaced by the currently matched text. The character sequence '\M' where M is a number in the range [1,9], is replaced by the Mth backreference expression - of the matched text. If REPLACEMENT consists of a single '%', then - REPLACEMENT from the last substitution is used. Newlines may be - embedded in REPLACEMENT if they are escaped with a backslash ('\'). + of the matched text. If the corresponding backreference expression + does not match, then the character sequence '\M' is replaced by + the empty string. If REPLACEMENT consists of a single '%', then + REPLACEMENT from the last substitution is used. + + A line can be split by including a newline escaped with a backslash + ('\') in REPLACEMENT, except if the 's' command is part of a 'g' + or 'v' COMMAND-LIST, because in this case the meaning of the + escaped newline becomes ambiguous. Each backslash in REPLACEMENT + removes the special meaning (if any) of the following character. '(.,.)s' Repeats the last substitution. This form of the 's' command accepts - a count suffix N, and any combination of the characters 'r', 'g', - and 'p'. If a count suffix N is given, then only the Nth match is - replaced. The 'r' suffix causes the regular expression of the last - search to be used instead of the that of the last substitution. - The 'g' suffix toggles the global suffix of the last substitution. - The 'p' suffix toggles the print suffix of the last substitution. - The current address is set to the last line affected. + the 'g' and 'COUNT' suffixes described above, and any combination + of the suffixes 'p' and 'r'. The 'g' suffix toggles the global + suffix of the last substitution and resets COUNT to 1. The 'p' + suffix toggles the print suffixes of the last substitution. The + 'r' suffix causes the regular expression of the last search to be + used instead of that of the last substitution (if the search + happened after the substitution). '(.,.)t(.)' Copies (i.e., transfers) the addressed lines to after the - right-hand destination address, which may be the address '0' - (zero). The current address is set to the last line copied. + right-hand destination address. If the destination address is '0' + (zero), the lines are copied at the beginning of the buffer. The + current address is set to the address of the last line copied. 'u' - Undoes the last command and restores the current address to what - it was before the command. The global commands 'g', 'G', 'v', and - 'V' are treated as a single command by undo. 'u' is its own - inverse. + Undoes the effect of the last command that modified anything in the + buffer and restores the current address to what it was before the + command. The global commands 'g', 'G', 'v', and 'V' are treated as + a single command by undo. 'u' is its own inverse. '(1,$)v/RE/COMMAND-LIST' This is similar to the 'g' command except that it applies @@ -815,10 +876,13 @@ specified (in parenthesis). filename is specified, then the default filename is used. The current address is unchanged. -'(1,$)w !COMMAND' - Writes the addressed lines to the standard input of '!COMMAND', - (see the '!' command below). The default filename and current - address are unchanged. + If FILE is prefixed with a bang (!), then it is interpreted as a + shell command and the addressed lines are written to its standard + input, (*note shell escape command:: '!' below). In this case the + default filename is unchanged. Writing the buffer to a shell + command does not prevent the warning to the user if an attempt is + made to overwrite or discard the buffer via the 'e' or 'q' + commands. '(1,$)wq FILE' Writes the addressed lines to FILE, and then executes a 'q' @@ -826,16 +890,17 @@ specified (in parenthesis). '(1,$)W FILE' Appends the addressed lines to the end of FILE. This is similar to - the 'w' command, expect that the previous contents of file is not + the 'w' command, except that the previous contents of file is not clobbered. The current address is unchanged. '(.)x' Copies (puts) the contents of the cut buffer to after the addressed - line. The current address is set to the last line copied. + line. The current address is set to the address of the last line + copied. '(.,.)y' Copies (yanks) the addressed lines to the cut buffer. The cut - buffer is overwritten by subsequent 'y', 's', 'j', 'd', or 'c' + buffer is overwritten by subsequent 'c', 'd', 'j', 's', or 'y' commands. The current address is unchanged. '(.+1)zN' @@ -843,15 +908,16 @@ specified (in parenthesis). window size to N. If N is not specified, then the current window size is used. Window size defaults to screen size minus two lines, or to 22 if screen size can't be determined. The current address - is set to the last line printed. + is set to the address of the last line printed. '!COMMAND' - Executes COMMAND via 'sh (1)'. If the first character of COMMAND - is '!', then it is replaced by text of the previous '!COMMAND'. - 'ed' does not process COMMAND for backslash ('\') escapes. - However, an unescaped '%' is replaced by the default filename. - When the shell returns from execution, a '!' is printed to the - standard output. The current line is unchanged. + Shell escape command. Executes COMMAND via 'sh (1)'. If the first + character of COMMAND is '!', then it is replaced by the text of + the previous '!COMMAND'. Thus, '!!' repeats the previous + '!COMMAND'. 'ed' does not process COMMAND for backslash ('\') + escapes. However, an unescaped '%' is replaced by the default + filename. When the shell returns from execution, a '!' is printed + to the standard output. The current address is unchanged. '(.,.)#' Begins a comment; the rest of the line, up to a newline, is @@ -860,12 +926,13 @@ specified (in parenthesis). address is unchanged. '($)=' - Prints the line number of the addressed line. + Prints the line number of the addressed line. The current address + is unchanged. '(.+1)<newline>' - An address alone prints the addressed line. A <newline> alone is - equivalent to '+1p'. The current address is set to the address of - the printed line. + Null command. An address alone prints the addressed line. A + <newline> alone is equivalent to '+1p'. The current address is set + to the address of the printed line. @@ -905,8 +972,6 @@ command list is executed only once. modified buffer results in an error. If the command is entered a second time, it succeeds, but any changes to the buffer are lost. - Exit status: 0 if no errors occurred; otherwise >0. - File: ed.info, Node: Problems, Next: GNU Free Documentation License, Prev: Diagnostics, Up: Top @@ -1412,16 +1477,17 @@ permit their use in free software. Tag Table: Node: Top535 -Node: Overview2195 -Node: Introduction to line editing4251 -Node: Invoking ed11470 -Node: Line addressing13270 -Node: Regular expressions16347 -Node: Commands21691 -Node: Limitations32963 -Node: Diagnostics33608 -Node: Problems34309 -Node: GNU Free Documentation License34842 +Node: Overview2198 +Node: Introduction to line editing4254 +Node: Invoking ed11527 +Node: Line addressing13529 +Node: Regular expressions17242 +Node: Commands22586 +Ref: shell escape command36495 +Node: Limitations37517 +Node: Diagnostics38162 +Node: Problems38807 +Node: GNU Free Documentation License39340 End Tag Table diff --git a/doc/ed.texi b/doc/ed.texi index 26fb2a9..cdf1f6c 100644 --- a/doc/ed.texi +++ b/doc/ed.texi @@ -6,8 +6,8 @@ @finalout @c %**end of header -@set UPDATED 24 January 2016 -@set VERSION 1.13 +@set UPDATED 22 February 2017 +@set VERSION 1.14.2 @dircategory Basics @direntry @@ -15,7 +15,7 @@ @end direntry @copying -Copyright @copyright{} 1993, 1994, 2006-2016 +Copyright @copyright{} 1993, 1994, 2006-2017 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -324,8 +324,8 @@ And loathsome canker lives in sweetest bud. # Move the title to its proper place. 5m0p Sonnet #50 -# The title is now the first line, and the current line has been -# set to this line as well. +# The title is now the first line, and the current address has been +# set to the address of this line as well. ,p Sonnet #50 No more be grieved at that which thou hast done. @@ -337,9 +337,9 @@ wq sonnet $ @end example -When @command{ed} opens a file, the current line is initially set to the -last line of that file. Similarly, the move command @samp{m} sets the -current line to the last line moved. +When @command{ed} opens a file, the current address is initially set to +the address of the last line of that file. Similarly, the move command +@samp{m} sets the current address to the address of the last line moved. Related programs or routines are @command{vi (1)}, @command{sed (1)}, @command{regex (3)}, @command{sh (1)}. Relevant documents @@ -409,15 +409,20 @@ current directory and execution of shell commands. @item -s @itemx --quiet @itemx --silent -Suppresses diagnostics. This should be used if @command{ed}'s standard +Suppresses diagnostics, the printing of byte counts by @samp{e}, +@samp{E}, @samp{r} and @samp{w} commands, and the @samp{!} prompt after +a @samp{!} command. This option may be useful if @command{ed}'s standard input is from a script. @item -v @itemx --verbose -Verbose mode. This may be toggled on and off with the @samp{H} command. +Verbose mode; prints error explanations. This may be toggled on and off +with the @samp{H} command. @end table +Exit status: 0 if no errors occurred; otherwise >0. + @node Line addressing @chapter Line addressing @@ -425,26 +430,30 @@ Verbose mode. This may be toggled on and off with the @samp{H} command. An address represents the number of a line in the buffer. @command{ed} maintains a @dfn{current address} which is typically supplied to commands as the default address when none is specified. When a file is -first read, the current address is set to the last line of the file. In -general, the current address is set to the last line affected by a -command. +first read, the current address is set to the address of the last line +of the file. In general, the current address is set to the address of +the last line affected by a command. One exception to the rule that addresses represent line numbers is the address @samp{0} (zero). This means "before the first line", and is valid wherever it makes sense. An address range is two addresses separated either by a comma (@samp{,}) -or a semicolon (@samp{;}). The value of the first address in a range -cannot exceed the value of the second. If only one address is given in a -range, then the second address is set to the given address. If an -@var{n}-tuple of addresses is given where @var{n} > 2, then the -corresponding range is determined by the last two addresses in the -@var{n}-tuple. If only one address is expected, then the last address is -used. - -In a semicolon-delimited range, the current address (@samp{.}) is set to -the first address before the second address is calculated. This feature -can be used to set the starting line for searches. +or a semicolon (@samp{;}). In a semicolon-delimited range, the current +address (@samp{.}) is set to the first address before the second address +is calculated. This feature can be used to set the starting line for +searches. The value of the first address in a range cannot exceed the +value of the second. + +Addresses can be omitted on either side of the comma or semicolon +separator. If only the first address is given in a range, then the +second address is set to the given address. If only the second address +is given, the resulting address pairs are @samp{1,addr} and +@samp{.;addr} respectively. If a @var{n}-tuple of addresses is given +where @var{n} > 2, then the corresponding range is determined by the +last two addresses in the @var{n}-tuple. If only one address is +expected, then the last address is used. It is an error to give any +number of addresses to a command that requires zero addresses. A line address is constructed as follows: @@ -479,17 +488,17 @@ address range @samp{1,$}. @item ; The current through last lines in the buffer. This is equivalent to the -address range @samp{.,$}. +address range @samp{.;$}. @item /@var{re}/ The next line containing the regular expression @var{re}. The search wraps to the beginning of the buffer and continues down to the current -line, if necessary. @samp{//} repeats the last search. +line, if necessary. A null @var{re} @samp{//} repeats the last search. @item ?@var{re}? The previous line containing the regular expression @var{re}. The search wraps to the end of the buffer and continues up to the current line, if -necessary. @samp{??} repeats the last search. +necessary. A null @var{re} @samp{??} repeats the last search. @item 'x The apostrophe-x character pair addresses the line previously marked by @@ -503,9 +512,6 @@ separated by whitespace. Offsets are constructed as follows: @itemize @bullet @item -A number adds the indicated number of lines to the address. - -@item @samp{+} or @samp{-} followed by a number adds or subtracts the indicated number of lines to or from the address. @@ -513,8 +519,17 @@ indicated number of lines to or from the address. @samp{+} or @samp{-} not followed by a number adds or subtracts 1 to or from the address. +@item +A number adds the indicated number of lines to the address. + @end itemize +It is not an error if an intermediate address value is negative or +greater than the address of the last line in the buffer. It is an error +if the final address value is negative or greater than the address of +the last line in the buffer. It is an error if a search for a @var{re} +fails to find a matching line. + @node Regular expressions @chapter Regular expressions @@ -688,7 +703,9 @@ backslash (@samp{\}). In general, at most one command is allowed per line. However, most commands accept a print suffix, which is any of @samp{p} (print), @samp{l} (list), or @samp{n} (enumerate), to print the last line -affected by the command. +affected by the command. It is not portable to give more than one print +suffix, but @command{ed} allows any combination of non-repeated print +suffixes and combines their effects. An interrupt (typically @key{Control-C}) has the effect of aborting the current command and returning the editor to command mode. @@ -700,65 +717,78 @@ specified (in parenthesis). @table @code @item (.)a -Appends text to the buffer after the addressed line, which may be the -address @samp{0} (zero). Text is entered in input mode. The current -address is set to last line entered. +Appends text to the buffer after the addressed line. The address +@samp{0} (zero) is valid for this command; it places the entered text at +the beginning of the buffer. Text is entered in input mode. The current +address is set to the address of the last line entered or, if there were +none, to the addressed line. @item (.,.)c Changes lines in the buffer. The addressed lines are deleted from the -buffer, and text is appended in their place. Text is entered in input -mode. The current address is set to last line entered. +buffer, and text is inserted in their place. Text is entered in input +mode. The current address is set to the address of the last line entered +or, if there were none, to the new address of the line after the last +line deleted; if the lines deleted were originally at the end of the +buffer, the current address is set to the address of the new last line; +if no lines remain in the buffer, the current address is set to zero. @item (.,.)d -Deletes the addressed lines from the buffer. If there is a line after -the deleted range, then the current address is set to this line. -Otherwise the current address is set to the line before the deleted -range. +Deletes the addressed lines from the buffer. The current address is set +to the new address of the line after the last line deleted; if the lines +deleted were originally at the end of the buffer, the current address is +set to the address of the new last line; if no lines remain in the +buffer, the current address is set to zero. @item e @var{file} Edits @var{file}, and sets the default filename. If @var{file} is not specified, then the default filename is used. Any lines in the buffer are deleted before the new file is read. The current address is set to -the last line read. +the address of the last line in the buffer. + +If @var{file} is prefixed with a bang (!), then it is interpreted as a +shell command whose output is to be read, (@pxref{shell escape command} +@samp{!} below). In this case the default filename is unchanged. -@item e !@var{command} -Edits the standard output of @samp{!@var{command}}, (see the @samp{!} -command below). The default filename is unchanged. Any lines in the -buffer are deleted before the output of @var{command} is read. The -current address is set to the last line read. +A warning is printed if any changes have been made in the buffer since +the last @samp{w} command that wrote the entire buffer to a file. @item E @var{file} Edits @var{file} unconditionally. This is similar to the @samp{e} command, except that unwritten changes are discarded without warning. -The current address is set to the last line read. @item f @var{file} Sets the default filename to @var{file}. If @var{file} is not specified, then the default unescaped filename is printed. @item (1,$)g/@var{re}/@var{command-list} -Global command. Applies @var{command-list} to each of the addressed -lines matching a regular expression @var{re}. The current address is set -to the line currently matched before @var{command-list} is executed. At -the end of the @samp{g} command, the current address is set to the last -line affected by @var{command-list}. - -At least the first command of @var{command-list} must appear on the same -line as the @samp{g} command. All lines of a multi-line -@var{command-list} except the last line must be terminated with a -backslash (@samp{\}). Any commands are allowed, except for @samp{g}, -@samp{G}, @samp{v}, and @samp{V}. By default, a newline alone in -@var{command-list} is equivalent to a @samp{p} command. If @command{ed} -is invoked with the command-line option @samp{-G}, then a newline in -@var{command-list} is equivalent to a @samp{.+1p} command. +Global command. The global command makes two passes over the file. On +the first pass, all the addressed lines matching a regular expression +@var{re} are marked. Then, going sequentially from the beginning of the +file to the end of the file, the given @var{command-list} is executed +for each marked line, with the current address set to the address of +that line. Any line modified by the @var{command-list} is unmarked. The +final value of the current address is the value assigned by the last +command in the last @var{command-list} executed. If there were no +matching lines, the current address is unchanged. + +The first command of @var{command-list} must appear on the same line as +the @samp{g} command. All lines of a multi-line @var{command-list} +except the last line must be terminated with a backslash (@samp{\}). Any +commands are allowed, except for @samp{g}, @samp{G}, @samp{v}, and +@samp{V}. The @samp{.} terminating the input mode of commands @samp{a}, +@samp{c}, and @samp{i} can be omitted if it would be the last line of +@var{command-list}. By default, a newline alone in @var{command-list} is +equivalent to a @samp{p} command. If @command{ed} is invoked with the +command-line option @samp{-G}, then a newline in @var{command-list} is +equivalent to a @samp{.+1p} command. @item (1,$)G/@var{re}/ Interactive global command. Interactively edits the addressed lines matching a regular expression @var{re}. For each matching line, the line is printed, the current address is set, and the user is prompted to -enter a @var{command-list}. At the end of the @samp{G} command, the -current address is set to the last line affected by (the last) -@var{command-list}. +enter a @var{command-list}. The final value of the current address is +the value assigned by the last command executed. If there were no +matching lines, the current address is unchanged. The format of @var{command-list} is the same as that of the @samp{g} command. A newline alone acts as a null command list. A single @samp{&} @@ -773,41 +803,47 @@ not printed. It is recommended that ed scripts begin with this command to aid in debugging. @item (.)i -Inserts text in the buffer before the current line. The address @samp{0} -(zero) is valid for this command; it is equivalent to address @samp{1}. -Text is entered in input mode. The current address is set to the last -line entered. +Inserts text in the buffer before the addressed line. The address +@samp{0} (zero) is valid for this command; it is equivalent to address +@samp{1}. Text is entered in input mode. The current address is set to +the address of the last line entered or, if there were none, to the +addressed line. @item (.,.+1)j -Joins the addressed lines. The addressed lines are deleted from the -buffer and replaced by a single line containing their joined text. The -current address is set to the resultant line. +Joins the addressed lines, replacing them by a single line containing +their joined text. If only one address is given, this command does +nothing. If lines are joined, the current address is set to the address +of the joined line. Else, the current address is unchanged. @item (.)kx Marks a line with a lower case letter @samp{x}. The line can then be addressed as @samp{'x} (i.e., a single quote followed by @samp{x}) in subsequent commands. The mark is not cleared until the line is deleted -or otherwise modified. +or otherwise modified. The current address is unchanged. @item (.,.)l -Prints the addressed lines unambiguously. The end of each line is marked -with a @samp{$}, and every @samp{$} character within the text is printed -with a preceding backslash. The current address is set to the last line -printed. +List command. Prints the addressed lines unambiguously. The end of each +line is marked with a @samp{$}, and every @samp{$} character within the +text is printed with a preceding backslash. Special characters are +printed as escape sequences. The current address is set to the address +of the last line printed. @item (.,.)m(.) Moves lines in the buffer. The addressed lines are moved to after the -right-hand destination address, which may be the address @samp{0} -(zero). The current address is set to the new address of the last line -moved. +right-hand destination address. The destination address @samp{0} (zero) +is valid for this command; it moves the addressed lines to the beginning +of the buffer. It is an error if the destination address falls within +the range of moved lines. The current address is set to the new address +of the last line moved. @item (.,.)n -Prints the addressed lines, preceding each line by its line number and a -@key{tab}. The current address is set to the last line printed. +Number command. Prints the addressed lines, preceding each line by its +line number and a @key{tab}. The current address is set to the address +of the last line printed. @item (.,.)p -Prints the addressed lines. The current address is set to the last line -printed. +Prints the addressed lines. The current address is set to the address of +the last line printed. @item P Toggles the command prompt on and off. Unless a prompt is specified with @@ -815,69 +851,89 @@ command-line option @samp{-p}, the command prompt is by default turned off. @item q -Quits @command{ed}. +Quits @command{ed}. A warning is printed if any changes have been made +in the buffer since the last @samp{w} command that wrote the entire +buffer to a file. @item Q Quits @command{ed} unconditionally. This is similar to the @code{q} command, except that unwritten changes are discarded without warning. @item ($)r @var{file} -Reads @var{file} to after the addressed line. If @var{file} is not -specified, then the default filename is used. If there is no default -filename prior to the command, then the default filename is set to -@var{file}. Otherwise, the default filename is unchanged. The current -address is set to the last line read. - -@item ($)r !@var{command} -Reads to after the addressed line the standard output of -@samp{!command}, (see the @samp{!} command below). The default filename -is unchanged. The current address is set to the last line read. +Reads @var{file} and appends it after the addressed line. If @var{file} +is not specified, then the default filename is used. If there is no +default filename prior to the command, then the default filename is set +to @var{file}. Otherwise, the default filename is unchanged. The address +@samp{0} (zero) is valid for this command; it reads the file at the +beginning of the buffer. The current address is set to the address of +the last line read or, if there were none, to the addressed line. + +If @var{file} is prefixed with a bang (!), then it is interpreted as a +shell command whose output is to be read, (@pxref{shell escape command} +@samp{!} below). In this case the default filename is unchanged. @item (.,.)s/@var{re}/@var{replacement}/ -@itemx (.,.)s/@var{re}/@var{replacement}/g -@itemx (.,.)s/@var{re}/@var{replacement}/@var{n} -Replaces text in the addressed lines matching a regular expression -@var{re} with @var{replacement}. By default, only the first match in -each line is replaced. If the @samp{g} (global) suffix is given, then -every match is replaced. The @var{n} suffix, where @var{n} is a postive -number, causes only the @var{n}th match to be replaced. It is an error -if no substitutions are performed on any of the addressed lines. The -current address is set to the last line affected. +Substitute command. Replaces text in the addressed lines matching a +regular expression @var{re} with @var{replacement}. By default, only the +first match in each line is replaced. The @samp{s} command accepts any +combination of the suffixes @samp{g}, @samp{@var{count}}, @samp{l}, +@samp{n}, and @samp{p}. If the @samp{g} (global) suffix is given, then +every match is replaced. The @samp{@var{count}} suffix, where +@var{count} is a positive number, causes only the @var{count}th match to +be replaced. @samp{g} and @samp{@var{count}} can't be specified in the +same command. @samp{l}, @samp{n}, and @samp{p} are the usual print +suffixes. It is an error if no substitutions are performed on any of the +addressed lines. The current address is set to the address of the last +line on which a substitution occurred. If a line is split, a +substitution is considered to have occurred on each of the new lines. If +no substitution is performed, the current address is unchanged. @var{re} and @var{replacement} may be delimited by any character other than @key{space}, @key{newline} and the characters used by the form of -the @samp{s} command shown below. If one or two of the last delimiters -is omitted, then the last line affected is printed as if the print -suffix @samp{p} were specified. +the @samp{s} command shown below. If the last delimiter is omitted, then +the last line affected is printed as if the print suffix @samp{p} were +specified. The last delimiter can't be omitted if the @samp{s} command +is part of a @samp{g} or @samp{v} @var{command-list} and is not the last +command in the list, because the meaning of the following escaped +newline becomes ambiguous. An unescaped @samp{&} in @var{replacement} is replaced by the currently matched text. The character sequence @samp{\@var{m}} where @var{m} is a number in the range [1,9], is replaced by the @var{m}th backreference -expression of the matched text. If @var{replacement} consists of a +expression of the matched text. If the corresponding backreference +expression does not match, then the character sequence @samp{\@var{m}} +is replaced by the empty string. If @var{replacement} consists of a single @samp{%}, then @var{replacement} from the last substitution is -used. Newlines may be embedded in @var{replacement} if they are escaped -with a backslash (@samp{\}). +used. + +A line can be split by including a newline escaped with a backslash +(@samp{\}) in @var{replacement}, except if the @samp{s} command is part +of a @samp{g} or @samp{v} @var{command-list}, because in this case the +meaning of the escaped newline becomes ambiguous. Each backslash in +@var{replacement} removes the special meaning (if any) of the following +character. @item (.,.)s Repeats the last substitution. This form of the @samp{s} command accepts -a count suffix @var{n}, and any combination of the characters @samp{r}, -@samp{g}, and @samp{p}. If a count suffix @var{n} is given, then only -the @var{n}th match is replaced. The @samp{r} suffix causes the regular -expression of the last search to be used instead of the that of the last -substitution. The @samp{g} suffix toggles the global suffix of the last -substitution. The @samp{p} suffix toggles the print suffix of the last -substitution. The current address is set to the last line affected. +the @samp{g} and @samp{@var{count}} suffixes described above, and any +combination of the suffixes @samp{p} and @samp{r}. The @samp{g} suffix +toggles the global suffix of the last substitution and resets +@var{count} to 1. The @samp{p} suffix toggles the print suffixes of the +last substitution. The @samp{r} suffix causes the regular expression of +the last search to be used instead of that of the last substitution (if +the search happened after the substitution). @item (.,.)t(.) Copies (i.e., transfers) the addressed lines to after the right-hand -destination address, which may be the address @samp{0} (zero). The -current address is set to the last line copied. +destination address. If the destination address is @samp{0} (zero), the +lines are copied at the beginning of the buffer. The current address is +set to the address of the last line copied. @item u -Undoes the last command and restores the current address to what it was -before the command. The global commands @samp{g}, @samp{G}, @samp{v}, -and @samp{V} are treated as a single command by undo. @samp{u} is its -own inverse. +Undoes the effect of the last command that modified anything in the +buffer and restores the current address to what it was before the +command. The global commands @samp{g}, @samp{G}, @samp{v}, and @samp{V} +are treated as a single command by undo. @samp{u} is its own inverse. @item (1,$)v/@var{re}/@var{command-list} This is similar to the @samp{g} command except that it applies @@ -895,10 +951,12 @@ then the default filename is set to @var{file}, otherwise it is unchanged. If no filename is specified, then the default filename is used. The current address is unchanged. -@item (1,$)w !@var{command} -Writes the addressed lines to the standard input of -@samp{!@var{command}}, (see the @samp{!} command below). The default -filename and current address are unchanged. +If @var{file} is prefixed with a bang (!), then it is interpreted as a +shell command and the addressed lines are written to its standard input, +(@pxref{shell escape command} @samp{!} below). In this case the default +filename is unchanged. Writing the buffer to a shell command does not +prevent the warning to the user if an attempt is made to overwrite or +discard the buffer via the @samp{e} or @samp{q} commands. @item (1,$)wq @var{file} Writes the addressed lines to @var{file}, and then executes a @samp{q} @@ -906,33 +964,35 @@ command. @item (1,$)W @var{file} Appends the addressed lines to the end of @var{file}. This is similar to -the @samp{w} command, expect that the previous contents of file is not +the @samp{w} command, except that the previous contents of file is not clobbered. The current address is unchanged. @item (.)x Copies (puts) the contents of the cut buffer to after the addressed -line. The current address is set to the last line copied. +line. The current address is set to the address of the last line copied. @item (.,.)y Copies (yanks) the addressed lines to the cut buffer. The cut buffer is -overwritten by subsequent @samp{y}, @samp{s}, @samp{j}, @samp{d}, or -@samp{c} commands. The current address is unchanged. +overwritten by subsequent @samp{c}, @samp{d}, @samp{j}, @samp{s}, or +@samp{y} commands. The current address is unchanged. @item (.+1)z@var{n} Scrolls @var{n} lines at a time starting at addressed line, and sets window size to @var{n}. If @var{n} is not specified, then the current window size is used. Window size defaults to screen size minus two lines, or to 22 if screen size can't be determined. The current address -is set to the last line printed. +is set to the address of the last line printed. +@anchor{shell escape command} @item !@var{command} -Executes @var{command} via @command{sh (1)}. If the first character of -@var{command} is @samp{!}, then it is replaced by text of the previous -@samp{!@var{command}}. @command{ed} does not process @var{command} for -backslash (@samp{\}) escapes. However, an unescaped @samp{%} is replaced -by the default filename. When the shell returns from execution, a -@samp{!} is printed to the standard output. The current line is -unchanged. +Shell escape command. Executes @var{command} via @command{sh (1)}. If +the first character of @var{command} is @samp{!}, then it is replaced by +the text of the previous @samp{!@var{command}}. Thus, @samp{!!} repeats +the previous @samp{!@var{command}}. @command{ed} does not process +@var{command} for backslash (@samp{\}) escapes. However, an unescaped +@samp{%} is replaced by the default filename. When the shell returns +from execution, a @samp{!} is printed to the standard output. The +current address is unchanged. @item (.,.)# Begins a comment; the rest of the line, up to a newline, is ignored. If @@ -941,12 +1001,13 @@ address is set to that address. Otherwise, the current address is unchanged. @item ($)= -Prints the line number of the addressed line. +Prints the line number of the addressed line. The current address is +unchanged. @item (.+1)@key{newline} -An address alone prints the addressed line. A @key{newline} alone is -equivalent to @samp{+1p}. The current address is set to the address of -the printed line. +Null command. An address alone prints the addressed line. A +@key{newline} alone is equivalent to @samp{+1p}. The current address is +set to the address of the printed line. @end table @@ -983,8 +1044,6 @@ Attempting to quit @command{ed} or edit another file before writing a modified buffer results in an error. If the command is entered a second time, it succeeds, but any changes to the buffer are lost. -Exit status: 0 if no errors occurred; otherwise >0. - @node Problems @chapter Reporting bugs |