source3/lib/srprs.h

   1 /*
   2  * Samba Unix/Linux SMB client library
   3  *
   4  * Copyright (C) Gregor Beck 2010
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /**
  21  * @file   srprs.h
  22  * @author Gregor Beck <gb@sernet.de>
  23  * @date   Aug 2010
  24  *
  25  * @brief  A simple recursive parser.
  26  *
  27  * This file contains functions which may be used to build a simple recursive
  28  * parser. They all take the parse position as their first argument. If they
  29  * match the parse position and the output arguments are updated accordingly and
  30  * true is returned else no argument is altered. For arguments of type @ref cbuf
  31  * this may hold only up to the current write position.
  32  */
  33
  34 #ifndef __SRPRS_H
  35 #define __SRPRS_H
  36
  37 #include <stddef.h>
  38 #include <stdbool.h>
  39 #include <stdint.h>
  40 struct cbuf;
  41
  42 /**
  43  * Matches any amount of whitespace.
  44  *
  45  * @see isspace
  46  * @param ptr parse position
  47  *
  48  * @return true
  49  */
  50 bool srprs_skipws(const char** ptr);
  51
  52 /**
  53  * Match a single character.
  54  *
  55  * @param[in,out] ptr parse position
  56  * @param         c   the character to match
  57  *
  58  * @return true if matched
  59  */
  60 bool srprs_char(const char** ptr, char c);
  61
  62 /**
  63  * Match a string.
  64  *
  65  * @param[in,out] ptr parse position
  66  * @param str string to match
  67  * @param len number of bytes to compare, -1 means strlen(str)
  68  *
  69  * @return true if matched
  70  */
  71 bool srprs_str(const char** ptr, const char* str, size_t len);
  72
  73 /**
  74  * Match a single character from a set.
  75  * Didn't match '\\0'
  76  *
  77  * @param[in,out] ptr parse position
  78  * @param[in] set the character set to look for
  79  * @param[out] oss output buffer where to put the match, may be NULL
  80  *
  81  * @return true if matched
  82  */
  83 bool srprs_charset(const char** ptr, const char* set, struct cbuf* oss);
  84
  85 /**
  86  * Match a single character not in set.
  87  * Didn't match '\\0'
  88  *
  89  * @param[in,out] ptr parse position
  90  * @param[in] set the character set to look for
  91  * @param[out] oss output buffer where to put the match, may be NULL
  92  *
  93  * @return true if matched
  94  */
  95 bool srprs_charsetinv(const char** ptr, const char* set, struct cbuf* oss);
  96
  97 /**
  98  * Match a quoted string.
  99  *
 100  *
 101  * If cont is not NULL the match may span multiple invocations.
 102  * @code
 103  * const char* start = "\"start...";
 104  * const char* cont  = "continued...";
 105  * const char* end   = "end\"";
 106  * bool  cont = false;
 107  * cbuf* out  = cbuf_new(talloc_tos());
 108  * srprs_quoted_string(&start, out, &cont);
 109  * assert(*cont == true);
 110  * srprs_quoted_string(&cont, out, &cont);
 111  * assert(*cont == true);
 112  * srprs_quoted_string(&end, out, &cont);
 113  * assert(*cont == false);
 114  * assert(strcmp(cbuf_gets(out, 0), "start...continued...end")==0);
 115  * @endcode
 116  * @see cbuf_print_quoted_string
 117  *
 118  * @param[in,out] ptr parse position
 119  * @param[out] str output buffer where to put the match
 120  * @param[in,out] cont
 121  *
 122  * @return true if matched
 123  */
 124 bool srprs_quoted_string(const char** ptr, struct cbuf* str, bool* cont);
 125
 126 /**
 127  * Match a hex string.
 128  *
 129  * @param[in,out] ptr parse position
 130  * @param         len maximum number of diggits to match
 131  * @param[out]    u   value of the match
 132  *
 133  * @return true if matched
 134  */
 135 bool srprs_hex(const char** ptr, size_t len, unsigned* u);
 136
 137 /**
 138  * Match the empty string at End Of String.
 139  * It doesn't consume the '\\0' unlike
 140  * @code
 141  *   srprs_char(ptr, '\0', NULL);
 142  * @endcode
 143  *
 144  * @param[in,out] ptr parse position
 145  *
 146  * @return true if **ptr == '\\0'
 147  */
 148 bool srprs_eos(const char** ptr);
 149
 150 /**
 151  * Match a newline.
 152  * A newline is either '\\n' (LF), '\\r' (CR), or "\r\n" (CRLF)
 153  *
 154  * @param[in,out] ptr parse position
 155  * @param[out]    nl  output buffer where to put the match, may be NULL
 156  *
 157  * @return true if matched
 158  */
 159 bool srprs_nl(const char** ptr, struct cbuf* nl);
 160
 161 /**
 162  * Match a newline or eos.
 163  *
 164  * @param ptr parse position
 165  * @param nl  output buffer where to put the match, may be NULL
 166  *
 167  * @return true if matched
 168  */
 169 bool srprs_eol(const char** ptr, struct cbuf* nl);
 170
 171 /**
 172  * Match a line up to but not including the newline.
 173  *
 174  * @param[in,out] ptr parse position
 175  * @param[out]    str output buffer where to put the match, may be NULL
 176  *
 177  * @return true
 178  */
 179 bool srprs_line(const char** ptr, struct cbuf* str);
 180
 181 /**
 182  * Match a quoted string with escaped characters.
 183  * @see cbuf_print_quoted
 184  *
 185  * @param[in,out] ptr parse position
 186  * @param[out] str output buffer where to put the match
 187  *
 188  * @return true if matched
 189  */
 190 bool srprs_quoted(const char** ptr, struct cbuf* str);
 191
 192 #endif /* __SRPRS_H */