jpayne@69: // © 2016 and later: Unicode, Inc. and others.
jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69: /*
jpayne@69: **********************************************************************
jpayne@69: *   Copyright (C) 1999-2005, International Business Machines
jpayne@69: *   Corporation and others.  All Rights Reserved.
jpayne@69: **********************************************************************
jpayne@69: *   Date        Name        Description
jpayne@69: *   03/14/00    aliu        Creation.
jpayne@69: *   06/27/00    aliu        Change from C++ class to C struct
jpayne@69: **********************************************************************
jpayne@69: */
jpayne@69: #ifndef PARSEERR_H
jpayne@69: #define PARSEERR_H
jpayne@69: 
jpayne@69: #include "unicode/utypes.h"
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \file
jpayne@69:  * \brief C API: Parse Error Information
jpayne@69:  */
jpayne@69: /**
jpayne@69:  * The capacity of the context strings in UParseError.
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */ 
jpayne@69: enum { U_PARSE_CONTEXT_LEN = 16 };
jpayne@69: 
jpayne@69: /**
jpayne@69:  * A UParseError struct is used to returned detailed information about
jpayne@69:  * parsing errors.  It is used by ICU parsing engines that parse long
jpayne@69:  * rules, patterns, or programs, where the text being parsed is long
jpayne@69:  * enough that more information than a UErrorCode is needed to
jpayne@69:  * localize the error.
jpayne@69:  *
jpayne@69:  * <p>The line, offset, and context fields are optional; parsing
jpayne@69:  * engines may choose not to use to use them.
jpayne@69:  *
jpayne@69:  * <p>The preContext and postContext strings include some part of the
jpayne@69:  * context surrounding the error.  If the source text is "let for=7"
jpayne@69:  * and "for" is the error (e.g., because it is a reserved word), then
jpayne@69:  * some examples of what a parser might produce are the following:
jpayne@69:  *
jpayne@69:  * <pre>
jpayne@69:  * preContext   postContext
jpayne@69:  * ""           ""            The parser does not support context
jpayne@69:  * "let "       "=7"          Pre- and post-context only
jpayne@69:  * "let "       "for=7"       Pre- and post-context and error text
jpayne@69:  * ""           "for"         Error text only
jpayne@69:  * </pre>
jpayne@69:  *
jpayne@69:  * <p>Examples of engines which use UParseError (or may use it in the
jpayne@69:  * future) are Transliterator, RuleBasedBreakIterator, and
jpayne@69:  * RegexPattern.
jpayne@69:  * 
jpayne@69:  * @stable ICU 2.0
jpayne@69:  */
jpayne@69: typedef struct UParseError {
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * The line on which the error occurred.  If the parser uses this
jpayne@69:      * field, it sets it to the line number of the source text line on
jpayne@69:      * which the error appears, which will be a value >= 1.  If the
jpayne@69:      * parse does not support line numbers, the value will be <= 0.
jpayne@69:      * @stable ICU 2.0
jpayne@69:      */
jpayne@69:     int32_t        line;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * The character offset to the error.  If the line field is >= 1,
jpayne@69:      * then this is the offset from the start of the line.  Otherwise,
jpayne@69:      * this is the offset from the start of the text.  If the parser
jpayne@69:      * does not support this field, it will have a value < 0.
jpayne@69:      * @stable ICU 2.0
jpayne@69:      */
jpayne@69:     int32_t        offset;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Textual context before the error.  Null-terminated.  The empty
jpayne@69:      * string if not supported by parser.
jpayne@69:      * @stable ICU 2.0   
jpayne@69:      */
jpayne@69:     UChar          preContext[U_PARSE_CONTEXT_LEN];
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * The error itself and/or textual context after the error.
jpayne@69:      * Null-terminated.  The empty string if not supported by parser.
jpayne@69:      * @stable ICU 2.0   
jpayne@69:      */
jpayne@69:     UChar          postContext[U_PARSE_CONTEXT_LEN];
jpayne@69: 
jpayne@69: } UParseError;
jpayne@69: 
jpayne@69: #endif