apiref.rst 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528
  1. =============
  2. API Reference
  3. =============
  4. Types
  5. =====
  6. .. c:type:: hipack_type_t
  7. Type of a value. This enumeration takes one of the following values:
  8. - ``HIPACK_INTEGER``: Integer value.
  9. - ``HIPACK_FLOAT``: Floating point value.
  10. - ``HIPACK_BOOL``: Boolean value.
  11. - ``HIPACK_STRING``: String value.
  12. - ``HIPACK_LIST``: List value.
  13. - ``HIPACK_DICT``: Dictionary value.
  14. .. c:type:: hipack_value_t
  15. Represent any valid HiPack value.
  16. - :func:`hipack_value_type()` obtains the type of a value.
  17. .. c:type:: hipack_string_t
  18. String value.
  19. .. c:type:: hipack_list_t
  20. List value.
  21. .. c:type:: hipack_dict_t
  22. Dictionary value.
  23. Memory Allocation
  24. =================
  25. How ``hipack-c`` allocates memory can be customized by setting
  26. :c:data:`hipack_alloc` to a custom allocation function.
  27. .. c:var:: hipack_alloc
  28. Allocation function. By default it is set to :func:`hipack_alloc_stdlib()`,
  29. which uses the implementations of ``malloc()``, ``realloc()``, and
  30. ``free()`` provided by the C library.
  31. Allocation functions always have the following prototype:
  32. .. code-block:: c
  33. void* func (void *oldptr, size_t size);
  34. The behavior must be as follows:
  35. - When invoked with ``oldptr`` set to ``NULL``, and a non-zero ``size``,
  36. the function behaves like ``malloc()``: a memory block of at least
  37. ``size`` bytes is allocated and a pointer to it returned.
  38. - When ``oldptr`` is non-``NULL``, and a non-zero ``size``, the function
  39. behaves like ``realloc()``: the memory area pointed to by ``oldptr``
  40. is resized to be at least ``size`` bytes, or its contents moved to a
  41. new memory area of at least ``size`` bytes. The returned pointer may
  42. either be ``oldptr``, or a pointer to the new memory area if the data
  43. was relocated.
  44. - When ``oldptr`` is non-``NULL``, and ``size`` is zero, the function
  45. behaves like ``free()``.
  46. .. c:function:: void* hipack_alloc_stdlib(void*, size_t)
  47. Default allocation function. It uses ``malloc()``, ``realloc()``, and
  48. ``free()`` from the C library. By default :any:`hipack_alloc` is set
  49. to use this function.
  50. .. c:function:: void* hipack_alloc_array_extra (void *oldptr, size_t nmemb, size_t size, size_t extra)
  51. Allocates (if `oldptr` is ``NULL``) or reallocates (if `oldptr` is
  52. non-``NULL``) memory for an array which contains `nmemb` elements, each one
  53. of `size` bytes, plus an arbitrary amount of `extra` bytes.
  54. This function is used internally by the HiPack parser, and it is not likely
  55. to be needed by client code.
  56. .. c:function:: void* hipack_alloc_array (void *optr, size_t nmemb, size_t size)
  57. Same as :c:func:`hipack_alloc_array_extra()`, without allowing to specify
  58. the amount of extra bytes. The following calls are both equivalent:
  59. .. code-block:: c
  60. void *a = hipack_alloc_array_extra (NULL, 10, 4, 0);
  61. void *b = hipack_alloc_array (NULL, 10, 4);
  62. See :c:func:`hipack_alloc_array_extra()` for details.
  63. .. c:function:: void* hipack_alloc_bzero (size_t size)
  64. Allocates an area of memory of `size` bytes, and initializes it to zeroes.
  65. .. c:function:: void hipack_alloc_free (void *pointer)
  66. Frees the memory area referenced by the given `pointer`.
  67. String Functions
  68. ================
  69. The following functions are provided as a convenience to operate on values
  70. of type :c:type:`hipack_string_t`.
  71. .. note:: The hash function used by :c:func:`hipack_string_hash()` is
  72. *not* guaranteed to be cryptographically safe. Please do avoid exposing
  73. values returned by this function to the attack surface of your
  74. applications, in particular *do not expose them to the network*.
  75. .. c:function:: hipack_string_t* hipack_string_copy (const hipack_string_t *hstr)
  76. Returns a new copy of a string.
  77. The returned value must be freed using :c:func:`hipack_string_free()`.
  78. .. c:function:: hipack_string_t* hipack_string_new_from_string (const char *str)
  79. Creates a new string from a C-style zero terminated string.
  80. The returned value must be freed using :c:func:`hipack_string_free()`.
  81. .. c:function:: hipack_string_t* hipack_string_new_from_lstring (const char *str, uint32_t len)
  82. Creates a new string from a memory area and its length.
  83. The returned value must be freed using :c:func:`hipack_string_free()`.
  84. .. c:function:: uint32_t hipack_string_hash (const hipack_string_t *hstr)
  85. Calculates a hash value for a string.
  86. .. c:function:: bool hipack_string_equal (const hipack_string_t *hstr1, const hipack_string_t *hstr2)
  87. Compares two strings to check whether their contents are the same.
  88. .. c:function:: void hipack_string_free (hipack_string_t *hstr)
  89. Frees the memory used by a string.
  90. List Functions
  91. ==============
  92. .. c:function:: hipack_list_t* hipack_list_new (uint32_t size)
  93. Creates a new list for ``size`` elements.
  94. .. c:function:: void hipack_list_free (hipack_list_t *list)
  95. Frees the memory used by a list.
  96. .. c:function:: bool hipack_list_equal (const hipack_list_t *a, const hipack_list_t *b)
  97. Checks whether two lists contains the same values.
  98. .. c:function:: uint32_t hipack_list_size (const hipack_list_t *list)
  99. Obtains the number of elements in a list.
  100. .. c:macro:: HIPACK_LIST_AT(list, index)
  101. Obtains a pointer to the element at a given `index` of a `list`.
  102. Dictionary Functions
  103. ====================
  104. .. c:function:: uint32_t hipack_dict_size (const hipack_dict_t *dict)
  105. Obtains the number of elements in a dictionary.
  106. .. c:function:: hipack_dict_t* hipack_dict_new (void)
  107. Creates a new, empty dictionary.
  108. .. c:function:: void hipack_dict_free (hipack_dict_t *dict)
  109. Frees the memory used by a dictionary.
  110. .. c:function:: bool hipack_dict_equal (const hipack_dict_t *a, const hipack_dict_t *b)
  111. Checks whether two dictinaries contain the same keys, and their associated
  112. values in each of the dictionaries are equal.
  113. .. c:function:: void hipack_dict_set (hipack_dict_t *dict, const hipack_string_t *key, const hipack_value_t *value)
  114. Adds an association of a `key` to a `value`.
  115. Note that this function will copy the `key`. If you are not planning to
  116. continue reusing the `key`, it is recommended to use
  117. :c:func:`hipack_dict_set_adopt_key()` instead.
  118. .. c:function:: void hipack_dict_set_adopt_key (hipack_dict_t *dict, hipack_string_t **key, const hipack_value_t *value)
  119. Adds an association of a `key` to a `value`, passing ownership of the
  120. memory using by the `key` to the dictionary (i.e. the string used as key
  121. will be freed by the dictionary).
  122. Use this function instead of :c:func:`hipack_dict_set()` when the `key`
  123. is not going to be used further afterwards.
  124. .. c:function:: void hipack_dict_del (hipack_dict_t *dict, const hipack_string_t *key)
  125. Removes the element from a dictionary associated to a `key`.
  126. .. c:function:: hipack_value_t* hipack_dict_get (const hipack_dict_t *dict, const hipack_string_t *key)
  127. Obtains the value associated to a `key` from a dictionary.
  128. The returned value points to memory owned by the dictionary. The value can
  129. be modified in-place, but it shall not be freed.
  130. .. c:function:: hipack_value_t* hipack_dict_first (const hipack_dict_t *dict, const hipack_string_t **key)
  131. Obtains an a *(key, value)* pair, which is considered the *first* in
  132. iteration order. This can be used in combination with
  133. :c:func:`hipack_dict_next()` to enumerate all the *(key, value)* pairs
  134. stored in the dictionary:
  135. .. code-block:: c
  136. hipack_dict_t *d = get_dictionary ();
  137. hipack_value_t *v;
  138. hipack_string_t *k;
  139. for (v = hipack_dict_first (d, &k);
  140. v != NULL;
  141. v = hipack_dict_next (v, &k)) {
  142. // Use "k" and "v" normally.
  143. }
  144. As a shorthand, consider using :c:macro:`HIPACK_DICT_FOREACH()` instead.
  145. .. c:function:: hipack_value_t* hipack_dict_next (hipack_value_t *value, const hipack_string_t **key)
  146. Iterates to the next *(key, value)* pair of a dictionary. For usage
  147. details, see :c:func:`hipack_dict_first()`.
  148. .. c:macro:: HIPACK_DICT_FOREACH(dict, key, value)
  149. Convenience macro used to iterate over the *(key, value)* pairs contained
  150. in a dictionary. Internally this uses :c:func:`hipack_dict_first()` and
  151. :c:func:`hipack_dict_next()`.
  152. .. code-block:: c
  153. hipack_dict_t *d = get_dictionary ();
  154. hipack_string_t *k;
  155. hipack_value_t *v;
  156. HIPACK_DICT_FOREACH (d, k, v) {
  157. // Use "k" and "v"
  158. }
  159. Using this macro is the recommended way of writing a loop to enumerate
  160. elements from a dictionary.
  161. Value Functions
  162. ===============
  163. .. c:function:: hipack_type_t hipack_value_type (const hipack_value_t *value)
  164. Obtains the type of a value.
  165. .. c:function:: bool hipack_value_is_integer (const hipack_value_t *value)
  166. Checks whether a value is an integer.
  167. .. c:function:: bool hipack_value_is_float (const hipack_value_t *value)
  168. Checks whether a value is a floating point number.
  169. .. c:function:: bool hipack_value_is_bool (const hipack_value_t *value)
  170. Checks whether a value is a boolean.
  171. .. c:function:: bool hipack_value_is_string (const hipack_value_t *value)
  172. Checks whether a value is a string.
  173. .. c:function:: bool hipack_value_is_list (const hipack_value_t *value)
  174. Checks whether a value is a list.
  175. .. c:function:: bool hipack_value_is_dict (const hipack_value_t *value)
  176. Checks whether a value is a dictionary.
  177. .. c:function:: const int32_t hipack_value_get_integer (const hipack_value_t *value)
  178. Obtains a numeric value as an ``int32_t``.
  179. .. c:function:: const double hipack_value_get_float (const hipack_value_t *value)
  180. Obtains a floating point value as a ``double``.
  181. .. c:function:: const bool hipack_value_get_bool (const hipack_value_t *value)
  182. Obtains a boolean value as a ``bool``.
  183. .. c:function:: const hipack_string_t* hipack_value_get_string (const hipack_value_t *value)
  184. Obtains a numeric value as a :c:type:`hipack_string_t`.
  185. .. c:function:: const hipack_list_t* hipack_value_get_list (const hipack_value_t *value)
  186. Obtains a numeric value as a :c:type:`hipack_list_t`.
  187. .. c:function:: const hipack_dict_t* hipack_value_get_dict (const hipack_value_t *value)
  188. Obtains a numeric value as a :c:type:`hipack_dict_t`.
  189. .. c:function:: bool hipack_value_equal (const hipack_value_t *a, const hipack_value_t *b)
  190. Checks whether two values are equal.
  191. .. c:function:: void hipack_value_free (hipack_value_t *value)
  192. Frees the memory used by a value.
  193. .. c:function:: void hipack_value_add_annot (hipack_value_t *value, const char *annot)
  194. Adds an annotation to a value. If the value already had the annotation,
  195. this function is a no-op.
  196. .. c:function:: bool hipack_value_has_annot (const hipack_value_t *value, const char *annot)
  197. Checks whether a value has a given annotation.
  198. .. c:function:: void hipack_value_del_annot (hipack_value_t *value, const char *annot)
  199. Removes an annotation from a value. If the annotation was not present, this
  200. function is a no-op.
  201. Reader Interface
  202. ================
  203. .. c:type:: hipack_reader_t
  204. Allows communicating with the parser, instructing it how to read text
  205. input data, and provides a way for the parser to report errors back.
  206. The following members of the structure are to be used by client code:
  207. .. c:member:: int (*getchar)(void *data)
  208. Reader callback function. The function will be called every time the
  209. next character of input is needed. It must return it as an integer,
  210. :any:`HIPACK_IO_EOF` when trying to read pas the end of the input,
  211. or :any:`HIPACK_IO_ERROR` if an input error occurs.
  212. .. c:member:: const char *error
  213. On error, a string describing the issue, suitable to be displayed to
  214. the user.
  215. .. c:member:: unsigned error_line
  216. On error, the line number where parsing was stopped.
  217. .. c:member:: unsigned error_column
  218. On error, the column where parsing was stopped.
  219. .. c:macro:: HIPACK_IO_EOF
  220. Constant returned by reader functions when trying to read past the end of
  221. the input.
  222. .. c:macro:: HIPACK_IO_ERROR
  223. Constant returned by reader functions on input errors.
  224. .. c:macro:: HIPACK_READ_ERROR
  225. Constant value used to signal an underlying input error.
  226. The `error` field of :c:type:`hipack_reader_t` is set to this value when
  227. the reader function returns :any:`HIPACK_IO_ERROR`. This is provided to
  228. allow client code to detect this condition and further query for the
  229. nature of the input error.
  230. .. c:function:: hipack_dict_t* hipack_read (hipack_reader_t *reader)
  231. Reads a HiPack message from a stream `reader` and returns a dictionary.
  232. On error, ``NULL`` is returned, and the members `error`, `error_line`,
  233. and `error_column` (see :c:type:`hipack_reader_t`) are set accordingly
  234. in the `reader`.
  235. .. c:function:: int hipack_stdio_getchar (void* fp)
  236. Reader function which uses ``FILE*`` objects from the standard C library.
  237. To use this function to read from a ``FILE*``, first open a file, and
  238. then create a reader using this function and the open file as data to
  239. be passed to it, and then use :c:func:`hipack_read()`:
  240. .. code-block:: c
  241. FILE* stream = fopen (HIPACK_FILE_PATH, "rb")
  242. hipack_reader_t reader = {
  243. .getchar = hipack_stdio_getchar,
  244. .getchar_data = stream,
  245. };
  246. hipack_dict_t *message = hipack_read (&reader);
  247. The user is responsible for closing the ``FILE*`` after using it.
  248. Writer Interface
  249. ================
  250. .. c:type:: hipack_writer_t
  251. Allows specifying how to write text output data, and configuring how
  252. the produced HiPack output looks like.
  253. The following members of the structure are to be used by client code:
  254. .. c:member:: int (*putchar)(void *data, int ch)
  255. Writer callback function. The function will be called every time a
  256. character is produced as output. It must return :any:`HIPACK_IO_ERROR`
  257. if an output error occurs, and it is invalid for the callback to
  258. return :any:`HIPACK_IO_EOF`. Any other value is interpreted as
  259. indication of success.
  260. .. c:member:: void* putchar_data
  261. Data passed to the writer callback function.
  262. .. c:member:: int32_t indent
  263. Either :any:`HIPACK_WRITER_COMPACT` or :any:`HIPACK_WRITER_INDENTED`.
  264. .. c:macro:: HIPACK_WRITER_COMPACT
  265. Flag to generate output HiPack messages in their compact representation.
  266. .. c:macro:: HIPACK_WRITER_INDENTED
  267. Flag to generate output HiPack messages in “indented” (pretty-printed)
  268. representation.
  269. .. c:function:: bool hipack_write (hipack_writer_t *writer, const hipack_dict_t *message)
  270. Writes a HiPack `message` to a stream `writer`, and returns whether writing
  271. the message was successful.
  272. .. c:function:: int hipack_stdio_putchar (void* data, int ch)
  273. Writer function which uses ``FILE*`` objects from the standard C library.
  274. To use this function to write a message to a ``FILE*``, first open a file,
  275. then create a writer using this function, and then use
  276. :c:func:`hipack_write()`:
  277. .. code-block:: c
  278. FILE* stream = fopen (HIPACK_FILE_PATH, "wb");
  279. hipack_writer_t writer = {
  280. .putchar = hipack_stdio_putchar,
  281. .putchar_data = stream,
  282. };
  283. hipack_write (&writer, message);
  284. The user is responsible for closing the ``FILE*`` after using it.