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 struct cbuf;
  38
  39 /**
  40  * Matches any amount of whitespace.
  41  *
  42  * @see isspace
  43  * @param ptr parse position
  44  *
  45  * @return true
  46  */
  47 bool srprs_skipws(const char** ptr);
  48
  49 /**
  50  * Match a single character.
  51  *
  52  * @param[in,out] ptr parse position
  53  * @param         c   the character to match
  54  *
  55  * @return true if matched
  56  */
  57 bool srprs_char(const char** ptr, char c);
  58
  59 /**
  60  * Match a string.
  61  *
  62  * @param[in,out] ptr parse position
  63  * @param str string to match
  64  * @param len number of bytes to compare, -1 means strlen(str)
  65  *
  66  * @return true if matched
  67  */
  68 bool srprs_str(const char** ptr, const char* str, ssize_t len);
  69
  70 /**
  71  * Match a single character from a set.
  72  * Didn't match '\\0'
  73  *
  74  * @param[in,out] ptr parse position
  75  * @param[in] set the character set to look for
  76  * @param[out] oss output buffer where to put the match, may be NULL
  77  *
  78  * @return true if matched
  79  */
  80 bool srprs_charset(const char** ptr, const char* set, struct cbuf* oss);
  81
  82 /**
  83  * Match a single character not in set.
  84  * Didn't match '\\0'
  85  *
  86  * @param[in,out] ptr parse position
  87  * @param[in] set the character set to look for
  88  * @param[out] oss output buffer where to put the match, may be NULL
  89  *
  90  * @return true if matched
  91  */
  92 bool srprs_charsetinv(const char** ptr, const char* set, struct cbuf* oss);
  93
  94 /**
  95  * Match a quoted string.
  96  *
  97  *
  98  * If cont is not NULL the match may span multiple invocations.
  99  * @code
 100  * const char* start = "\"start...";
 101  * const char* cont  = "continued...";
 102  * const char* end   = "end\"";
 103  * bool  cont = false;
 104  * cbuf* out  = cbuf_new(talloc_tos());
 105  * srprs_quoted_string(&start, out, &cont);
 106  * assert(*cont == true);
 107  * srprs_quoted_string(&cont, out, &cont);
 108  * assert(*cont == true);
 109  * srprs_quoted_string(&end, out, &cont);
 110  * assert(*cont == false);
 111  * assert(strcmp(cbuf_gets(out, 0), "start...continued...end")==0);
 112  * @endcode
 113  * @see cbuf_print_quoted_string
 114  *
 115  * @param[in,out] ptr parse position
 116  * @param[out] str output buffer where to put the match
 117  * @param[in,out] cont
 118  *
 119  * @return true if matched
 120  */
 121 bool srprs_quoted_string(const char** ptr, struct cbuf* str, bool* cont);
 122
 123 /**
 124  * Match a hex string.
 125  *
 126  * @param[in,out] ptr parse position
 127  * @param         len maximum number of digits to match
 128  * @param[out]    u   value of the match
 129  *
 130  * @return true if matched
 131  */
 132 bool srprs_hex(const char** ptr, size_t len, unsigned* u);
 133
 134 /**
 135  * Match the empty string at End Of String.
 136  * It doesn't consume the '\\0' unlike
 137  * @code
 138  *   srprs_char(ptr, '\0', NULL);
 139  * @endcode
 140  *
 141  * @param[in,out] ptr parse position
 142  *
 143  * @return true if **ptr == '\\0'
 144  */
 145 bool srprs_eos(const char** ptr);
 146
 147 /**
 148  * Match a newline.
 149  * A newline is either '\\n' (LF), '\\r' (CR), or "\r\n" (CRLF)
 150  *
 151  * @param[in,out] ptr parse position
 152  * @param[out]    nl  output buffer where to put the match, may be NULL
 153  *
 154  * @return true if matched
 155  */
 156 bool srprs_nl(const char** ptr, struct cbuf* nl);
 157
 158 /**
 159  * Match a newline or eos.
 160  *
 161  * @param ptr parse position
 162  * @param nl  output buffer where to put the match, may be NULL
 163  *
 164  * @return true if matched
 165  */
 166 bool srprs_eol(const char** ptr, struct cbuf* nl);
 167
 168 /**
 169  * Match a line up to but not including the newline.
 170  *
 171  * @param[in,out] ptr parse position
 172  * @param[out]    str output buffer where to put the match, may be NULL
 173  *
 174  * @return true
 175  */
 176 bool srprs_line(const char** ptr, struct cbuf* str);
 177
 178 /**
 179  * Match a quoted string with escaped characters.
 180  * @see cbuf_print_quoted
 181  *
 182  * @param[in,out] ptr parse position
 183  * @param[out] str output buffer where to put the match
 184  *
 185  * @return true if matched
 186  */
 187 bool srprs_quoted(const char** ptr, struct cbuf* str);
 188
 189 #endif /* __SRPRS_H */