Line data Source code
1 : //
2 : // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
3 : //
4 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
5 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 : //
7 : // Official repository: https://github.com/boostorg/url
8 : //
9 :
10 : #ifndef BOOST_URL_GRAMMAR_RANGE_RULE_HPP
11 : #define BOOST_URL_GRAMMAR_RANGE_RULE_HPP
12 :
13 : #include <boost/url/detail/config.hpp>
14 : #include <boost/url/error.hpp>
15 : #include <boost/core/detail/string_view.hpp>
16 : #include <boost/url/grammar/parse.hpp>
17 : #include <boost/url/grammar/type_traits.hpp>
18 : #include <boost/core/detail/static_assert.hpp>
19 : #include <cstddef>
20 : #include <iterator>
21 : #include <type_traits>
22 : #include <stddef.h> // ::max_align_t
23 :
24 : namespace boost {
25 : namespace urls {
26 : namespace grammar {
27 : namespace implementation_defined {
28 : template<class R0, class R1>
29 : struct range_rule_t;
30 : } // implementation_defined
31 :
32 : /** A forward range of parsed elements
33 :
34 : Objects of this type are forward ranges
35 : returned when parsing using the
36 : @ref range_rule.
37 : Iteration is performed by re-parsing the
38 : underlying character buffer. Ownership
39 : of the buffer is not transferred; the
40 : caller is responsible for ensuring that
41 : the lifetime of the buffer extends until
42 : it is no longer referenced by the range.
43 :
44 : @note
45 :
46 : The implementation may use temporary,
47 : recycled storage for type-erasure. Objects
48 : of type `range` are intended to be used
49 : ephemerally. That is, for short durations
50 : such as within a function scope. If it is
51 : necessary to store the range for a long
52 : period of time or with static storage
53 : duration, it is necessary to copy the
54 : contents to an object of a different type.
55 :
56 : @tparam T The value type of the range
57 :
58 : @see
59 : @ref parse,
60 : @ref range_rule.
61 : */
62 : template<class T>
63 : class range
64 : {
65 : // buffer size for type-erased rule
66 : static constexpr
67 : std::size_t BufferSize = 128;
68 :
69 : struct small_buffer
70 : {
71 : alignas(alignof(::max_align_t))
72 : unsigned char buf[BufferSize];
73 :
74 707 : void const* addr() const noexcept
75 : {
76 707 : return buf;
77 : }
78 :
79 3317 : void* addr() noexcept
80 : {
81 3317 : return buf;
82 : }
83 : };
84 :
85 : small_buffer sb_;
86 : core::string_view s_;
87 : std::size_t n_ = 0;
88 :
89 : //--------------------------------------------
90 :
91 : struct any_rule;
92 :
93 : template<class R, bool>
94 : struct impl1;
95 :
96 : template<
97 : class R0, class R1, bool>
98 : struct impl2;
99 :
100 : template<
101 : class R0, class R1>
102 : friend struct implementation_defined::range_rule_t;
103 :
104 : any_rule&
105 3317 : get() noexcept
106 : {
107 : return *reinterpret_cast<
108 3317 : any_rule*>(sb_.addr());
109 : }
110 :
111 : any_rule const&
112 707 : get() const noexcept
113 : {
114 : return *reinterpret_cast<
115 : any_rule const*>(
116 707 : sb_.addr());
117 : }
118 :
119 : template<class R>
120 : range(
121 : core::string_view s,
122 : std::size_t n,
123 : R const& r);
124 :
125 : template<
126 : class R0, class R1>
127 : range(
128 : core::string_view s,
129 : std::size_t n,
130 : R0 const& first,
131 : R1 const& next);
132 :
133 : public:
134 : /** The type of each element of the range
135 : */
136 : using value_type = T;
137 :
138 : /** The type of each element of the range
139 : */
140 : using reference = T const&;
141 :
142 : /** The type of each element of the range
143 : */
144 : using const_reference = T const&;
145 :
146 : /** Provided for compatibility, unused
147 : */
148 : using pointer = void const*;
149 :
150 : /** The type used to represent unsigned integers
151 : */
152 : using size_type = std::size_t;
153 :
154 : /** The type used to represent signed integers
155 : */
156 : using difference_type = std::ptrdiff_t;
157 :
158 : /** A constant, forward iterator to elements of the range
159 : */
160 : class iterator;
161 :
162 : /** A constant, forward iterator to elements of the range
163 : */
164 : using const_iterator = iterator;
165 :
166 : /** Destructor
167 : */
168 : ~range();
169 :
170 : /** Constructor
171 :
172 : Default-constructed ranges have
173 : zero elements.
174 :
175 : @par Exception Safety
176 : Throws nothing.
177 : */
178 : range() noexcept;
179 :
180 : /** Constructor
181 :
182 : The new range references the
183 : same underlying character buffer.
184 : Ownership is not transferred; the
185 : caller is responsible for ensuring
186 : that the lifetime of the buffer
187 : extends until it is no longer
188 : referenced. The moved-from object
189 : becomes as if default-constructed.
190 :
191 : @par Exception Safety
192 : Throws nothing.
193 : */
194 : range(range&&) noexcept;
195 :
196 : /** Constructor
197 :
198 : The copy references the same
199 : underlying character buffer.
200 : Ownership is not transferred; the
201 : caller is responsible for ensuring
202 : that the lifetime of the buffer
203 : extends until it is no longer
204 : referenced.
205 :
206 : @par Exception Safety
207 : Throws nothing.
208 : */
209 : range(range const&) noexcept;
210 :
211 : /** Assignment
212 :
213 : After the move, this references the
214 : same underlying character buffer. Ownership
215 : is not transferred; the caller is responsible
216 : for ensuring that the lifetime of the buffer
217 : extends until it is no longer referenced.
218 : The moved-from object becomes as if
219 : default-constructed.
220 :
221 : @par Exception Safety
222 : Throws nothing.
223 :
224 : @return `*this`
225 : */
226 : range&
227 : operator=(range&&) noexcept;
228 :
229 : /** Assignment
230 :
231 : The copy references the same
232 : underlying character buffer.
233 : Ownership is not transferred; the
234 : caller is responsible for ensuring
235 : that the lifetime of the buffer
236 : extends until it is no longer
237 : referenced.
238 :
239 : @par Exception Safety
240 : Throws nothing.
241 :
242 : @return `*this`
243 : */
244 : range&
245 : operator=(range const&) noexcept;
246 :
247 : /** Return an iterator to the beginning
248 :
249 : @return An iterator to the first element
250 : */
251 : iterator begin() const noexcept;
252 :
253 : /** Return an iterator to the end
254 :
255 : @return An iterator to one past the last element
256 : */
257 : iterator end() const noexcept;
258 :
259 : /** Return true if the range is empty
260 :
261 : @return `true` if the range is empty
262 : */
263 : bool
264 11 : empty() const noexcept
265 : {
266 11 : return n_ == 0;
267 : }
268 :
269 : /** Return the number of elements in the range
270 :
271 : @return The number of elements
272 : */
273 : std::size_t
274 34 : size() const noexcept
275 : {
276 34 : return n_;
277 : }
278 :
279 : /** Return the matching part of the string
280 :
281 : @return A string view representing the range
282 : */
283 : core::string_view
284 19 : string() const noexcept
285 : {
286 19 : return s_;
287 : }
288 : };
289 :
290 : //------------------------------------------------
291 :
292 : namespace implementation_defined {
293 : template<
294 : class R0,
295 : class R1 = void>
296 : struct range_rule_t;
297 : }
298 :
299 : //------------------------------------------------
300 :
301 : namespace implementation_defined {
302 : template<class R>
303 : struct range_rule_t<R>
304 : {
305 : using value_type =
306 : range<typename R::value_type>;
307 :
308 : system::result<value_type>
309 : parse(
310 : char const*& it,
311 : char const* end) const;
312 :
313 : constexpr
314 18 : range_rule_t(
315 : R const& next,
316 : std::size_t N,
317 : std::size_t M) noexcept
318 18 : : next_(next)
319 18 : , N_(N)
320 18 : , M_(M)
321 : {
322 18 : }
323 :
324 : private:
325 : R const next_;
326 : std::size_t N_;
327 : std::size_t M_;
328 : };
329 : } // implementation_defined
330 :
331 : /** Match a repeating number of elements
332 :
333 : Elements are matched using the passed rule.
334 : <br>
335 : Normally when the rule returns an error,
336 : the range ends and the input is rewound to
337 : one past the last character that matched
338 : successfully. However, if the rule returns
339 : the special value @ref error::end_of_range, the
340 : input is not rewound. This allows for rules
341 : which consume input without producing
342 : elements in the range. For example, to
343 : relax the grammar for a comma-delimited
344 : list by allowing extra commas in between
345 : elements.
346 :
347 : @par Value Type
348 : @code
349 : using value_type = range< typename Rule::value_type >;
350 : @endcode
351 :
352 : @par Example
353 : Rules are used with the function @ref parse.
354 : @code
355 : // range = 1*( ";" token )
356 :
357 : system::result< range<core::string_view> > rv = parse( ";alpha;xray;charlie",
358 : range_rule(
359 : tuple_rule(
360 : squelch( delim_rule( ';' ) ),
361 : token_rule( alpha_chars ) ),
362 : 1 ) );
363 : @endcode
364 :
365 : @par BNF
366 : @code
367 : range = <N>*<M>next
368 : @endcode
369 :
370 : @par Specification
371 : @li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
372 : >3.6. Variable Repetition (rfc5234)</a>
373 :
374 : @param next The rule to use for matching
375 : each element. The range extends until this
376 : rule returns an error.
377 :
378 : @param N The minimum number of elements for
379 : the range to be valid. If omitted, this
380 : defaults to zero.
381 :
382 : @param M The maximum number of elements for
383 : the range to be valid. If omitted, this
384 : defaults to unlimited.
385 :
386 : @return A rule that matches the range.
387 :
388 : @see
389 : @ref alpha_chars,
390 : @ref delim_rule,
391 : @ref error::end_of_range,
392 : @ref parse,
393 : @ref range,
394 : @ref tuple_rule,
395 : @ref squelch.
396 : */
397 : template<BOOST_URL_CONSTRAINT(Rule) R>
398 : constexpr
399 : implementation_defined::range_rule_t<R>
400 18 : range_rule(
401 : R const& next,
402 : std::size_t N = 0,
403 : std::size_t M =
404 : std::size_t(-1)) noexcept
405 : {
406 : // If you get a compile error here it
407 : // means that your rule does not meet
408 : // the type requirements. Please check
409 : // the documentation.
410 : static_assert(
411 : is_rule<R>::value,
412 : "Rule requirements not met");
413 :
414 : return implementation_defined::range_rule_t<R>{
415 18 : next, N, M};
416 : }
417 :
418 : //------------------------------------------------
419 :
420 : namespace implementation_defined {
421 : template<class R0, class R1>
422 : struct range_rule_t
423 : {
424 : using value_type =
425 : range<typename R0::value_type>;
426 :
427 : system::result<value_type>
428 : parse(
429 : char const*& it,
430 : char const* end) const;
431 :
432 : constexpr
433 1 : range_rule_t(
434 : R0 const& first,
435 : R1 const& next,
436 : std::size_t N,
437 : std::size_t M) noexcept
438 1 : : first_(first)
439 1 : , next_(next)
440 1 : , N_(N)
441 1 : , M_(M)
442 : {
443 1 : }
444 :
445 : private:
446 : R0 const first_;
447 : R1 const next_;
448 : std::size_t N_;
449 : std::size_t M_;
450 : };
451 : } // implementation_defined
452 :
453 : /** Match a repeating number of elements
454 :
455 : Two rules are used for match. The rule
456 : `first` is used for matching the first
457 : element, while the `next` rule is used
458 : to match every subsequent element.
459 : <br>
460 : Normally when the rule returns an error,
461 : the range ends and the input is rewound to
462 : one past the last character that matched
463 : successfully. However, if the rule returns
464 : the special value @ref error::end_of_range, the
465 : input is not rewound. This allows for rules
466 : which consume input without producing
467 : elements in the range. For example, to
468 : relax the grammar for a comma-delimited
469 : list by allowing extra commas in between
470 : elements.
471 :
472 : @par Value Type
473 : @code
474 : using value_type = range< typename Rule::value_type >;
475 : @endcode
476 :
477 : @par Example
478 : Rules are used with the function @ref parse.
479 : @code
480 : // range = [ token ] *( "," token )
481 :
482 : system::result< range< core::string_view > > rv = parse( "whiskey,tango,foxtrot",
483 : range_rule(
484 : token_rule( alpha_chars ), // first
485 : tuple_rule( // next
486 : squelch( delim_rule(',') ),
487 : token_rule( alpha_chars ) ) ) );
488 : @endcode
489 :
490 : @par BNF
491 : @code
492 : range = <1>*<1>first
493 : / first <N-1>*<M-1>next
494 : @endcode
495 :
496 : @par Specification
497 : @li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
498 : >3.6. Variable Repetition (rfc5234)</a>
499 :
500 : @param first The rule to use for matching
501 : the first element. If this rule returns
502 : an error, the range is empty.
503 :
504 : @param next The rule to use for matching
505 : each subsequent element. The range extends
506 : until this rule returns an error.
507 :
508 : @param N The minimum number of elements for
509 : the range to be valid. If omitted, this
510 : defaults to zero.
511 :
512 : @param M The maximum number of elements for
513 : the range to be valid. If omitted, this
514 : defaults to unlimited.
515 :
516 : @return A rule that matches the range.
517 :
518 : @see
519 : @ref alpha_chars,
520 : @ref delim_rule,
521 : @ref error::end_of_range,
522 : @ref parse,
523 : @ref range,
524 : @ref tuple_rule,
525 : @ref squelch.
526 : */
527 : template<
528 : BOOST_URL_CONSTRAINT(Rule) R1,
529 : BOOST_URL_CONSTRAINT(Rule) R2>
530 : constexpr
531 : auto
532 1 : range_rule(
533 : R1 const& first,
534 : R2 const& next,
535 : std::size_t N = 0,
536 : std::size_t M =
537 : std::size_t(-1)) noexcept ->
538 : #if 1
539 : typename std::enable_if<
540 : ! std::is_integral<R2>::value,
541 : implementation_defined::range_rule_t<R1, R2>>::type
542 : #else
543 : range_rule_t<R1, R2>
544 : #endif
545 : {
546 : // If you get a compile error here it
547 : // means that your rule does not meet
548 : // the type requirements. Please check
549 : // the documentation.
550 : static_assert(
551 : is_rule<R1>::value,
552 : "Rule requirements not met");
553 : static_assert(
554 : is_rule<R2>::value,
555 : "Rule requirements not met");
556 :
557 : // If you get a compile error here it
558 : // means that your rules do not have
559 : // the exact same value_type. Please
560 : // check the documentation.
561 : static_assert(
562 : std::is_same<
563 : typename R1::value_type,
564 : typename R2::value_type>::value,
565 : "Rule requirements not met");
566 :
567 : return implementation_defined::range_rule_t<R1, R2>{
568 1 : first, next, N, M};
569 : }
570 :
571 : } // grammar
572 : } // urls
573 : } // boost
574 :
575 : #include <boost/url/grammar/impl/range_rule.hpp>
576 :
577 : #endif
|
