Ignore:
Timestamp:
07/23/06 07:57:36 (8 years ago)
Author:
xi
Message:

Add Emitter definitions and implement the Writer.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • libyaml/trunk/include/yaml.h

    r208 r211  
    101101    YAML_UTF16BE_ENCODING 
    102102} yaml_encoding_t; 
     103 
     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; 
    103112 
    104113/** Many bad things could happen with the parser and emitter. */ 
     
    436445 * @returns On success, the handler should return @c 1.  If the handler failed, 
    437446 * the returned value should be @c 0.  On EOF, the handler should set the 
    438  * @a length to @c 0 and return @c 1. 
     447 * @a size_read to @c 0 and return @c 1. 
    439448 */ 
    440449 
     
    555564    /** The working buffer. */ 
    556565    struct { 
    557         /* The beginning of the buffer. */ 
     566        /** The beginning of the buffer. */ 
    558567        yaml_char_t *start; 
    559         /* The end of the buffer. */ 
     568        /** The end of the buffer. */ 
    560569        yaml_char_t *end; 
    561         /* The current position of the buffer. */ 
     570        /** The current position of the buffer. */ 
    562571        yaml_char_t *pointer; 
    563         /* The last filled position of the buffer. */ 
     572        /** The last filled position of the buffer. */ 
    564573        yaml_char_t *last; 
    565574    } buffer; 
     
    707716 * @param[in]   parser  An empty parser object. 
    708717 * 
    709  * @returns #c 1 if the function succeeded, @c 0 on error. 
     718 * @returns @c 1 if the function succeeded, @c 0 on error. 
    710719 */ 
    711720 
     
    737746yaml_parser_set_input_string(yaml_parser_t *parser, 
    738747        unsigned char *input, size_t size); 
    739  
    740748 
    741749/** 
     
    822830/** @} */ 
    823831 
    824 /* 
     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 
    825883typedef struct { 
     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 
    8261049} yaml_emitter_t; 
    8271050 
     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 
     1062YAML_DECLARE(int) 
     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 
    8281192YAML_DECLARE(int) 
    8291193yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event); 
     1194 
     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 */ 
    8301203 
    8311204YAML_DECLARE(int) 
     
    8331206        yaml_encoding_t encoding); 
    8341207 
    835 */ 
     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 */ 
     1215 
     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/** @} */ 
    8361371 
    8371372#ifdef __cplusplus 
Note: See TracChangeset for help on using the changeset viewer.