TLA Line data Source code
1 : //
2 : // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3 : // Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
4 : //
5 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
6 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 : //
8 : // Official repository: https://github.com/boostorg/json
9 : //
10 :
11 : #ifndef BOOST_JSON_BASIC_PARSER_HPP
12 : #define BOOST_JSON_BASIC_PARSER_HPP
13 :
14 : #include <boost/json/detail/config.hpp>
15 : #include <boost/json/detail/except.hpp>
16 : #include <boost/json/error.hpp>
17 : #include <boost/json/kind.hpp>
18 : #include <boost/json/parse_options.hpp>
19 : #include <boost/json/detail/stack.hpp>
20 : #include <boost/json/detail/stream.hpp>
21 : #include <boost/json/detail/utf8.hpp>
22 : #include <boost/json/detail/sbo_buffer.hpp>
23 :
24 : namespace boost {
25 : namespace json {
26 :
27 : /** An incremental SAX parser for serialized JSON.
28 :
29 : This implements a SAX-style parser, invoking a
30 : caller-supplied handler with each parsing event.
31 : To use, first declare a variable of type
32 : `basic_parser<T>` where `T` meets the handler
33 : requirements specified below. Then call
34 : @ref write_some one or more times with the input,
35 : setting `more = false` on the final buffer.
36 : The parsing events are realized through member
37 : function calls on the handler, which exists
38 : as a data member of the parser.
39 : \n
40 : The parser may dynamically allocate intermediate
41 : storage as needed to accommodate the nesting level
42 : of the input JSON. On subsequent invocations, the
43 : parser can cheaply re-use this memory, improving
44 : performance. This storage is freed when the
45 : parser is destroyed
46 :
47 : @par Usage
48 :
49 : To get the declaration and function definitions
50 : for this class it is necessary to include this
51 : file instead:
52 : @code
53 : #include <boost/json/basic_parser_impl.hpp>
54 : @endcode
55 :
56 : Users who wish to parse JSON into the DOM container
57 : @ref value will not use this class directly; instead
58 : they will create an instance of @ref parser or
59 : @ref stream_parser and use that instead. Alternatively,
60 : they may call the function @ref parse. This class is
61 : designed for users who wish to perform custom actions
62 : instead of building a @ref value. For example, to
63 : produce a DOM from an external library.
64 : \n
65 : @note
66 :
67 : By default, only conforming JSON using UTF-8
68 : encoding is accepted. However, select non-compliant
69 : syntax can be allowed by construction using a
70 : @ref parse_options set to desired values.
71 :
72 : @par Handler
73 :
74 : The handler provided must be implemented as an
75 : object of class type which defines each of the
76 : required event member functions below. The event
77 : functions return a `bool` where `true` indicates
78 : success, and `false` indicates failure. If the
79 : member function returns `false`, it must set
80 : the error code to a suitable value. This error
81 : code will be returned by the write function to
82 : the caller.
83 : \n
84 : Handlers are required to declare the maximum
85 : limits on various elements. If these limits
86 : are exceeded during parsing, then parsing
87 : fails with an error.
88 : \n
89 : The following declaration meets the parser's
90 : handler requirements:
91 :
92 : @code
93 : struct handler
94 : {
95 : /// The maximum number of elements allowed in an array
96 : static constexpr std::size_t max_array_size = -1;
97 :
98 : /// The maximum number of elements allowed in an object
99 : static constexpr std::size_t max_object_size = -1;
100 :
101 : /// The maximum number of characters allowed in a string
102 : static constexpr std::size_t max_string_size = -1;
103 :
104 : /// The maximum number of characters allowed in a key
105 : static constexpr std::size_t max_key_size = -1;
106 :
107 : /// Called once when the JSON parsing begins.
108 : ///
109 : /// @return `true` on success.
110 : /// @param ec Set to the error, if any occurred.
111 : ///
112 : bool on_document_begin( error_code& ec );
113 :
114 : /// Called when the JSON parsing is done.
115 : ///
116 : /// @return `true` on success.
117 : /// @param ec Set to the error, if any occurred.
118 : ///
119 : bool on_document_end( error_code& ec );
120 :
121 : /// Called when the beginning of an array is encountered.
122 : ///
123 : /// @return `true` on success.
124 : /// @param ec Set to the error, if any occurred.
125 : ///
126 : bool on_array_begin( error_code& ec );
127 :
128 : /// Called when the end of the current array is encountered.
129 : ///
130 : /// @return `true` on success.
131 : /// @param n The number of elements in the array.
132 : /// @param ec Set to the error, if any occurred.
133 : ///
134 : bool on_array_end( std::size_t n, error_code& ec );
135 :
136 : /// Called when the beginning of an object is encountered.
137 : ///
138 : /// @return `true` on success.
139 : /// @param ec Set to the error, if any occurred.
140 : ///
141 : bool on_object_begin( error_code& ec );
142 :
143 : /// Called when the end of the current object is encountered.
144 : ///
145 : /// @return `true` on success.
146 : /// @param n The number of elements in the object.
147 : /// @param ec Set to the error, if any occurred.
148 : ///
149 : bool on_object_end( std::size_t n, error_code& ec );
150 :
151 : /// Called with characters corresponding to part of the current string.
152 : ///
153 : /// @return `true` on success.
154 : /// @param s The partial characters
155 : /// @param n The total size of the string thus far
156 : /// @param ec Set to the error, if any occurred.
157 : ///
158 : bool on_string_part( string_view s, std::size_t n, error_code& ec );
159 :
160 : /// Called with the last characters corresponding to the current string.
161 : ///
162 : /// @return `true` on success.
163 : /// @param s The remaining characters
164 : /// @param n The total size of the string
165 : /// @param ec Set to the error, if any occurred.
166 : ///
167 : bool on_string( string_view s, std::size_t n, error_code& ec );
168 :
169 : /// Called with characters corresponding to part of the current key.
170 : ///
171 : /// @return `true` on success.
172 : /// @param s The partial characters
173 : /// @param n The total size of the key thus far
174 : /// @param ec Set to the error, if any occurred.
175 : ///
176 : bool on_key_part( string_view s, std::size_t n, error_code& ec );
177 :
178 : /// Called with the last characters corresponding to the current key.
179 : ///
180 : /// @return `true` on success.
181 : /// @param s The remaining characters
182 : /// @param n The total size of the key
183 : /// @param ec Set to the error, if any occurred.
184 : ///
185 : bool on_key( string_view s, std::size_t n, error_code& ec );
186 :
187 : /// Called with the characters corresponding to part of the current number.
188 : ///
189 : /// @return `true` on success.
190 : /// @param s The partial characters
191 : /// @param ec Set to the error, if any occurred.
192 : ///
193 : bool on_number_part( string_view s, error_code& ec );
194 :
195 : /// Called when a signed integer is parsed.
196 : ///
197 : /// @return `true` on success.
198 : /// @param i The value
199 : /// @param s The remaining characters
200 : /// @param ec Set to the error, if any occurred.
201 : ///
202 : bool on_int64( int64_t i, string_view s, error_code& ec );
203 :
204 : /// Called when an unsigend integer is parsed.
205 : ///
206 : /// @return `true` on success.
207 : /// @param u The value
208 : /// @param s The remaining characters
209 : /// @param ec Set to the error, if any occurred.
210 : ///
211 : bool on_uint64( uint64_t u, string_view s, error_code& ec );
212 :
213 : /// Called when a double is parsed.
214 : ///
215 : /// @return `true` on success.
216 : /// @param d The value
217 : /// @param s The remaining characters
218 : /// @param ec Set to the error, if any occurred.
219 : ///
220 : bool on_double( double d, string_view s, error_code& ec );
221 :
222 : /// Called when a boolean is parsed.
223 : ///
224 : /// @return `true` on success.
225 : /// @param b The value
226 : /// @param s The remaining characters
227 : /// @param ec Set to the error, if any occurred.
228 : ///
229 : bool on_bool( bool b, error_code& ec );
230 :
231 : /// Called when a null is parsed.
232 : ///
233 : /// @return `true` on success.
234 : /// @param ec Set to the error, if any occurred.
235 : ///
236 : bool on_null( error_code& ec );
237 :
238 : /// Called with characters corresponding to part of the current comment.
239 : ///
240 : /// @return `true` on success.
241 : /// @param s The partial characters.
242 : /// @param ec Set to the error, if any occurred.
243 : ///
244 : bool on_comment_part( string_view s, error_code& ec );
245 :
246 : /// Called with the last characters corresponding to the current comment.
247 : ///
248 : /// @return `true` on success.
249 : /// @param s The remaining characters
250 : /// @param ec Set to the error, if any occurred.
251 : ///
252 : bool on_comment( string_view s, error_code& ec );
253 : };
254 : @endcode
255 :
256 : @see
257 : @ref parse,
258 : @ref stream_parser,
259 : [Validating parser example](../../doc/html/json/examples.html#json.examples.validate).
260 :
261 : @headerfile <boost/json/basic_parser.hpp>
262 : */
263 : template<class Handler>
264 : class basic_parser
265 : {
266 : enum class state : char
267 : {
268 : doc1, doc3,
269 : com1, com2, com3, com4,
270 : lit1,
271 : str1, str2, str3, str4,
272 : str5, str6, str7, str8,
273 : sur1, sur2, sur3,
274 : sur4, sur5, sur6,
275 : obj1, obj2, obj3, obj4,
276 : obj5, obj6, obj7, obj8,
277 : obj9, obj10, obj11,
278 : arr1, arr2, arr3,
279 : arr4, arr5, arr6,
280 : num1, num2, num3, num4,
281 : num5, num6, num7, num8,
282 : exp1, exp2, exp3,
283 : val1, val2, val3
284 : };
285 :
286 : struct number
287 : {
288 : uint64_t mant;
289 : int bias;
290 : int exp;
291 : bool frac;
292 : bool neg;
293 : };
294 :
295 : template< bool StackEmpty_, char First_ >
296 : struct parse_number_helper;
297 :
298 : // optimization: must come first
299 : Handler h_;
300 :
301 : number num_;
302 : system::error_code ec_;
303 : detail::stack st_;
304 : detail::utf8_sequence seq_;
305 : unsigned u1_;
306 : unsigned u2_;
307 : bool more_; // false for final buffer
308 : bool done_ = false; // true on complete parse
309 : bool clean_ = true; // write_some exited cleanly
310 : const char* end_;
311 : detail::sbo_buffer<16 + 16 + 1 + 1> num_buf_;
312 : parse_options opt_;
313 : // how many levels deeper the parser can go
314 : std::size_t depth_ = opt_.max_depth;
315 : unsigned char cur_lit_ = 0;
316 : unsigned char lit_offset_ = 0;
317 :
318 : inline void reserve();
319 : inline const char* sentinel();
320 : inline bool incomplete(
321 : const detail::const_stream_wrapper& cs);
322 :
323 : #ifdef __INTEL_COMPILER
324 : #pragma warning push
325 : #pragma warning disable 2196
326 : #endif
327 :
328 : BOOST_NOINLINE
329 : inline
330 : const char*
331 : suspend_or_fail(state st);
332 :
333 : BOOST_NOINLINE
334 : inline
335 : const char*
336 : suspend_or_fail(
337 : state st,
338 : std::size_t n);
339 :
340 : BOOST_NOINLINE
341 : inline
342 : const char*
343 : fail(const char* p) noexcept;
344 :
345 : BOOST_NOINLINE
346 : inline
347 : const char*
348 : fail(
349 : const char* p,
350 : error ev,
351 : source_location const* loc) noexcept;
352 :
353 : BOOST_NOINLINE
354 : inline
355 : const char*
356 : maybe_suspend(
357 : const char* p,
358 : state st);
359 :
360 : BOOST_NOINLINE
361 : inline
362 : const char*
363 : maybe_suspend(
364 : const char* p,
365 : state st,
366 : std::size_t n);
367 :
368 : BOOST_NOINLINE
369 : inline
370 : const char*
371 : maybe_suspend(
372 : const char* p,
373 : state st,
374 : const number& num);
375 :
376 : BOOST_NOINLINE
377 : inline
378 : const char*
379 : suspend(
380 : const char* p,
381 : state st);
382 :
383 : BOOST_NOINLINE
384 : inline
385 : const char*
386 : suspend(
387 : const char* p,
388 : state st,
389 : const number& num);
390 :
391 : #ifdef __INTEL_COMPILER
392 : #pragma warning pop
393 : #endif
394 :
395 : template<bool StackEmpty_/*, bool Terminal_*/>
396 : const char* parse_comment(const char* p,
397 : std::integral_constant<bool, StackEmpty_> stack_empty,
398 : /*std::integral_constant<bool, Terminal_>*/ bool terminal);
399 :
400 : template<bool StackEmpty_>
401 : const char* parse_document(const char* p,
402 : std::integral_constant<bool, StackEmpty_> stack_empty);
403 :
404 : template<bool StackEmpty_, bool AllowComments_/*,
405 : bool AllowTrailing_, bool AllowBadUTF8_*/>
406 : const char* parse_value(const char* p,
407 : std::integral_constant<bool, StackEmpty_> stack_empty,
408 : std::integral_constant<bool, AllowComments_> allow_comments,
409 : /*std::integral_constant<bool, AllowTrailing_>*/ bool allow_trailing,
410 : /*std::integral_constant<bool, AllowBadUTF8_>*/ bool allow_bad_utf8,
411 : bool allow_bad_utf16);
412 :
413 : template<bool AllowComments_/*,
414 : bool AllowTrailing_, bool AllowBadUTF8_*/>
415 : const char* resume_value(const char* p,
416 : std::integral_constant<bool, AllowComments_> allow_comments,
417 : /*std::integral_constant<bool, AllowTrailing_>*/ bool allow_trailing,
418 : /*std::integral_constant<bool, AllowBadUTF8_>*/ bool allow_bad_utf8,
419 : bool allow_bad_utf16);
420 :
421 : template<bool StackEmpty_, bool AllowComments_/*,
422 : bool AllowTrailing_, bool AllowBadUTF8_*/>
423 : const char* parse_object(const char* p,
424 : std::integral_constant<bool, StackEmpty_> stack_empty,
425 : std::integral_constant<bool, AllowComments_> allow_comments,
426 : /*std::integral_constant<bool, AllowTrailing_>*/ bool allow_trailing,
427 : /*std::integral_constant<bool, AllowBadUTF8_>*/ bool allow_bad_utf8,
428 : bool allow_bad_utf16);
429 :
430 : template<bool StackEmpty_, bool AllowComments_/*,
431 : bool AllowTrailing_, bool AllowBadUTF8_*/>
432 : const char* parse_array(const char* p,
433 : std::integral_constant<bool, StackEmpty_> stack_empty,
434 : std::integral_constant<bool, AllowComments_> allow_comments,
435 : /*std::integral_constant<bool, AllowTrailing_>*/ bool allow_trailing,
436 : /*std::integral_constant<bool, AllowBadUTF8_>*/ bool allow_bad_utf8,
437 : bool allow_bad_utf16);
438 :
439 : template<class Literal>
440 : const char* parse_literal(const char* p, Literal literal);
441 :
442 : template<bool StackEmpty_, bool IsKey_>
443 : const char* parse_string(const char* p,
444 : std::integral_constant<bool, StackEmpty_> stack_empty,
445 : std::integral_constant<bool, IsKey_> is_key,
446 : bool allow_bad_utf8,
447 : bool allow_bad_utf16);
448 :
449 : template<bool StackEmpty_>
450 : const char* parse_escaped(
451 : const char* p,
452 : std::size_t& total,
453 : std::integral_constant<bool, StackEmpty_> stack_empty,
454 : bool is_key,
455 : bool allow_bad_utf16);
456 :
457 : template<bool StackEmpty_, char First_, number_precision Numbers_>
458 : const char* parse_number(const char* p,
459 : std::integral_constant<bool, StackEmpty_> stack_empty,
460 : std::integral_constant<char, First_> first,
461 : std::integral_constant<number_precision, Numbers_> numbers);
462 :
463 : // intentionally private
464 : std::size_t
465 HIT 173315 : depth() const noexcept
466 : {
467 173315 : return opt_.max_depth - depth_;
468 : }
469 :
470 : public:
471 : /// Copy constructor (deleted)
472 : basic_parser(
473 : basic_parser const&) = delete;
474 :
475 : /// Copy assignment (deleted)
476 : basic_parser& operator=(
477 : basic_parser const&) = delete;
478 :
479 : /** Destructor.
480 :
481 : All dynamically allocated internal memory is freed.
482 :
483 : @par Effects
484 : @code
485 : this->handler().~Handler()
486 : @endcode
487 :
488 : @par Complexity
489 : Same as `~Handler()`.
490 :
491 : @par Exception Safety
492 : Same as `~Handler()`.
493 : */
494 2164639 : ~basic_parser() = default;
495 :
496 : /** Constructor.
497 :
498 : This function constructs the parser with
499 : the specified options, with any additional
500 : arguments forwarded to the handler's constructor.
501 :
502 : @par Complexity
503 : Same as `Handler( std::forward< Args >( args )... )`.
504 :
505 : @par Exception Safety
506 : Same as `Handler( std::forward< Args >( args )... )`.
507 :
508 : @param opt Configuration settings for the parser.
509 : If this structure is default constructed, the
510 : parser will accept only standard JSON.
511 :
512 : @param args Optional additional arguments
513 : forwarded to the handler's constructor.
514 : */
515 : template<class... Args>
516 : explicit
517 : basic_parser(
518 : parse_options const& opt,
519 : Args&&... args);
520 :
521 : /** Return a reference to the handler.
522 :
523 : This function provides access to the constructed
524 : instance of the handler owned by the parser.
525 :
526 : @par Complexity
527 : Constant.
528 :
529 : @par Exception Safety
530 : No-throw guarantee.
531 : */
532 : Handler&
533 6310634 : handler() noexcept
534 : {
535 6310634 : return h_;
536 : }
537 :
538 : /** Return a reference to the handler.
539 :
540 : This function provides access to the constructed
541 : instance of the handler owned by the parser.
542 :
543 : @par Complexity
544 : Constant.
545 :
546 : @par Exception Safety
547 : No-throw guarantee.
548 : */
549 : Handler const&
550 24 : handler() const noexcept
551 : {
552 24 : return h_;
553 : }
554 :
555 : /** Return the last error.
556 :
557 : This returns the last error code which
558 : was generated in the most recent call
559 : to @ref write_some.
560 :
561 : @par Complexity
562 : Constant.
563 :
564 : @par Exception Safety
565 : No-throw guarantee.
566 : */
567 : system::error_code
568 8 : last_error() const noexcept
569 : {
570 8 : return ec_;
571 : }
572 :
573 : /** Return true if a complete JSON has been parsed.
574 :
575 : This function returns `true` when all of these
576 : conditions are met:
577 :
578 : @li A complete serialized JSON has been
579 : presented to the parser, and
580 :
581 : @li No error or exception has occurred since the
582 : parser was constructed, or since the last call
583 : to @ref reset,
584 :
585 : @par Complexity
586 : Constant.
587 :
588 : @par Exception Safety
589 : No-throw guarantee.
590 : */
591 : bool
592 4078231 : done() const noexcept
593 : {
594 4078231 : return done_;
595 : }
596 :
597 : /** Reset the state, to parse a new document.
598 :
599 : This function discards the current parsing
600 : state, to prepare for parsing a new document.
601 : Dynamically allocated temporary memory used
602 : by the implementation is not deallocated.
603 :
604 : @par Complexity
605 : Constant.
606 :
607 : @par Exception Safety
608 : No-throw guarantee.
609 : */
610 : void
611 : reset() noexcept;
612 :
613 : /** Indicate a parsing failure.
614 :
615 : This changes the state of the parser to indicate
616 : that the parse has failed. A parser implementation
617 : can use this to fail the parser if needed due to
618 : external inputs.
619 :
620 : @note
621 :
622 : If `!ec`, the stored error code is unspecified.
623 :
624 : @par Complexity
625 : Constant.
626 :
627 : @par Exception Safety
628 : No-throw guarantee.
629 :
630 : @param ec The error code to set. If the code does
631 : not indicate failure, an implementation-defined
632 : error code that indicates failure will be stored
633 : instead.
634 : */
635 : void
636 : fail(system::error_code ec) noexcept;
637 :
638 : /** Parse some of an input string as JSON, incrementally.
639 :
640 : This function parses the JSON in the specified
641 : buffer, calling the handler to emit each SAX
642 : parsing event. The parse proceeds from the
643 : current state, which is at the beginning of a
644 : new JSON or in the middle of the current JSON
645 : if any characters were already parsed.
646 : \n
647 : The characters in the buffer are processed
648 : starting from the beginning, until one of the
649 : following conditions is met:
650 :
651 : @li All of the characters in the buffer
652 : have been parsed, or
653 :
654 : @li Some of the characters in the buffer
655 : have been parsed and the JSON is complete, or
656 :
657 : @li A parsing error occurs.
658 :
659 : The supplied buffer does not need to contain the
660 : entire JSON. Subsequent calls can provide more
661 : serialized data, allowing JSON to be processed
662 : incrementally. The end of the serialized JSON
663 : can be indicated by passing `more = false`.
664 :
665 : @par Complexity
666 : Linear in `size`.
667 :
668 : @par Exception Safety
669 : Basic guarantee.
670 : Calls to the handler may throw.
671 : Upon error or exception, subsequent calls will
672 : fail until @ref reset is called to parse a new JSON.
673 :
674 : @return The number of characters successfully
675 : parsed, which may be smaller than `size`.
676 :
677 : @param more `true` if there are possibly more
678 : buffers in the current JSON, otherwise `false`.
679 :
680 : @param data A pointer to a buffer of `size`
681 : characters to parse.
682 :
683 : @param size The number of characters pointed to
684 : by `data`.
685 :
686 : @param ec Set to the error, if any occurred.
687 : */
688 : /** @{ */
689 : std::size_t
690 : write_some(
691 : bool more,
692 : char const* data,
693 : std::size_t size,
694 : system::error_code& ec);
695 :
696 : std::size_t
697 : write_some(
698 : bool more,
699 : char const* data,
700 : std::size_t size,
701 : std::error_code& ec);
702 : /** @} */
703 : };
704 :
705 : } // namespace json
706 : } // namespace boost
707 :
708 : #endif
|
