7.5.3.7 for-each: perform function on each argument

This produces a main procedure that invokes a procedure once for each operand on the command line (non-option arguments), OR once for each non-blank, non-comment stdin input line. Leading and trailing white space is trimmed from the input line and comment lines are lines that are empty or begin with a comment character, defaulting to a hash ('#') character.

NB: The argument program attribute (see section Program Description Attributes) must begin with the [ character, to indicate that there are command operands, but that they are optional.

There are a number of attributes to main that may be used:

handler-proc

This attribute is required. It is used to name the procedure to call. That procedure is presumed to be external, but if you provide the code for it, then the procedure is emitted as a static procedure in the generated code.

This procedure should return 0 on success, a cumulative error code on warning and exit without returning on an unrecoverable error. As the cumulative warning codes are or-ed together, the codes should be some sort of bit mask in order to be ultimately decipherable (if you need to do that).

If the called procedure needs to cause a fail-exit, it is expected to call exit(3) directly. If you want to cause a warning exit code, then this handler function should return a non-zero status. That value will be OR-ed into a result integer for computing the final exit code. E.g., here is part of the emitted code:

int res = 0; if (argc > 0) { do { res |= my_handler( *(argv++) ); } while (--argc > 0); } else { ...

handler-type

If you do not supply this attribute, your handler procedure must be the default type. The profile of the procedure must be:

int my_handler( char const *pz_entry );

However, if you do supply this attribute, you may select any of three alternate flavors:

`name-of-file'

This is essentially the same as the default handler type, except that before your procedure is invoked, the generated code has verified that the string names an existing file. The profile is unchanged.

`file-X'

Before calling your procedure, the file is f-opened according to the "X", where "X" may be any of the legal modes for fopen(3C). In this case, the profile for your procedure must be:

int my_handler( char const* pz_fname, FILE* entry_fp );

`text-of-file'

`some-text-of-file'

Before calling your procedure, the contents of the file are read into memory. (Excessively large files may cause problems.) The "`some-text-of-file'" disallows empty files. Both require regular files. In this case, the profile for your procedure must be:

int my_handler( char const* pz_fname, char* file_text, size_t text_size );

Note that though the file_text is not const, any changes made to it are not written back to the original file. It is merely a memory image of the file contents. Also, the memory allocated to hold the text is text_size + 1 bytes long and the final byte is always NUL. The file contents need not be text, as the data are read with the read(2) system call.

my_handler-code

With this attribute, you provide the code for your handler procedure in the option definition file. In this case, your main() procedure specification might look something like this:

main = { main-type = for-each; handler-proc = my_handler; my_handler-code = <<- EndOfMyCode /* whatever you want to do */ EndOfMyCode; };

and instead of an emitted external reference, a procedure will be emitted that looks like this:

static int my_handler( char const* pz_entry ) { int res = 0; <<my_handler-code goes here>> return res; }

main-init

This is code that gets inserted after the options have been processed, but before the handler procs get invoked.

main-fini

This is code that gets inserted after all the entries have been processed, just before returning from main().

comment-char

If you wish comment lines to start with a character other than a hash (#) character, then specify one character with this attribute. If that character is the NUL byte, then only blank lines will be considered comments.

This document was generated by Bruce Korb on September, 30 2006 using texi2html 1.76.