diff options
Diffstat (limited to 'gawk.info-7')
| -rw-r--r-- | gawk.info-7 | 1265 |
1 files changed, 0 insertions, 1265 deletions
diff --git a/gawk.info-7 b/gawk.info-7 deleted file mode 100644 index b3ac7254..00000000 --- a/gawk.info-7 +++ /dev/null @@ -1,1265 +0,0 @@ -This is Info file gawk.info, produced by Makeinfo-1.54 from the input -file gawk.texi. - - This file documents `awk', a program that you can use to select -particular records in a file and perform operations upon them. - - This is Edition 0.15 of `The GAWK Manual', -for the 2.15 version of the GNU implementation -of AWK. - - Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. - - -File: gawk.info, Node: V7/S5R3.1, Next: S5R4, Prev: Language History, Up: Language History - -Major Changes between V7 and S5R3.1 -=================================== - - The `awk' language evolved considerably between the release of -Version 7 Unix (1978) and the new version first made widely available in -System V Release 3.1 (1987). This section summarizes the changes, with -cross-references to further details. - - * The requirement for `;' to separate rules on a line (*note `awk' - Statements versus Lines: Statements/Lines.). - - * User-defined functions, and the `return' statement (*note - User-defined Functions: User-defined.). - - * The `delete' statement (*note The `delete' Statement: Delete.). - - * The `do'-`while' statement (*note The `do'-`while' Statement: Do - Statement.). - - * The built-in functions `atan2', `cos', `sin', `rand' and `srand' - (*note Numeric Built-in Functions: Numeric Functions.). - - * The built-in functions `gsub', `sub', and `match' (*note Built-in - Functions for String Manipulation: String Functions.). - - * The built-in functions `close', which closes an open file, and - `system', which allows the user to execute operating system - commands (*note Built-in Functions for Input/Output: I/O - Functions.). - - * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP' - built-in variables (*note Built-in Variables::.). - - * The conditional expression using the operators `?' and `:' (*note - Conditional Expressions: Conditional Exp.). - - * The exponentiation operator `^' (*note Arithmetic Operators: - Arithmetic Ops.) and its assignment operator form `^=' (*note - Assignment Expressions: Assignment Ops.). - - * C-compatible operator precedence, which breaks some old `awk' - programs (*note Operator Precedence (How Operators Nest): - Precedence.). - - * Regexps as the value of `FS' (*note Specifying how Fields are - Separated: Field Separators.), and as the third argument to the - `split' function (*note Built-in Functions for String - Manipulation: String Functions.). - - * Dynamic regexps as operands of the `~' and `!~' operators (*note - How to Use Regular Expressions: Regexp Usage.). - - * Escape sequences (*note Constant Expressions: Constants.) in - regexps. - - * The escape sequences `\b', `\f', and `\r' (*note Constant - Expressions: Constants.). - - * Redirection of input for the `getline' function (*note Explicit - Input with `getline': Getline.). - - * Multiple `BEGIN' and `END' rules (*note `BEGIN' and `END' Special - Patterns: BEGIN/END.). - - * Simulated multi-dimensional arrays (*note Multi-dimensional - Arrays: Multi-dimensional.). - - -File: gawk.info, Node: S5R4, Next: POSIX, Prev: V7/S5R3.1, Up: Language History - -Changes between S5R3.1 and S5R4 -=============================== - - The System V Release 4 version of Unix `awk' added these features -(some of which originated in `gawk'): - - * The `ENVIRON' variable (*note Built-in Variables::.). - - * Multiple `-f' options on the command line (*note Invoking `awk': - Command Line.). - - * The `-v' option for assigning variables before program execution - begins (*note Invoking `awk': Command Line.). - - * The `--' option for terminating command line options. - - * The `\a', `\v', and `\x' escape sequences (*note Constant - Expressions: Constants.). - - * A defined return value for the `srand' built-in function (*note - Numeric Built-in Functions: Numeric Functions.). - - * The `toupper' and `tolower' built-in string functions for case - translation (*note Built-in Functions for String Manipulation: - String Functions.). - - * A cleaner specification for the `%c' format-control letter in the - `printf' function (*note Using `printf' Statements for Fancier - Printing: Printf.). - - * The ability to dynamically pass the field width and precision - (`"%*.*d"') in the argument list of the `printf' function (*note - Using `printf' Statements for Fancier Printing: Printf.). - - * The use of constant regexps such as `/foo/' as expressions, where - they are equivalent to use of the matching operator, as in `$0 ~ - /foo/' (*note Constant Expressions: Constants.). - - -File: gawk.info, Node: POSIX, Next: POSIX/GNU, Prev: S5R4, Up: Language History - -Changes between S5R4 and POSIX `awk' -==================================== - - The POSIX Command Language and Utilities standard for `awk' -introduced the following changes into the language: - - * The use of `-W' for implementation-specific options. - - * The use of `CONVFMT' for controlling the conversion of numbers to - strings (*note Conversion of Strings and Numbers: Conversion.). - - * The concept of a numeric string, and tighter comparison rules to go - with it (*note Comparison Expressions: Comparison Ops.). - - * More complete documentation of many of the previously undocumented - features of the language. - - -File: gawk.info, Node: POSIX/GNU, Prev: POSIX, Up: Language History - -Extensions in `gawk' not in POSIX `awk' -======================================= - - The GNU implementation, `gawk', adds these features: - - * The `AWKPATH' environment variable for specifying a path search for - the `-f' command line option (*note Invoking `awk': Command Line.). - - * The various `gawk' specific features available via the `-W' - command line option (*note Invoking `awk': Command Line.). - - * The `ARGIND' variable, that tracks the movement of `FILENAME' - through `ARGV'. (*note Built-in Variables::.). - - * The `ERRNO' variable, that contains the system error message when - `getline' returns -1, or when `close' fails. (*note Built-in - Variables::.). - - * The `IGNORECASE' variable and its effects (*note Case-sensitivity - in Matching: Case-sensitivity.). - - * The `FIELDWIDTHS' variable and its effects (*note Reading - Fixed-width Data: Constant Size.). - - * The `next file' statement for skipping to the next data file - (*note The `next file' Statement: Next File Statement.). - - * The `systime' and `strftime' built-in functions for obtaining and - printing time stamps (*note Functions for Dealing with Time - Stamps: Time Functions.). - - * The `/dev/stdin', `/dev/stdout', `/dev/stderr', and `/dev/fd/N' - file name interpretation (*note Standard I/O Streams: Special - Files.). - - * The `-W compat' option to turn off these extensions (*note - Invoking `awk': Command Line.). - - * The `-W posix' option for full POSIX compliance (*note Invoking - `awk': Command Line.). - - -File: gawk.info, Node: Installation, Next: Gawk Summary, Prev: Language History, Up: Top - -Installing `gawk' -***************** - - This chapter provides instructions for installing `gawk' on the -various platforms that are supported by the developers. The primary -developers support Unix (and one day, GNU), while the other ports were -contributed. The file `ACKNOWLEDGMENT' in the `gawk' distribution -lists the electronic mail addresses of the people who did the -respective ports. - -* Menu: - -* Gawk Distribution:: What is in the `gawk' distribution. -* Unix Installation:: Installing `gawk' under various versions - of Unix. -* VMS Installation:: Installing `gawk' on VMS. -* MS-DOS Installation:: Installing `gawk' on MS-DOS. -* Atari Installation:: Installing `gawk' on the Atari ST. - - -File: gawk.info, Node: Gawk Distribution, Next: Unix Installation, Prev: Installation, Up: Installation - -The `gawk' Distribution -======================= - - This section first describes how to get and extract the `gawk' -distribution, and then discusses what is in the various files and -subdirectories. - -* Menu: - -* Extracting:: How to get and extract the distribution. -* Distribution contents:: What is in the distribution. - - -File: gawk.info, Node: Extracting, Next: Distribution contents, Prev: Gawk Distribution, Up: Gawk Distribution - -Getting the `gawk' Distribution -------------------------------- - - `gawk' is distributed as a `tar' file compressed with the GNU Zip -program, `gzip'. You can get it via anonymous `ftp' to the Internet -host `prep.ai.mit.edu'. Like all GNU software, it will be archived at -other well known systems, from which it will be possible to use some -sort of anonymous `uucp' to obtain the distribution as well. You can -also order `gawk' on tape or CD-ROM directly from the Free Software -Foundation. (The address is on the copyright page.) Doing so directly -contributes to the support of the foundation and to the production of -more free software. - - Once you have the distribution (for example, `gawk-2.15.0.tar.z'), -first use `gzip' to expand the file, and then use `tar' to extract it. -You can use the following pipeline to produce the `gawk' distribution: - - # Under System V, add 'o' to the tar flags - gzip -d -c gawk-2.15.0.tar.z | tar -xvpf - - -This will create a directory named `gawk-2.15' in the current directory. - - The distribution file name is of the form `gawk-2.15.N.tar.Z'. The -N represents a "patchlevel", meaning that minor bugs have been fixed in -the major release. The current patchlevel is 0, but when retrieving -distributions, you should get the version with the highest patchlevel. - - If you are not on a Unix system, you will need to make other -arrangements for getting and extracting the `gawk' distribution. You -should consult a local expert. - - -File: gawk.info, Node: Distribution contents, Prev: Extracting, Up: Gawk Distribution - -Contents of the `gawk' Distribution ------------------------------------ - - `gawk' has a number of C source files, documentation files, -subdirectories and files related to the configuration process (*note -Compiling and Installing `gawk' on Unix: Unix Installation.), and -several subdirectories related to different, non-Unix, operating -systems. - -various `.c', `.y', and `.h' files - The C and YACC source files are the actual `gawk' source code. - -`README' -`README.VMS' -`README.dos' -`README.rs6000' -`README.ultrix' - Descriptive files: `README' for `gawk' under Unix, and the rest - for the various hardware and software combinations. - -`PORTS' - A list of systems to which `gawk' has been ported, and which have - successfully run the test suite. - -`ACKNOWLEDGMENT' - A list of the people who contributed major parts of the code or - documentation. - -`NEWS' - A list of changes to `gawk' since the last release or patch. - -`COPYING' - The GNU General Public License. - -`FUTURES' - A brief list of features and/or changes being contemplated for - future releases, with some indication of the time frame for the - feature, based on its difficulty. - -`LIMITATIONS' - A list of those factors that limit `gawk''s performance. Most of - these depend on the hardware or operating system software, and are - not limits in `gawk' itself. - -`PROBLEMS' - A file describing known problems with the current release. - -`gawk.1' - The `troff' source for a manual page describing `gawk'. - -`gawk.texinfo' - The `texinfo' source file for this Info file. It should be - processed with TeX to produce a printed manual, and with - `makeinfo' to produce the Info file. - -`Makefile.in' -`config' -`config.in' -`configure' -`missing' -`mungeconf' - These files and subdirectories are used when configuring `gawk' - for various Unix systems. They are explained in detail in *Note - Compiling and Installing `gawk' on Unix: Unix Installation. - -`atari' - Files needed for building `gawk' on an Atari ST. *Note Installing - `gawk' on the Atari ST: Atari Installation, for details. - -`pc' - Files needed for building `gawk' under MS-DOS. *Note Installing - `gawk' on MS-DOS: MS-DOS Installation, for details. - -`vms' - Files needed for building `gawk' under VMS. *Note Compiling - Installing and Running `gawk' on VMS: VMS Installation, for - details. - -`test' - Many interesting `awk' programs, provided as a test suite for - `gawk'. You can use `make test' from the top level `gawk' - directory to run your version of `gawk' against the test suite. - If `gawk' successfully passes `make test' then you can be - confident of a successful port. - - -File: gawk.info, Node: Unix Installation, Next: VMS Installation, Prev: Gawk Distribution, Up: Installation - -Compiling and Installing `gawk' on Unix -======================================= - - Often, you can compile and install `gawk' by typing only two -commands. However, if you do not use a supported system, you may need -to configure `gawk' for your system yourself. - -* Menu: - -* Quick Installation:: Compiling `gawk' on a - supported Unix version. -* Configuration Philosophy:: How it's all supposed to work. -* New Configurations:: What to do if there is no supplied - configuration for your system. - - -File: gawk.info, Node: Quick Installation, Next: Configuration Philosophy, Prev: Unix Installation, Up: Unix Installation - -Compiling `gawk' for a Supported Unix Version ---------------------------------------------- - - After you have extracted the `gawk' distribution, `cd' to -`gawk-2.15'. Look in the `config' subdirectory for a file that matches -your hardware/software combination. In general, only the software is -relevant; for example `sunos41' is used for SunOS 4.1, on both Sun 3 -and Sun 4 hardware. - - If you find such a file, run the command: - - # assume you have SunOS 4.1 - ./configure sunos41 - - This produces a `Makefile' and `config.h' tailored to your system. -You may wish to edit the `Makefile' to use a different C compiler, such -as `gcc', the GNU C compiler, if you have it. You may also wish to -change the `CFLAGS' variable, which controls the command line options -that are passed to the C compiler (such as optimization levels, or -compiling for debugging). - - After you have configured `Makefile' and `config.h', type: - - make - -and shortly thereafter, you should have an executable version of `gawk'. -That's all there is to it! - - -File: gawk.info, Node: Configuration Philosophy, Next: New Configurations, Prev: Quick Installation, Up: Unix Installation - -The Configuration Process -------------------------- - - (This section is of interest only if you know something about using -the C language and the Unix operating system.) - - The source code for `gawk' generally attempts to adhere to industry -standards wherever possible. This means that `gawk' uses library -routines that are specified by the ANSI C standard and by the POSIX -operating system interface standard. When using an ANSI C compiler, -function prototypes are provided to help improve the compile-time -checking. - - Many older Unix systems do not support all of either the ANSI or the -POSIX standards. The `missing' subdirectory in the `gawk' distribution -contains replacement versions of those subroutines that are most likely -to be missing. - - The `config.h' file that is created by the `configure' program -contains definitions that describe features of the particular operating -system where you are attempting to compile `gawk'. For the most part, -it lists which standard subroutines are *not* available. For example, -if your system lacks the `getopt' routine, then `GETOPT_MISSING' would -be defined. - - `config.h' also defines constants that describe facts about your -variant of Unix. For example, there may not be an `st_blksize' element -in the `stat' structure. In this case `BLKSIZE_MISSING' would be -defined. - - Based on the list in `config.h' of standard subroutines that are -missing, `missing.c' will do a `#include' of the appropriate file(s) -from the `missing' subdirectory. - - Conditionally compiled code in the other source files relies on the -other definitions in the `config.h' file. - - Besides creating `config.h', `configure' produces a `Makefile' from -`Makefile.in'. There are a number of lines in `Makefile.in' that are -system or feature specific. For example, there is line that begins -with `##MAKE_ALLOCA_C##'. This is normally a comment line, since it -starts with `#'. If a configuration file has `MAKE_ALLOCA_C' in it, -then `configure' will delete the `##MAKE_ALLOCA_C##' from the beginning -of the line. This will enable the rules in the `Makefile' that use a C -version of `alloca'. There are several similar features that work in -this fashion. - - -File: gawk.info, Node: New Configurations, Prev: Configuration Philosophy, Up: Unix Installation - -Configuring `gawk' for a New System ------------------------------------ - - (This section is of interest only if you know something about using -the C language and the Unix operating system, and if you have to install -`gawk' on a system that is not supported by the `gawk' distribution. -If you are a C or Unix novice, get help from a local expert.) - - If you need to configure `gawk' for a Unix system that is not -supported in the distribution, first see *Note The Configuration -Process: Configuration Philosophy. Then, copy `config.in' to -`config.h', and copy `Makefile.in' to `Makefile'. - - Next, edit both files. Both files are liberally commented, and the -necessary changes should be straightforward. - - While editing `config.h', you need to determine what library -routines you do or do not have by consulting your system documentation, -or by perusing your actual libraries using the `ar' or `nm' utilities. -In the worst case, simply do not define *any* of the macros for missing -subroutines. When you compile `gawk', the final link-editing step will -fail. The link editor will provide you with a list of unresolved -external references--these are the missing subroutines. Edit -`config.h' again and recompile, and you should be set. - - Editing the `Makefile' should also be straightforward. Enable or -disable the lines that begin with `##MAKE_WHATEVER##', as appropriate. -Select the correct C compiler and `CFLAGS' for it. Then run `make'. - - Getting a correct configuration is likely to be an iterative process. -Do not be discouraged if it takes you several tries. If you have no -luck whatsoever, please report your system type, and the steps you took. -Once you do have a working configuration, please send it to the -maintainers so that support for your system can be added to the -official release. - - *Note Reporting Problems and Bugs: Bugs, for information on how to -report problems in configuring `gawk'. You may also use the same -mechanisms for sending in new configurations. - - -File: gawk.info, Node: VMS Installation, Next: MS-DOS Installation, Prev: Unix Installation, Up: Installation - -Compiling, Installing, and Running `gawk' on VMS -================================================ - - This section describes how to compile and install `gawk' under VMS. - -* Menu: - -* VMS Compilation:: How to compile `gawk' under VMS. -* VMS Installation Details:: How to install `gawk' under VMS. -* VMS Running:: How to run `gawk' under VMS. -* VMS POSIX:: Alternate instructions for VMS POSIX. - - -File: gawk.info, Node: VMS Compilation, Next: VMS Installation Details, Prev: VMS Installation, Up: VMS Installation - -Compiling `gawk' under VMS --------------------------- - - To compile `gawk' under VMS, there is a `DCL' command procedure that -will issue all the necessary `CC' and `LINK' commands, and there is -also a `Makefile' for use with the `MMS' utility. From the source -directory, use either - - $ @[.VMS]VMSBUILD.COM - -or - - $ MMS/DESCRIPTION=[.VMS]DECSRIP.MMS GAWK - - Depending upon which C compiler you are using, follow one of the sets -of instructions in this table: - -VAX C V3.x - Use either `vmsbuild.com' or `descrip.mms' as is. These use - `CC/OPTIMIZE=NOLINE', which is essential for Version 3.0. - -VAX C V2.x - You must have Version 2.3 or 2.4; older ones won't work. Edit - either `vmsbuild.com' or `descrip.mms' according to the comments - in them. For `vmsbuild.com', this just entails removing two `!' - delimiters. Also edit `config.h' (which is a copy of file - `[.config]vms-conf.h') and comment out or delete the two lines - `#define __STDC__ 0' and `#define VAXC_BUILTINS' near the end. - -GNU C - Edit `vmsbuild.com' or `descrip.mms'; the changes are different - from those for VAX C V2.x, but equally straightforward. No - changes to `config.h' should be needed. - -DEC C - Edit `vmsbuild.com' or `descrip.mms' according to their comments. - No changes to `config.h' should be needed. - - `gawk' 2.15 has been tested under VAX/VMS 5.5-1 using VAX C V3.2, -GNU C 1.40 and 2.3. It should work without modifications for VMS V4.6 -and up. - - -File: gawk.info, Node: VMS Installation Details, Next: VMS Running, Prev: VMS Compilation, Up: VMS Installation - -Installing `gawk' on VMS ------------------------- - - To install `gawk', all you need is a "foreign" command, which is a -`DCL' symbol whose value begins with a dollar sign. - - $ GAWK :== $device:[directory]GAWK - -(Substitute the actual location of `gawk.exe' for -`device:[directory]'.) The symbol should be placed in the `login.com' -of any user who wishes to run `gawk', so that it will be defined every -time the user logs on. Alternatively, the symbol may be placed in the -system-wide `sylogin.com' procedure, which will allow all users to run -`gawk'. - - Optionally, the help entry can be loaded into a VMS help library: - - $ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP - -(You may want to substitute a site-specific help library rather than -the standard VMS library `HELPLIB'.) After loading the help text, - - $ HELP GAWK - -will provide information about both the `gawk' implementation and the -`awk' programming language. - - The logical name `AWK_LIBRARY' can designate a default location for -`awk' program files. For the `-f' option, if the specified filename -has no device or directory path information in it, `gawk' will look in -the current directory first, then in the directory specified by the -translation of `AWK_LIBRARY' if the file was not found. If after -searching in both directories, the file still is not found, then `gawk' -appends the suffix `.awk' to the filename and the file search will be -re-tried. If `AWK_LIBRARY' is not defined, that portion of the file -search will fail benignly. - - -File: gawk.info, Node: VMS Running, Next: VMS POSIX, Prev: VMS Installation Details, Up: VMS Installation - -Running `gawk' on VMS ---------------------- - - Command line parsing and quoting conventions are significantly -different on VMS, so examples in this manual or from other sources -often need minor changes. They *are* minor though, and all `awk' -programs should run correctly. - - Here are a couple of trivial tests: - - $ gawk -- "BEGIN {print ""Hello, World!""}" - $ gawk -"W" version ! could also be -"W version" or "-W version" - -Note that upper-case and mixed-case text must be quoted. - - The VMS port of `gawk' includes a `DCL'-style interface in addition -to the original shell-style interface (see the help entry for details). -One side-effect of dual command line parsing is that if there is only a -single parameter (as in the quoted string program above), the command -becomes ambiguous. To work around this, the normally optional `--' -flag is required to force Unix style rather than `DCL' parsing. If any -other dash-type options (or multiple parameters such as data files to be -processed) are present, there is no ambiguity and `--' can be omitted. - - The default search path when looking for `awk' program files -specified by the `-f' option is `"SYS$DISK:[],AWK_LIBRARY:"'. The -logical name `AWKPATH' can be used to override this default. The format -of `AWKPATH' is a comma-separated list of directory specifications. -When defining it, the value should be quoted so that it retains a single -translation, and not a multi-translation `RMS' searchlist. - - -File: gawk.info, Node: VMS POSIX, Prev: VMS Running, Up: VMS Installation - -Building and using `gawk' under VMS POSIX ------------------------------------------ - - Ignore the instructions above, although `vms/gawk.hlp' should still -be made available in a help library. Make sure that the two scripts, -`configure' and `mungeconf', are executable; use `chmod +x' on them if -necessary. Then execute the following commands: - - $ POSIX - psx> configure vms-posix - psx> make awktab.c gawk - -The first command will construct files `config.h' and `Makefile' out of -templates. The second command will compile and link `gawk'. Due to a -`make' bug in VMS POSIX V1.0 and V1.1, the file `awktab.c' must be -given as an explicit target or it will not be built and the final link -step will fail. Ignore the warning `"Could not find lib m in lib -list"'; it is harmless, caused by the explicit use of `-lm' as a linker -option which is not needed under VMS POSIX. Under V1.1 (but not V1.0) -a problem with the `yacc' skeleton `/etc/yyparse.c' will cause a -compiler warning for `awktab.c', followed by a linker warning about -compilation warnings in the resulting object module. These warnings -can be ignored. - - Once built, `gawk' will work like any other shell utility. Unlike -the normal VMS port of `gawk', no special command line manipulation is -needed in the VMS POSIX environment. - - -File: gawk.info, Node: MS-DOS Installation, Next: Atari Installation, Prev: VMS Installation, Up: Installation - -Installing `gawk' on MS-DOS -=========================== - - The first step is to get all the files in the `gawk' distribution -onto your PC. Move all the files from the `pc' directory into the main -directory where the other files are. Edit the file `make.bat' so that -it will be an acceptable MS-DOS batch file. This means making sure -that all lines are terminated with the ASCII carriage return and line -feed characters. restrictions. - - `gawk' has only been compiled with version 5.1 of the Microsoft C -compiler. The file `make.bat' from the `pc' directory assumes that you -have this compiler. - - Copy the file `setargv.obj' from the library directory where it -resides to the `gawk' source code directory. - - Run `make.bat'. This will compile `gawk' for you, and link it. -That's all there is to it! - - -File: gawk.info, Node: Atari Installation, Prev: MS-DOS Installation, Up: Installation - -Installing `gawk' on the Atari ST -================================= - - This section assumes that you are running TOS. It applies to other -Atari models (STe, TT) as well. - - In order to use `gawk', you need to have a shell, either text or -graphics, that does not map all the characters of a command line to -upper case. Maintaining case distinction in option flags is very -important (*note Invoking `awk': Command Line.). Popular shells like -`gulam' or `gemini' will work, as will newer versions of `desktop'. -Support for I/O redirection is necessary to make it easy to import -`awk' programs from other environments. Pipes are nice to have, but -not vital. - - If you have received an executable version of `gawk', place it, as -usual, anywhere in your `PATH' where your shell will find it. - - While executing, `gawk' creates a number of temporary files. `gawk' -looks for either of the environment variables `TEMP' or `TMPDIR', in -that order. If either one is found, its value is assumed to be a -directory for temporary files. This directory must exist, and if you -can spare the memory, it is a good idea to put it on a RAM drive. If -neither `TEMP' nor `TMPDIR' are found, then `gawk' uses the current -directory for its temporary files. - - The ST version of `gawk' searches for its program files as described -in *Note The `AWKPATH' Environment Variable: AWKPATH Variable. On the -ST, the default value for the `AWKPATH' variable is -`".,c:\lib\awk,c:\gnu\lib\awk"'. The search path can be modified by -explicitly setting `AWKPATH' to whatever you wish. Note that colons -cannot be used on the ST to separate elements in the `AWKPATH' -variable, since they have another, reserved, meaning. Instead, you -must use a comma to separate elements in the path. If you are -recompiling `gawk' on the ST, then you can choose a new default search -path, by setting the value of `DEFPATH' in the file `...\config\atari'. -You may choose a different separator character by setting the value of -`ENVSEP' in the same file. The new values will be used when creating -the header file `config.h'. - - Although `awk' allows great flexibility in doing I/O redirections -from within a program, this facility should be used with care on the ST. -In some circumstances the OS routines for file handle pool processing -lose track of certain events, causing the computer to crash, and -requiring a reboot. Often a warm reboot is sufficient. Fortunately, -this happens infrequently, and in rather esoteric situations. In -particular, avoid having one part of an `awk' program using `print' -statements explicitly redirected to `"/dev/stdout"', while other -`print' statements use the default standard output, and a calling shell -has redirected standard output to a file. - - When `gawk' is compiled with the ST version of `gcc' and its usual -libraries, it will accept both `/' and `\' as path separators. While -this is convenient, it should be remembered that this removes one, -technically legal, character (`/') from your file names, and that it -may create problems for external programs, called via the `system()' -function, which may not support this convention. Whenever it is -possible that a file created by `gawk' will be used by some other -program, use only backslashes. Also remember that in `awk', -backslashes in strings have to be doubled in order to get literal -backslashes. - - The initial port of `gawk' to the ST was done with `gcc'. If you -wish to recompile `gawk' from scratch, you will need to use a compiler -that accepts ANSI standard C (such as `gcc', Turbo C, or Prospero C). -If `sizeof(int) != sizeof(int *)', the correctness of the generated -code depends heavily on the fact that all function calls have function -prototypes in the current scope. If your compiler does not accept -function prototypes, you will probably have to add a number of casts to -the code. - - If you are using `gcc', make sure that you have up-to-date libraries. -Older versions have problems with some library functions (`atan2()', -`strftime()', the `%g' conversion in `sprintf()') which may affect the -operation of `gawk'. - - In the `atari' subdirectory of the `gawk' distribution is a version -of the `system()' function that has been tested with `gulam' and `msh'; -it should work with other shells as well. With `gulam', it passes the -string to be executed without spawning an extra copy of a shell. It is -possible to replace this version of `system()' with a similar function -from a library or from some other source if that version would be a -better choice for the shell you prefer. - - The files needed to recompile `gawk' on the ST can be found in the -`atari' directory. The provided files and instructions below assume -that you have the GNU C compiler (`gcc'), the `gulam' shell, and an ST -version of `sed'. The `Makefile' is set up to use `byacc' as a `yacc' -replacement. With a different set of tools some adjustments and/or -editing will be needed. - - `cd' to the `atari' directory. Copy `Makefile.st' to `makefile' in -the source (parent) directory. Possibly adjust `../config/atari' to -suit your system. Execute the script `mkconf.g' which will create the -header file `../config.h'. Go back to the source directory. If you -are not using `gcc', check the file `missing.c'. It may be necessary -to change forward slashes in the references to files from the `atari' -subdirectory into backslashes. Type `make' and enjoy. - - Compilation with `gcc' of some of the bigger modules, like -`awk_tab.c', may require a full four megabytes of memory. On smaller -machines you would need to cut down on optimizations, or you would have -to switch to another, less memory hungry, compiler. - - -File: gawk.info, Node: Gawk Summary, Next: Sample Program, Prev: Installation, Up: Top - -`gawk' Summary -************** - - This appendix provides a brief summary of the `gawk' command line -and the `awk' language. It is designed to serve as "quick reference." -It is therefore terse, but complete. - -* Menu: - -* Command Line Summary:: Recapitulation of the command line. -* Language Summary:: A terse review of the language. -* Variables/Fields:: Variables, fields, and arrays. -* Rules Summary:: Patterns and Actions, and their - component parts. -* Functions Summary:: Defining and calling functions. -* Historical Features:: Some undocumented but supported "features". - - -File: gawk.info, Node: Command Line Summary, Next: Language Summary, Prev: Gawk Summary, Up: Gawk Summary - -Command Line Options Summary -============================ - - The command line consists of options to `gawk' itself, the `awk' -program text (if not supplied via the `-f' option), and values to be -made available in the `ARGC' and `ARGV' predefined `awk' variables: - - awk [POSIX OR GNU STYLE OPTIONS] -f source-file [`--'] FILE ... - awk [POSIX OR GNU STYLE OPTIONS] [`--'] 'PROGRAM' FILE ... - - The options that `gawk' accepts are: - -`-F FS' -`--field-separator=FS' - Use FS for the input field separator (the value of the `FS' - predefined variable). - -`-f PROGRAM-FILE' -`--file=PROGRAM-FILE' - Read the `awk' program source from the file PROGRAM-FILE, instead - of from the first command line argument. - -`-v VAR=VAL' -`--assign=VAR=VAL' - Assign the variable VAR the value VAL before program execution - begins. - -`-W compat' -`--compat' - Specifies compatibility mode, in which `gawk' extensions are turned - off. - -`-W copyleft' -`-W copyright' -`--copyleft' -`--copyright' - Print the short version of the General Public License on the error - output. This option may disappear in a future version of `gawk'. - -`-W help' -`-W usage' -`--help' -`--usage' - Print a relatively short summary of the available options on the - error output. - -`-W lint' -`--lint' - Give warnings about dubious or non-portable `awk' constructs. - -`-W posix' -`--posix' - Specifies POSIX compatibility mode, in which `gawk' extensions are - turned off and additional restrictions apply. - -`-W source=PROGRAM-TEXT' -`--source=PROGRAM-TEXT' - Use PROGRAM-TEXT as `awk' program source code. This option allows - mixing command line source code with source code from files, and is - particularly useful for mixing command line programs with library - functions. - -`-W version' -`--version' - Print version information for this particular copy of `gawk' on - the error output. This option may disappear in a future version - of `gawk'. - -`--' - Signal the end of options. This is useful to allow further - arguments to the `awk' program itself to start with a `-'. This - is mainly for consistency with the argument parsing conventions of - POSIX. - - Any other options are flagged as invalid, but are otherwise ignored. -*Note Invoking `awk': Command Line, for more details. - - -File: gawk.info, Node: Language Summary, Next: Variables/Fields, Prev: Command Line Summary, Up: Gawk Summary - -Language Summary -================ - - An `awk' program consists of a sequence of pattern-action statements -and optional function definitions. - - PATTERN { ACTION STATEMENTS } - - function NAME(PARAMETER LIST) { ACTION STATEMENTS } - - `gawk' first reads the program source from the PROGRAM-FILE(s) if -specified, or from the first non-option argument on the command line. -The `-f' option may be used multiple times on the command line. `gawk' -reads the program text from all the PROGRAM-FILE files, effectively -concatenating them in the order they are specified. This is useful for -building libraries of `awk' functions, without having to include them -in each new `awk' program that uses them. To use a library function in -a file from a program typed in on the command line, specify `-f -/dev/tty'; then type your program, and end it with a `Control-d'. -*Note Invoking `awk': Command Line. - - The environment variable `AWKPATH' specifies a search path to use -when finding source files named with the `-f' option. The default -path, which is `.:/usr/lib/awk:/usr/local/lib/awk' is used if `AWKPATH' -is not set. If a file name given to the `-f' option contains a `/' -character, no path search is performed. *Note The `AWKPATH' -Environment Variable: AWKPATH Variable, for a full description of the -`AWKPATH' environment variable. - - `gawk' compiles the program into an internal form, and then proceeds -to read each file named in the `ARGV' array. If there are no files -named on the command line, `gawk' reads the standard input. - - If a "file" named on the command line has the form `VAR=VAL', it is -treated as a variable assignment: the variable VAR is assigned the -value VAL. If any of the files have a value that is the null string, -that element in the list is skipped. - - For each line in the input, `gawk' tests to see if it matches any -PATTERN in the `awk' program. For each pattern that the line matches, -the associated ACTION is executed. - - -File: gawk.info, Node: Variables/Fields, Next: Rules Summary, Prev: Language Summary, Up: Gawk Summary - -Variables and Fields -==================== - - `awk' variables are dynamic; they come into existence when they are -first used. Their values are either floating-point numbers or strings. -`awk' also has one-dimension arrays; multiple-dimensional arrays may be -simulated. There are several predefined variables that `awk' sets as a -program runs; these are summarized below. - -* Menu: - -* Fields Summary:: Input field splitting. -* Built-in Summary:: `awk''s built-in variables. -* Arrays Summary:: Using arrays. -* Data Type Summary:: Values in `awk' are numbers or strings. - - -File: gawk.info, Node: Fields Summary, Next: Built-in Summary, Prev: Variables/Fields, Up: Variables/Fields - -Fields ------- - - As each input line is read, `gawk' splits the line into FIELDS, -using the value of the `FS' variable as the field separator. If `FS' -is a single character, fields are separated by that character. -Otherwise, `FS' is expected to be a full regular expression. In the -special case that `FS' is a single blank, fields are separated by runs -of blanks and/or tabs. Note that the value of `IGNORECASE' (*note -Case-sensitivity in Matching: Case-sensitivity.) also affects how -fields are split when `FS' is a regular expression. - - Each field in the input line may be referenced by its position, `$1', -`$2', and so on. `$0' is the whole line. The value of a field may be -assigned to as well. Field numbers need not be constants: - - n = 5 - print $n - -prints the fifth field in the input line. The variable `NF' is set to -the total number of fields in the input line. - - References to nonexistent fields (i.e., fields after `$NF') return -the null-string. However, assigning to a nonexistent field (e.g., -`$(NF+2) = 5') increases the value of `NF', creates any intervening -fields with the null string as their value, and causes the value of -`$0' to be recomputed, with the fields being separated by the value of -`OFS'. - - *Note Reading Input Files: Reading Files, for a full description of -the way `awk' defines and uses fields. - - -File: gawk.info, Node: Built-in Summary, Next: Arrays Summary, Prev: Fields Summary, Up: Variables/Fields - -Built-in Variables ------------------- - - `awk''s built-in variables are: - -`ARGC' - The number of command line arguments (not including options or the - `awk' program itself). - -`ARGIND' - The index in `ARGV' of the current file being processed. It is - always true that `FILENAME == ARGV[ARGIND]'. - -`ARGV' - The array of command line arguments. The array is indexed from 0 - to `ARGC' - 1. Dynamically changing the contents of `ARGV' can - control the files used for data. - -`CONVFMT' - The conversion format to use when converting numbers to strings. - -`FIELDWIDTHS' - A space separated list of numbers describing the fixed-width input - data. - -`ENVIRON' - An array containing the values of the environment variables. The - array is indexed by variable name, each element being the value of - that variable. Thus, the environment variable `HOME' would be in - `ENVIRON["HOME"]'. Its value might be `/u/close'. - - Changing this array does not affect the environment seen by - programs which `gawk' spawns via redirection or the `system' - function. (This may change in a future version of `gawk'.) - - Some operating systems do not have environment variables. The - array `ENVIRON' is empty when running on these systems. - -`ERRNO' - The system error message when an error occurs using `getline' or - `close'. - -`FILENAME' - The name of the current input file. If no files are specified on - the command line, the value of `FILENAME' is `-'. - -`FNR' - The input record number in the current input file. - -`FS' - The input field separator, a blank by default. - -`IGNORECASE' - The case-sensitivity flag for regular expression operations. If - `IGNORECASE' has a nonzero value, then pattern matching in rules, - field splitting with `FS', regular expression matching with `~' - and `!~', and the `gsub', `index', `match', `split' and `sub' - predefined functions all ignore case when doing regular expression - operations. - -`NF' - The number of fields in the current input record. - -`NR' - The total number of input records seen so far. - -`OFMT' - The output format for numbers for the `print' statement, `"%.6g"' - by default. - -`OFS' - The output field separator, a blank by default. - -`ORS' - The output record separator, by default a newline. - -`RS' - The input record separator, by default a newline. `RS' is - exceptional in that only the first character of its string value - is used for separating records. If `RS' is set to the null - string, then records are separated by blank lines. When `RS' is - set to the null string, then the newline character always acts as - a field separator, in addition to whatever value `FS' may have. - -`RSTART' - The index of the first character matched by `match'; 0 if no match. - -`RLENGTH' - The length of the string matched by `match'; -1 if no match. - -`SUBSEP' - The string used to separate multiple subscripts in array elements, - by default `"\034"'. - - *Note Built-in Variables::, for more information. - - -File: gawk.info, Node: Arrays Summary, Next: Data Type Summary, Prev: Built-in Summary, Up: Variables/Fields - -Arrays ------- - - Arrays are subscripted with an expression between square brackets -(`[' and `]'). Array subscripts are *always* strings; numbers are -converted to strings as necessary, following the standard conversion -rules (*note Conversion of Strings and Numbers: Conversion.). - - If you use multiple expressions separated by commas inside the square -brackets, then the array subscript is a string consisting of the -concatenation of the individual subscript values, converted to strings, -separated by the subscript separator (the value of `SUBSEP'). - - The special operator `in' may be used in an `if' or `while' -statement to see if an array has an index consisting of a particular -value. - - if (val in array) - print array[val] - - If the array has multiple subscripts, use `(i, j, ...) in array' to -test for existence of an element. - - The `in' construct may also be used in a `for' loop to iterate over -all the elements of an array. *Note Scanning all Elements of an Array: -Scanning an Array. - - An element may be deleted from an array using the `delete' statement. - - *Note Arrays in `awk': Arrays, for more detailed information. - - -File: gawk.info, Node: Data Type Summary, Prev: Arrays Summary, Up: Variables/Fields - -Data Types ----------- - - The value of an `awk' expression is always either a number or a -string. - - Certain contexts (such as arithmetic operators) require numeric -values. They convert strings to numbers by interpreting the text of -the string as a numeral. If the string does not look like a numeral, -it converts to 0. - - Certain contexts (such as concatenation) require string values. -They convert numbers to strings by effectively printing them with -`sprintf'. *Note Conversion of Strings and Numbers: Conversion, for -the details. - - To force conversion of a string value to a number, simply add 0 to -it. If the value you start with is already a number, this does not -change it. - - To force conversion of a numeric value to a string, concatenate it -with the null string. - - The `awk' language defines comparisons as being done numerically if -both operands are numeric, or if one is numeric and the other is a -numeric string. Otherwise one or both operands are converted to -strings and a string comparison is performed. - - Uninitialized variables have the string value `""' (the null, or -empty, string). In contexts where a number is required, this is -equivalent to 0. - - *Note Variables::, for more information on variable naming and -initialization; *note Conversion of Strings and Numbers: Conversion., -for more information on how variable values are interpreted. - - -File: gawk.info, Node: Rules Summary, Next: Functions Summary, Prev: Variables/Fields, Up: Gawk Summary - -Patterns and Actions -==================== - -* Menu: - -* Pattern Summary:: Quick overview of patterns. -* Regexp Summary:: Quick overview of regular expressions. -* Actions Summary:: Quick overview of actions. - - An `awk' program is mostly composed of rules, each consisting of a -pattern followed by an action. The action is enclosed in `{' and `}'. -Either the pattern may be missing, or the action may be missing, but, -of course, not both. If the pattern is missing, the action is executed -for every single line of input. A missing action is equivalent to this -action, - - { print } - -which prints the entire line. - - Comments begin with the `#' character, and continue until the end of -the line. Blank lines may be used to separate statements. Normally, a -statement ends with a newline, however, this is not the case for lines -ending in a `,', `{', `?', `:', `&&', or `||'. Lines ending in `do' or -`else' also have their statements automatically continued on the -following line. In other cases, a line can be continued by ending it -with a `\', in which case the newline is ignored. - - Multiple statements may be put on one line by separating them with a -`;'. This applies to both the statements within the action part of a -rule (the usual case), and to the rule statements. - - *Note Comments in `awk' Programs: Comments, for information on -`awk''s commenting convention; *note `awk' Statements versus Lines: -Statements/Lines., for a description of the line continuation mechanism -in `awk'. - - -File: gawk.info, Node: Pattern Summary, Next: Regexp Summary, Prev: Rules Summary, Up: Rules Summary - -Patterns --------- - - `awk' patterns may be one of the following: - - /REGULAR EXPRESSION/ - RELATIONAL EXPRESSION - PATTERN && PATTERN - PATTERN || PATTERN - PATTERN ? PATTERN : PATTERN - (PATTERN) - ! PATTERN - PATTERN1, PATTERN2 - BEGIN - END - - `BEGIN' and `END' are two special kinds of patterns that are not -tested against the input. The action parts of all `BEGIN' rules are -merged as if all the statements had been written in a single `BEGIN' -rule. They are executed before any of the input is read. Similarly, -all the `END' rules are merged, and executed when all the input is -exhausted (or when an `exit' statement is executed). `BEGIN' and `END' -patterns cannot be combined with other patterns in pattern expressions. -`BEGIN' and `END' rules cannot have missing action parts. - - For `/REGULAR-EXPRESSION/' patterns, the associated statement is -executed for each input line that matches the regular expression. -Regular expressions are extensions of those in `egrep', and are -summarized below. - - A RELATIONAL EXPRESSION may use any of the operators defined below in -the section on actions. These generally test whether certain fields -match certain regular expressions. - - The `&&', `||', and `!' operators are logical "and," logical "or," -and logical "not," respectively, as in C. They do short-circuit -evaluation, also as in C, and are used for combining more primitive -pattern expressions. As in most languages, parentheses may be used to -change the order of evaluation. - - The `?:' operator is like the same operator in C. If the first -pattern matches, then the second pattern is matched against the input -record; otherwise, the third is matched. Only one of the second and -third patterns is matched. - - The `PATTERN1, PATTERN2' form of a pattern is called a range -pattern. It matches all input lines starting with a line that matches -PATTERN1, and continuing until a line that matches PATTERN2, inclusive. -A range pattern cannot be used as an operand to any of the pattern -operators. - - *Note Patterns::, for a full description of the pattern part of `awk' -rules. - |