Please document parser error handling

[ipilcher]

I've searched high and low, and I can't find anything that documents how applications are expected to handle (i.e. report) parser errors.

yaml_parser_s includes these members:

    /**
     * @name Error handling
     * @{
     */

    /** Error type. */
    yaml_error_type_t error;
    /** Error description. */
    const char *problem;
    /** The byte about which the problem occured. */
    size_t problem_offset;
    /** The problematic value (@c -1 is none). */
    int problem_value;
    /** The problem position. */
    yaml_mark_t problem_mark;
    /** The error context. */
    const char *context;
    /** The context position. */
    yaml_mark_t context_mark;

These look promising, but right above this it says:

 * All members are internal.  Manage the structure using the @c yaml_parser_
 * family of functions.

And I don't see any functions related to error-reporting.

Assuming that the error-related members should be accessed directly, how should they be used?

• Is there any way to transform a yaml_error_type_t into a human-readable message?
• When can I use the problem member?
  • Is it set for certain types of errors (i.e. certain values of error)?
  • Should I just check if for a non-NULL value?
  • If so, do I need to set it to NULL before calling certain functions?
• Similarly with the problem_mark member; how can an application determine whether its contents are valid?
• What is the significance of the problem_offset, problem_value, context, and context_mark members?

I apologize if this is all written down somewhere, and I've just missed it.

[kennykarnama]

@ipilcher

Have you tried using these lines?

https://github.com/yaml/libyaml/blob/master/tests/test-reader.c#L142

https://github.com/yaml/libyaml/blob/master/tests/test-reader.c#L148

Both can access the field you described before.

Hope it helps.