include/nettle/sexp.h

0001 /* sexp.h
0002
0003    Parsing s-expressions.
0004    Copyright (C) 2002 Niels Möller
0005
0006    This file is part of GNU Nettle.
0007
0008    GNU Nettle is free software: you can redistribute it and/or
0009    modify it under the terms of either:
0010
0011      * the GNU Lesser General Public License as published by the Free
0012        Software Foundation; either version 3 of the License, or (at your
0013        option) any later version.
0014
0015    or
0016
0017      * the GNU General Public License as published by the Free
0018        Software Foundation; either version 2 of the License, or (at your
0019        option) any later version.
0020
0021    or both in parallel, as here.
0022
0023    GNU Nettle is distributed in the hope that it will be useful,
0024    but WITHOUT ANY WARRANTY; without even the implied warranty of
0025    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0026    General Public License for more details.
0027
0028    You should have received copies of the GNU General Public License and
0029    the GNU Lesser General Public License along with this program.  If
0030    not, see http://www.gnu.org/licenses/.
0031 */
0032
0033 #ifndef NETTLE_SEXP_H_INCLUDED
0034 #define NETTLE_SEXP_H_INCLUDED
0035
0036 #include <stdarg.h>
0037 #include "nettle-types.h"
0038
0039 #ifdef __cplusplus
0040 extern "C" {
0041 #endif
0042
0043 /* Name mangling */
0044 #define sexp_iterator_first nettle_sexp_iterator_first
0045 #define sexp_transport_iterator_first nettle_sexp_transport_iterator_first
0046 #define sexp_iterator_next nettle_sexp_iterator_next
0047 #define sexp_iterator_enter_list nettle_sexp_iterator_enter_list
0048 #define sexp_iterator_exit_list nettle_sexp_iterator_exit_list
0049 #define sexp_iterator_subexpr nettle_sexp_iterator_subexpr
0050 #define sexp_iterator_get_uint32 nettle_sexp_iterator_get_uint32
0051 #define sexp_iterator_check_type nettle_sexp_iterator_check_type
0052 #define sexp_iterator_check_types nettle_sexp_iterator_check_types
0053 #define sexp_iterator_assoc nettle_sexp_iterator_assoc
0054 #define sexp_format nettle_sexp_format
0055 #define sexp_vformat nettle_sexp_vformat
0056 #define sexp_transport_format nettle_sexp_transport_format
0057 #define sexp_transport_vformat nettle_sexp_transport_vformat
0058 #define sexp_token_chars nettle_sexp_token_chars
0059
0060 enum sexp_type
0061   { SEXP_ATOM, SEXP_LIST, SEXP_END };
0062
0063 struct sexp_iterator
0064 {
0065   size_t length;
0066   const uint8_t *buffer;
0067
0068   /* Points at the start of the current sub expression. */
0069   size_t start;
0070   /* If type is SEXP_LIST, pos points at the start of the current
0071    * element. Otherwise, it points at the end. */
0072   size_t pos;
0073   unsigned level;
0074
0075   enum sexp_type type;
0076
0077   size_t display_length;
0078   const uint8_t *display;
0079
0080   size_t atom_length;
0081   const uint8_t *atom;
0082 };
0083
0084
0085 /* All these functions return 1 on success, 0 on failure */
0086
0087 /* Initializes the iterator. */
0088 int
0089 sexp_iterator_first(struct sexp_iterator *iterator,
0090             size_t length, const uint8_t *input);
0091
0092 /* NOTE: Decodes the input string in place */
0093 int
0094 sexp_transport_iterator_first(struct sexp_iterator *iterator,
0095                   size_t length, uint8_t *input);
0096
0097 int
0098 sexp_iterator_next(struct sexp_iterator *iterator);
0099
0100 /* Current element must be a list. */
0101 int
0102 sexp_iterator_enter_list(struct sexp_iterator *iterator);
0103
0104 /* Skips the rest of the current list */
0105 int
0106 sexp_iterator_exit_list(struct sexp_iterator *iterator);
0107
0108 #if 0
0109 /* Skips out of as many lists as necessary to get back to the given
0110  * level. */
0111 int
0112 sexp_iterator_exit_lists(struct sexp_iterator *iterator,
0113              unsigned level);
0114 #endif
0115
0116 /* Gets start and length of the current subexpression. Implies
0117  * sexp_iterator_next. */
0118 const uint8_t *
0119 sexp_iterator_subexpr(struct sexp_iterator *iterator,
0120               size_t *length);
0121
0122 int
0123 sexp_iterator_get_uint32(struct sexp_iterator *iterator,
0124              uint32_t *x);
0125
0126
0127 /* Checks the type of the current expression, which should be a list
0128  *
0129  *  (<type> ...)
0130  */
0131 int
0132 sexp_iterator_check_type(struct sexp_iterator *iterator,
0133              const char *type);
0134
0135 const char *
0136 sexp_iterator_check_types(struct sexp_iterator *iterator,
0137               unsigned ntypes,
0138               const char * const *types);
0139
0140 /* Current element must be a list. Looks up element of type
0141  *
0142  *   (key rest...)
0143  *
0144  * For a matching key, the corresponding iterator is initialized
0145  * pointing at the start of REST.
0146  *
0147  * On success, exits the current list.
0148  */
0149 int
0150 sexp_iterator_assoc(struct sexp_iterator *iterator,
0151             unsigned nkeys,
0152             const char * const *keys,
0153             struct sexp_iterator *values);
0154
0155
0156 /* Output functions. What is a reasonable API for this? It seems
0157  * ugly to have to reimplement string streams. */
0158
0159 /* Declared for real in buffer.h */
0160 struct nettle_buffer;
0161
0162 /* Returns the number of output characters, or 0 on out of memory. If
0163  * buffer == NULL, just compute length.
0164  *
0165  * Format strings can contained matched parentheses, tokens ("foo" in
0166  * the format string is formatted as "3:foo"), whitespace (which
0167  * separates tokens but is otherwise ignored) and the following
0168  * formatting specifiers:
0169  *
0170  *   %s   String represented as size_t length, const uint8_t *data.
0171  *
0172  *   %t   Optional display type, represented as
0173  *        size_t display_length, const uint8_t *display,
0174  *        display == NULL means no display type.
0175  *
0176  *   %i   Non-negative small integer, uint32_t.
0177  *
0178  *   %b   Non-negative bignum, mpz_t.
0179  *
0180  *   %l   Literal string (no length added), typically a balanced
0181  *        subexpression. Represented as size_t length, const uint8_t
0182  *        *data.
0183  *
0184  *   %(, %)  Allows insertion of unbalanced parenthesis.
0185  *
0186  * Modifiers:
0187  *
0188  *   %0   For %s, %t and %l, says that there's no length argument,
0189  *        instead the string is NUL-terminated, and there's only one
0190  *        const uint8_t * argument.
0191  */
0192
0193 size_t
0194 sexp_format(struct nettle_buffer *buffer,
0195         const char *format, ...);
0196
0197 size_t
0198 sexp_vformat(struct nettle_buffer *buffer,
0199          const char *format, va_list args);
0200
0201 size_t
0202 sexp_transport_format(struct nettle_buffer *buffer,
0203               const char *format, ...);
0204
0205 size_t
0206 sexp_transport_vformat(struct nettle_buffer *buffer,
0207                const char *format, va_list args);
0208
0209 #ifdef __cplusplus
0210 }
0211 #endif
0212
0213 #endif /* NETTLE_SEXP_H_INCLUDED */