sexp.h

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