source: libyaml/trunk/include/yaml.h @ 211

Revision 211, 34.3 KB checked in by xi, 8 years ago (diff)

Add Emitter definitions and implement the Writer.

RevLine 
[172]1/**
2 * @file yaml.h
3 * @brief Public interface for libyaml.
4 *
[178]5 * Include the header file with the code:
[172]6 * @code
7 * #include <yaml/yaml.h>
8 * @endcode
9 */
[162]10
[169]11#ifndef YAML_H
12#define YAML_H
[162]13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
[169]18#include <stdlib.h>
[179]19#include <stdio.h>
20#include <string.h>
[162]21
[178]22/**
[184]23 * @defgroup export Export Definitions
[183]24 * @{
25 */
26
27/** The public API declaration. */
28
29#ifdef WIN32
30#   if defined(YAML_DECLARE_STATIC)
31#       define  YAML_DECLARE(type)  type
32#   elif defined(YAML_DECLARE_EXPORT)
33#       define  YAML_DECLARE(type)  __declspec(dllexport) type
34#   else
35#       define  YAML_DECLARE(type)  __declspec(dllimport) type
36#   endif
37#else
38#   define  YAML_DECLARE(type)  type
39#endif
40
41/** @} */
42
43/**
[178]44 * @defgroup version Version Information
45 * @{
46 */
[169]47
[178]48/**
49 * Get the library version as a string.
50 *
51 * @returns The function returns the pointer to a static string of the form
52 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
53 * number, and @c Z is the patch version number.
54 */
55
[183]56YAML_DECLARE(const char *)
[178]57yaml_get_version_string(void);
58
59/**
60 * Get the library version numbers.
61 *
62 * @param[out]  major   Major version number.
63 * @param[out]  minor   Minor version number.
64 * @param[out]  patch   Patch version number.
65 */
66
[183]67YAML_DECLARE(void)
[178]68yaml_get_version(int *major, int *minor, int *patch);
69
70/** @} */
71
72/**
73 * @defgroup basic Basic Types
74 * @{
75 */
76
[183]77/** The character type (UTF-8 octet). */
[178]78typedef unsigned char yaml_char_t;
79
[199]80/** The version directive data. */
81typedef struct {
82    /** The major version number. */
83    int major;
84    /** The minor version number. */
85    int minor;
86} yaml_version_directive_t;
87
88/** The tag directive data. */
89typedef struct {
90    /** The tag handle. */
91    yaml_char_t *handle;
92    /** The tag prefix. */
93    yaml_char_t *prefix;
94} yaml_tag_directive_t;
95
[178]96/** The stream encoding. */
[162]97typedef enum {
[178]98    YAML_ANY_ENCODING,
[162]99    YAML_UTF8_ENCODING,
100    YAML_UTF16LE_ENCODING,
101    YAML_UTF16BE_ENCODING
102} yaml_encoding_t;
103
[211]104/** Line break types. */
105
106typedef enum {
107    YAML_ANY_BREAK,
108    YAML_CR_BREAK,
109    YAML_LN_BREAK,
110    YAML_CRLN_BREAK
111} yaml_break_t;
112
[179]113/** Many bad things could happen with the parser and emitter. */
[162]114typedef enum {
[178]115    YAML_NO_ERROR,
116
117    YAML_MEMORY_ERROR,
118
119    YAML_READER_ERROR,
120    YAML_SCANNER_ERROR,
121    YAML_PARSER_ERROR,
122
123    YAML_WRITER_ERROR,
124    YAML_EMITTER_ERROR
125} yaml_error_type_t;
126
[183]127/** The pointer position. */
128typedef struct {
129    /** The position index. */
130    size_t index;
131
132    /** The position line. */
133    size_t line;
134
135    /** The position column. */
136    size_t column;
137} yaml_mark_t;
138
[179]139/** @} */
140
[183]141/**
[184]142 * @defgroup styles Node Styles
[183]143 * @{
144 */
[179]145
[183]146/** Scalar styles. */
[178]147typedef enum {
[169]148    YAML_ANY_SCALAR_STYLE,
[183]149
[162]150    YAML_PLAIN_SCALAR_STYLE,
[183]151
[162]152    YAML_SINGLE_QUOTED_SCALAR_STYLE,
153    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
[183]154
[162]155    YAML_LITERAL_SCALAR_STYLE,
156    YAML_FOLDED_SCALAR_STYLE
157} yaml_scalar_style_t;
158
[183]159/** Sequence styles. */
[162]160typedef enum {
[169]161    YAML_ANY_SEQUENCE_STYLE,
[183]162
[162]163    YAML_BLOCK_SEQUENCE_STYLE,
164    YAML_FLOW_SEQUENCE_STYLE
165} yaml_sequence_style_t;
166
[183]167/** Mapping styles. */
[162]168typedef enum {
[169]169    YAML_ANY_MAPPING_STYLE,
[183]170
[162]171    YAML_BLOCK_MAPPING_STYLE,
[208]172    YAML_FLOW_MAPPING_STYLE,
173    YAML_FLOW_SET_MAPPING_STYLE
[162]174} yaml_mapping_style_t;
175
[183]176/** @} */
177
178/**
[184]179 * @defgroup tokens Tokens
[183]180 * @{
181 */
182
183/** Token types. */
[162]184typedef enum {
[208]185    YAML_NO_TOKEN,
186
[162]187    YAML_STREAM_START_TOKEN,
188    YAML_STREAM_END_TOKEN,
[169]189
[162]190    YAML_VERSION_DIRECTIVE_TOKEN,
191    YAML_TAG_DIRECTIVE_TOKEN,
192    YAML_DOCUMENT_START_TOKEN,
193    YAML_DOCUMENT_END_TOKEN,
[169]194
[162]195    YAML_BLOCK_SEQUENCE_START_TOKEN,
196    YAML_BLOCK_MAPPING_START_TOKEN,
197    YAML_BLOCK_END_TOKEN,
[169]198
[162]199    YAML_FLOW_SEQUENCE_START_TOKEN,
200    YAML_FLOW_SEQUENCE_END_TOKEN,
201    YAML_FLOW_MAPPING_START_TOKEN,
202    YAML_FLOW_MAPPING_END_TOKEN,
[169]203
[162]204    YAML_BLOCK_ENTRY_TOKEN,
205    YAML_FLOW_ENTRY_TOKEN,
206    YAML_KEY_TOKEN,
207    YAML_VALUE_TOKEN,
[169]208
[162]209    YAML_ALIAS_TOKEN,
210    YAML_ANCHOR_TOKEN,
211    YAML_TAG_TOKEN,
212    YAML_SCALAR_TOKEN
213} yaml_token_type_t;
214
[183]215/** The token structure. */
216typedef struct {
[169]217
[183]218    /** The token type. */
219    yaml_token_type_t type;
[169]220
[183]221    /** The token data. */
222    union {
[169]223
[199]224        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
225        struct {
226            /** The stream encoding. */
227            yaml_encoding_t encoding;
228        } stream_start;
[169]229
[199]230        /** The alias (for @c YAML_ALIAS_TOKEN). */
231        struct {
232            /** The alias value. */
233            yaml_char_t *value;
234        } alias;
[162]235
[199]236        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
237        struct {
238            /** The anchor value. */
239            yaml_char_t *value;
240        } anchor;
241
[183]242        /** The tag (for @c YAML_TAG_TOKEN). */
243        struct {
244            /** The tag handle. */
245            yaml_char_t *handle;
246            /** The tag suffix. */
247            yaml_char_t *suffix;
248        } tag;
[162]249
[183]250        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
[162]251        struct {
[183]252            /** The scalar value. */
253            yaml_char_t *value;
254            /** The length of the scalar value. */
[169]255            size_t length;
[183]256            /** The scalar style. */
[162]257            yaml_scalar_style_t style;
258        } scalar;
[183]259
260        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
[162]261        struct {
[183]262            /** The major version number. */
[162]263            int major;
[183]264            /** The minor version number. */
[162]265            int minor;
[183]266        } version_directive;
267
268        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
[162]269        struct {
[183]270            /** The tag handle. */
271            yaml_char_t *handle;
272            /** The tag prefix. */
273            yaml_char_t *prefix;
274        } tag_directive;
[208]275
[162]276    } data;
[183]277
278    /** The beginning of the token. */
[162]279    yaml_mark_t start_mark;
[183]280    /** The end of the token. */
[162]281    yaml_mark_t end_mark;
[183]282
[162]283} yaml_token_t;
284
[183]285/**
[208]286 * Free any memory allocated for a token object.
[183]287 *
288 * @param[in]   token   A token object.
289 */
290
291YAML_DECLARE(void)
292yaml_token_delete(yaml_token_t *token);
293
294/** @} */
295
[199]296/**
297 * @defgroup events Events
298 * @{
299 */
[183]300
[199]301/** Event types. */
[183]302typedef enum {
[208]303    YAML_NO_EVENT,
304
[183]305    YAML_STREAM_START_EVENT,
306    YAML_STREAM_END_EVENT,
307
308    YAML_DOCUMENT_START_EVENT,
309    YAML_DOCUMENT_END_EVENT,
310
311    YAML_ALIAS_EVENT,
312    YAML_SCALAR_EVENT,
313
314    YAML_SEQUENCE_START_EVENT,
315    YAML_SEQUENCE_END_EVENT,
316
317    YAML_MAPPING_START_EVENT,
318    YAML_MAPPING_END_EVENT
319} yaml_event_type_t;
320
[199]321/** The event structure. */
[162]322typedef struct {
[199]323
324    /** The event type. */
[162]325    yaml_event_type_t type;
[199]326
327    /** The event data. */
[162]328    union {
[199]329       
330        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
[162]331        struct {
[199]332            /** The document encoding. */
[162]333            yaml_encoding_t encoding;
334        } stream_start;
[199]335
336        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
[162]337        struct {
[199]338            /** The version directive. */
339            yaml_version_directive_t *version_directive;
[208]340
[199]341            /** The list of tag directives. */
[208]342            struct {
343                /** The beginning of the tag directives list. */
344                yaml_tag_directive_t *start;
345                /** The end of the tag directives list. */
346                yaml_tag_directive_t *end;
347            } tag_directives;
348
[199]349            /** Is the document indicator implicit? */
[162]350            int implicit;
351        } document_start;
[199]352
353        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
[162]354        struct {
[199]355            /** Is the document end indicator implicit? */
[162]356            int implicit;
357        } document_end;
[199]358
359        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
[162]360        struct {
[199]361            /** The anchor. */
362            yaml_char_t *anchor;
[162]363        } alias;
[199]364
365        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
[162]366        struct {
[199]367            /** The anchor. */
368            yaml_char_t *anchor;
369            /** The tag. */
370            yaml_char_t *tag;
371            /** The scalar value. */
372            yaml_char_t *value;
373            /** The length of the scalar value. */
[169]374            size_t length;
[199]375            /** Is the tag optional for the plain style? */
[162]376            int plain_implicit;
[199]377            /** Is the tag optional for any non-plain style? */
[162]378            int quoted_implicit;
[199]379            /** The scalar style. */
[162]380            yaml_scalar_style_t style;
381        } scalar;
[199]382
383        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
[162]384        struct {
[199]385            /** The anchor. */
386            yaml_char_t *anchor;
387            /** The tag. */
388            yaml_char_t *tag;
389            /** Is the tag optional? */
[162]390            int implicit;
[199]391            /** The sequence style. */
[162]392            yaml_sequence_style_t style;
393        } sequence_start;
[199]394
395        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
[162]396        struct {
[199]397            /** The anchor. */
398            yaml_char_t *anchor;
399            /** The tag. */
400            yaml_char_t *tag;
401            /** Is the tag optional? */
[162]402            int implicit;
[199]403            /** The mapping style. */
[162]404            yaml_mapping_style_t style;
405        } mapping_start;
[199]406
[162]407    } data;
[199]408
409    /** The beginning of the token. */
[162]410    yaml_mark_t start_mark;
[199]411    /** The end of the token. */
[162]412    yaml_mark_t end_mark;
[208]413
[162]414} yaml_event_t;
415
[199]416/**
[208]417 * Free any memory allocated for an event object.
[199]418 *
419 * @param[in]   event   An event object.
420 */
421
422YAML_DECLARE(void)
423yaml_event_delete(yaml_event_t *event);
424
425/** @} */
426
427/**
[178]428 * @defgroup parser Parser Definitions
429 * @{
430 */
431
432/**
433 * The prototype of a read handler.
434 *
435 * The read handler is called when the parser needs to read more bytes from the
436 * source.  The handler should write not more than @a size bytes to the @a
437 * buffer.  The number of written bytes should be set to the @a length variable.
438 *
[180]439 * @param[in]   data        A pointer to an application data specified by
[179]440 *                          @c yaml_parser_set_read_handler.
441 * @param[out]  buffer      The buffer to write the data from the source.
442 * @param[in]   size        The size of the buffer.
443 * @param[out]  size_read   The actual number of bytes read from the source.
[178]444 *
445 * @returns On success, the handler should return @c 1.  If the handler failed,
446 * the returned value should be @c 0.  On EOF, the handler should set the
[211]447 * @a size_read to @c 0 and return @c 1.
[178]448 */
[180]449
450typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
[179]451        size_t *size_read);
[178]452
453/**
[184]454 * This structure holds information about a potential simple key.
455 */
456
457typedef struct {
[208]458    /** Is a simple key possible? */
459    int possible;
460
[184]461    /** Is a simple key required? */
462    int required;
463
464    /** The number of the token. */
465    size_t token_number;
466
467    /** The position mark. */
468    yaml_mark_t mark;
469} yaml_simple_key_t;
470
471/**
[201]472 * The states of the parser.
473 */
474typedef enum {
475    YAML_PARSE_STREAM_START_STATE,
476    YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
477    YAML_PARSE_DOCUMENT_START_STATE,
478    YAML_PARSE_DOCUMENT_CONTENT_STATE,
479    YAML_PARSE_DOCUMENT_END_STATE,
480    YAML_PARSE_BLOCK_NODE_STATE,
481    YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
482    YAML_PARSE_FLOW_NODE_STATE,
483    YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
484    YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
485    YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
486    YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
487    YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
488    YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
489    YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
490    YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
491    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
492    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
493    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
494    YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
495    YAML_PARSE_FLOW_MAPPING_KEY_STATE,
496    YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
[208]497    YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
498    YAML_PARSE_END_STATE
[201]499} yaml_parser_state_t;
500
501/**
[178]502 * The parser structure.
503 *
504 * All members are internal.  Manage the structure using the @c yaml_parser_
505 * family of functions.
506 */
507
[162]508typedef struct {
[178]509
510    /**
[179]511     * @name Error handling
512     * @{
513     */
514
[181]515    /** Error type. */
[180]516    yaml_error_type_t error;
[181]517    /** Error description. */
518    const char *problem;
519    /** The byte about which the problem occured. */
520    size_t problem_offset;
[182]521    /** The problematic value (@c -1 is none). */
522    int problem_value;
[185]523    /** The problem position. */
524    yaml_mark_t problem_mark;
525    /** The error context. */
526    const char *context;
527    /** The context position. */
528    yaml_mark_t context_mark;
529
[179]530    /**
531     * @}
532     */
533
534    /**
[178]535     * @name Reader stuff
536     * @{
537     */
538
[181]539    /** Read handler. */
[179]540    yaml_read_handler_t *read_handler;
[178]541
542    /** A pointer for passing to the read handler. */
[179]543    void *read_handler_data;
[178]544
[208]545    /** Standard (string or file) input data. */
546    union {
547        /** String input data. */
548        struct {
549            /** The string start pointer. */
550            unsigned char *start;
551            /** The string end pointer. */
552            unsigned char *end;
553            /** The string current position. */
554            unsigned char *current;
555        } string;
556
557        /** File input data. */
558        FILE *file;
559    } input;
560
[178]561    /** EOF flag */
562    int eof;
563
[208]564    /** The working buffer. */
565    struct {
[211]566        /** The beginning of the buffer. */
[208]567        yaml_char_t *start;
[211]568        /** The end of the buffer. */
[208]569        yaml_char_t *end;
[211]570        /** The current position of the buffer. */
[208]571        yaml_char_t *pointer;
[211]572        /** The last filled position of the buffer. */
[208]573        yaml_char_t *last;
574    } buffer;
[178]575
[208]576    /* The number of unread characters in the buffer. */
[180]577    size_t unread;
[179]578
[208]579    /** The raw buffer. */
580    struct {
581        /** The beginning of the buffer. */
582        unsigned char *start;
583        /** The end of the buffer. */
584        unsigned char *end;
585        /** The current position of the buffer. */
586        unsigned char *pointer;
587        /** The last filled position of the buffer. */
588        unsigned char *last;
589    } raw_buffer;
[178]590
591    /** The input encoding. */
592    yaml_encoding_t encoding;
593
[179]594    /** The offset of the current position (in bytes). */
595    size_t offset;
596
[208]597    /** The mark of the current position. */
598    yaml_mark_t mark;
[179]599
[178]600    /**
601     * @}
602     */
603
[184]604    /**
605     * @name Scanner stuff
606     * @{
607     */
608
609    /** Have we started to scan the input stream? */
610    int stream_start_produced;
611
612    /** Have we reached the end of the input stream? */
613    int stream_end_produced;
614
615    /** The number of unclosed '[' and '{' indicators. */
616    int flow_level;
617
[208]618    /** The tokens queue. */
619    struct {
620        /** The beginning of the tokens queue. */
621        yaml_token_t *start;
622        /** The end of the tokens queue. */
623        yaml_token_t *end;
624        /** The head of the tokens queue. */
625        yaml_token_t *head;
626        /** The tail of the tokens queue. */
627        yaml_token_t *tail;
628    } tokens;
[184]629
[208]630    /** The number of tokens fetched from the queue. */
[184]631    size_t tokens_parsed;
632
[208]633    /* Does the tokens queue contain a token ready for dequeueing. */
634    int token_available;
[184]635
[208]636    /** The indentation levels stack. */
637    struct {
638        /** The beginning of the stack. */
639        int *start;
640        /** The end of the stack. */
641        int *end;
642        /** The top of the stack. */
643        int *top;
644    } indents;
[184]645
646    /** The current indentation level. */
647    int indent;
648
649    /** May a simple key occur at the current position? */
650    int simple_key_allowed;
651
[208]652    /** The stack of simple keys. */
653    struct {
654        /** The beginning of the stack. */
655        yaml_simple_key_t *start;
656        /** The end of the stack. */
657        yaml_simple_key_t *end;
658        /** The top of the stack. */
659        yaml_simple_key_t *top;
660    } simple_keys;
[184]661
662    /**
663     * @}
664     */
665
[201]666    /**
667     * @name Parser stuff
668     * @{
669     */
670
671    /** The parser states stack. */
[208]672    struct {
673        /** The beginning of the stack. */
674        yaml_parser_state_t *start;
675        /** The end of the stack. */
676        yaml_parser_state_t *end;
677        /** The top of the stack. */
678        yaml_parser_state_t *top;
679    } states;
[201]680
681    /** The current parser state. */
682    yaml_parser_state_t state;
683
684    /** The stack of marks. */
[208]685    struct {
686        /** The beginning of the stack. */
687        yaml_mark_t *start;
688        /** The end of the stack. */
689        yaml_mark_t *end;
690        /** The top of the stack. */
691        yaml_mark_t *top;
692    } marks;
[201]693
694    /** The list of TAG directives. */
[208]695    struct {
696        /** The beginning of the list. */
697        yaml_tag_directive_t *start;
698        /** The end of the list. */
699        yaml_tag_directive_t *end;
700        /** The top of the list. */
701        yaml_tag_directive_t *top;
702    } tag_directives;
[201]703
704    /**
705     * @}
706     */
707
[162]708} yaml_parser_t;
709
[178]710/**
[208]711 * Initialize a parser.
[178]712 *
713 * This function creates a new parser object.  An application is responsible
714 * for destroying the object using the @c yaml_parser_delete function.
715 *
[208]716 * @param[in]   parser  An empty parser object.
717 *
[211]718 * @returns @c 1 if the function succeeded, @c 0 on error.
[178]719 */
720
[208]721YAML_DECLARE(int)
722yaml_parser_initialize(yaml_parser_t *parser);
[178]723
724/**
725 * Destroy a parser.
726 *
727 * @param[in]   parser  A parser object.
728 */
729
[183]730YAML_DECLARE(void)
[178]731yaml_parser_delete(yaml_parser_t *parser);
732
[179]733/**
734 * Set a string input.
735 *
736 * Note that the @a input pointer must be valid while the @a parser object
737 * exists.  The application is responsible for destroing @a input after
738 * destroying the @a parser.
739 *
740 * @param[in]   parser  A parser object.
741 * @param[in]   input   A source data.
[183]742 * @param[in]   size    The length of the source data in bytes.
[179]743 */
744
[183]745YAML_DECLARE(void)
[179]746yaml_parser_set_input_string(yaml_parser_t *parser,
747        unsigned char *input, size_t size);
748
749/**
750 * Set a file input.
751 *
752 * @a file should be a file object open for reading.  The application is
753 * responsible for closing the @a file.
754 *
755 * @param[in]   parser  A parser object.
756 * @param[in]   file    An open file.
757 */
758
[183]759YAML_DECLARE(void)
[179]760yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
761
762/**
763 * Set a generic input handler.
764 *
765 * @param[in]   parser  A parser object.
766 * @param[in]   handler A read handler.
767 * @param[in]   data    Any application data for passing to the read handler.
768 */
769
[183]770YAML_DECLARE(void)
[179]771yaml_parser_set_input(yaml_parser_t *parser,
772        yaml_read_handler_t *handler, void *data);
773
774/**
775 * Set the source encoding.
776 *
[183]777 * @param[in]   parser      A parser object.
[179]778 * @param[in]   encoding    The source encoding.
779 */
780
[183]781YAML_DECLARE(void)
[179]782yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
783
[184]784/**
[208]785 * Scan the input stream and produce the next token.
[184]786 *
[208]787 * Call the function subsequently to produce a sequence of tokens corresponding
788 * to the input stream.  The initial token has the type
789 * @c YAML_STREAM_START_TOKEN while the ending token has the type
790 * @c YAML_STREAM_END_TOKEN.
[184]791 *
[208]792 * An application is responsible for freeing any buffers associated with the
793 * produced token object using the @c yaml_token_delete function.
[184]794 *
[208]795 * An application must not alternate the calls of @c yaml_parser_scan with the
796 * calls of @c yaml_parser_parse. Doing this will break the parser.
[184]797 *
798 * @param[in]   parser      A parser object.
[208]799 * @param[in]   token       An empty token object.
[184]800 *
[208]801 * @returns @c 1 if the function succeeded, @c 0 on error.
[184]802 */
803
[208]804YAML_DECLARE(int)
805yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
[184]806
[201]807/**
[208]808 * Parse the input stream and produce the next parsing event.
[201]809 *
[208]810 * Call the function subsequently to produce a sequence of events corresponding
811 * to the input stream.  The initial event has the type
812 * @c YAML_STREAM_START_EVENT while the ending event has the type
813 * @c YAML_STREAM_END_EVENT.
[201]814 *
[208]815 * An application is responsible for freeing any buffers associated with the
816 * produced event object using the @c yaml_event_delete function.
[201]817 *
[208]818 * An application must not alternate the calls of @c yaml_parser_scan with the
819 * calls of @c yaml_parser_parse. Doing this will break the parser.
[201]820 *
821 * @param[in]   parser      A parser object.
[208]822 * @param[in]   event       An empty event object.
[201]823 *
[208]824 * @returns @c 1 if the function succeeded, @c 0 on error.
[201]825 */
826
[208]827YAML_DECLARE(int)
828yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
[201]829
[178]830/** @} */
831
[211]832/**
833 * @defgroup emitter Emitter Definitions
834 * @{
835 */
836
837/**
838 * The prototype of a write handler.
839 *
840 * The write handler is called when the emitter needs to flush the accumulated
841 * characters to the output.  The handler should write @a size bytes of the
842 * @a buffer to the output.
843 *
844 * @param[in]   data        A pointer to an application data specified by
845 *                          @c yaml_emitter_set_write_handler.
846 * @param[out]  buffer      The buffer with bytes to be written.
847 * @param[in]   size        The size of the buffer.
848 *
849 * @returns On success, the handler should return @c 1.  If the handler failed,
850 * the returned value should be @c 0.
851 */
852
853typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
854
855/** The emitter states. */
856typedef enum {
857    YAML_EMIT_STREAM_START_STATE,
858    YAML_EMIT_FIRST_DOCUMENT_START_STATE,
859    YAML_EMIT_DOCUMENT_START_STATE,
860    YAML_EMIT_DOCUMENT_CONTENT_STATE,
861    YAML_EMIT_DOCUMENT_END_STATE,
862    YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
863    YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
864    YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
865    YAML_EMIT_FLOW_MAPPING_KEY_STATE,
866    YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
867    YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
868    YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
869    YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
870    YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
871    YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
872    YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
873    YAML_EMIT_BLOCK_MAPPING_VALUE_STATE
874} yaml_emitter_state_t;
875
876/**
877 * The emitter structure.
878 *
879 * All members are internal.  Manage the structure using the @c yaml_emitter_
880 * family of functions.
881 */
882
[162]883typedef struct {
[211]884
885    /**
886     * @name Error handling
887     * @{
888     */
889
890    /** Error type. */
891    yaml_error_type_t error;
892    /** Error description. */
893    const char *problem;
894
895    /**
896     * @}
897     */
898
899    /**
900     * @name Writer stuff
901     * @{
902     */
903
904    /** Write handler. */
905    yaml_write_handler_t *write_handler;
906
907    /** A pointer for passing to the white handler. */
908    void *write_handler_data;
909
910    /** Standard (string or file) output data. */
911    union {
912        /** String output data. */
913        struct {
914            /** The buffer pointer. */
915            unsigned char *buffer;
916            /** The buffer size. */
917            size_t size;
918            /** The number of written bytes. */
919            size_t *size_written;
920        } string;
921
922        /** File output data. */
923        FILE *file;
924    } output;
925
926    /** The working buffer. */
927    struct {
928        /** The beginning of the buffer. */
929        yaml_char_t *start;
930        /** The end of the buffer. */
931        yaml_char_t *end;
932        /** The current position of the buffer. */
933        yaml_char_t *pointer;
934        /** The last filled position of the buffer. */
935        yaml_char_t *last;
936    } buffer;
937
938    /** The raw buffer. */
939    struct {
940        /** The beginning of the buffer. */
941        unsigned char *start;
942        /** The end of the buffer. */
943        unsigned char *end;
944        /** The current position of the buffer. */
945        unsigned char *pointer;
946        /** The last filled position of the buffer. */
947        unsigned char *last;
948    } raw_buffer;
949
950    /** The stream encoding. */
951    yaml_encoding_t encoding;
952
953    /**
954     * @}
955     */
956
957    /**
958     * @name Emitter stuff
959     * @{
960     */
961
962    /** If the output is in the canonical style? */
963    int canonical;
964    /** The number of indentation spaces. */
965    int best_indent;
966    /** The preferred width of the output lines. */
967    int best_width;
968    /** Allow unescaped non-ASCII characters? */
969    int unicode;
970    /** The preferred line break. */
971    yaml_break_t line_break;
972
973    /** The stack of states. */
974    struct {
975        /** The beginning of the stack. */
976        yaml_emitter_state_t *start;
977        /** The end of the stack. */
978        yaml_emitter_state_t *end;
979        /** The top of the stack. */
980        yaml_emitter_state_t *top;
981    } states;
982
983    /** The current emitter state. */
984    yaml_emitter_state_t state;
985
986    /** The event queue. */
987    struct {
988        /** The beginning of the event queue. */
989        yaml_event_t *start;
990        /** The end of the event queue. */
991        yaml_event_t *end;
992        /** The head of the event queue. */
993        yaml_event_t *head;
994        /** The tail of the event queue. */
995        yaml_event_t *tail;
996    } events;
997
998    /** The current event. */
999    yaml_event_t event;
1000
1001    /** The stack of indentation levels. */
1002    struct {
1003        /** The beginning of the stack. */
1004        int *start;
1005        /** The end of the stack. */
1006        int *end;
1007        /** The top of the stack. */
1008        int *top;
1009    } indents;
1010
1011    /** The list of tag directives. */
1012    struct {
1013        /** The beginning of the list. */
1014        yaml_tag_directive_t *start;
1015        /** The end of the list. */
1016        yaml_tag_directive_t *end;
1017        /** The top of the list. */
1018        yaml_tag_directive_t *top;
1019    } tag_directives;
1020
1021    /** The current indentation level. */
1022    int indent;
1023
1024    /** The current flow level. */
1025    int flow_level;
1026
1027    /** Is it the document root context? */
1028    int root_context;
1029    /** Is it a sequence context? */
1030    int sequence_context;
1031    /** Is it a mapping context? */
1032    int mapping_context;
1033    /** Is it a simple mapping key context? */
1034    int simple_key_context;
1035
1036    /** The current line. */
1037    int line;
1038    /** The current column. */
1039    int column;
1040    /** If the last character was a whitespace? */
1041    int whitespace;
1042    /** If the last character was an indentation character (' ', '-', '?', ':')? */
1043    int indention;
1044
1045    /**
1046     * @}
1047     */
1048
[162]1049} yaml_emitter_t;
1050
[211]1051/**
1052 * Initialize an emitter.
1053 *
1054 * This function creates a new emitter object.  An application is responsible
1055 * for destroying the object using the @c yaml_emitter_delete function.
1056 *
1057 * @param[in]   emitter An empty parser object.
1058 *
1059 * @returns @c 1 if the function succeeded, @c 0 on error.
1060 */
1061
[208]1062YAML_DECLARE(int)
[211]1063yaml_emitter_initialize(yaml_emitter_t *emitter);
1064
1065/**
1066 * Destroy an emitter.
1067 *
1068 * @param[in]   emitter An emitter object.
1069 */
1070
1071YAML_DECLARE(void)
1072yaml_emitter_delete(yaml_emitter_t *emitter);
1073
1074/**
1075 * Set a string output.
1076 *
1077 * The emitter will write the output characters to the @a output buffer of the
1078 * size @a size.  The emitter will set @a size_written to the number of written
1079 * bytes.  If the buffer is smaller than required, the emitter produces the
1080 * YAML_WRITE_ERROR error.
1081 *
1082 * @param[in]   emitter         An emitter object.
1083 * @param[in]   output          An output buffer.
1084 * @param[in]   size            The buffer size.
1085 * @param[in]   size_written    The pointer to save the number of written bytes.
1086 */
1087
1088YAML_DECLARE(void)
1089yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1090        unsigned char *output, size_t size, size_t *size_written);
1091
1092/**
1093 * Set a file output.
1094 *
1095 * @a file should be a file object open for writing.  The application is
1096 * responsible for closing the @a file.
1097 *
1098 * @param[in]   emitter An emitter object.
1099 * @param[in]   file    An open file.
1100 */
1101
1102YAML_DECLARE(void)
1103yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1104
1105/**
1106 * Set a generic output handler.
1107 *
1108 * @param[in]   emitter An emitter object.
1109 * @param[in]   handler A write handler.
1110 * @param[in]   data    Any application data for passing to the write handler.
1111 */
1112
1113YAML_DECLARE(void)
1114yaml_emitter_set_output(yaml_emitter_t *emitter,
1115        yaml_write_handler_t *handler, void *data);
1116
1117/**
1118 * Set the output encoding.
1119 *
1120 * @param[in]   emitter     An emitter object.
1121 * @param[in]   encoding    The output encoding.
1122 */
1123
1124YAML_DECLARE(void)
1125yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1126
1127/**
1128 * Set if the output should be in the "canonical" format as in the YAML
1129 * specification.
1130 *
1131 * @param[in]   emitter     An emitter object.
1132 * @param[in]   canonical   If the output is canonical.
1133 */
1134
1135YAML_DECLARE(void)
1136yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1137
1138/**
1139 * Set the intendation increment.
1140 *
1141 * @param[in]   emitter     An emitter object.
1142 * @param[in]   indent      The indentation increment (> 1).
1143 */
1144
1145YAML_DECLARE(void)
1146yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1147
1148/**
1149 * Set the preferred line width. @c 0 means unlimited.
1150 *
1151 * @param[in]   emitter     An emitter object.
1152 * @param[in]   width       The preferred line width.
1153 */
1154
1155YAML_DECLARE(void)
1156yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1157
1158/**
1159 * Set if unescaped non-ASCII characters are allowed.
1160 *
1161 * @param[in]   emitter     An emitter object.
1162 * @param[in]   unicode     If unescaped Unicode characters are allowed.
1163 */
1164
1165YAML_DECLARE(void)
1166yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1167
1168/**
1169 * Set the preferred line break.
1170 *
1171 * @param[in]   emitter     An emitter object.
1172 * @param[in]   line_break  The preferred line break.
1173 */
1174
1175YAML_DECLARE(void)
1176yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1177
1178/**
1179 * Emit an event.
1180 *
1181 * The event object may be generated using the @c yaml_parser_parse function.
1182 * The emitter will destroy the event object if the function succeeds.  If the
1183 * function fails, the application is responsible for destroing the event
1184 * object.
1185 *
1186 * @param[in]   emitter     An emitter object.
1187 * @param[in]   event       An event object.
1188 *
1189 * @returns @c 1 if the function succeeded, @c 0 on error.
1190 */
1191
1192YAML_DECLARE(int)
[208]1193yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
[179]1194
[211]1195/**
1196 * Emit the STREAM-START event.
1197 *
1198 * @param[in]   emitter     An emitter object.
1199 * @param[in]   encoding    The stream encoding.
1200 *
1201 * @returns @c 1 if the function succeeded, @c 0 on error.
1202 */
1203
[183]1204YAML_DECLARE(int)
[208]1205yaml_emitter_emit_stream_start(yaml_emitter_t *emitter,
1206        yaml_encoding_t encoding);
[181]1207
[211]1208/**
1209 * Emit the STREAM-END event.
1210 *
1211 * @param[in]   emitter     An emitter object.
1212 *
1213 * @returns @c 1 if the function succeeded, @c 0 on error.
1214 */
[179]1215
[211]1216YAML_DECLARE(int)
1217yaml_emitter_emit_stream_end(yaml_emitter_t *emitter);
1218
1219/**
1220 * Emit the DOCUMENT-START event.
1221 *
1222 * The @a implicit argument is considered as a stylistic parameter and may be
1223 * ignored by the emitter.
1224 *
1225 * @param[in]   emitter                 An emitter object.
1226 * @param[in]   version_directive       The %YAML directive value or @c NULL.
1227 * @param[in]   tag_directives_start    The beginning of the %TAG directives list.
1228 * @param[in]   tag_directives_end      The end of the %TAG directives list.
1229 * @param[in]   implicit                If the document start indicator is implicit.
1230 *
1231 * @returns @c 1 if the function succeeded, @c 0 on error.
1232 */
1233
1234YAML_DECLARE(int)
1235yaml_emitter_emit_document_start(yaml_emitter_t *emitter,
1236        yaml_version_directive_t *version_directive,
1237        yaml_tag_directive_t *tag_directives_start,
1238        yaml_tag_directive_t *tag_directives_end,
1239        int implicit);
1240
1241/**
1242 * Emit the DOCUMENT-END event.
1243 *
1244 * The @a implicit argument is considered as a stylistic parameter and may be
1245 * ignored by the emitter.
1246 *
1247 * @param[in]   emitter     An emitter object.
1248 * @param[in]   implicit    If the document end indicator is implicit.
1249 *
1250 * @returns @c 1 if the function succeeded, @c 0 on error.
1251 */
1252
1253YAML_DECLARE(int)
1254yaml_emitter_emit_document_end(yaml_emitter_t *emitter, int implicit);
1255
1256/**
1257 * Emit an ALIAS event.
1258 *
1259 * @param[in]   emitter     An emitter object.
1260 * @param[in]   anchor      The anchor value.
1261 *
1262 * @returns @c 1 if the function succeeded, @c 0 on error.
1263 */
1264
1265YAML_DECLARE(int)
1266yaml_emitter_emit_alias(yaml_emitter_t *emitter, yaml_char_t *anchor);
1267
1268/**
1269 * Emit a SCALAR event.
1270 *
1271 * The @a style argument may be ignored by the emitter.
1272 *
1273 * Either the @a tag attribute or one of the @a plain_implicit and
1274 * @a quoted_implicit flags must be set.
1275 *
1276 * @param[in]   emitter         An emitter object.
1277 * @param[in]   anchor          The scalar anchor or @c NULL.
1278 * @param[in]   tag             The scalar tag or @c NULL.
1279 * @param[in]   value           The scalar value.
1280 * @param[in]   length          The length of the scalar value.
1281 * @param[in]   plain_implicit  If the tag may be omitted for the plain style.
1282 * @param[in]   quoted_implicit If the tag may be omitted for any non-plain style.
1283 * @param[in]   style           The scalar style.
1284 *
1285 * @returns @c 1 if the function succeeded, @c 0 on error.
1286 */
1287
1288YAML_DECLARE(int)
1289yaml_emitter_emit_scalar(yaml_emitter_t *emitter,
1290        yaml_char_t *anchor, yaml_char_t *tag,
1291        yaml_char_t *value, size_t length,
1292        int plain_implicit, int quoted_implicit,
1293        yaml_scalar_style_t style);
1294
1295/**
1296 * Emit a SEQUENCE-START event.
1297 *
1298 * The @a style argument may be ignored by the emitter.
1299 *
1300 * Either the @a tag attribute or the @a implicit flag must be set.
1301 *
1302 * @param[in]   emitter     An emitter object.
1303 * @param[in]   anchor      The sequence anchor or @c NULL.
1304 * @param[in]   tag         The sequence tag or @c NULL.
1305 * @param[in]   implicit    If the tag may be omitted.
1306 * @param[in]   style       The sequence style.
1307 *
1308 * @returns @c 1 if the function succeeded, @c 0 on error.
1309 */
1310
1311YAML_DECLARE(int)
1312yaml_emitter_emit_sequence_start(yaml_emitter_t *emitter,
1313        yaml_char_t *anchor, yaml_char_t *tag, int implicit,
1314        yaml_sequence_style_t style);
1315
1316/**
1317 * Emit a SEQUENCE-END event.
1318 *
1319 * @param[in]   emitter     An emitter object.
1320 *
1321 * @returns @c 1 if the function succeeded, @c 0 on error.
1322 */
1323
1324YAML_DECLARE(int)
1325yaml_emitter_emit_sequence_end(yaml_emitter_t *emitter);
1326
1327/**
1328 * Emit a MAPPING-START event.
1329 *
1330 * The @a style argument may be ignored by the emitter.
1331 *
1332 * Either the @a tag attribute or the @a implicit flag must be set.
1333 *
1334 * @param[in]   emitter     An emitter object.
1335 * @param[in]   anchor      The mapping anchor or @c NULL.
1336 * @param[in]   tag         The mapping tag or @c NULL.
1337 * @param[in]   implicit    If the tag may be omitted.
1338 * @param[in]   style       The mapping style.
1339 *
1340 * @returns @c 1 if the function succeeded, @c 0 on error.
1341 */
1342
1343YAML_DECLARE(int)
1344yaml_emitter_emit_mapping_start(yaml_emitter_t *emitter,
1345        yaml_char_t *anchor, yaml_char_t *tag, int implicit,
1346        yaml_mapping_style_t style);
1347
1348/**
1349 * Emit a MAPPING-END event.
1350 *
1351 * @param[in]   emitter     An emitter object.
1352 *
1353 * @returns @c 1 if the function succeeded, @c 0 on error.
1354 */
1355
1356YAML_DECLARE(int)
1357yaml_emitter_emit_mapping_end(yaml_emitter_t *emitter);
1358
1359/**
1360 * Flush the accumulated characters to the output.
1361 *
1362 * @param[in]   emitter     An emitter object.
1363 *
1364 * @returns @c 1 if the function succeeded, @c 0 on error.
1365 */
1366
1367YAML_DECLARE(int)
1368yaml_emitter_flush(yaml_emitter_t *emitter);
1369
1370/** @} */
1371
[162]1372#ifdef __cplusplus
1373}
1374#endif
1375
[169]1376#endif /* #ifndef YAML_H */
[162]1377
Note: See TracBrowser for help on using the repository browser.