diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 148 |
1 files changed, 0 insertions, 148 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi index 17df090e..2adad8be 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -560,8 +560,6 @@ particular records in a file and perform operations upon them. * Library Names:: How to best name private global variables in library functions. * General Functions:: Functions that are of general use. -* Nextfile Function:: Two implementations of a @code{nextfile} - function. * Strtonum Function:: A replacement for the built-in @code{strtonum()} function. * Assert Function:: A function for assertions in @command{awk} @@ -12173,12 +12171,6 @@ reserved for closing files, pipes, and coprocesses that are opened with redirections. It is not related to the main processing that @command{awk} does with the files listed in @code{ARGV}. -If it's necessary to use an @command{awk} version that doesn't support -@code{nextfile}, see -@ref{Nextfile Function}, -for a user-defined function that simulates the @code{nextfile} -statement. - @cindex functions, user-defined, @code{next}/@code{nextfile} statements and @cindex @code{nextfile} statement, user-defined functions and The current version of the Brian Kernighan's @command{awk} (@pxref{Other @@ -18991,8 +18983,6 @@ does not have a @file{/dev/stderr}, or if you cannot use @command{gawk}. A number of programs use @code{nextfile} (@pxref{Nextfile Statement}) to skip any remaining input in the input file. -@ref{Nextfile Function}, -shows you how to write a function that does the same thing. @item @c 12/2000: Thanks to Nelson Beebe for pointing out the output issue. @@ -19130,8 +19120,6 @@ This @value{SECTION} presents a number of functions that are of general programming use. @menu -* Nextfile Function:: Two implementations of a @code{nextfile} - function. * Strtonum Function:: A replacement for the built-in @code{strtonum()} function. * Assert Function:: A function for assertions in @command{awk} @@ -19145,138 +19133,6 @@ programming use. * Gettimeofday Function:: A function to get formatted times. @end menu -@node Nextfile Function -@subsection Implementing @code{nextfile} as a Function - -@cindex input files, skipping -@c STARTOFRANGE libfnex -@cindex libraries of @command{awk} functions, @code{nextfile} statement -@c STARTOFRANGE flibnex -@cindex functions, library, @code{nextfile} statement -@c STARTOFRANGE nexim -@cindex @code{nextfile} statement, implementing -@cindex @command{gawk}, @code{nextfile} statement in -The @code{nextfile} statement, presented in -@ref{Nextfile Statement}, -is a @command{gawk}-specific extension---it is not available in most other -implementations of @command{awk}. This @value{SECTION} shows two versions of a -@code{nextfile()} function that you can use to simulate @command{gawk}'s -@code{nextfile} statement if you cannot use @command{gawk}. - -A first attempt at writing a @code{nextfile()} function is as follows: - -@example -# nextfile --- skip remaining records in current file -# this should be read in before the "main" awk program - -function nextfile() @{ _abandon_ = FILENAME; next @} -_abandon_ == FILENAME @{ next @} -@end example - -@cindex programming conventions, @code{nextfile} statement -Because it supplies a rule that must be executed first, this file should -be included before the main program. This rule compares the current -@value{DF}'s name (which is always in the @code{FILENAME} variable) to -a private variable named @code{_abandon_}. If the @value{FN} matches, -then the action part of the rule executes a @code{next} statement to -go on to the next record. (The use of @samp{_} in the variable name is -a convention. It is discussed more fully in -@ref{Library Names}.) - -The use of the @code{next} statement effectively creates a loop that reads -all the records from the current @value{DF}. -The end of the file is eventually reached and -a new @value{DF} is opened, changing the value of @code{FILENAME}. -Once this happens, the comparison of @code{_abandon_} to @code{FILENAME} -fails, and execution continues with the first rule of the ``real'' program. - -The @code{nextfile()} function itself simply sets the value of @code{_abandon_} -and then executes a @code{next} statement to start the -loop. -@ignore -@c If the function can't be used on other versions of awk, this whole -@c section is pointless, no? Sigh. -@footnote{@command{gawk} is the only known @command{awk} implementation -that allows you to -execute @code{next} from within a function body. Some other workaround -is necessary if you are not using @command{gawk}.} -@end ignore - -@cindex @code{nextfile()} user-defined function -This initial version has a subtle problem. -If the same @value{DF} is listed @emph{twice} on the command line, -one right after the other -or even with just a variable assignment between them, -this code skips right through the file a second time, even though -it should stop when it gets to the end of the first occurrence. -A second version of @code{nextfile()} that remedies this problem -is shown here: - -@example -@c file eg/lib/nextfile.awk -# nextfile --- skip remaining records in current file -# correctly handle successive occurrences of the same file -@c endfile -@ignore -@c file eg/lib/nextfile.awk -# -# Arnold Robbins, arnold@@skeeve.com, Public Domain -# May, 1993 - -@c endfile -@end ignore -@c file eg/lib/nextfile.awk -# this should be read in before the "main" awk program - -function nextfile() @{ _abandon_ = FILENAME; next @} - -_abandon_ == FILENAME @{ - if (FNR == 1) - _abandon_ = "" - else - next -@} -@c endfile -@end example - -The @code{nextfile()} function has not changed. It makes @code{_abandon_} -equal to the current @value{FN} and then executes a @code{next} statement. -The @code{next} statement reads the next record and increments @code{FNR} -so that @code{FNR} is guaranteed to have a value of at least two. -However, if @code{nextfile()} is called for the last record in the file, -then @command{awk} closes the current @value{DF} and moves on to the next -one. Upon doing so, @code{FILENAME} is set to the name of the new file -and @code{FNR} is reset to one. If this next file is the same as -the previous one, @code{_abandon_} is still equal to @code{FILENAME}. -However, @code{FNR} is equal to one, telling us that this is a new -occurrence of the file and not the one we were reading when the -@code{nextfile()} function was executed. In that case, @code{_abandon_} -is reset to the empty string, so that further executions of this rule -fail (until the next time that @code{nextfile()} is called). - -If @code{FNR} is not one, then we are still in the original @value{DF} -and the program executes a @code{next} statement to skip through it. - -An important question to ask at this point is: given that the -functionality of @code{nextfile} can be provided with a library file, -why is it built into @command{gawk}? Adding -features for little reason leads to larger, slower programs that are -harder to maintain. -The answer is that building @code{nextfile} into @command{gawk} provides -significant gains in efficiency. If the @code{nextfile()} function is executed -at the beginning of a large @value{DF}, @command{awk} still has to scan the entire -file, splitting it up into records, -@c at least conceptually -just to skip over it. The built-in -@code{nextfile} can simply close the file immediately and proceed to the -next one, which saves a lot of time. This is particularly important in -@command{awk}, because @command{awk} programs are generally I/O-bound (i.e., -they spend most of their time doing input and output, instead of performing -computations). -@c ENDOFRANGE libfnex -@c ENDOFRANGE flibnex -@c ENDOFRANGE nexim - @node Strtonum Function @subsection Converting Strings To Numbers @@ -19990,8 +19846,6 @@ again the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function -This version has same problem as the first version of @code{nextfile()} -(@pxref{Nextfile Function}). If the same @value{DF} occurs twice in a row on the command line, then @code{endfile()} and @code{beginfile()} are not executed at the end of the first pass and at the beginning of the second pass. @@ -20105,8 +19959,6 @@ or modify this code as appropriate. The @code{rewind()} function also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). -@xref{Nextfile Function}, -for a function version of @code{nextfile}. @node File Checking @subsection Checking for Readable @value{DDF}s |