Actual source code: yaml.h

      1: /**
      2:  * @file yaml.h
      3:  * @brief Public interface for libyaml.
      4:  *
      5:  * Include the header file with the code:
      6:  * @code
      7:  * #include <yaml.h>
      8:  * @endcode
      9:  */

     11: #ifndef YAML_H
     12: #define YAML_H

     14: #ifdef __cplusplus
     15: extern "C" {
     16: #endif

     18: #include <stdlib.h>
     19: #include <stdio.h>
     20: #include <string.h>

     22: /**
     23:  * @defgroup export Export Definitions
     24:  * @{
     25:  */

     27: /** The public API declaration. */

     29: #define YAML_DECLARE(type) static type

     31: /** @} */

     33: /**
     34:  * @defgroup basic Basic Types
     35:  * @{
     36:  */

     38: /** The character type (UTF-8 octet). */
     39: typedef unsigned char yaml_char_t;

     41: /** The version directive data. */
     42: typedef struct yaml_version_directive_s {
     43:     /** The major version number. */
     44:     int major;
     45:     /** The minor version number. */
     46:     int minor;
     47: } yaml_version_directive_t;

     49: /** The tag directive data. */
     50: typedef struct yaml_tag_directive_s {
     51:     /** The tag handle. */
     52:     yaml_char_t *handle;
     53:     /** The tag prefix. */
     54:     yaml_char_t *prefix;
     55: } yaml_tag_directive_t;

     57: /** The stream encoding. */
     58: typedef enum yaml_encoding_e {
     59:     /** Let the parser choose the encoding. */
     60:     YAML_ANY_ENCODING,
     61:     /** The default UTF-8 encoding. */
     62:     YAML_UTF8_ENCODING,
     63:     /** The UTF-16-LE encoding with BOM. */
     64:     YAML_UTF16LE_ENCODING,
     65:     /** The UTF-16-BE encoding with BOM. */
     66:     YAML_UTF16BE_ENCODING
     67: } yaml_encoding_t;

     69: /** Line break types. */

     71: typedef enum yaml_break_e {
     72:     /** Let the parser choose the break type. */
     73:     YAML_ANY_BREAK,
     74:     /** Use CR for line breaks (Mac style). */
     75:     YAML_CR_BREAK,
     76:     /** Use LN for line breaks (Unix style). */
     77:     YAML_LN_BREAK,
     78:     /** Use CR LN for line breaks (DOS style). */
     79:     YAML_CRLN_BREAK
     80: } yaml_break_t;

     82: /** Many bad things could happen with the parser and emitter. */
     83: typedef enum yaml_error_type_e {
     84:     /** No error is produced. */
     85:     YAML_NO_ERROR,

     87:     /** Cannot allocate or reallocate a block of memory. */
     88:     YAML_MEMORY_ERROR,

     90:     /** Cannot read or decode the input stream. */
     91:     YAML_READER_ERROR,
     92:     /** Cannot scan the input stream. */
     93:     YAML_SCANNER_ERROR,
     94:     /** Cannot parse the input stream. */
     95:     YAML_PARSER_ERROR,
     96:     /** Cannot compose a YAML document. */
     97:     YAML_COMPOSER_ERROR,

     99:     /** Cannot write to the output stream. */
    100:     YAML_WRITER_ERROR,
    101:     /** Cannot emit a YAML stream. */
    102:     YAML_EMITTER_ERROR
    103: } yaml_error_type_t;

    105: /** The pointer position. */
    106: typedef struct yaml_mark_s {
    107:     /** The position index. */
    108:     size_t index;

    110:     /** The position line. */
    111:     size_t line;

    113:     /** The position column. */
    114:     size_t column;
    115: } yaml_mark_t;

    117: /** @} */

    119: /**
    120:  * @defgroup styles Node Styles
    121:  * @{
    122:  */

    124: /** Scalar styles. */
    125: typedef enum yaml_scalar_style_e {
    126:     /** Let the emitter choose the style. */
    127:     YAML_ANY_SCALAR_STYLE,

    129:     /** The plain scalar style. */
    130:     YAML_PLAIN_SCALAR_STYLE,

    132:     /** The single-quoted scalar style. */
    133:     YAML_SINGLE_QUOTED_SCALAR_STYLE,
    134:     /** The double-quoted scalar style. */
    135:     YAML_DOUBLE_QUOTED_SCALAR_STYLE,

    137:     /** The literal scalar style. */
    138:     YAML_LITERAL_SCALAR_STYLE,
    139:     /** The folded scalar style. */
    140:     YAML_FOLDED_SCALAR_STYLE
    141: } yaml_scalar_style_t;

    143: /** Sequence styles. */
    144: typedef enum yaml_sequence_style_e {
    145:     /** Let the emitter choose the style. */
    146:     YAML_ANY_SEQUENCE_STYLE,

    148:     /** The block sequence style. */
    149:     YAML_BLOCK_SEQUENCE_STYLE,
    150:     /** The flow sequence style. */
    151:     YAML_FLOW_SEQUENCE_STYLE
    152: } yaml_sequence_style_t;

    154: /** Mapping styles. */
    155: typedef enum yaml_mapping_style_e {
    156:     /** Let the emitter choose the style. */
    157:     YAML_ANY_MAPPING_STYLE,

    159:     /** The block mapping style. */
    160:     YAML_BLOCK_MAPPING_STYLE,
    161:     /** The flow mapping style. */
    162:     YAML_FLOW_MAPPING_STYLE
    163: /*    YAML_FLOW_SET_MAPPING_STYLE   */
    164: } yaml_mapping_style_t;

    166: /** @} */

    168: /**
    169:  * @defgroup tokens Tokens
    170:  * @{
    171:  */

    173: /** Token types. */
    174: typedef enum yaml_token_type_e {
    175:     /** An empty token. */
    176:     YAML_NO_TOKEN,

    178:     /** A STREAM-START token. */
    179:     YAML_STREAM_START_TOKEN,
    180:     /** A STREAM-END token. */
    181:     YAML_STREAM_END_TOKEN,

    183:     /** A VERSION-DIRECTIVE token. */
    184:     YAML_VERSION_DIRECTIVE_TOKEN,
    185:     /** A TAG-DIRECTIVE token. */
    186:     YAML_TAG_DIRECTIVE_TOKEN,
    187:     /** A DOCUMENT-START token. */
    188:     YAML_DOCUMENT_START_TOKEN,
    189:     /** A DOCUMENT-END token. */
    190:     YAML_DOCUMENT_END_TOKEN,

    192:     /** A BLOCK-SEQUENCE-START token. */
    193:     YAML_BLOCK_SEQUENCE_START_TOKEN,
    194:     /** A BLOCK-MAPPING-START token. */
    195:     YAML_BLOCK_MAPPING_START_TOKEN,
    196:     /** A BLOCK-END token. */
    197:     YAML_BLOCK_END_TOKEN,

    199:     /** A FLOW-SEQUENCE-START token. */
    200:     YAML_FLOW_SEQUENCE_START_TOKEN,
    201:     /** A FLOW-SEQUENCE-END token. */
    202:     YAML_FLOW_SEQUENCE_END_TOKEN,
    203:     /** A FLOW-MAPPING-START token. */
    204:     YAML_FLOW_MAPPING_START_TOKEN,
    205:     /** A FLOW-MAPPING-END token. */
    206:     YAML_FLOW_MAPPING_END_TOKEN,

    208:     /** A BLOCK-ENTRY token. */
    209:     YAML_BLOCK_ENTRY_TOKEN,
    210:     /** A FLOW-ENTRY token. */
    211:     YAML_FLOW_ENTRY_TOKEN,
    212:     /** A KEY token. */
    213:     YAML_KEY_TOKEN,
    214:     /** A VALUE token. */
    215:     YAML_VALUE_TOKEN,

    217:     /** An ALIAS token. */
    218:     YAML_ALIAS_TOKEN,
    219:     /** An ANCHOR token. */
    220:     YAML_ANCHOR_TOKEN,
    221:     /** A TAG token. */
    222:     YAML_TAG_TOKEN,
    223:     /** A SCALAR token. */
    224:     YAML_SCALAR_TOKEN
    225: } yaml_token_type_t;

    227: /** The token structure. */
    228: typedef struct yaml_token_s {

    230:     /** The token type. */
    231:     yaml_token_type_t type;

    233:     /** The token data. */
    234:     union {

    236:         /** The stream start (for @c YAML_STREAM_START_TOKEN). */
    237:         struct {
    238:             /** The stream encoding. */
    239:             yaml_encoding_t encoding;
    240:         } stream_start;

    242:         /** The alias (for @c YAML_ALIAS_TOKEN). */
    243:         struct {
    244:             /** The alias value. */
    245:             yaml_char_t *value;
    246:         } alias;

    248:         /** The anchor (for @c YAML_ANCHOR_TOKEN). */
    249:         struct {
    250:             /** The anchor value. */
    251:             yaml_char_t *value;
    252:         } anchor;

    254:         /** The tag (for @c YAML_TAG_TOKEN). */
    255:         struct {
    256:             /** The tag handle. */
    257:             yaml_char_t *handle;
    258:             /** The tag suffix. */
    259:             yaml_char_t *suffix;
    260:         } tag;

    262:         /** The scalar value (for @c YAML_SCALAR_TOKEN). */
    263:         struct {
    264:             /** The scalar value. */
    265:             yaml_char_t *value;
    266:             /** The length of the scalar value. */
    267:             size_t length;
    268:             /** The scalar style. */
    269:             yaml_scalar_style_t style;
    270:         } scalar;

    272:         /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
    273:         struct {
    274:             /** The major version number. */
    275:             int major;
    276:             /** The minor version number. */
    277:             int minor;
    278:         } version_directive;

    280:         /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
    281:         struct {
    282:             /** The tag handle. */
    283:             yaml_char_t *handle;
    284:             /** The tag prefix. */
    285:             yaml_char_t *prefix;
    286:         } tag_directive;

    288:     } data;

    290:     /** The beginning of the token. */
    291:     yaml_mark_t start_mark;
    292:     /** The end of the token. */
    293:     yaml_mark_t end_mark;

    295: } yaml_token_t;

    297: /**
    298:  * Free any memory allocated for a token object.
    299:  *
    300:  * @param[in,out]   token   A token object.
    301:  */

    303: YAML_DECLARE(void)
    304: yaml_token_delete(yaml_token_t *token);

    306: /** @} */

    308: /**
    309:  * @defgroup events Events
    310:  * @{
    311:  */

    313: /** Event types. */
    314: typedef enum yaml_event_type_e {
    315:     /** An empty event. */
    316:     YAML_NO_EVENT,

    318:     /** A STREAM-START event. */
    319:     YAML_STREAM_START_EVENT,
    320:     /** A STREAM-END event. */
    321:     YAML_STREAM_END_EVENT,

    323:     /** A DOCUMENT-START event. */
    324:     YAML_DOCUMENT_START_EVENT,
    325:     /** A DOCUMENT-END event. */
    326:     YAML_DOCUMENT_END_EVENT,

    328:     /** An ALIAS event. */
    329:     YAML_ALIAS_EVENT,
    330:     /** A SCALAR event. */
    331:     YAML_SCALAR_EVENT,

    333:     /** A SEQUENCE-START event. */
    334:     YAML_SEQUENCE_START_EVENT,
    335:     /** A SEQUENCE-END event. */
    336:     YAML_SEQUENCE_END_EVENT,

    338:     /** A MAPPING-START event. */
    339:     YAML_MAPPING_START_EVENT,
    340:     /** A MAPPING-END event. */
    341:     YAML_MAPPING_END_EVENT
    342: } yaml_event_type_t;

    344: /** The event structure. */
    345: typedef struct yaml_event_s {

    347:     /** The event type. */
    348:     yaml_event_type_t type;

    350:     /** The event data. */
    351:     union {
    352:
    353:         /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
    354:         struct {
    355:             /** The document encoding. */
    356:             yaml_encoding_t encoding;
    357:         } stream_start;

    359:         /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
    360:         struct {
    361:             /** The version directive. */
    362:             yaml_version_directive_t *version_directive;

    364:             /** The list of tag directives. */
    365:             struct {
    366:                 /** The beginning of the tag directives list. */
    367:                 yaml_tag_directive_t *start;
    368:                 /** The end of the tag directives list. */
    369:                 yaml_tag_directive_t *end;
    370:             } tag_directives;

    372:             /** Is the document indicator implicit? */
    373:             int implicit;
    374:         } document_start;

    376:         /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
    377:         struct {
    378:             /** Is the document end indicator implicit? */
    379:             int implicit;
    380:         } document_end;

    382:         /** The alias parameters (for @c YAML_ALIAS_EVENT). */
    383:         struct {
    384:             /** The anchor. */
    385:             yaml_char_t *anchor;
    386:         } alias;

    388:         /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
    389:         struct {
    390:             /** The anchor. */
    391:             yaml_char_t *anchor;
    392:             /** The tag. */
    393:             yaml_char_t *tag;
    394:             /** The scalar value. */
    395:             yaml_char_t *value;
    396:             /** The length of the scalar value. */
    397:             size_t length;
    398:             /** Is the tag optional for the plain style? */
    399:             int plain_implicit;
    400:             /** Is the tag optional for any non-plain style? */
    401:             int quoted_implicit;
    402:             /** The scalar style. */
    403:             yaml_scalar_style_t style;
    404:         } scalar;

    406:         /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
    407:         struct {
    408:             /** The anchor. */
    409:             yaml_char_t *anchor;
    410:             /** The tag. */
    411:             yaml_char_t *tag;
    412:             /** Is the tag optional? */
    413:             int implicit;
    414:             /** The sequence style. */
    415:             yaml_sequence_style_t style;
    416:         } sequence_start;

    418:         /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
    419:         struct {
    420:             /** The anchor. */
    421:             yaml_char_t *anchor;
    422:             /** The tag. */
    423:             yaml_char_t *tag;
    424:             /** Is the tag optional? */
    425:             int implicit;
    426:             /** The mapping style. */
    427:             yaml_mapping_style_t style;
    428:         } mapping_start;

    430:     } data;

    432:     /** The beginning of the event. */
    433:     yaml_mark_t start_mark;
    434:     /** The end of the event. */
    435:     yaml_mark_t end_mark;

    437: } yaml_event_t;

    439: /** @} */

    441: /**
    442:  * @defgroup nodes Nodes
    443:  * @{
    444:  */

    446: /** The tag @c !!null with the only possible value: @c null. */
    447: #define YAML_NULL_TAG       "tag:yaml.org,2002:null"
    448: /** The tag @c !!bool with the values: @c true and @c false. */
    449: #define YAML_BOOL_TAG       "tag:yaml.org,2002:bool"
    450: /** The tag @c !!str for string values. */
    451: #define YAML_STR_TAG        "tag:yaml.org,2002:str"
    452: /** The tag @c !!int for integer values. */
    453: #define YAML_INT_TAG        "tag:yaml.org,2002:int"
    454: /** The tag @c !!float for float values. */
    455: #define YAML_FLOAT_TAG      "tag:yaml.org,2002:float"
    456: /** The tag @c !!timestamp for date and time values. */
    457: #define YAML_TIMESTAMP_TAG  "tag:yaml.org,2002:timestamp"

    459: /** The tag @c !!seq is used to denote sequences. */
    460: #define YAML_SEQ_TAG        "tag:yaml.org,2002:seq"
    461: /** The tag @c !!map is used to denote mapping. */
    462: #define YAML_MAP_TAG        "tag:yaml.org,2002:map"

    464: /** The default scalar tag is @c !!str. */
    465: #define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
    466: /** The default sequence tag is @c !!seq. */
    467: #define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
    468: /** The default mapping tag is @c !!map. */
    469: #define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG

    471: /** Node types. */
    472: typedef enum yaml_node_type_e {
    473:     /** An empty node. */
    474:     YAML_NO_NODE,

    476:     /** A scalar node. */
    477:     YAML_SCALAR_NODE,
    478:     /** A sequence node. */
    479:     YAML_SEQUENCE_NODE,
    480:     /** A mapping node. */
    481:     YAML_MAPPING_NODE
    482: } yaml_node_type_t;

    484: /** The forward definition of a document node structure. */
    485: typedef struct yaml_node_s yaml_node_t;

    487: /** An element of a sequence node. */
    488: typedef int yaml_node_item_t;

    490: /** An element of a mapping node. */
    491: typedef struct yaml_node_pair_s {
    492:     /** The key of the element. */
    493:     int key;
    494:     /** The value of the element. */
    495:     int value;
    496: } yaml_node_pair_t;

    498: /** The node structure. */
    499: struct yaml_node_s {

    501:     /** The node type. */
    502:     yaml_node_type_t type;

    504:     /** The node tag. */
    505:     yaml_char_t *tag;

    507:     /** The node data. */
    508:     union {
    509:
    510:         /** The scalar parameters (for @c YAML_SCALAR_NODE). */
    511:         struct {
    512:             /** The scalar value. */
    513:             yaml_char_t *value;
    514:             /** The length of the scalar value. */
    515:             size_t length;
    516:             /** The scalar style. */
    517:             yaml_scalar_style_t style;
    518:         } scalar;

    520:         /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
    521:         struct {
    522:             /** The stack of sequence items. */
    523:             struct {
    524:                 /** The beginning of the stack. */
    525:                 yaml_node_item_t *start;
    526:                 /** The end of the stack. */
    527:                 yaml_node_item_t *end;
    528:                 /** The top of the stack. */
    529:                 yaml_node_item_t *top;
    530:             } items;
    531:             /** The sequence style. */
    532:             yaml_sequence_style_t style;
    533:         } sequence;

    535:         /** The mapping parameters (for @c YAML_MAPPING_NODE). */
    536:         struct {
    537:             /** The stack of mapping pairs (key, value). */
    538:             struct {
    539:                 /** The beginning of the stack. */
    540:                 yaml_node_pair_t *start;
    541:                 /** The end of the stack. */
    542:                 yaml_node_pair_t *end;
    543:                 /** The top of the stack. */
    544:                 yaml_node_pair_t *top;
    545:             } pairs;
    546:             /** The mapping style. */
    547:             yaml_mapping_style_t style;
    548:         } mapping;

    550:     } data;

    552:     /** The beginning of the node. */
    553:     yaml_mark_t start_mark;
    554:     /** The end of the node. */
    555:     yaml_mark_t end_mark;

    557: };

    559: /** The document structure. */
    560: typedef struct yaml_document_s {

    562:     /** The document nodes. */
    563:     struct {
    564:         /** The beginning of the stack. */
    565:         yaml_node_t *start;
    566:         /** The end of the stack. */
    567:         yaml_node_t *end;
    568:         /** The top of the stack. */
    569:         yaml_node_t *top;
    570:     } nodes;

    572:     /** The version directive. */
    573:     yaml_version_directive_t *version_directive;

    575:     /** The list of tag directives. */
    576:     struct {
    577:         /** The beginning of the tag directives list. */
    578:         yaml_tag_directive_t *start;
    579:         /** The end of the tag directives list. */
    580:         yaml_tag_directive_t *end;
    581:     } tag_directives;

    583:     /** Is the document start indicator implicit? */
    584:     int start_implicit;
    585:     /** Is the document end indicator implicit? */
    586:     int end_implicit;

    588:     /** The beginning of the document. */
    589:     yaml_mark_t start_mark;
    590:     /** The end of the document. */
    591:     yaml_mark_t end_mark;

    593: } yaml_document_t;

    595: /**
    596:  * Delete a YAML document and all its nodes.
    597:  *
    598:  * @param[in,out]   document        A document object.
    599:  */

    601: YAML_DECLARE(void)
    602: yaml_document_delete(yaml_document_t *document);

    604: /**
    605:  * Get a node of a YAML document.
    606:  *
    607:  * The pointer returned by this function is valid until any of the functions
    608:  * modifying the documents are called.
    609:  *
    610:  * @param[in]       document        A document object.
    611:  * @param[in]       index           The node id.
    612:  *
    613:  * @returns the node object or @c NULL if @c node_id is out of range.
    614:  */

    616: YAML_DECLARE(yaml_node_t *)
    617: yaml_document_get_node(yaml_document_t *document, int index);

    619: /**
    620:  * Get the root of a YAML document node.
    621:  *
    622:  * The root object is the first object added to the document.
    623:  *
    624:  * The pointer returned by this function is valid until any of the functions
    625:  * modifying the documents are called.
    626:  *
    627:  * An empty document produced by the parser signifies the end of a YAML
    628:  * stream.
    629:  *
    630:  * @param[in]       document        A document object.
    631:  *
    632:  * @returns the node object or @c NULL if the document is empty.
    633:  */

    635: YAML_DECLARE(yaml_node_t *)
    636: yaml_document_get_root_node(yaml_document_t *document);

    638: /**
    639:  * Create a SCALAR node and attach it to the document.
    640:  *
    641:  * The @a style argument may be ignored by the emitter.
    642:  *
    643:  * @param[in,out]   document        A document object.
    644:  * @param[in]       tag             The scalar tag.
    645:  * @param[in]       value           The scalar value.
    646:  * @param[in]       length          The length of the scalar value.
    647:  * @param[in]       style           The scalar style.
    648:  *
    649:  * @returns the node id or @c 0 on error.
    650:  */

    652: /** @} */

    654: /**
    655:  * @defgroup parser Parser Definitions
    656:  * @{
    657:  */

    659: /**
    660:  * The prototype of a read handler.
    661:  *
    662:  * The read handler is called when the parser needs to read more bytes from the
    663:  * source.  The handler should write not more than @a size bytes to the @a
    664:  * buffer.  The number of written bytes should be set to the @a length variable.
    665:  *
    666:  * @param[in,out]   data        A pointer to an application data specified by
    667:  *                              yaml_parser_set_input().
    668:  * @param[out]      buffer      The buffer to write the data from the source.
    669:  * @param[in]       size        The size of the buffer.
    670:  * @param[out]      size_read   The actual number of bytes read from the source.
    671:  *
    672:  * @returns On success, the handler should return @c 1.  If the handler failed,
    673:  * the returned value should be @c 0.  On EOF, the handler should set the
    674:  * @a size_read to @c 0 and return @c 1.
    675:  */

    677: typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
    678:         size_t *size_read);

    680: /**
    681:  * This structure holds information about a potential simple key.
    682:  */

    684: typedef struct yaml_simple_key_s {
    685:     /** Is a simple key possible? */
    686:     int possible;

    688:     /** Is a simple key required? */
    689:     int required;

    691:     /** The number of the token. */
    692:     size_t token_number;

    694:     /** The position mark. */
    695:     yaml_mark_t mark;
    696: } yaml_simple_key_t;

    698: /**
    699:  * The states of the parser.
    700:  */
    701: typedef enum yaml_parser_state_e {
    702:     /** Expect STREAM-START. */
    703:     YAML_PARSE_STREAM_START_STATE,
    704:     /** Expect the beginning of an implicit document. */
    705:     YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
    706:     /** Expect DOCUMENT-START. */
    707:     YAML_PARSE_DOCUMENT_START_STATE,
    708:     /** Expect the content of a document. */
    709:     YAML_PARSE_DOCUMENT_CONTENT_STATE,
    710:     /** Expect DOCUMENT-END. */
    711:     YAML_PARSE_DOCUMENT_END_STATE,

    713:     /** Expect a block node. */
    714:     YAML_PARSE_BLOCK_NODE_STATE,
    715:     /** Expect a block node or indentless sequence. */
    716:     YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
    717:     /** Expect a flow node. */
    718:     YAML_PARSE_FLOW_NODE_STATE,
    719:     /** Expect the first entry of a block sequence. */
    720:     YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
    721:     /** Expect an entry of a block sequence. */
    722:     YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,

    724:     /** Expect an entry of an indentless sequence. */
    725:     YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
    726:     /** Expect the first key of a block mapping. */
    727:     YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
    728:     /** Expect a block mapping key. */
    729:     YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
    730:     /** Expect a block mapping value. */
    731:     YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
    732:     /** Expect the first entry of a flow sequence. */
    733:     YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,

    735:     /** Expect an entry of a flow sequence. */
    736:     YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
    737:     /** Expect a key of an ordered mapping. */
    738:     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
    739:     /** Expect a value of an ordered mapping. */
    740:     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
    741:     /** Expect the and of an ordered mapping entry. */
    742:     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
    743:     /** Expect the first key of a flow mapping. */
    744:     YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
    745:     /** Expect a key of a flow mapping. */

    747:     YAML_PARSE_FLOW_MAPPING_KEY_STATE,
    748:     /** Expect a value of a flow mapping. */
    749:     YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
    750:     /** Expect an empty value of a flow mapping. */
    751:     YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
    752:     /** Expect nothing. */
    753:     YAML_PARSE_END_STATE
    754: } yaml_parser_state_t;

    756: /**
    757:  * This structure holds aliases data.
    758:  */

    760: typedef struct yaml_alias_data_s {
    761:     /** The anchor. */
    762:     yaml_char_t *anchor;
    763:     /** The node id. */
    764:     int index;
    765:     /** The anchor mark. */
    766:     yaml_mark_t mark;
    767: } yaml_alias_data_t;

    769: /**
    770:  * The parser structure.
    771:  *
    772:  * All members are internal.  Manage the structure using the @c yaml_parser_
    773:  * family of functions.
    774:  */

    776: typedef struct yaml_parser_s {

    778:     /**
    779:      * @name Error handling
    780:      * @{
    781:      */

    783:     /** Error type. */
    784:     yaml_error_type_t error;
    785:     /** Error description. */
    786:     const char *problem;
    787:     /** The byte about which the problem occurred. */
    788:     size_t problem_offset;
    789:     /** The problematic value (@c -1 is none). */
    790:     int problem_value;
    791:     /** The problem position. */
    792:     yaml_mark_t problem_mark;
    793:     /** The error context. */
    794:     const char *context;
    795:     /** The context position. */
    796:     yaml_mark_t context_mark;

    798:     /**
    799:      * @}
    800:      */

    802:     /**
    803:      * @name Reader stuff
    804:      * @{
    805:      */

    807:     /** Read handler. */
    808:     yaml_read_handler_t *read_handler;

    810:     /** A pointer for passing to the read handler. */
    811:     void *read_handler_data;

    813:     /** Standard (string or file) input data. */
    814:     union {
    815:         /** String input data. */
    816:         struct {
    817:             /** The string start pointer. */
    818:             const unsigned char *start;
    819:             /** The string end pointer. */
    820:             const unsigned char *end;
    821:             /** The string current position. */
    822:             const unsigned char *current;
    823:         } string;

    825:         /** File input data. */
    826:         FILE *file;
    827:     } input;

    829:     /** EOF flag */
    830:     int eof;

    832:     /** The working buffer. */
    833:     struct {
    834:         /** The beginning of the buffer. */
    835:         yaml_char_t *start;
    836:         /** The end of the buffer. */
    837:         yaml_char_t *end;
    838:         /** The current position of the buffer. */
    839:         yaml_char_t *pointer;
    840:         /** The last filled position of the buffer. */
    841:         yaml_char_t *last;
    842:     } buffer;

    844:     /* The number of unread characters in the buffer. */
    845:     size_t unread;

    847:     /** The raw buffer. */
    848:     struct {
    849:         /** The beginning of the buffer. */
    850:         unsigned char *start;
    851:         /** The end of the buffer. */
    852:         unsigned char *end;
    853:         /** The current position of the buffer. */
    854:         unsigned char *pointer;
    855:         /** The last filled position of the buffer. */
    856:         unsigned char *last;
    857:     } raw_buffer;

    859:     /** The input encoding. */
    860:     yaml_encoding_t encoding;

    862:     /** The offset of the current position (in bytes). */
    863:     size_t offset;

    865:     /** The mark of the current position. */
    866:     yaml_mark_t mark;

    868:     /**
    869:      * @}
    870:      */

    872:     /**
    873:      * @name Scanner stuff
    874:      * @{
    875:      */

    877:     /** Have we started to scan the input stream? */
    878:     int stream_start_produced;

    880:     /** Have we reached the end of the input stream? */
    881:     int stream_end_produced;

    883:     /** The number of unclosed '[' and '{' indicators. */
    884:     int flow_level;

    886:     /** The tokens queue. */
    887:     struct {
    888:         /** The beginning of the tokens queue. */
    889:         yaml_token_t *start;
    890:         /** The end of the tokens queue. */
    891:         yaml_token_t *end;
    892:         /** The head of the tokens queue. */
    893:         yaml_token_t *head;
    894:         /** The tail of the tokens queue. */
    895:         yaml_token_t *tail;
    896:     } tokens;

    898:     /** The number of tokens fetched from the queue. */
    899:     size_t tokens_parsed;

    901:     /** Does the tokens queue contain a token ready for dequeueing. */
    902:     int token_available;

    904:     /** The indentation levels stack. */
    905:     struct {
    906:         /** The beginning of the stack. */
    907:         int *start;
    908:         /** The end of the stack. */
    909:         int *end;
    910:         /** The top of the stack. */
    911:         int *top;
    912:     } indents;

    914:     /** The current indentation level. */
    915:     int indent;

    917:     /** May a simple key occur at the current position? */
    918:     int simple_key_allowed;

    920:     /** The stack of simple keys. */
    921:     struct {
    922:         /** The beginning of the stack. */
    923:         yaml_simple_key_t *start;
    924:         /** The end of the stack. */
    925:         yaml_simple_key_t *end;
    926:         /** The top of the stack. */
    927:         yaml_simple_key_t *top;
    928:     } simple_keys;

    930:     /**
    931:      * @}
    932:      */

    934:     /**
    935:      * @name Parser stuff
    936:      * @{
    937:      */

    939:     /** The parser states stack. */
    940:     struct {
    941:         /** The beginning of the stack. */
    942:         yaml_parser_state_t *start;
    943:         /** The end of the stack. */
    944:         yaml_parser_state_t *end;
    945:         /** The top of the stack. */
    946:         yaml_parser_state_t *top;
    947:     } states;

    949:     /** The current parser state. */
    950:     yaml_parser_state_t state;

    952:     /** The stack of marks. */
    953:     struct {
    954:         /** The beginning of the stack. */
    955:         yaml_mark_t *start;
    956:         /** The end of the stack. */
    957:         yaml_mark_t *end;
    958:         /** The top of the stack. */
    959:         yaml_mark_t *top;
    960:     } marks;

    962:     /** The list of TAG directives. */
    963:     struct {
    964:         /** The beginning of the list. */
    965:         yaml_tag_directive_t *start;
    966:         /** The end of the list. */
    967:         yaml_tag_directive_t *end;
    968:         /** The top of the list. */
    969:         yaml_tag_directive_t *top;
    970:     } tag_directives;

    972:     /**
    973:      * @}
    974:      */

    976:     /**
    977:      * @name Dumper stuff
    978:      * @{
    979:      */

    981:     /** The alias data. */
    982:     struct {
    983:         /** The beginning of the list. */
    984:         yaml_alias_data_t *start;
    985:         /** The end of the list. */
    986:         yaml_alias_data_t *end;
    987:         /** The top of the list. */
    988:         yaml_alias_data_t *top;
    989:     } aliases;

    991:     /** The currently parsed document. */
    992:     yaml_document_t *document;

    994:     /**
    995:      * @}
    996:      */

    998: } yaml_parser_t;

    1000: /**
    1001:  * Initialize a parser.
    1002:  *
    1003:  * This function creates a new parser object.  An application is responsible
    1004:  * for destroying the object using the yaml_parser_delete() function.
    1005:  *
    1006:  * @param[out]      parser  An empty parser object.
    1007:  *
    1008:  * @returns @c 1 if the function succeeded, @c 0 on error.
    1009:  */

    1011: YAML_DECLARE(int)
    1012: yaml_parser_initialize(yaml_parser_t *parser);

    1014: /**
    1015:  * Destroy a parser.
    1016:  *
    1017:  * @param[in,out]   parser  A parser object.
    1018:  */

    1020: YAML_DECLARE(void)
    1021: yaml_parser_delete(yaml_parser_t *parser);

    1023: /**
    1024:  * Set a string input.
    1025:  *
    1026:  * Note that the @a input pointer must be valid while the @a parser object
    1027:  * exists.  The application is responsible for destroying @a input after
    1028:  * destroying the @a parser.
    1029:  *
    1030:  * @param[in,out]   parser  A parser object.
    1031:  * @param[in]       input   A source data.
    1032:  * @param[in]       size    The length of the source data in bytes.
    1033:  */

    1035: YAML_DECLARE(void)
    1036: yaml_parser_set_input_string(yaml_parser_t *parser,
    1037:         const unsigned char *input, size_t size);

    1039: /**
    1040:  * Set a file input.
    1041:  *
    1042:  * @a file should be a file object open for reading.  The application is
    1043:  * responsible for closing the @a file.
    1044:  *
    1045:  * @param[in,out]   parser  A parser object.
    1046:  * @param[in]       file    An open file.
    1047:  */

    1049: YAML_DECLARE(void)
    1050: yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);

    1052: /**
    1053:  * Set a generic input handler.
    1054:  *
    1055:  * @param[in,out]   parser  A parser object.
    1056:  * @param[in]       handler A read handler.
    1057:  * @param[in]       data    Any application data for passing to the read
    1058:  *                          handler.
    1059:  */

    1061: YAML_DECLARE(void)
    1062: yaml_parser_set_input(yaml_parser_t *parser,
    1063:         yaml_read_handler_t *handler, void *data);

    1065: /**
    1066:  * Set the source encoding.
    1067:  *
    1068:  * @param[in,out]   parser      A parser object.
    1069:  * @param[in]       encoding    The source encoding.
    1070:  */

    1072: YAML_DECLARE(void)
    1073: yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);

    1075: /**
    1076:  * Scan the input stream and produce the next token.
    1077:  *
    1078:  * Call the function subsequently to produce a sequence of tokens corresponding
    1079:  * to the input stream.  The initial token has the type
    1080:  * @c YAML_STREAM_START_TOKEN while the ending token has the type
    1081:  * @c YAML_STREAM_END_TOKEN.
    1082:  *
    1083:  * An application is responsible for freeing any buffers associated with the
    1084:  * produced token object using the @c yaml_token_delete function.
    1085:  *
    1086:  * An application must not alternate the calls of yaml_parser_scan() with the
    1087:  * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break
    1088:  * the parser.
    1089:  *
    1090:  * @param[in,out]   parser      A parser object.
    1091:  * @param[out]      token       An empty token object.
    1092:  *
    1093:  * @returns @c 1 if the function succeeded, @c 0 on error.
    1094:  */

    1096: YAML_DECLARE(int)
    1097: yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);

    1099: /**
    1100:  * Parse the input stream and produce the next parsing event.
    1101:  *
    1102:  * Call the function subsequently to produce a sequence of events corresponding
    1103:  * to the input stream.  The initial event has the type
    1104:  * @c YAML_STREAM_START_EVENT while the ending event has the type
    1105:  * @c YAML_STREAM_END_EVENT.
    1106:  *
    1107:  * An application is responsible for freeing any buffers associated with the
    1108:  * produced event object using the yaml_event_delete() function.
    1109:  *
    1110:  * An application must not alternate the calls of yaml_parser_parse() with the
    1111:  * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the
    1112:  * parser.
    1113:  *
    1114:  * @param[in,out]   parser      A parser object.
    1115:  * @param[out]      event       An empty event object.
    1116:  *
    1117:  * @returns @c 1 if the function succeeded, @c 0 on error.
    1118:  */

    1120: YAML_DECLARE(int)
    1121: yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);

    1123: /**
    1124:  * Parse the input stream and produce the next YAML document.
    1125:  *
    1126:  * Call this function subsequently to produce a sequence of documents
    1127:  * constituting the input stream.
    1128:  *
    1129:  * If the produced document has no root node, it means that the document
    1130:  * end has been reached.
    1131:  *
    1132:  * An application is responsible for freeing any data associated with the
    1133:  * produced document object using the yaml_document_delete() function.
    1134:  *
    1135:  * An application must not alternate the calls of yaml_parser_load() with the
    1136:  * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break
    1137:  * the parser.
    1138:  *
    1139:  * @param[in,out]   parser      A parser object.
    1140:  * @param[out]      document    An empty document object.
    1141:  *
    1142:  * @returns @c 1 if the function succeeded, @c 0 on error.
    1143:  */

    1145: YAML_DECLARE(int)
    1146: yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document);

    1148: /** @} */

    1150: #ifdef __cplusplus
    1151: }
    1152: #endif

    1154: #endif /* #ifndef YAML_H */