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  *
 117  * @param[in,out] ptr parse position
 118  * @param[out] str output buffer where to put the match, may be NULL
 119  * @param[in,out] cont
 120  *
 121  * @return true if matched
 122  */
 123 bool srprs_quoted_string(const char** ptr, struct cbuf* str, bool* cont);
 124
 125 /**
 126  * Match a hex string.
 127  *
 128  * @param[in,out] ptr parse position
 129  * @param         len maximum number of diggits to match
 130  * @param[out]    u   value of the match
 131  *
 132  * @return true if matched
 133  */
 134 bool srprs_hex(const char** ptr, size_t len, unsigned* u);
 135
 136 /**
 137  * Match the empty string at End Of String.
 138  * It doesn't consume the '\\0' unlike
 139  * @code
 140  *   srprs_char(ptr, '\0', NULL);
 141  * @endcode
 142  *
 143  * @param[in,out] ptr parse position
 144  *
 145  * @return true if **ptr == '\\0'
 146  */
 147 bool srprs_eos(const char** ptr);
 148
 149 /**
 150  * Match a newline.
 151  * A newline is either '\\n' (LF), '\\r' (CR), or "\r\n" (CRLF)
 152  *
 153  * @param[in,out] ptr parse position
 154  * @param[out]    nl  output buffer where to put the match, may be NULL
 155  *
 156  * @return true if matched
 157  */
 158 bool srprs_nl(const char** ptr, struct cbuf* nl);
 159
 160 /**
 161  * Match a newline or eos.
 162  *
 163  * @param ptr parse position
 164  * @param nl  output buffer where to put the match, may be NULL
 165  *
 166  * @return true if matched
 167  */
 168 bool srprs_eol(const char** ptr, struct cbuf* nl);
 169
 170 /**
 171  * Match a line up to but not including the newline.
 172  *
 173  * @param[in,out] ptr parse position
 174  * @param[out]    str output buffer where to put the match, may be NULL
 175  *
 176  * @return true
 177  */
 178 bool srprs_line(const char** ptr, struct cbuf* str);
 179
 180
 181 #endif /* __SRPRS_H */