Changeset 267

Show
Ignore:
Timestamp:
01/19/08 08:54:22 (8 months ago)
Author:
xi
Message:

Minor API updates.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • libyaml/trunk/include/yaml.h

    r266 r267  
    88 *****************************************************************************/ 
    99 
    10 /* 
     10/***************************************************************************** 
    1111 * General guidelines. 
    12  * 
    13  * Naming conventions: all functions exported by LibYAML starts with the `yaml_` prefix; 
    14  * types starts with `yaml_` and ends with `_t`; macros and enumerations starts 
    15  * with `YAML_`. 
     12 *****************************************************************************/ 
     13 
     14/* 
     15 * Basic conventions. 
     16 * 
     17 * All functions exported by exported by LibYAML starts with the the prefix 
     18 * `yaml_`; types starts with `yaml_` and ends with `_t`; macros and 
     19 * enumeration values start with `YAML_`. 
     20 * 
     21 * A function may serve as method for an object or a particular type; such 
     22 * functions start with `yaml_<type>`.  A type constructor is named 
     23 * `yaml_<type>_new()`, a type destructor is named `yaml_<type>_delete()`. 
     24 * 
     25 * A function signifies whether it succeeded or failed with its return value; 
     26 * typically it is `1` for success, `0` for failure.  Functions that return a 
     27 * pointer may indicate an error condition by returning `NULL`.  Functions that 
     28 * never fail commonly do not return any value.  For most of the functions, an 
     29 * error value means that the function is unable to allocate some memory 
     30 * buffer.  For parsing and emitting functions, detailed information on the 
     31 * nature of the error could be obtained. 
     32 * 
     33 * LibYAML provides two active objects: parsers and emitters and three passive 
     34 * objects: tokens, events and documents. 
     35 * 
     36 *  
     37 * 
    1638 * 
    1739 * FIXME: Calling conventions. 
    …… 
    1941 * FIXME: Errors and exceptions. 
    2042 * FIXME: And so on, and so forth. 
     43 * 
     44 * 
     45 * 
     46 * 
    2147 */ 
    2248 
    …… 
    270296yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity); 
    271297 
    272 /****************************************************************************** 
     298/***************************************************************************** 
    273299 * Basic Types 
    274  ******************************************************************************/ 
     300 *****************************************************************************/ 
    275301 
    276302/* 
    …… 
    348374} yaml_break_t; 
    349375 
    350 /****************************************************************************** 
     376/***************************************************************************** 
    351377 * Node Styles 
    352  ******************************************************************************/ 
     378 *****************************************************************************/ 
    353379 
    354380/* 
    …… 
    403429 
    404430    /* The flow sequence style. */ 
    405     YAML_FLOW_SEQUENCE_STYLE 
     431    YAML_FLOW_SEQUENCE_STYLE, 
    406432    /* The block sequence style. */ 
    407     YAML_BLOCK_SEQUENCE_STYLE, 
     433    YAML_BLOCK_SEQUENCE_STYLE 
    408434} yaml_sequence_style_t; 
    409435 
    …… 
    431457} yaml_mapping_style_t; 
    432458 
    433 /****************************************************************************** 
     459/***************************************************************************** 
    434460 * Tokens 
    435  ******************************************************************************/ 
     461 *****************************************************************************/ 
    436462 
    437463/* 
    …… 
    681707yaml_token_clear(yaml_token_t *token); 
    682708 
    683 /****************************************************************************** 
     709/***************************************************************************** 
    684710 * Events 
    685  ******************************************************************************/ 
     711 *****************************************************************************/ 
    686712 
    687713/* 
    …… 
    12211247yaml_event_create_mapping_end(yaml_event_t *event); 
    12221248 
    1223 /****************************************************************************** 
     1249/***************************************************************************** 
    12241250 * Documents and Nodes 
    1225  ******************************************************************************/ 
     1251 *****************************************************************************/ 
    12261252 
    12271253/* 
    …… 
    12611287typedef enum yaml_document_type_e { 
    12621288    /* An empty uninitialized document. */ 
    1263     YAML_NO_DOCUMENT. 
     1289    YAML_NO_DOCUMENT, 
    12641290 
    12651291    /* A YAML document. */ 
    …… 
    13831409 */ 
    13841410 
    1385 struct yaml_node_s { 
     1411typedef struct yaml_node_s { 
    13861412 
    13871413    /* The node type. */ 
    …… 
    14431469    yaml_mark_t end_mark; 
    14441470 
    1445 }; 
     1471} yaml_node_t; 
    14461472 
    14471473/* 
    …… 
    18191845 
    18201846/* 
    1821  * Get the value of a `!!null` SCALAR node. 
    1822  * 
    1823  * Use this function to ensure that the given node is a scalar, the node tag is 
    1824  * equal to `tag:yaml.org,2002:null` and the node value is a valid null value. 
    1825  * Given that the `!!null` tag admits only one valid value, the value is not 
    1826  * returned. 
    1827  * 
    1828  * Arguments: 
    1829  * 
    1830  * - `document`: a document object. 
    1831  * 
    1832  * - `node_id`: the node id; could be negative. 
    1833  * 
    1834  * Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise. 
    1835  */ 
    1836  
    1837 YAML_DECLARE(int) 
    1838 yaml_document_get_null_node(yaml_document_t *document, int node_id); 
    1839  
    1840 /* 
    1841  * Get the value of a `!!bool` SCALAR node. 
    1842  * 
    1843  * Use this function to ensure that the given node is a scalar, the node tag is 
    1844  * `tag:yaml.org,2002:bool` and the node value is a valid boolean value.  The 
    1845  * function returns the true value as `1` and the false value as `0`. 
    1846  * 
    1847  * Arguments: 
    1848  * 
    1849  * - `document`: a document object. 
    1850  * 
    1851  * - `node_id`: the node id; could be negative. 
    1852  * 
    1853  * - `value`: a pointer to save the node value or `NULL`. 
    1854  * 
    1855  * Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise.  If the 
    1856  * function succeeds and `value` is not `NULL`, the node value is saved to 
    1857  * `value`. 
    1858  */ 
    1859  
    1860 YAML_DECLARE(int) 
    1861 yaml_document_get_bool_node(yaml_document_t *document, int node_id, 
    1862         int *value); 
    1863  
    1864 /* 
    1865  * Get the value of a `!!str` SCALAR node. 
    1866  * 
    1867  * Use this function to ensure that the given node is a scalar, the node tag is 
    1868  * `tag:yaml.org,2002:str` and the node value is a string that does not contain 
    1869  * the NUL character.  In this case, the function returns the node value.  The 
    1870  * produced value is valid until the document object is cleared or deleted. 
    1871  * 
    1872  * Arguments: 
    1873  * 
    1874  * - `document`: a document object. 
    1875  * 
    1876  * - `node_id`: the node id; could be negative. 
    1877  * 
    1878  * - `value`: a pointer to save the node value or `NULL`. 
    1879  * 
    1880  * Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise.  If the 
    1881  * function succeeds and `value` is not `NULL`, the node value is saved to 
    1882  * `value`. 
    1883  */ 
    1884  
    1885 YAML_DECLARE(int) 
    1886 yaml_document_get_str_node(yaml_document_t *document, int node_id, 
    1887         char **value); 
    1888  
    1889 /* 
    1890  * Get the value of an `!!int` SCALAR node. 
    1891  * 
    1892  * Use this function to ensure that the given node is a scalar, the node tag is 
    1893  * `tag:yaml.org,2002:int` and the node value is a valid integer.  In this 
    1894  * case, the function parses the node value and returns an integer number.  The 
    1895  * function recognizes decimal, hexdecimal and octal numbers including negative 
    1896  * numbers. 
    1897  * 
    1898  * Arguments: 
    1899  * 
    1900  * - `document`: a document object. 
    1901  * 
    1902  * - `node_id`: the node id; could be negative. 
    1903  * 
    1904  * - `value`: a pointer to save the node value or `NULL`. 
    1905  * 
    1906  * Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise.  If the 
    1907  * function succeeds and `value` is not `NULL`, the node value is saved to 
    1908  * `value`. 
    1909  */ 
    1910  
    1911 YAML_DECLARE(int) 
    1912 yaml_document_get_int_node(yaml_document_t *document, int node_id, 
    1913         int *value); 
    1914  
    1915 /* 
    1916  * Get the value of a `!!float` SCALAR node. 
    1917  * 
    1918  * Use this function to ensure that the given node is a scalar, the node tag is 
    1919  * `tag:yaml.org,2002:float` and the node value is a valid float value.  In 
    1920  * this case, the function parses the node value and returns a float number. 
    1921  * The function recognizes float values in exponential and fixed notation as 
    1922  * well as special values `.nan`, `.inf` and `-.inf`. 
    1923  * 
    1924  * Arguments: 
    1925  * 
    1926  * - `document`: a document object. 
    1927  * 
    1928  * - `node_id`: the node id; could be negative. 
    1929  * 
    1930  * - `value`: a pointer to save the node value or `NULL`. 
    1931  * 
    1932  * Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise.  If the 
    1933  * function succeeds and `value` is not `NULL`, the node value is saved to 
    1934  * `value`. 
    1935  */ 
    1936  
    1937 YAML_DECLARE(int) 
    1938 yaml_document_get_float_node(yaml_document_t *document, int node_id, 
    1939         double *value); 
    1940  
    1941 /* 
    1942  * Get the value of a `!!seq` SEQUENCE node. 
    1943  * 
    1944  * Use this function to ensure that the given node is a sequence and the node 
    1945  * tag is `tag:yaml.org,2002:seq`.  In this case, the function returns the list 
    1946  * of nodes that belong to the sequence.  The produced list is valid until the 
    1947  * document object is modified. 
    1948  * 
    1949  * Arguments: 
    1950  * 
    1951  * - `document`: a document object. 
    1952  * 
    1953  * - `node_id`: the node id; could be negative. 
    1954  * 
    1955  * - `items`: a pointer to save the list of sequence items or `NULL`. 
    1956  * 
    1957  * - `length`: a pointer to save the length of the sequence or `NULL`. 
    1958  *   `length` must be equal to `NULL` if and only if `items` is also `NULL`. 
    1959  * 
    1960  * Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise.  If the 
    1961  * function succeeds and `items` is not `NULL`, the list of sequence items is 
    1962  * saved to `items` and the sequence length is saved to `length`. 
    1963  */ 
    1964  
    1965 YAML_DECLARE(int) 
    1966 yaml_document_get_seq_node(yaml_document_t *document, int node_id, 
    1967         yaml_node_item_t **items, size_t *length); 
    1968  
    1969 /* 
    1970  * Get the value of a `!!map` MAPPING node. 
    1971  * 
    1972  * Use this function to ensure that the given node is a mapping and the node 
    1973  * tag is `tag:yaml.org,2002:map`.  In this case, the function returns the list 
    1974  * of node pairs (key, value) that belong to the sequence.  The produced list 
    1975  * is valid until the document is modified. 
    1976  * 
    1977  * Arguments: 
    1978  * 
    1979  * - `document`: a document object. 
    1980  * 
    1981  * - `node_id`: the node id; could be negative. 
    1982  * 
    1983  * - `pairs`: a pointer to save the list of mapping pairs or `NULL`. 
    1984  * 
    1985  * - `length`: a pointer to save the length of the mapping or `NULL`. 
    1986  *   `length` must be equal to `NULL` if and only if `pairs` is also `NULL`. 
    1987  * 
    1988  * Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise.  If the 
    1989  * function succeeds and `pairs` is not `NULL`, the list of mapping pairs is 
    1990  * saved to `pairs` and the mapping length is saved to `length`. 
    1991  */ 
    1992  
    1993 YAML_DECLARE(int) 
    1994 yaml_document_get_map_node(yaml_document_t *document, int node_id, 
    1995         yaml_node_pair_t **pairs, size_t *length); 
    1996  
    1997 /* 
    1998  * Add a `!!null` SCALAR node to the document. 
    1999  * 
    2000  * This function is a shorthand for the call: 
    2001  * 
    2002  *      yaml_document_add_scalar(document, node_id, NULL, 
    2003  *              YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE) 
    2004  * 
    2005  * Arguments: 
    2006  * 
    2007  * - `document`: a document object. 
    2008  * 
    2009  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2010  * 
    2011  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2012  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2013  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2014  */ 
    2015  
    2016 YAML_DECLARE(int) 
    2017 yaml_document_add_null_node(yaml_document_t *document, int *node_id); 
    2018  
    2019 /* 
    2020  * Add a `!!bool` SCALAR node to the document. 
    2021  * 
    2022  * This function is a shorthand for the call: 
    2023  * 
    2024  *      yaml_document_add_scalar(document, node_id, NULL, 
    2025  *              YAML_BOOL_TAG, (value ? "true" : "false"), -1, 
    2026  *              YAML_ANY_SCALAR_STYLE) 
    2027  * 
    2028  * Arguments: 
    2029  * 
    2030  * - `document`: a document object. 
    2031  * 
    2032  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2033  * 
    2034  * - `value`: a boolean value; any non-zero value is true, `0` is false. 
    2035  * 
    2036  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2037  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2038  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2039  */ 
    2040  
    2041 YAML_DECLARE(int) 
    2042 yaml_document_add_bool_node(yaml_document_t *document, int *node_id, 
    2043         int value); 
    2044  
    2045 /* 
    2046  * Add a `!!str` SCALAR node to the document. 
    2047  * 
    2048  * This function is a shorthand for the call: 
    2049  * 
    2050  *      yaml_document_add_scalar(document, node_id, NULL, 
    2051  *              YAML_STR_TAG, (const yaml_char_t *) value, -1, 
    2052  *              YAML_ANY_SCALAR_STYLE) 
    2053  * 
    2054  * Arguments: 
    2055  * 
    2056  * - `document`: a document object. 
    2057  * 
    2058  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2059  * 
    2060  * - `value`: a NUL-terminated UTF-8 string.  The function does not check if 
    2061  *   `value` is a valid UTF-8 string, but if it is not so, the emitter will 
    2062  *   fail to emit the node. 
    2063  * 
    2064  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2065  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2066  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2067  */ 
    2068  
    2069 YAML_DECLARE(int) 
    2070 yaml_document_add_str_node(yaml_document_t *document, int *node_id, 
    2071         const char *value); 
    2072  
    2073 /* 
    2074  * Add an `!!int` SCALAR node to the document. 
    2075  * 
    2076  * This function is a shorthand for the call: 
    2077  * 
    2078  *      yaml_document_add_scalar(document, node_id, NULL, 
    2079  *              YAML_INT_TAG, <string representation of the value>, -1, 
    2080  *              YAML_ANY_SCALAR_STYLE) 
    2081  * 
    2082  * Arguments: 
    2083  * 
    2084  * - `document`: a document object. 
    2085  * 
    2086  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2087  * 
    2088  * - `value`: an integer value. 
    2089  * 
    2090  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2091  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2092  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2093  */ 
    2094  
    2095 YAML_DECLARE(int) 
    2096 yaml_document_add_int_node(yaml_document_t *document, int *node_id, 
    2097         int value); 
    2098  
    2099 /* 
    2100  * Add a `!!float` SCALAR node to the document. 
    2101  * 
    2102  * This function is a shorthand for the call: 
    2103  * 
    2104  *      yaml_document_add_scalar(document, node_id, NULL, 
    2105  *              YAML_FLOAT_TAG, <string representation of the value>, -1, 
    2106  *              YAML_ANY_SCALAR_STYLE) 
    2107  * 
    2108  * Arguments: 
    2109  * 
    2110  * - `document`: a document object. 
    2111  * 
    2112  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2113  * 
    2114  * - `value`: a float value. 
    2115  * 
    2116  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2117  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2118  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2119  */ 
    2120  
    2121 YAML_DECLARE(int) 
    2122 yaml_document_add_float_node(yaml_document_t *document, int *node_id, 
    2123         double value); 
    2124  
    2125 /* 
    2126  * Add a `!!seq` SEQUENCE node to the document. 
    2127  * 
    2128  * This function is a shorthand for the call: 
    2129  * 
    2130  *      yaml_document_add_sequence(document, node_id, NULL, 
    2131  *              YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE) 
    2132  * 
    2133  * Arguments: 
    2134  * 
    2135  * - `document`: a document object. 
    2136  * 
    2137  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2138  * 
    2139  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2140  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2141  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2142  */ 
    2143  
    2144 YAML_DECLARE(int) 
    2145 yaml_document_add_seq_node(yaml_document_t *document, int *node_id); 
    2146  
    2147 /* 
    2148  * Add a `!!map` MAPPING node to the document. 
    2149  * 
    2150  * This function is a shorthand for the call: 
    2151  * 
    2152  *      yaml_document_add_mapping(document, node_id, NULL, 
    2153  *              YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE) 
    2154  * 
    2155  * Arguments: 
    2156  * 
    2157  * - `document`: a document object. 
    2158  * 
    2159  * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
    2160  * 
    2161  * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
    2162  * allocate memory for new buffers.  If the function succeeds, the id of the 
    2163  * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
    2164  */ 
    2165  
    2166 YAML_DECLARE(int) 
    2167 yaml_document_add_map_node(yaml_document_t *document, int *node_id); 
    2168  
    2169 /* 
    21701847 * Add an item to a SEQUENCE node. 
    21711848 * 
    …… 
    22231900        int mapping_id, int key_id, int value_id); 
    22241901 
    2225 /****************************************************************************** 
     1902/* 
     1903 * Get the value of a `!!null` SCALAR node. 
     1904 * 
     1905 * Use this function to ensure that the given node is a scalar, the node tag is 
     1906 * equal to `tag:yaml.org,2002:null` and the node value is a valid null value. 
     1907 * Given that the `!!null` tag admits only one valid value, the value is not 
     1908 * returned. 
     1909 * 
     1910 * Arguments: 
     1911 * 
     1912 * - `document`: a document object. 
     1913 * 
     1914 * - `node_id`: the node id; could be negative. 
     1915 * 
     1916 * Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise. 
     1917 */ 
     1918 
     1919YAML_DECLARE(int) 
     1920yaml_document_get_null_node(yaml_document_t *document, int node_id); 
     1921 
     1922/* 
     1923 * Get the value of a `!!bool` SCALAR node. 
     1924 * 
     1925 * Use this function to ensure that the given node is a scalar, the node tag is 
     1926 * `tag:yaml.org,2002:bool` and the node value is a valid boolean value.  The 
     1927 * function returns the true value as `1` and the false value as `0`. 
     1928 * 
     1929 * Arguments: 
     1930 * 
     1931 * - `document`: a document object. 
     1932 * 
     1933 * - `node_id`: the node id; could be negative. 
     1934 * 
     1935 * - `value`: a pointer to save the node value or `NULL`. 
     1936 * 
     1937 * Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise.  If the 
     1938 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1939 * `value`. 
     1940 */ 
     1941 
     1942YAML_DECLARE(int) 
     1943yaml_document_get_bool_node(yaml_document_t *document, int node_id, 
     1944        int *value); 
     1945 
     1946/* 
     1947 * Get the value of a `!!str` SCALAR node. 
     1948 * 
     1949 * Use this function to ensure that the given node is a scalar, the node tag is 
     1950 * `tag:yaml.org,2002:str` and the node value is a string that does not contain 
     1951 * the NUL character.  In this case, the function returns the node value.  The 
     1952 * produced value is valid until the document object is cleared or deleted. 
     1953 * 
     1954 * Arguments: 
     1955 * 
     1956 * - `document`: a document object. 
     1957 * 
     1958 * - `node_id`: the node id; could be negative. 
     1959 * 
     1960 * - `value`: a pointer to save the node value or `NULL`. 
     1961 * 
     1962 * Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise.  If the 
     1963 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1964 * `value`. 
     1965 */ 
     1966 
     1967YAML_DECLARE(int) 
     1968yaml_document_get_str_node(yaml_document_t *document, int node_id, 
     1969        char **value); 
     1970 
     1971/* 
     1972 * Get the value of an `!!int` SCALAR node. 
     1973 * 
     1974 * Use this function to ensure that the given node is a scalar, the node tag is 
     1975 * `tag:yaml.org,2002:int` and the node value is a valid integer.  In this 
     1976 * case, the function parses the node value and returns an integer number.  The 
     1977 * function recognizes decimal, hexdecimal and octal numbers including negative 
     1978 * numbers.  The function uses `strtol()` for string-to-integer conversion. 
     1979 * 
     1980 * Arguments: 
     1981 * 
     1982 * - `document`: a document object. 
     1983 * 
     1984 * - `node_id`: the node id; could be negative. 
     1985 * 
     1986 * - `value`: a pointer to save the node value or `NULL`. 
     1987 * 
     1988 * Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise.  If the 
     1989 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1990 * `value`. 
     1991 */ 
     1992 
     1993YAML_DECLARE(int) 
     1994yaml_document_get_int_node(yaml_document_t *document, int node_id, 
     1995        long *value); 
     1996 
     1997/* 
     1998 * Get the value of a `!!float` SCALAR node. 
     1999 * 
     2000 * Use this function to ensure that the given node is a scalar, the node tag is 
     2001 * `tag:yaml.org,2002:float` and the node value is a valid float value.  In 
     2002 * this case, the function parses the node value and returns a float number. 
     2003 * The function recognizes float values in exponential and fixed notation as 
     2004 * well as special values `.nan`, `.inf` and `-.inf`.  The function uses 
     2005 * `strtod()` for string-to-float conversion.  The `.nan`, `.inf` and `-.inf` 
     2006 * values are generated as `0.0/0.0`, `1.0/0.0` and `-1.0/0.0` respectively. 
     2007 * 
     2008 * Arguments: 
     2009 * 
     2010 * - `document`: a document object. 
     2011 * 
     2012 * - `node_id`: the node id; could be negative. 
     2013 * 
     2014 * - `value`: a pointer to save the node value or `NULL`. 
     2015 * 
     2016 * Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise.  If the 
     2017 * function succeeds and `value` is not `NULL`, the node value is saved to 
     2018 * `value`. 
     2019 */ 
     2020 
     2021YAML_DECLARE(int) 
     2022yaml_document_get_float_node(yaml_document_t *document, int node_id, 
     2023        double *value); 
     2024 
     2025/* 
     2026 * Get the value of a `!!seq` SEQUENCE node. 
     2027 * 
     2028 * Use this function to ensure that the given node is a sequence and the node 
     2029 * tag is `tag:yaml.org,2002:seq`.  In this case, the function returns the list 
     2030 * of nodes that belong to the sequence.  The produced list is valid until the 
     2031 * document object is modified. 
     2032 * 
     2033 * Arguments: 
     2034 * 
     2035 * - `document`: a document object. 
     2036 * 
     2037 * - `node_id`: the node id; could be negative. 
     2038 * 
     2039 * - `items`: a pointer to save the list of sequence items or `NULL`. 
     2040 * 
     2041 * - `length`: a pointer to save the length of the sequence or `NULL`. 
     2042 *   `length` must be equal to `NULL` if and only if `items` is also `NULL`. 
     2043 * 
     2044 * Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise.  If the 
     2045 * function succeeds and `items` is not `NULL`, the list of sequence items is 
     2046 * saved to `items` and the sequence length is saved to `length`. 
     2047 */ 
     2048 
     2049YAML_DECLARE(int) 
     2050yaml_document_get_seq_node(yaml_document_t *document, int node_id, 
     2051        yaml_node_item_t **items, size_t *length); 
     2052 
     2053/* 
     2054 * Get the value of a `!!map` MAPPING node. 
     2055 * 
     2056 * Use this function to ensure that the given node is a mapping and the node 
     2057 * tag is `tag:yaml.org,2002:map`.  In this case, the function returns the list 
     2058 * of node pairs (key, value) that belong to the sequence.  The produced list 
     2059 * is valid until the document is modified. 
     2060 * 
     2061 * Arguments: 
     2062 * 
     2063 * - `document`: a document object. 
     2064 * 
     2065 * - `node_id`: the node id; could be negative. 
     2066 * 
     2067 * - `pairs`: a pointer to save the list of mapping pairs or `NULL`. 
     2068 * 
     2069 * - `length`: a pointer to save the length of the mapping or `NULL`. 
     2070 *   `length` must be equal to `NULL` if and only if `pairs` is also `NULL`. 
     2071 * 
     2072 * Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise.  If the 
     2073 * function succeeds and `pairs` is not `NULL`, the list of mapping pairs is 
     2074 * saved to `pairs` and the mapping length is saved to `length`. 
     2075 */ 
     2076 
     2077YAML_DECLARE(int) 
     2078yaml_document_get_map_node(yaml_document_t *document, int node_id, 
     2079        yaml_node_pair_t **pairs, size_t *length); 
     2080 
     2081/* 
     2082 * Add a `!!null` SCALAR node to the document. 
     2083 * 
     2084 * This function is a shorthand for the call: 
     2085 * 
     2086 *      yaml_document_add_scalar(document, node_id, NULL, 
     2087 *              YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE) 
     2088 * 
     2089 * Arguments: 
     2090 * 
     2091 * - `document`: a document object. 
     2092 * 
     2093 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2094 * 
     2095 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2096 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2097 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2098 */ 
     2099 
     2100YAML_DECLARE(int) 
     2101yaml_document_add_null_node(yaml_document_t *document, int *node_id); 
     2102 
     2103/* 
     2104 * Add a `!!bool` SCALAR node to the document. 
     2105 * 
     2106 * This function is a shorthand for the call: 
     2107 * 
     2108 *      yaml_document_add_scalar(document, node_id, NULL, 
     2109 *              YAML_BOOL_TAG, (value ? "true" : "false"), -1, 
     2110 *              YAML_ANY_SCALAR_STYLE) 
     2111 * 
     2112 * Arguments: 
     2113 * 
     2114 * - `document`: a document object. 
     2115 * 
     2116 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2117 * 
     2118 * - `value`: a boolean value; any non-zero value is true, `0` is false. 
     2119 * 
     2120 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2121 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2122 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2123 */ 
     2124 
     2125YAML_DECLARE(int) 
     2126yaml_document_add_bool_node(yaml_document_t *document, int *node_id, 
     2127        int value); 
     2128 
     2129/* 
     2130 * Add a `!!str` SCALAR node to the document. 
     2131 * 
     2132 * This function is a shorthand for the call: 
     2133 * 
     2134 *      yaml_document_add_scalar(document, node_id, NULL, 
     2135 *              YAML_STR_TAG, (const yaml_char_t *) value, -1, 
     2136 *              YAML_ANY_SCALAR_STYLE) 
     2137 * 
     2138 * Arguments: 
     2139 * 
     2140 * - `document`: a document object. 
     2141 * 
     2142 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2143 * 
     2144 * - `value`: a NUL-terminated UTF-8 string.  The function does not check if 
     2145 *   `value` is a valid UTF-8 string, but if it is not so, the emitter will 
     2146 *   fail to emit the node. 
     2147 * 
     2148 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2149 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2150 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2151 */ 
     2152 
     2153YAML_DECLARE(int) 
     2154yaml_document_add_str_node(yaml_document_t *document, int *node_id, 
     2155        const char *value); 
     2156 
     2157/* 
     2158 * Add an `!!int` SCALAR node to the document. 
     2159 * 
     2160 * This function is a shorthand for the call: 
     2161 * 
     2162 *      yaml_document_add_scalar(document, node_id, NULL, 
     2163 *              YAML_INT_TAG, <string representation of the value>, -1, 
     2164 *              YAML_ANY_SCALAR_STYLE) 
     2165 * 
     2166 * Arguments: 
     2167 * 
     2168 * - `document`: a document object. 
     2169 * 
     2170 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2171 * 
     2172 * - `value`: an integer value. 
     2173 * 
     2174 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2175 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2176 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2177 */ 
     2178 
     2179YAML_DECLARE(int) 
     2180yaml_document_add_int_node(yaml_document_t *document, int *node_id, 
     2181        long value); 
     2182 
     2183/* 
     2184 * Add a `!!float` SCALAR node to the document. 
     2185 * 
     2186 * This function is a shorthand for the call: 
     2187 * 
     2188 *      yaml_document_add_scalar(document, node_id, NULL, 
     2189 *              YAML_FLOAT_TAG, <string representation of the value>, -1, 
     2190 *              YAML_ANY_SCALAR_STYLE) 
     2191 * 
     2192 * Arguments: 
     2193 * 
     2194 * - `document`: a document object. 
     2195 * 
     2196 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2197 * 
     2198 * - `value`: a float value. 
     2199 * 
     2200 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2201 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2202 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2203 */ 
     2204 
     2205YAML_DECLARE(int) 
     2206yaml_document_add_float_node(yaml_document_t *document, int *node_id, 
     2207        double value); 
     2208 
     2209/* 
     2210 * Add a `!!seq` SEQUENCE node to the document. 
     2211 * 
     2212 * This function is a shorthand for the call: 
     2213 * 
     2214 *      yaml_document_add_sequence(document, node_id, NULL, 
     2215 *              YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE) 
     2216 * 
     2217 * Arguments: 
     2218 * 
     2219 * - `document`: a document object. 
     2220 * 
     2221 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2222 * 
     2223 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2224 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2225 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2226 */ 
     2227 
     2228YAML_DECLARE(int) 
     2229yaml_document_add_seq_node(yaml_document_t *document, int *node_id); 
     2230 
     2231/* 
     2232 * Add a `!!map` MAPPING node to the document. 
     2233 * 
     2234 * This function is a shorthand for the call: 
     2235 * 
     2236 *      yaml_document_add_mapping(document, node_id, NULL, 
     2237 *              YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE) 
     2238 * 
     2239 * Arguments: 
     2240 * 
     2241 * - `document`: a document object. 
     2242 * 
     2243 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2244 * 
     2245 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2246 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2247 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2248 */ 
     2249 
     2250YAML_DECLARE(int) 
     2251yaml_document_add_map_node(yaml_document_t *document, int *node_id); 
     2252 
     2253/***************************************************************************** 
    22262254 * Callback Definitions 
    2227  ******************************************************************************/ 
     2255 *****************************************************************************/ 
    22282256 
    22292257/* 
    …… 
    23062334 
    23072335typedef int yaml_resolver_t(void *data, yaml_incomplete_node_t *node, 
    2308         yaml_char_t **tag); 
    2309  
    2310 /****************************************************************************** 
     2336        const yaml_char_t **tag); 
     2337 
     2338/***************************************************************************** 
    23112339 * Parser Definitions 
    2312  ******************************************************************************/ 
     2340 *****************************************************************************/ 
    23132341 
    23142342/* 
    …… 
    23602388 
    23612389YAML_DECLARE(void) 
    2362 yaml_parser_clear(yaml_parser_t *parser); 
     2390yaml_parser_reset(yaml_parser_t *parser); 
    23632391 
    23642392/* 
    …… 
    26182646        yaml_document_t *document); 
    26192647 
    2620 /****************************************************************************** 
     2648/***************************************************************************** 
    26212649 * Emitter Definitions 
    2622  ******************************************************************************/ 
     2650 *****************************************************************************/ 
    26232651 
    26242652/* 
    …… 
    26702698 
    26712699YAML_DECLARE(void) 
    2672 yaml_emitter_clear(yaml_emitter_t *emitter); 
     2700yaml_emitter_reset(yaml_emitter_t *emitter); 
    26732701 
    26742702/* 

  • libyaml/trunk/src/api.c

    r265 r267  
     1/***************************************************************************** 
     2 * LibYAML API Implementation 
     3 * 
     4 * Copyright (c) 2006 Kirill Simonov 
     5 * 
     6 * LibYAML is free software; you can use, modify and/or redistribute it under 
     7 * the terms of the MIT license; see the file LICENCE for more details. 
     8 *****************************************************************************/ 
    19 
    210#include "yaml_private.h" 
    311 
    4 /* 
    5  * Get the library version. 
     12/***************************************************************************** 
     13 * Version Information 
     14 *****************************************************************************/ 
     15 
     16/* 
     17 * Get the library version as a static string. 
    618 */ 
    719 
    …… 
    2436} 
    2537 
     38/***************************************************************************** 
     39 * Memory Management 
     40 *****************************************************************************/ 
     41 
    2642/* 
    2743 * Allocate a dynamic memory block. 
    …… 
    6682    return (yaml_char_t *)strdup((char *)str); 
    6783} 
     84 
     85/***************************************************************************** 
     86 * Error Handling 
     87 *****************************************************************************/ 
    6888 
    6989/* 
    …… 
    171191} 
    172192 
     193/***************************************************************************** 
     194 * String, Stack and Queue Management 
     195 *****************************************************************************/ 
    173196 
    174197/* 
    …… 
    264287} 
    265288 
    266  
    267 /* 
    268  * Create a new parser object. 
    269  */ 
    270  
    271 YAML_DECLARE(yaml_parser_t *) 
    272 yaml_parser_new(void) 
    273 { 
    274     yaml_parser_t *parser = yaml_malloc(sizeof(yaml_parser_t)); 
    275  
    276     if (!parser) 
    277         return NULL; 
    278  
    279     memset(parser, 0, sizeof(yaml_parser_t)); 
    280     if (!IOSTRING_INIT(parser, parser->raw_input, RAW_INPUT_BUFFER_CAPACITY)) 
    281         goto error; 
    282     if (!IOSTRING_INIT(parser, parser->input, INPUT_BUFFER_CAPACITY)) 
    283         goto error; 
    284     if (!QUEUE_INIT(parser, parser->tokens, INITIAL_QUEUE_CAPACITY)) 
    285         goto error; 
    286     if (!STACK_INIT(parser, parser->indents, INITIAL_STACK_CAPACITY)) 
    287         goto error; 
    288     if (!STACK_INIT(parser, parser->simple_keys, INITIAL_STACK_CAPACITY)) 
    289         goto error; 
    290     if (!STACK_INIT(parser, parser->states, INITIAL_STACK_CAPACITY)) 
    291         goto error; 
    292     if (!STACK_INIT(parser, parser->marks, INITIAL_STACK_CAPACITY)) 
    293         goto error; 
    294     if (!STACK_INIT(parser, parser->tag_directives, INITIAL_STACK_CAPACITY)) 
    295         goto error; 
    296  
    297     return parser; 
    298  
    299 error: 
    300     yaml_parser_delete(parser); 
    301  
    302     return NULL; 
    303 } 
    304  
    305 /* 
    306  * Destroy a parser object. 
    307  */ 
    308  
    309 YAML_DECLARE(void) 
    310 yaml_parser_delete(yaml_parser_t *parser) 
    311 { 
    312     assert(parser); /* Non-NULL parser object expected. */ 
    313  
    314     IOSTRING_DEL(parser, parser->raw_input); 
    315     IOSTRING_DEL(parser, parser->input); 
    316     while (!QUEUE_EMPTY(parser, parser->tokens)) { 
    317         yaml_token_destroy(&DEQUEUE(parser, parser->tokens)); 
    318     } 
    319     QUEUE_DEL(parser, parser->tokens); 
    320     STACK_DEL(parser, parser->indents); 
    321     STACK_DEL(parser, parser->simple_keys); 
    322     STACK_DEL(parser, parser->states); 
    323     STACK_DEL(parser, parser->marks); 
    324     while (!STACK_EMPTY(parser, parser->tag_directives)) { 
    325         yaml_tag_directive_t tag_directive = POP(parser, parser->tag_directives); 
    326         yaml_free(tag_directive.handle); 
    327         yaml_free(tag_directive.prefix); 
    328     } 
    329     STACK_DEL(parser, parser->tag_directives); 
    330  
    331     memset(parser, 0, sizeof(yaml_parser_t)); 
    332     yaml_free(parser); 
    333 } 
    334  
    335 /* 
    336  * Get the current parser error. 
    337  */ 
    338  
    339 YAML_DECLARE(void) 
    340 yaml_parser_get_error(yaml_parser_t *parser, yaml_error_t *error) 
    341 { 
    342     assert(parser); /* Non-NULL parser object expected. */ 
    343  
    344     *error = parser->error; 
    345 } 
    346  
    347 /* 
    348  * Standard string read handler. 
    349  */ 
    350  
    351 static int 
    352 yaml_string_reader(void *untyped_data, unsigned char *buffer, size_t capacity, 
    353         size_t *length) 
    354 { 
    355     yaml_standard_reader_data_t *data = untyped_data; 
    356  
    357     if (data->string.pointer == data->string.length) { 
    358         *length = 0; 
    359         return 1; 
    360     } 
    361  
    362     if (capacity > (size_t)(data->string.length - data->string.pointer)) { 
    363         capacity = data->string.length - data->string.pointer; 
    364     } 
    365  
    366     memcpy(buffer, data->string.buffer + data->string.pointer, capacity); 
    367     data->string.pointer += capacity; 
    368     *length = capacity; 
    369     return 1; 
    370 } 
    371  
    372 /* 
    373  * Standard file read handler. 
    374  */ 
    375  
    376 static int 
    377 yaml_file_reader(void *untyped_data, unsigned char *buffer, size_t capacity, 
    378         size_t *length) 
    379 { 
    380     yaml_standard_reader_data_t *data = untyped_data; 
    381  
    382     *length = fread(buffer, 1, capacity, data->file); 
    383     return !ferror(data->file); 
    384 } 
    385  
    386 /* 
    387  * Set a string input. 
    388  */ 
    389  
    390 YAML_DECLARE(void) 
    391 yaml_parser_set_string_reader(yaml_parser_t *parser, 
    392         const unsigned char *buffer, size_t length) 
    393 { 
    394     assert(parser); /* Non-NULL parser object expected. */ 
    395     assert(!parser->reader);    /* You can set the input handler only once. */ 
    396     assert(buffer); /* Non-NULL input string expected. */ 
    397  
    398     parser->reader = yaml_string_reader; 
    399     parser->reader_data = &(parser->standard_reader_data); 
    400  
    401     parser->standard_reader_data.string.buffer = buffer; 
    402     parser->standard_reader_data.string.pointer = 0; 
    403     parser->standard_reader_data.string.length = length; 
    404 } 
    405  
    406 /* 
    407  * Set a file input. 
    408  */ 
    409  
    410 YAML_DECLARE(void) 
    411 yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file) 
    412 { 
    413     assert(parser); /* Non-NULL parser object expected. */ 
    414     assert(!parser->reader);    /* You can set the input handler only once. */ 
    415     assert(file);   /* Non-NULL file object expected. */ 
    416  
    417     parser->reader = yaml_file_reader; 
    418     parser->reader_data = &(parser->standard_reader_data); 
    419  
    420     parser->standard_reader_data.file = file; 
    421 } 
    422  
    423 /* 
    424  * Set a generic input. 
    425  */ 
    426  
    427 YAML_DECLARE(void) 
    428 yaml_parser_set_reader(yaml_parser_t *parser, 
    429         yaml_reader_t *reader, void *data) 
    430 { 
    431     assert(parser); /* Non-NULL parser object expected. */ 
    432     assert(!parser->reader);    /* You can set the input handler only once. */ 
    433     assert(reader); /* Non-NULL read handler expected. */ 
    434  
    435     parser->reader = reader; 
    436     parser->reader_data = data; 
    437 } 
    438  
    439 /* 
    440  * Set the source encoding. 
    441  */ 
    442  
    443 YAML_DECLARE(void) 
    444 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding) 
    445 { 
    446     assert(parser); /* Non-NULL parser object expected. */ 
    447     assert(!parser->encoding);  /* Encoding is already set or detected. */ 
    448  
    449     parser->encoding = encoding; 
    450 } 
    451  
    452 /* 
    453  * Create a new emitter object. 
    454  */ 
    455  
    456 YAML_DECLARE(yaml_emitter_t *) 
    457 yaml_emitter_new(void) 
    458 { 
    459     yaml_emitter_t *emitter = yaml_malloc(sizeof(yaml_emitter_t)); 
    460  
    461     if (!emitter) 
    462         return NULL; 
    463  
    464     memset(emitter, 0, sizeof(yaml_emitter_t)); 
    465     if (!IOSTRING_INIT(emitter, emitter->output, OUTPUT_BUFFER_CAPACITY)) 
    466         goto error; 
    467     if (!IOSTRING_INIT(emitter, emitter->raw_output, RAW_OUTPUT_BUFFER_CAPACITY)) 
    468         goto error; 
    469     if (!STACK_INIT(emitter, emitter->states, INITIAL_STACK_CAPACITY)) 
    470         goto error; 
    471     if (!QUEUE_INIT(emitter, emitter->events, INITIAL_QUEUE_CAPACITY)) 
    472         goto error; 
    473     if (!STACK_INIT(emitter, emitter->indents, INITIAL_STACK_CAPACITY)) 
    474         goto error; 
    475     if (!STACK_INIT(emitter, emitter->tag_directives, INITIAL_STACK_CAPACITY)) 
    476         goto error; 
    477  
    478     return emitter; 
    479  
    480 error: 
    481     yaml_emitter_delete(emitter); 
    482  
    483     return NULL; 
    484 } 
    485  
    486 /* 
    487  * Destroy an emitter object. 
    488  */ 
    489  
    490 YAML_DECLARE(void) 
    491 yaml_emitter_delete(yaml_emitter_t *emitter) 
    492 { 
    493     assert(emitter);    /* Non-NULL emitter object expected. */ 
    494  
    495     IOSTRING_DEL(emitter, emitter->output); 
    496     IOSTRING_DEL(emitter, emitter->raw_output); 
    497     STACK_DEL(emitter, emitter->states); 
    498     while (!QUEUE_EMPTY(emitter, emitter->events)) { 
    499         yaml_event_destroy(&DEQUEUE(emitter, emitter->events)); 
    500     } 
    501     QUEUE_DEL(emitter, emitter->events); 
    502     STACK_DEL(emitter, emitter->indents); 
    503     while (!STACK_EMPTY(empty, emitter->tag_directives)) { 
    504         yaml_tag_directive_t tag_directive = POP(emitter, emitter->tag_directives); 
    505         yaml_free(tag_directive.handle); 
    506 <