git.samba.org - gd/nettle/blob - sexp.h

   1 /* sexp.h
   2
   3    Parsing s-expressions.
   4    Copyright (C) 2002 Niels Möller
   5
   6    This file is part of GNU Nettle.
   7
   8    GNU Nettle is free software: you can redistribute it and/or
   9    modify it under the terms of either:
  10
  11      * the GNU Lesser General Public License as published by the Free
  12        Software Foundation; either version 3 of the License, or (at your
  13        option) any later version.
  14
  15    or
  16
  17      * the GNU General Public License as published by the Free
  18        Software Foundation; either version 2 of the License, or (at your
  19        option) any later version.
  20
  21    or both in parallel, as here.
  22
  23    GNU Nettle is distributed in the hope that it will be useful,
  24    but WITHOUT ANY WARRANTY; without even the implied warranty of
  25    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  26    General Public License for more details.
  27
  28    You should have received copies of the GNU General Public License and
  29    the GNU Lesser General Public License along with this program.  If
  30    not, see http://www.gnu.org/licenses/.
  31 */
  32
  33 #ifndef NETTLE_SEXP_H_INCLUDED
  34 #define NETTLE_SEXP_H_INCLUDED
  35
  36 #include <stdarg.h>
  37 #include "nettle-types.h"
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /* Name mangling */
  44 #define sexp_iterator_first nettle_sexp_iterator_first
  45 #define sexp_transport_iterator_first nettle_sexp_transport_iterator_first
  46 #define sexp_iterator_next nettle_sexp_iterator_next
  47 #define sexp_iterator_enter_list nettle_sexp_iterator_enter_list
  48 #define sexp_iterator_exit_list nettle_sexp_iterator_exit_list
  49 #define sexp_iterator_subexpr nettle_sexp_iterator_subexpr
  50 #define sexp_iterator_get_uint32 nettle_sexp_iterator_get_uint32
  51 #define sexp_iterator_check_type nettle_sexp_iterator_check_type
  52 #define sexp_iterator_check_types nettle_sexp_iterator_check_types
  53 #define sexp_iterator_assoc nettle_sexp_iterator_assoc
  54 #define sexp_format nettle_sexp_format
  55 #define sexp_vformat nettle_sexp_vformat
  56 #define sexp_transport_format nettle_sexp_transport_format
  57 #define sexp_transport_vformat nettle_sexp_transport_vformat
  58 #define sexp_token_chars nettle_sexp_token_chars
  59
  60 enum sexp_type
  61   { SEXP_ATOM, SEXP_LIST, SEXP_END };
  62
  63 struct sexp_iterator
  64 {
  65   size_t length;
  66   const uint8_t *buffer;
  67
  68   /* Points at the start of the current sub expression. */
  69   size_t start;
  70   /* If type is SEXP_LIST, pos points at the start of the current
  71    * element. Otherwise, it points at the end. */
  72   size_t pos;
  73   unsigned level;
  74
  75   enum sexp_type type;
  76
  77   size_t display_length;
  78   const uint8_t *display;
  79
  80   size_t atom_length;
  81   const uint8_t *atom;
  82 };
  83
  84
  85 /* All these functions return 1 on success, 0 on failure */
  86
  87 /* Initializes the iterator. */
  88 int
  89 sexp_iterator_first(struct sexp_iterator *iterator,
  90                     size_t length, const uint8_t *input);
  91
  92 /* NOTE: Decodes the input string in place */
  93 int
  94 sexp_transport_iterator_first(struct sexp_iterator *iterator,
  95                               size_t length, uint8_t *input);
  96
  97 int
  98 sexp_iterator_next(struct sexp_iterator *iterator);
  99
 100 /* Current element must be a list. */
 101 int
 102 sexp_iterator_enter_list(struct sexp_iterator *iterator);
 103
 104 /* Skips the rest of the current list */
 105 int
 106 sexp_iterator_exit_list(struct sexp_iterator *iterator);
 107
 108 #if 0
 109 /* Skips out of as many lists as necessary to get back to the given
 110  * level. */
 111 int
 112 sexp_iterator_exit_lists(struct sexp_iterator *iterator,
 113                          unsigned level);
 114 #endif
 115
 116 /* Gets start and length of the current subexpression. Implies
 117  * sexp_iterator_next. */
 118 const uint8_t *
 119 sexp_iterator_subexpr(struct sexp_iterator *iterator,
 120                       size_t *length);
 121
 122 int
 123 sexp_iterator_get_uint32(struct sexp_iterator *iterator,
 124                          uint32_t *x);
 125
 126 \f
 127 /* Checks the type of the current expression, which should be a list
 128  *
 129  *  (<type> ...)
 130  */
 131 int
 132 sexp_iterator_check_type(struct sexp_iterator *iterator,
 133                          const char *type);
 134
 135 const char *
 136 sexp_iterator_check_types(struct sexp_iterator *iterator,
 137                           unsigned ntypes,
 138                           const char * const *types);
 139
 140 /* Current element must be a list. Looks up element of type
 141  *
 142  *   (key rest...)
 143  *
 144  * For a matching key, the corresponding iterator is initialized
 145  * pointing at the start of REST.
 146  *
 147  * On success, exits the current list.
 148  */
 149 int
 150 sexp_iterator_assoc(struct sexp_iterator *iterator,
 151                     unsigned nkeys,
 152                     const char * const *keys,
 153                     struct sexp_iterator *values);
 154
 155 \f
 156 /* Output functions. What is a reasonable API for this? It seems
 157  * ugly to have to reimplement string streams. */
 158
 159 /* Declared for real in buffer.h */
 160 struct nettle_buffer;
 161
 162 /* Returns the number of output characters, or 0 on out of memory. If
 163  * buffer == NULL, just compute length.
 164  *
 165  * Format strings can contained matched parentheses, tokens ("foo" in
 166  * the format string is formatted as "3:foo"), whitespace (which
 167  * separates tokens but is otherwise ignored) and the following
 168  * formatting specifiers:
 169  *
 170  *   %s   String represented as size_t length, const uint8_t *data.
 171  *
 172  *   %t   Optional display type, represented as
 173  *        size_t display_length, const uint8_t *display,
 174  *        display == NULL means no display type.
 175  *
 176  *   %i   Non-negative small integer, uint32_t.
 177  *
 178  *   %b   Non-negative bignum, mpz_t.
 179  *
 180  *   %l   Literal string (no length added), typically a balanced
 181  *        subexpression. Represented as size_t length, const uint8_t
 182  *        *data.
 183  *
 184  *   %(, %)  Allows insertion of unbalanced parenthesis.
 185  *
 186  * Modifiers:
 187  *
 188  *   %0   For %s, %t and %l, says that there's no length argument,
 189  *        instead the string is NUL-terminated, and there's only one
 190  *        const uint8_t * argument.
 191  */
 192
 193 size_t
 194 sexp_format(struct nettle_buffer *buffer,
 195             const char *format, ...);
 196
 197 size_t
 198 sexp_vformat(struct nettle_buffer *buffer,
 199              const char *format, va_list args);
 200
 201 size_t
 202 sexp_transport_format(struct nettle_buffer *buffer,
 203                       const char *format, ...);
 204
 205 size_t
 206 sexp_transport_vformat(struct nettle_buffer *buffer,
 207                        const char *format, va_list args);
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif
 212
 213 #endif /* NETTLE_SEXP_H_INCLUDED */