NAME
    qprepDirectiveParse: parse and evaluate qprep directive


  USAGE
    $status_code = qprepDirectiveParse(\%state_table,
                                       \%message_table,
                                       \%directives_table,
                                       \%translation_table,
                                        $string_to_parse,
                                        $output_stream)

  ARGUMENTS
   \%state_table (in/out): reference to hash table of qprep properties

   \%message_table (in): nested hash table of error messages and codes.
     (See qprepMessageTableInitialize(3))

   \%directives_table (in): table of valid directives

   \%translation_table (in): table of directive translation rules

   $string_to_parse (in): string containing candidate directive

   $output_stream (in/out): file handle to output script


  DESCRIPTION
    This routine attempts to parse a string as a directive in the form
    "key=value", then evaluates that directive:

      () The parser verifies the syntax of the directive, and also
         verifies that the value is in the valid range for the associated
         key, by looking up the set of possible values indicated in
         directives_table.

      () If the value is acceptable then it is assigned to the
         corresponding key entry in the state_table, via
         qprepDirectiveAssign().

      () Then the qprepPreTranslationCallback is called, which can modify
         the directive key and value, and write to $output_stream.

      () Then qprepTranslationTableApply is called to perform table-based
         translation on the directive key and value, and to write the
         result to the $output_stream.


  RETURN VALUES
    Returns error code from message_table if this routine or one of
    its subordinates detects an error.  Possible errors include a
    syntax error of the string_to_parse, a bad directive value for the
    associated directive key, or a failure within the machine-specific
    qprepPreTranslationCallback subroutine.

    Returns zero if no errors detected.


  SEE ALSO
    qprepDirectiveCheck(in 'qprep.pm'),
    qprepDirectiveAssign(in 'qprep.pm'),
    qprepPreTranslationCallback(in 'localQprep.pm'),
    qprepTranslationTableApply(in 'qprep.pm').


  AUTHOR
    Written by Michael J. Gourlay
    in collaboration with Joe Werne, Chris Bizon and others.