AutoGen: 7.3.2.7 for-each: perform function on each argument

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 7.3.2.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( const char *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( const char* 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( const char* 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( const char* 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruce Korb on July, 28 2005 using texi2html 1.76.