NAME
    qprepDirectiveCheck: verify syntax and validity of directive string


  USAGE
    my($status_code) = qprepDirectiveCheck(\%state_table,
                                           \%message_table,
                                           \%directives_table,
                                            $string_to_parse,
                                           \$directive_key,
                                           \$directive_value);


 ARGUMENTS
   \%state_table (in): reference to hash table of qprep options.
      (reads operation_verbosity member for verbose mode.)

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

   \%directives_table (in): table of valid directives
      (See qprepValidDirectiveTableInitialize(in 'qprep.pm'))

   $string_to_pares (in): string containing candidate directive

   \$directive_key (out): directive key, parsed from string_to_parse

   \$directive_value (out): directive value, parsed from string_to_parse


  DESCRIPTION
    This generic internal qprep Perl subroutine parses an input string
    into a qprep directive (which is a key-value pair with a specific
    format) and compares the directive key and value to an entry in the
    table of valid directives (directives_table) to verify that the
    directive is valid.

    This grammar entry describes the syntax for a valid qprep
    directive:

      qprep-directive:
        qprep-key = qprep-value

      qprep-key:
        {one of the options described in the qprep(1) man page}

      qprep-value:
        string_constant (terminal symbol)

    Leading white space and white space between qprep-key and the
    literal '=' are ignored.  White space after the '=' is
    significant, except for a termining newline character, which is
    ignored if present.

    This routine rejects input strings not in that form.

    The string preceding the '=' is stored into directive_key,
    except for leading and trailing white space.

    The string following the '=' is stored into directive_value.

    If the input string fits the prescribed syntax, then this routine
    uses the value of directive_key as the key in the
    directives_table.  The associated value is an array of strings
    which this routine interprets as regular expressions (regex).  The
    contents of directive_value are compared with each regex from the
    table entry.  If none of the regexes match the contents of
    directive_value then the directive is rejected.


  RETURN VALUES
    Returns zero if the input string is accepted.

    Returns an error code from message_table if the input string is
    rejected.


  SEE ALSO
    qprepStateInitialize(in 'qprep.pm'),
    qprepMessageTableInitialize(in 'qprep.pm'),
    qprepValidDirectiveTableInitialize(in 'qprep.pm'),