From: Kirill Simonov Date: Fri, 26 May 2006 21:46:47 +0000 (+0000) Subject: Doxygenify the header file. X-Git-Tag: upstream/0.1.1~43 X-Git-Url: http://andersk.mit.edu/gitweb/libyaml.git/commitdiff_plain/a51447c932b63bcf7cc0226dafd621c6cd8a347a Doxygenify the header file. Add basic reader fields to the parser structure. Start implementing basic parser functions. --- diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index c3f6d85..f7a9aef 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -10,7 +10,7 @@ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English USE_WINDOWS_ENCODING = NO BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = NO +REPEAT_BRIEF = YES ABBREVIATE_BRIEF = ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO @@ -18,7 +18,7 @@ FULL_PATH_NAMES = YES STRIP_FROM_PATH = STRIP_FROM_INC_PATH = SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES MULTILINE_CPP_IS_BRIEF = NO DETAILS_AT_TOP = NO INHERIT_DOCS = YES @@ -46,7 +46,7 @@ CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = YES INLINE_INFO = YES -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO SORT_BRIEF_DOCS = NO SORT_BY_SCOPE_NAME = NO GENERATE_TODOLIST = YES @@ -117,7 +117,7 @@ GENERATE_CHI = NO BINARY_TOC = NO TOC_EXPAND = NO DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 +ENUM_VALUES_PER_LINE = 1 GENERATE_TREEVIEW = NO TREEVIEW_WIDTH = 250 #--------------------------------------------------------------------------- diff --git a/include/Makefile.am b/include/Makefile.am index 5db6705..5c5f7dd 100644 --- a/include/Makefile.am +++ b/include/Makefile.am @@ -1,4 +1,4 @@ -INCLUDES = yaml/yaml.h yaml/yaml_version.h yaml/yaml_error.h +INCLUDES = yaml/yaml.h #yaml/yaml_version.h yaml/yaml_error.h DOXYGEN_CFG = $(top_srcdir)/doc/doxygen.cfg nobase_include_HEADERS = $(INCLUDES) diff --git a/include/yaml/yaml.h b/include/yaml/yaml.h index 64412c7..40cd9af 100644 --- a/include/yaml/yaml.h +++ b/include/yaml/yaml.h @@ -2,7 +2,7 @@ * @file yaml.h * @brief Public interface for libyaml. * - * Include the header file with + * Include the header file with the code: * @code * #include * @endcode @@ -17,16 +17,68 @@ extern "C" { #include -#include "yaml_version.h" -#include "yaml_error.h" +/** + * @defgroup version Version Information + * @{ + */ + +/** + * Get the library version as a string. + * + * @returns The function returns the pointer to a static string of the form + * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version + * number, and @c Z is the patch version number. + */ + +const char * +yaml_get_version_string(void); + +/** + * Get the library version numbers. + * + * @param[out] major Major version number. + * @param[out] minor Minor version number. + * @param[out] patch Patch version number. + */ + +void +yaml_get_version(int *major, int *minor, int *patch); + +/** @} */ + +/** + * @defgroup basic Basic Types + * @{ + */ + +/** The character type. */ +typedef unsigned char yaml_char_t; +/** The stream encoding. */ typedef enum { - YAML_DETECT_ENCODING, + YAML_ANY_ENCODING, YAML_UTF8_ENCODING, YAML_UTF16LE_ENCODING, YAML_UTF16BE_ENCODING } yaml_encoding_t; +/** @} */ + +/* + +typedef enum { + YAML_NO_ERROR, + + YAML_MEMORY_ERROR, + + YAML_READER_ERROR, + YAML_SCANNER_ERROR, + YAML_PARSER_ERROR, + + YAML_WRITER_ERROR, + YAML_EMITTER_ERROR +} yaml_error_type_t; + typedef enum { YAML_ANY_SCALAR_STYLE, YAML_PLAIN_SCALAR_STYLE, @@ -182,10 +234,103 @@ typedef struct { yaml_mark_t end_mark; } yaml_event_t; -/* +*/ + + +/** + * @defgroup parser Parser Definitions + * @{ + */ + +/** + * The prototype of a read handler. + * + * The read handler is called when the parser needs to read more bytes from the + * 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] ext 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] length 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 + * @a length to @c 0 and return @c 1. + */ +typedef int yaml_read_handler_t(void *ext, yaml_char_t *buffer, size_t size, + size_t *length); + + +/** + * The parser structure. + * + * All members are internal. Manage the structure using the @c yaml_parser_ + * family of functions. + */ + typedef struct { + + /** + * @name Reader stuff + * @{ + */ + + /** Read handler */ + yaml_read_handler_t *reader; + + /** A pointer for passing to the read handler. */ + void *reader_ext; + + /** EOF flag */ + int eof; + + /** The pointer to the beginning of the working buffer. */ + yaml_char_t *buffer; + + /** The pointer to the current character in the working buffer. */ + yaml_char_t *pointer; + + /** The remaining undecoded characters. */ + unsigned char *raw_buffer; + + /** The size of the raw buffer. */ + size_t raw_buffer_size; + + /** The input encoding. */ + yaml_encoding_t encoding; + + /** + * @} + */ + } yaml_parser_t; +/** + * Create a new parser. + * + * This function creates a new parser object. An application is responsible + * for destroying the object using the @c yaml_parser_delete function. + * + * @returns A new parser object; @c NULL on error. + */ + +yaml_parser_t * +yaml_parser_new(void); + +/** + * Destroy a parser. + * + * @param[in] parser A parser object. + */ + +void +yaml_parser_delete(yaml_parser_t *parser); + +/** @} */ + +/* typedef struct { } yaml_emitter_t; */ diff --git a/include/yaml/yaml_version.h b/include/yaml/yaml_version.h index 2ff74a5..9718db2 100644 --- a/include/yaml/yaml_version.h +++ b/include/yaml/yaml_version.h @@ -1,4 +1,4 @@ -/** +/* * @file yaml_version.h * @brief Version information. * @@ -12,14 +12,14 @@ extern "C" { #endif -/** +/* * @brief Get the library version. */ const char * yaml_get_version_string(void); -/** +/* * @brief Get the library version numbers. */ diff --git a/src/Makefile.am b/src/Makefile.am index 963962e..fac4a55 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -1,4 +1,4 @@ AM_CPPFLAGS = -I$(top_srcdir)/include lib_LTLIBRARIES = libyaml.la -libyaml_la_SOURCES = version.c +libyaml_la_SOURCES = version.c api.c libyaml_la_LDFLAGS = -release $(YAML_LT_RELEASE) -version-info $(YAML_LT_CURRENT):$(YAML_LT_REVISION):$(YAML_LT_AGE) diff --git a/src/api.c b/src/api.c new file mode 100644 index 0000000..cffa8e9 --- /dev/null +++ b/src/api.c @@ -0,0 +1,34 @@ + +#if HAVE_CONFIG_H +#include +#endif + +#include + +/* + * Create a new parser. + */ + +yaml_parser_t * +yaml_parser_new(void) +{ + yaml_parser_t *parser; + + parser = malloc(sizeof(yaml_parser_t)); + if (!parser) return NULL; + + memset(parser, 0, sizeof(yaml_parser_t)); + + return parser; +} + +/* + * Destroy a parser object. + */ + +void +yaml_parser_delete(yaml_parser_t *parser) +{ + free(parser); +} +