From 028f3e8709fdd7574f34aa19dd600777a7d86289 Mon Sep 17 00:00:00 2001 From: Kirill Simonov Date: Tue, 1 Aug 2006 11:28:16 +0000 Subject: [PATCH] Prepare the initial release. --- Makefile.am | 2 +- README | 19 +++-- announcement.msg | 23 ++++++ include/yaml.h | 147 +++++++++++++++++----------------- tests/example-deconstructor.c | 20 ++--- tests/example-reformatter.c | 20 ++--- 6 files changed, 132 insertions(+), 99 deletions(-) create mode 100644 announcement.msg diff --git a/Makefile.am b/Makefile.am index d1c309f..1cf4114 100644 --- a/Makefile.am +++ b/Makefile.am @@ -3,7 +3,7 @@ SUBDIRS = include src . tests -EXTRA_DIST = doc/doxygen.cfg +EXTRA_DIST = README LICENSE doc/doxygen.cfg maintainer-clean-local: -rm -f aclocal.m4 config.h.in configure config/* diff --git a/README b/README index fdda610..a762f97 100644 --- a/README +++ b/README @@ -1,22 +1,29 @@ -libyaml - A C library for parsing and emitting YAML. +LibYAML - A C library for parsing and emitting YAML. -The project is in an early stage of development and not usable for end users. +The project is in an early stage of development. To build and install the library, run: +$ ./configure +$ make +# make install + +If you checked the source code from the Subversion repository, run $ ./bootstrap $ ./configure $ make -$ make check # make install -For more information, check the libyaml homepage: +For more information, check the LibYAML homepage: 'http://pyyaml.org/wiki/LibYAML'. Post your questions and opinions to the YAML-Core mailing list: 'http://lists.sourceforge.net/lists/listinfo/yaml-core'. -Submit bug reports and feature requests to the libyaml bug tracker: +Submit bug reports and feature requests to the LibYAML bug tracker: 'http://pyyaml.org/newticket?component=libyaml'. -libyaml is written by Kirill Simonov . It is released +LibYAML is written by Kirill Simonov . It is released under the MIT license. See the file LICENSE for more details. + +This project is developed for Python Software Foundation as a part of +Google Summer of Code under the mentorship of Clark Evans. diff --git a/announcement.msg b/announcement.msg new file mode 100644 index 0000000..a2dae20 --- /dev/null +++ b/announcement.msg @@ -0,0 +1,23 @@ +From: Kirill Simonov +To: yaml-core@lists.sourceforge.net +Subject: LibYAML-0.0.1: The initial release + +I'd like to present the initial release of LibYAML, a YAML parser and emitter +written in C. + +LibYAML homepage: http://pyyaml.org/wiki/LibYAML +TAR.GZ package: http://pyyaml.org/download/libyaml/yaml-0.0.1.tar.gz +SVN repository: http://svn.pyyaml.org/libyaml +Bug tracker: http://pyyaml.org/newticket?component=libyaml + +The library is functionally complete, but the documentation is scarce and the +API is subject to change. For more information, you may check the project +homepage, the doxygen-generated documentation in the `doc` directory of the +source distribution, and the examples `tests/example-reformatter.c` and +`tests/example-deconstructor.c`. + +LibYAML is written by Kirill Simonov . It is released +under the MIT license. See the file LICENSE for more details. + +This project is developed for Python Software Foundation as a part of +Google Summer of Code under the mentorship of Clark Evans. diff --git a/include/yaml.h b/include/yaml.h index 47de95d..8aec0be 100644 --- a/include/yaml.h +++ b/include/yaml.h @@ -4,7 +4,7 @@ * * Include the header file with the code: * @code - * #include + * #include * @endcode */ @@ -285,7 +285,7 @@ typedef struct { /** * Free any memory allocated for a token object. * - * @param[in] token A token object. + * @param[in,out] token A token object. */ YAML_DECLARE(void) @@ -416,7 +416,7 @@ typedef struct { /** * Create the STREAM-START event. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] encoding The stream encoding. * * @returns @c 1 if the function succeeded, @c 0 on error. @@ -429,7 +429,7 @@ yaml_stream_start_event_initialize(yaml_event_t *event, /** * Create the STREAM-END event. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -443,7 +443,7 @@ yaml_stream_end_event_initialize(yaml_event_t *event); * The @a implicit argument is considered as a stylistic parameter and may be * ignored by the emitter. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] version_directive The %YAML directive value or @c NULL. * @param[in] tag_directives_start The beginning of the %TAG directives list. * @param[in] tag_directives_end The end of the %TAG directives list. @@ -465,7 +465,7 @@ yaml_document_start_event_initialize(yaml_event_t *event, * The @a implicit argument is considered as a stylistic parameter and may be * ignored by the emitter. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] implicit If the document end indicator is implicit. * * @returns @c 1 if the function succeeded, @c 0 on error. @@ -477,7 +477,7 @@ yaml_document_end_event_initialize(yaml_event_t *event, int implicit); /** * Create an ALIAS event. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] anchor The anchor value. * * @returns @c 1 if the function succeeded, @c 0 on error. @@ -494,7 +494,7 @@ yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor); * Either the @a tag attribute or one of the @a plain_implicit and * @a quoted_implicit flags must be set. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] anchor The scalar anchor or @c NULL. * @param[in] tag The scalar tag or @c NULL. * @param[in] value The scalar value. @@ -520,7 +520,7 @@ yaml_scalar_event_initialize(yaml_event_t *event, * * Either the @a tag attribute or the @a implicit flag must be set. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] anchor The sequence anchor or @c NULL. * @param[in] tag The sequence tag or @c NULL. * @param[in] implicit If the tag may be omitted. @@ -537,7 +537,7 @@ yaml_sequence_start_event_initialize(yaml_event_t *event, /** * Create a SEQUENCE-END event. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -552,7 +552,7 @@ yaml_sequence_end_event_initialize(yaml_event_t *event); * * Either the @a tag attribute or the @a implicit flag must be set. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * @param[in] anchor The mapping anchor or @c NULL. * @param[in] tag The mapping tag or @c NULL. * @param[in] implicit If the tag may be omitted. @@ -569,7 +569,7 @@ yaml_mapping_start_event_initialize(yaml_event_t *event, /** * Create a MAPPING-END event. * - * @param[in] event An empty event object. + * @param[out] event An empty event object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -580,7 +580,7 @@ yaml_mapping_end_event_initialize(yaml_event_t *event); /** * Free any memory allocated for an event object. * - * @param[in] event An event object. + * @param[out] event An event object. */ YAML_DECLARE(void) @@ -600,11 +600,11 @@ yaml_event_delete(yaml_event_t *event); * source. The handler should write not more than @a size bytes to the @a * buffer. The number of written bytes should be set to the @a length variable. * - * @param[in] data A pointer to an application data specified by - * @c yaml_parser_set_read_handler. - * @param[out] buffer The buffer to write the data from the source. - * @param[in] size The size of the buffer. - * @param[out] size_read The actual number of bytes read from the source. + * @param[in,out] data A pointer to an application data specified by + * yaml_parser_set_input(). + * @param[out] buffer The buffer to write the data from the source. + * @param[in] size The size of the buffer. + * @param[out] size_read The actual number of bytes read from the source. * * @returns On success, the handler should return @c 1. If the handler failed, * the returned value should be @c 0. On EOF, the handler should set the @@ -875,9 +875,9 @@ typedef struct { * Initialize a parser. * * This function creates a new parser object. An application is responsible - * for destroying the object using the @c yaml_parser_delete function. + * for destroying the object using the yaml_parser_delete() function. * - * @param[in] parser An empty parser object. + * @param[out] parser An empty parser object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -888,7 +888,7 @@ yaml_parser_initialize(yaml_parser_t *parser); /** * Destroy a parser. * - * @param[in] parser A parser object. + * @param[in,out] parser A parser object. */ YAML_DECLARE(void) @@ -901,9 +901,9 @@ yaml_parser_delete(yaml_parser_t *parser); * exists. The application is responsible for destroing @a input after * destroying the @a parser. * - * @param[in] parser A parser object. - * @param[in] input A source data. - * @param[in] size The length of the source data in bytes. + * @param[in,out] parser A parser object. + * @param[in] input A source data. + * @param[in] size The length of the source data in bytes. */ YAML_DECLARE(void) @@ -916,8 +916,8 @@ yaml_parser_set_input_string(yaml_parser_t *parser, * @a file should be a file object open for reading. The application is * responsible for closing the @a file. * - * @param[in] parser A parser object. - * @param[in] file An open file. + * @param[in,out] parser A parser object. + * @param[in] file An open file. */ YAML_DECLARE(void) @@ -926,9 +926,10 @@ yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file); /** * Set a generic input handler. * - * @param[in] parser A parser object. - * @param[in] handler A read handler. - * @param[in] data Any application data for passing to the read handler. + * @param[in,out] parser A parser object. + * @param[in] handler A read handler. + * @param[in] data Any application data for passing to the read + * handler. */ YAML_DECLARE(void) @@ -938,8 +939,8 @@ yaml_parser_set_input(yaml_parser_t *parser, /** * Set the source encoding. * - * @param[in] parser A parser object. - * @param[in] encoding The source encoding. + * @param[in,out] parser A parser object. + * @param[in] encoding The source encoding. */ YAML_DECLARE(void) @@ -956,11 +957,11 @@ yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); * An application is responsible for freeing any buffers associated with the * produced token object using the @c yaml_token_delete function. * - * An application must not alternate the calls of @c yaml_parser_scan with the - * calls of @c yaml_parser_parse. Doing this will break the parser. + * An application must not alternate the calls of yaml_parser_scan() with the + * calls of yaml_parser_parse(). Doing this will break the parser. * - * @param[in] parser A parser object. - * @param[in] token An empty token object. + * @param[in,out] parser A parser object. + * @param[out] token An empty token object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -977,13 +978,13 @@ yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token); * @c YAML_STREAM_END_EVENT. * * An application is responsible for freeing any buffers associated with the - * produced event object using the @c yaml_event_delete function. + * produced event object using the yaml_event_delete() function. * - * An application must not alternate the calls of @c yaml_parser_scan with the - * calls of @c yaml_parser_parse. Doing this will break the parser. + * An application must not alternate the calls of yaml_parser_scan() with the + * calls of yaml_parser_parse(). Doing this will break the parser. * - * @param[in] parser A parser object. - * @param[in] event An empty event object. + * @param[in,out] parser A parser object. + * @param[out] event An empty event object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -1005,10 +1006,10 @@ yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event); * characters to the output. The handler should write @a size bytes of the * @a buffer to the output. * - * @param[in] data A pointer to an application data specified by - * @c yaml_emitter_set_write_handler. - * @param[out] buffer The buffer with bytes to be written. - * @param[in] size The size of the buffer. + * @param[in,out] data A pointer to an application data specified by + * yaml_emitter_set_output(). + * @param[in] buffer The buffer with bytes to be written. + * @param[in] size The size of the buffer. * * @returns On success, the handler should return @c 1. If the handler failed, * the returned value should be @c 0. @@ -1256,9 +1257,9 @@ typedef struct { * Initialize an emitter. * * This function creates a new emitter object. An application is responsible - * for destroying the object using the @c yaml_emitter_delete function. + * for destroying the object using the yaml_emitter_delete() function. * - * @param[in] emitter An empty parser object. + * @param[out] emitter An empty parser object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -1269,7 +1270,7 @@ yaml_emitter_initialize(yaml_emitter_t *emitter); /** * Destroy an emitter. * - * @param[in] emitter An emitter object. + * @param[in,out] emitter An emitter object. */ YAML_DECLARE(void) @@ -1283,10 +1284,11 @@ yaml_emitter_delete(yaml_emitter_t *emitter); * bytes. If the buffer is smaller than required, the emitter produces the * YAML_WRITE_ERROR error. * - * @param[in] emitter An emitter object. - * @param[in] output An output buffer. - * @param[in] size The buffer size. - * @param[in] size_written The pointer to save the number of written bytes. + * @param[in,out] emitter An emitter object. + * @param[in] output An output buffer. + * @param[in] size The buffer size. + * @param[in] size_written The pointer to save the number of written + * bytes. */ YAML_DECLARE(void) @@ -1299,8 +1301,8 @@ yaml_emitter_set_output_string(yaml_emitter_t *emitter, * @a file should be a file object open for writing. The application is * responsible for closing the @a file. * - * @param[in] emitter An emitter object. - * @param[in] file An open file. + * @param[in,out] emitter An emitter object. + * @param[in] file An open file. */ YAML_DECLARE(void) @@ -1309,9 +1311,10 @@ yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file); /** * Set a generic output handler. * - * @param[in] emitter An emitter object. - * @param[in] handler A write handler. - * @param[in] data Any application data for passing to the write handler. + * @param[in,out] emitter An emitter object. + * @param[in] handler A write handler. + * @param[in] data Any application data for passing to the write + * handler. */ YAML_DECLARE(void) @@ -1321,8 +1324,8 @@ yaml_emitter_set_output(yaml_emitter_t *emitter, /** * Set the output encoding. * - * @param[in] emitter An emitter object. - * @param[in] encoding The output encoding. + * @param[in,out] emitter An emitter object. + * @param[in] encoding The output encoding. */ YAML_DECLARE(void) @@ -1332,8 +1335,8 @@ yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding); * Set if the output should be in the "canonical" format as in the YAML * specification. * - * @param[in] emitter An emitter object. - * @param[in] canonical If the output is canonical. + * @param[in,out] emitter An emitter object. + * @param[in] canonical If the output is canonical. */ YAML_DECLARE(void) @@ -1342,8 +1345,8 @@ yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical); /** * Set the intendation increment. * - * @param[in] emitter An emitter object. - * @param[in] indent The indentation increment (1 < . < 10). + * @param[in,out] emitter An emitter object. + * @param[in] indent The indentation increment (1 < . < 10). */ YAML_DECLARE(void) @@ -1352,8 +1355,8 @@ yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent); /** * Set the preferred line width. @c -1 means unlimited. * - * @param[in] emitter An emitter object. - * @param[in] width The preferred line width. + * @param[in,out] emitter An emitter object. + * @param[in] width The preferred line width. */ YAML_DECLARE(void) @@ -1362,8 +1365,8 @@ yaml_emitter_set_width(yaml_emitter_t *emitter, int width); /** * Set if unescaped non-ASCII characters are allowed. * - * @param[in] emitter An emitter object. - * @param[in] unicode If unescaped Unicode characters are allowed. + * @param[in,out] emitter An emitter object. + * @param[in] unicode If unescaped Unicode characters are allowed. */ YAML_DECLARE(void) @@ -1372,8 +1375,8 @@ yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode); /** * Set the preferred line break. * - * @param[in] emitter An emitter object. - * @param[in] line_break The preferred line break. + * @param[in,out] emitter An emitter object. + * @param[in] line_break The preferred line break. */ YAML_DECLARE(void) @@ -1382,13 +1385,13 @@ yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break); /** * Emit an event. * - * The event object may be generated using the @c yaml_parser_parse function. + * The event object may be generated using the yaml_parser_parse() function. * The emitter takes the responsibility for the event object and destroys its * content after it is emitted. The event object is destroyed even if the * function fails. * - * @param[in] emitter An emitter object. - * @param[in] event An event object. + * @param[in,out] emitter An emitter object. + * @param[in,out] event An event object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ @@ -1399,7 +1402,7 @@ yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event); /** * Flush the accumulated characters to the output. * - * @param[in] emitter An emitter object. + * @param[in,out] emitter An emitter object. * * @returns @c 1 if the function succeeded, @c 0 on error. */ diff --git a/tests/example-deconstructor.c b/tests/example-deconstructor.c index d41b5ae..57e6693 100644 --- a/tests/example-deconstructor.c +++ b/tests/example-deconstructor.c @@ -1046,14 +1046,14 @@ parser_error: if (parser.context) { fprintf(stderr, "Scanner error: %s at line %d, column %d\n" "%s at line %d, column %d\n", parser.context, - parser.context_mark.line, parser.context_mark.column, - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.context_mark.line+1, parser.context_mark.column+1, + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } else { fprintf(stderr, "Scanner error: %s at line %d, column %d\n", - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } break; @@ -1061,14 +1061,14 @@ parser_error: if (parser.context) { fprintf(stderr, "Parser error: %s at line %d, column %d\n" "%s at line %d, column %d\n", parser.context, - parser.context_mark.line, parser.context_mark.column, - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.context_mark.line+1, parser.context_mark.column+1, + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } else { fprintf(stderr, "Parser error: %s at line %d, column %d\n", - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } break; diff --git a/tests/example-reformatter.c b/tests/example-reformatter.c index a999fbe..946d556 100644 --- a/tests/example-reformatter.c +++ b/tests/example-reformatter.c @@ -133,14 +133,14 @@ parser_error: if (parser.context) { fprintf(stderr, "Scanner error: %s at line %d, column %d\n" "%s at line %d, column %d\n", parser.context, - parser.context_mark.line, parser.context_mark.column, - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.context_mark.line+1, parser.context_mark.column+1, + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } else { fprintf(stderr, "Scanner error: %s at line %d, column %d\n", - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } break; @@ -148,14 +148,14 @@ parser_error: if (parser.context) { fprintf(stderr, "Parser error: %s at line %d, column %d\n" "%s at line %d, column %d\n", parser.context, - parser.context_mark.line, parser.context_mark.column, - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.context_mark.line+1, parser.context_mark.column+1, + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } else { fprintf(stderr, "Parser error: %s at line %d, column %d\n", - parser.problem, parser.problem_mark.line, - parser.problem_mark.column); + parser.problem, parser.problem_mark.line+1, + parser.problem_mark.column+1); } break; -- 2.45.2