docs: use the stdarg.option entity in the popt.common.samba entity
[Samba/gebeck_regimport.git] / source3 / lib / srprs.h
blobc1aec13e4af0cd0884c4955f525beeae60a917b9
1 /*
2 * Samba Unix/Linux SMB client library
4 * Copyright (C) Gregor Beck 2010
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.
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.
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/>.
20 /**
21 * @file srprs.h
22 * @author Gregor Beck <gb@sernet.de>
23 * @date Aug 2010
25 * @brief A simple recursive parser.
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.
34 #ifndef __SRPRS_H
35 #define __SRPRS_H
37 struct cbuf;
39 /**
40 * Matches any amount of whitespace.
42 * @see isspace
43 * @param ptr parse position
45 * @return true
47 bool srprs_skipws(const char** ptr);
49 /**
50 * Match a single character.
52 * @param[in,out] ptr parse position
53 * @param c the character to match
55 * @return true if matched
57 bool srprs_char(const char** ptr, char c);
59 /**
60 * Match a string.
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)
66 * @return true if matched
68 bool srprs_str(const char** ptr, const char* str, size_t len);
70 /**
71 * Match a single character from a set.
72 * Didn't match '\\0'
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
78 * @return true if matched
80 bool srprs_charset(const char** ptr, const char* set, struct cbuf* oss);
82 /**
83 * Match a single character not in set.
84 * Didn't match '\\0'
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
90 * @return true if matched
92 bool srprs_charsetinv(const char** ptr, const char* set, struct cbuf* oss);
94 /**
95 * Match a quoted string.
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
115 * @param[in,out] ptr parse position
116 * @param[out] str output buffer where to put the match
117 * @param[in,out] cont
119 * @return true if matched
121 bool srprs_quoted_string(const char** ptr, struct cbuf* str, bool* cont);
124 * Match a hex string.
126 * @param[in,out] ptr parse position
127 * @param len maximum number of diggits to match
128 * @param[out] u value of the match
130 * @return true if matched
132 bool srprs_hex(const char** ptr, size_t len, unsigned* u);
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
141 * @param[in,out] ptr parse position
143 * @return true if **ptr == '\\0'
145 bool srprs_eos(const char** ptr);
148 * Match a newline.
149 * A newline is either '\\n' (LF), '\\r' (CR), or "\r\n" (CRLF)
151 * @param[in,out] ptr parse position
152 * @param[out] nl output buffer where to put the match, may be NULL
154 * @return true if matched
156 bool srprs_nl(const char** ptr, struct cbuf* nl);
159 * Match a newline or eos.
161 * @param ptr parse position
162 * @param nl output buffer where to put the match, may be NULL
164 * @return true if matched
166 bool srprs_eol(const char** ptr, struct cbuf* nl);
169 * Match a line up to but not including the newline.
171 * @param[in,out] ptr parse position
172 * @param[out] str output buffer where to put the match, may be NULL
174 * @return true
176 bool srprs_line(const char** ptr, struct cbuf* str);
179 * Match a quoted string with escaped characters.
180 * @see cbuf_print_quoted
182 * @param[in,out] ptr parse position
183 * @param[out] str output buffer where to put the match
185 * @return true if matched
187 bool srprs_quoted(const char** ptr, struct cbuf* str);
189 #endif /* __SRPRS_H */