s3-docs: overrided -> overridden
[Samba.git] / source3 / lib / srprs.h
blob350e08c2c1810aee02309f8a62400083338262e7
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 #include <stddef.h>
38 #include <stdbool.h>
39 #include <stdint.h>
40 struct cbuf;
42 /**
43 * Matches any amount of whitespace.
45 * @see isspace
46 * @param ptr parse position
48 * @return true
50 bool srprs_skipws(const char** ptr);
52 /**
53 * Match a single character.
55 * @param[in,out] ptr parse position
56 * @param c the character to match
58 * @return true if matched
60 bool srprs_char(const char** ptr, char c);
62 /**
63 * Match a string.
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)
69 * @return true if matched
71 bool srprs_str(const char** ptr, const char* str, size_t len);
73 /**
74 * Match a single character from a set.
75 * Didn't match '\\0'
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
81 * @return true if matched
83 bool srprs_charset(const char** ptr, const char* set, struct cbuf* oss);
85 /**
86 * Match a single character not in set.
87 * Didn't match '\\0'
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
93 * @return true if matched
95 bool srprs_charsetinv(const char** ptr, const char* set, struct cbuf* oss);
97 /**
98 * Match a quoted string.
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
118 * @param[in,out] ptr parse position
119 * @param[out] str output buffer where to put the match
120 * @param[in,out] cont
122 * @return true if matched
124 bool srprs_quoted_string(const char** ptr, struct cbuf* str, bool* cont);
127 * Match a hex string.
129 * @param[in,out] ptr parse position
130 * @param len maximum number of diggits to match
131 * @param[out] u value of the match
133 * @return true if matched
135 bool srprs_hex(const char** ptr, size_t len, unsigned* u);
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
144 * @param[in,out] ptr parse position
146 * @return true if **ptr == '\\0'
148 bool srprs_eos(const char** ptr);
151 * Match a newline.
152 * A newline is either '\\n' (LF), '\\r' (CR), or "\r\n" (CRLF)
154 * @param[in,out] ptr parse position
155 * @param[out] nl output buffer where to put the match, may be NULL
157 * @return true if matched
159 bool srprs_nl(const char** ptr, struct cbuf* nl);
162 * Match a newline or eos.
164 * @param ptr parse position
165 * @param nl output buffer where to put the match, may be NULL
167 * @return true if matched
169 bool srprs_eol(const char** ptr, struct cbuf* nl);
172 * Match a line up to but not including the newline.
174 * @param[in,out] ptr parse position
175 * @param[out] str output buffer where to put the match, may be NULL
177 * @return true
179 bool srprs_line(const char** ptr, struct cbuf* str);
182 * Match a quoted string with escaped characters.
183 * @see cbuf_print_quoted
185 * @param[in,out] ptr parse position
186 * @param[out] str output buffer where to put the match
188 * @return true if matched
190 bool srprs_quoted(const char** ptr, struct cbuf* str);
192 #endif /* __SRPRS_H */