diff options
Diffstat (limited to 'doc/gawktexi.in')
| -rw-r--r-- | doc/gawktexi.in | 76 |
1 files changed, 44 insertions, 32 deletions
diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 96abe297..a186f902 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -3499,6 +3499,8 @@ noticed because it is ``hidden'' inside the comment. Thus, the @cindex statements, multiple @cindex @code{;} (semicolon), separating statements in actions @cindex semicolon (@code{;}), separating statements in actions +@cindex @code{;} (semicolon), separating rules +@cindex semicolon (@code{;}), separating rules When @command{awk} statements within one rule are short, you might want to put more than one of them on a line. This is accomplished by separating the statements with a semicolon (@samp{;}). @@ -4038,6 +4040,7 @@ that this option may disappear in a future version of @command{gawk}. Force the use of the locale's decimal point character when parsing numeric input data (@pxref{Locales}). +@cindex pretty printing @item @option{-o}[@var{file}] @itemx @option{--pretty-print}[@code{=}@var{file}] @cindex @option{-o} option @@ -5558,7 +5561,7 @@ expressions are not available in regular expressions. @cindex bracket expressions @cindex bracket expressions, range expressions @cindex range expressions (regexps) -@cindex character lists in regular expression +@cindex character lists in regular expressions As mentioned earlier, a bracket expression matches any character among those listed between the opening and closing square brackets. @@ -12951,6 +12954,8 @@ Logical ``or.'' @cindex @code{?} (question mark), @code{?:} operator @cindex question mark (@code{?}), @code{?:} operator +@cindex @code{:} (colon), @code{?:} operator +@cindex colon (@code{:}), @code{?:} operator @item @code{?:} Conditional. This operator groups right to left. @@ -14663,8 +14668,8 @@ is to simply say @samp{FS = FS}, perhaps with an explanatory comment. @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable @cindex differences in @command{awk} and @command{gawk}, @code{IGNORECASE} variable -@cindex case sensitivity, and string comparisons -@cindex case sensitivity, and regexps +@cindex case sensitivity, string comparisons and +@cindex case sensitivity, regexps and @cindex regular expressions, case sensitivity @item IGNORECASE # If @code{IGNORECASE} is nonzero or non-null, then all string comparisons @@ -14991,7 +14996,7 @@ are guaranteed to be available: @table @code @item PROCINFO["argv"] -@cindex command line arguments, @code{PROCINFO["argv"]} +@cindex command line, arguments The @code{PROCINFO["argv"]} array contains all of the command-line arguments (after glob expansion and redirection processing on platforms where that must be done manually by the program) with subscripts ranging from 0 through @@ -15224,7 +15229,7 @@ if no match was found. @cindex @command{gawk}, @code{RT} variable in @cindex @code{RT} variable -@cindex differences in @command{awk} and @command{gawk}, @code{RT} variable +@cindex differences in @command{awk} and @command{gawk}, @code{RS}/@code{RT} variables @item @code{RT #} The input text that matched the text denoted by @code{RS}, the record separator. It is set every time a record is read. @@ -15868,8 +15873,8 @@ automatically converts it to a string. @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex case sensitivity, array indices and -@cindex arrays, and @code{IGNORECASE} variable -@cindex @code{IGNORECASE} variable, and array indices +@cindex arrays, @code{IGNORECASE} variable and +@cindex @code{IGNORECASE} variable, array indices and The value of @code{IGNORECASE} has no effect upon array subscripting. The identical string value used to store an array element must be used to retrieve it. @@ -16352,7 +16357,7 @@ sorting arrays; see @ref{Array Sorting Functions}. @cindex numbers, as array subscripts @cindex arrays, numeric subscripts @cindex subscripts in arrays, numbers as -@cindex @code{CONVFMT} variable, and array subscripts +@cindex @code{CONVFMT} variable, array subscripts and An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting @@ -16509,7 +16514,7 @@ if (4 in foo) print "This will never be printed" @end example -@cindex null strings, and deleting array elements +@cindex null strings, deleting array elements and It is important to note that deleting an element is @emph{not} the same as assigning it a null value (the empty string, @code{""}). For example: @@ -16604,7 +16609,7 @@ languages, including @command{awk}) to refer to an element of a two-dimensional array named @code{grid} is with @code{grid[@var{x},@var{y}]}. -@cindex @code{SUBSEP} variable, and multidimensional arrays +@cindex @code{SUBSEP} variable, multidimensional arrays and Multidimensional arrays are supported in @command{awk} through concatenation of indices into one string. @command{awk} converts the indices into strings @@ -17521,7 +17526,7 @@ warning about this. @cindex common extensions, @code{length()} applied to an array @cindex extensions, common@comma{} @code{length()} applied to an array -@cindex differences between @command{gawk} and @command{awk} +@cindex differences in @command{awk} and @command{gawk}, @code{length()} function @cindex number of array elements @cindex array, number of elements With @command{gawk} and several other @command{awk} implementations, when given an @@ -19095,7 +19100,7 @@ Operands | 0 | 1 | 0 | 1 | 0 | 1 @end docbook @end float -@cindex bitwise, complement +@cindex bitwise complement @cindex complement, bitwise As you can see, the result of an AND operation is 1 only when @emph{both} bits are 1. @@ -22772,7 +22777,7 @@ uses these functions. @cindex functions, library, group database@comma{} reading @cindex group database, reading @cindex database, group, reading -@cindex @code{PROCINFO} array, and group membership +@cindex @code{PROCINFO} array, group membership and @cindex @code{getgrent()} function (C library) @cindex @code{getgrent()} user-defined function @cindex groups@comma{} information about @@ -24071,7 +24076,7 @@ $ @kbd{id} @print{} uid=1000(arnold) gid=1000(arnold) groups=1000(arnold),4(adm),7(lp),27(sudo) @end example -@cindex @code{PROCINFO} array, and user and group ID numbers +@cindex @code{PROCINFO} array, user and group ID numbers and This information is part of what is provided by @command{gawk}'s @code{PROCINFO} array (@pxref{Built-in Variables}). However, the @command{id} utility provides a more palatable output than just @@ -27485,8 +27490,8 @@ both arrays use the values. @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in -@cindex arrays, sorting, and @code{IGNORECASE} variable -@cindex @code{IGNORECASE} variable, and array sorting functions +@cindex arrays, sorting, @code{IGNORECASE} variable and +@cindex @code{IGNORECASE} variable, array sorting functions and Because @code{IGNORECASE} affects string comparisons, the value of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}. Note also that the locale's sorting order does @emph{not} @@ -27734,7 +27739,7 @@ or @code{getline}. @end quotation @cindex @command{gawk}, @code{PROCINFO} array in -@cindex @code{PROCINFO} array, and communications via ptys +@cindex @code{PROCINFO} array, communications via ptys and You may also use pseudo-ttys (ptys) for two-way communication instead of pipes, if your system supports them. This is done on a per-command basis, by setting a special element @@ -27767,7 +27772,7 @@ driver and not passed through. Finally, coprocesses open up the possibility of @dfn{deadlock} between @command{gawk} and the program running in the coprocess. This can occur if you send ``too much'' data to the coprocess before reading any back; -each process is blocked writing data with noone available to read what +each process is blocked writing data with no one available to read what they've already written. There is no workaround for deadlock; careful programming and knowledge of the behavior of the coprocess are required. @end quotation @@ -28019,8 +28024,8 @@ Here is the @file{awkprof.out} that results from running the illustrates that @command{awk} programmers sometimes get up very early in the morning to work): -@cindex @code{BEGIN} pattern, and profiling -@cindex @code{END} pattern, and profiling +@cindex @code{BEGIN} pattern, profiling and +@cindex @code{END} pattern, profiling and @example # gawk profile, created Mon Sep 29 05:16:21 2014 @@ -28253,6 +28258,7 @@ keyboard. The @code{INT} signal is generated by the @kbd{Ctrl-c} or @kbd{Ctrl-BREAK} key, while the @code{QUIT} signal is generated by the @kbd{Ctrl-\} key. +@cindex pretty printing Finally, @command{gawk} also accepts another option, @option{--pretty-print}. When called this way, @command{gawk} ``pretty-prints'' the program into @file{awkprof.out}, without any execution counts. @@ -28262,6 +28268,8 @@ Once upon a time, the @option{--pretty-print} option would also run your program. This is is no longer the case. @end quotation +@cindex profiling, pretty-printing, difference with +@cindex pretty-printing, profiling, difference with There is a significant difference between the output created when profiling, and that created when pretty-printing. Pretty-printed output preserves the original comments that were in the program, although their @@ -28285,7 +28293,7 @@ Because the internal representation of your program is formatted to recreate an @command{awk} program, profiling and pretty-printing automatically disable @command{gawk}'s default optimizations. -Pretty printing also preserves the original format of numeric +Profiling and pretty-printing also preserve the original format of numeric constants; if you used an octal or hexadecimal value in your source code, it will appear that way in the output. @@ -29288,7 +29296,7 @@ functional program that you or someone else wrote). @node Debugging Terms @subsection Debugging Concepts -@cindex debugger concepts +@cindex debugger, concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list defines terms used throughout the rest of @@ -29482,7 +29490,7 @@ let's see how we got to where we are. At the prompt, we type @samp{bt} (short for ``backtrace''), and the debugger responds with a listing of the current stack frames: -@cindex debugger, show stack frames +@cindex debugger, stack frames, showing @cindex debugger, @code{bt} command @cindex debugger, @code{backtrace} command @example @@ -29770,7 +29778,7 @@ it continues executing the program. @cindex debugger commands, @code{clear} @cindex @code{clear} debugger command -@cindex delete breakpoint at location +@cindex delete breakpoint, at location @cindex breakpoint at location, how to delete @item @code{clear} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, delete any breakpoint at the next instruction @@ -29807,7 +29815,7 @@ watchpoint is made unconditional). @cindex debugger commands, @code{delete} @cindex @code{delete} debugger command @cindex @code{d} debugger command (alias for @code{delete}) -@cindex delete breakpoint by number +@cindex delete breakpoint, by number @cindex breakpoint, delete by number @item @code{delete} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @itemx @code{d} [@var{n1 n2} @dots{}] [@var{n}--@var{m}] @@ -29906,6 +29914,7 @@ gawk> @cindex debugger commands, @code{c} (@code{continue}) @cindex debugger commands, @code{continue} @cindex continue program, in debugger +@cindex @code{continue} debugger command @item @code{continue} [@var{count}] @itemx @code{c} [@var{count}] Resume program execution. If continued from a breakpoint and @var{count} is @@ -30246,7 +30255,7 @@ from a file. The commands are: @cindex @code{option} debugger command @cindex @code{o} debugger command (alias for @code{option}) @cindex display debugger options -@cindex debugger options +@cindex debugger, options @item @code{option} [@var{name}[@code{=}@var{value}]] @itemx @code{o} [@var{name}[@code{=}@var{value}]] Without an argument, display the available debugger options @@ -30259,12 +30268,12 @@ The available options are: @c asis for docbook @table @asis @item @code{history_size} -@cindex debugger history size +@cindex debugger, history size Set the maximum number of lines to keep in the history file @file{./.gawk_history}. The default is 100. @item @code{listsize} -@cindex debugger default list amount +@cindex debugger, default list amount Specify the number of lines that @code{list} prints. The default is 15. @item @code{outfile} @@ -30274,11 +30283,11 @@ to standard output. An empty string (@code{""}) resets output to standard output. @item @code{prompt} -@cindex debugger prompt +@cindex debugger, prompt Change the debugger prompt. The default is @samp{@w{gawk> }}. @item @code{save_history} [@code{on} | @code{off}] -@cindex debugger history file +@cindex debugger, history file Save command history to file @file{./.gawk_history}. The default is @code{on}. @@ -30760,7 +30769,7 @@ the use of arbitrary-precision floating-point calculations. @cindex floating-point, numbers@comma{} arbitrary-precision @cindex single-precision @cindex double-precision -@cindex arbitrary-precision +@cindex arbitrary precision POSIX @command{awk} uses @dfn{double-precision} floating-point numbers, which can hold more digits than @dfn{single-precision} floating-point numbers. @command{gawk} has facilities for performing arbitrary-precision @@ -31662,6 +31671,7 @@ word sizes. See @cindex MPFR, checking availability of @cindex checking for MPFR +@cindex MPFR, checking for Occasionally, you might like to be able to check if @command{gawk} was invoked with the @option{-M} option, enabling arbitrary-precision arithmetic. You can do so with the following function, contributed @@ -32516,6 +32526,7 @@ process and reduces the time needed to create the value. @subsection Memory Allocation Functions and Convenience Macros @cindex allocating memory for extensions @cindex extensions, allocating memory +@cindex memory, allocating for extensions The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, as well as a number of @@ -33908,6 +33919,7 @@ you should release any cached values that you created, using @node Array Manipulation @subsection Array Manipulation @cindex array manipulation in extensions +@cindex extensions, array manipulation in The primary data structure@footnote{OK, the only data structure.} in @command{awk} is the associative array (@pxref{Arrays}). @@ -39369,7 +39381,7 @@ flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any other dash-type options (or multiple parameters such as @value{DF}s to process) are present, there is no ambiguity and @option{--} can be omitted. -@cindex exit status, of VMS +@cindex exit status, of @command{gawk}, on VMS The @code{exit} value is a Unix-style value and is encoded into a VMS exit status value when the program exits. |