Root/parser.hpp
Prev Index Next

parser.hpp

100.0% Lines (29/29) 100.0% Functions (11/11) -% Branches (0/0)
parser.hpp
Line Hits Source Code
1 //
2 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.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/json
8 //
9
10 #ifndef BOOST_JSON_PARSER_HPP
11 #define BOOST_JSON_PARSER_HPP
12
13 #include <boost/json/detail/config.hpp>
14 #include <boost/json/basic_parser.hpp>
15 #include <boost/json/storage_ptr.hpp>
16 #include <boost/json/value.hpp>
17 #include <boost/json/detail/handler.hpp>
18 #include <type_traits>
19 #include <cstddef>
20
21 namespace boost {
22 namespace json {
23
24 //----------------------------------------------------------
25
26 /** A DOM parser for JSON contained in a single buffer.
27
28 This class is used to parse a JSON text contained in a
29 single character buffer, into a @ref value container.
30
31 @par Usage
32
33 To use the parser first construct it, then optionally
34 call @ref reset to specify a @ref storage_ptr to use
35 for the resulting @ref value. Then call @ref write
36 to parse a character buffer containing a complete
37 JSON text. If the parse is successful, call @ref release
38 to take ownership of the value:
39 @code
40 parser p; // construct a parser
41 size_t n = p.write( "[1,2,3]" ); // parse a complete JSON text
42 assert( n == 7 ); // all characters consumed
43 value jv = p.release(); // take ownership of the value
44 @endcode
45
46 @par Extra Data
47
48 When the character buffer provided as input contains
49 additional data that is not part of the complete
50 JSON text, an error is returned. The @ref write_some
51 function is an alternative which allows the parse
52 to finish early, without consuming all the characters
53 in the buffer. This allows parsing of a buffer
54 containing multiple individual JSON texts or containing
55 different protocol data:
56 @code
57 parser p; // construct a parser
58 size_t n = p.write_some( "[1,2,3] null" ); // parse a complete JSON text
59 assert( n == 8 ); // only some characters consumed
60 value jv = p.release(); // take ownership of the value
61 @endcode
62
63 @par Temporary Storage
64
65 The parser may dynamically allocate temporary
66 storage as needed to accommodate the nesting level
67 of the JSON text being parsed. Temporary storage is
68 first obtained from an optional, caller-owned
69 buffer specified upon construction. When that
70 is exhausted, the next allocation uses the
71 `boost::container::pmr::memory_resource` passed to the constructor; if
72 no such argument is specified, the default memory
73 resource is used. Temporary storage is freed only
74 when the parser is destroyed; The performance of
75 parsing multiple JSON texts may be improved by reusing
76 the same parser instance.
77 \n
78 It is important to note that the `boost::container::pmr::memory_resource`
79 supplied upon construction is used for temporary
80 storage only, and not for allocating the elements
81 which make up the parsed value. That other memory
82 resource is optionally supplied in each call
83 to @ref reset.
84
85 @par Duplicate Keys
86
87 If there are object elements with duplicate keys;
88 that is, if multiple elements in an object have
89 keys that compare equal, only the last equivalent
90 element will be inserted.
91
92 @par Non-Standard JSON
93
94 The @ref parse_options structure optionally
95 provided upon construction is used to customize
96 some parameters of the parser, including which
97 non-standard JSON extensions should be allowed.
98 A default-constructed parse options allows only
99 standard JSON.
100
101 @par Thread Safety
102
103 Distinct instances may be accessed concurrently.
104 Non-const member functions of a shared instance
105 may not be called concurrently with any other
106 member functions of that instance.
107
108 @see
109 @ref parse,
110 @ref parse_options,
111 @ref stream_parser.
112 */
113 class parser
114 {
115 basic_parser<detail::handler> p_;
116
117 public:
118 /// Copy constructor (deleted)
119 parser(
120 parser const&) = delete;
121
122 /// Copy assignment (deleted)
123 parser& operator=(
124 parser const&) = delete;
125
126 /** Destructor.
127
128 All dynamically allocated memory, including
129 any incomplete parsing results, is freed.
130
131 @par Complexity
132 Linear in the size of partial results
133
134 @par Exception Safety
135 No-throw guarantee.
136 */
137 2001563 ~parser() = default;
138
139 /** Constructor.
140
141 This constructs a new parser which first uses
142 the caller-owned storage pointed to by `buffer`
143 for temporary storage, falling back to the memory
144 resource `sp` if needed. The parser will use the
145 specified parsing options.
146 \n
147 The parsed value will use the default memory
148 resource for storage. To use a different resource,
149 call @ref reset after construction.
150
151 @par Complexity
152 Constant.
153
154 @par Exception Safety
155 No-throw guarantee.
156
157 @param sp The memory resource to use for
158 temporary storage after `buffer` is exhausted.
159
160 @param opt The parsing options to use.
161
162 @param buffer A pointer to valid memory of at least
163 `size` bytes for the parser to use for temporary storage.
164 Ownership is not transferred, the caller is responsible
165 for ensuring the lifetime of the memory pointed to by
166 `buffer` extends until the parser is destroyed.
167
168 @param size The number of valid bytes in `buffer`.
169 */
170 BOOST_JSON_DECL
171 parser(
172 storage_ptr sp,
173 parse_options const& opt,
174 unsigned char* buffer,
175 std::size_t size) noexcept;
176
177 /** Constructor.
178
179 This constructs a new parser which uses the default
180 memory resource for temporary storage, and accepts
181 only strict JSON.
182 \n
183 The parsed value will use the default memory
184 resource for storage. To use a different resource,
185 call @ref reset after construction.
186
187 @par Complexity
188 Constant.
189
190 @par Exception Safety
191 No-throw guarantee.
192 */
193 53 parser() noexcept
194 53 : parser({}, {})
195 {
196 53 }
197
198 /** Constructor.
199
200 This constructs a new parser which uses the
201 specified memory resource for temporary storage,
202 and is configured to use the specified parsing
203 options.
204 \n
205 The parsed value will use the default memory
206 resource for storage. To use a different resource,
207 call @ref reset after construction.
208
209 @par Complexity
210 Constant.
211
212 @par Exception Safety
213 No-throw guarantee.
214
215 @param sp The memory resource to use for temporary storage.
216
217 @param opt The parsing options to use.
218 */
219 BOOST_JSON_DECL
220 parser(
221 storage_ptr sp,
222 parse_options const& opt) noexcept;
223
224 /** Constructor.
225
226 This constructs a new parser which uses the
227 specified memory resource for temporary storage,
228 and accepts only strict JSON.
229 \n
230 The parsed value will use the default memory
231 resource for storage. To use a different resource,
232 call @ref reset after construction.
233
234 @par Complexity
235 Constant.
236
237 @par Exception Safety
238 No-throw guarantee.
239
240 @param sp The memory resource to use for temporary storage.
241 */
242 explicit
243 1 parser(storage_ptr sp) noexcept
244 1 : parser(std::move(sp), {})
245 {
246 1 }
247
248 /** Constructor.
249
250 This constructs a new parser which first uses the
251 caller-owned storage `buffer` for temporary storage,
252 falling back to the memory resource `sp` if needed.
253 The parser will use the specified parsing options.
254 \n
255 The parsed value will use the default memory
256 resource for storage. To use a different resource,
257 call @ref reset after construction.
258
259 @par Complexity
260 Constant.
261
262 @par Exception Safety
263 No-throw guarantee.
264
265 @param sp The memory resource to use for
266 temporary storage after `buffer` is exhausted.
267
268 @param opt The parsing options to use.
269
270 @param buffer A buffer for the parser to use for
271 temporary storage. Ownership is not transferred,
272 the caller is responsible for ensuring the lifetime
273 of `buffer` extends until the parser is destroyed.
274 */
275 template<std::size_t N>
276 2001506 parser(
277 storage_ptr sp,
278 parse_options const& opt,
279 unsigned char(&buffer)[N]) noexcept
280 2001506 : parser(std::move(sp),
281 2001506 opt, &buffer[0], N)
282 {
283 2001506 }
284
285 #if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS)
286 /** Constructor.
287
288 This constructs a new parser which first uses
289 the caller-owned storage pointed to by `buffer`
290 for temporary storage, falling back to the memory
291 resource `sp` if needed. The parser will use the
292 specified parsing options.
293 \n
294 The parsed value will use the default memory
295 resource for storage. To use a different resource,
296 call @ref reset after construction.
297
298 @par Complexity
299 Constant.
300
301 @par Exception Safety
302 No-throw guarantee.
303
304 @param sp The memory resource to use for
305 temporary storage after `buffer` is exhausted.
306
307 @param opt The parsing options to use.
308
309 @param buffer A pointer to valid memory of at least
310 `size` bytes for the parser to use for temporary storage.
311 Ownership is not transferred, the caller is responsible
312 for ensuring the lifetime of the memory pointed to by
313 `buffer` extends until the parser is destroyed.
314
315 @param size The number of valid bytes in `buffer`.
316 */
317 parser(
318 storage_ptr sp,
319 parse_options const& opt,
320 std::byte* buffer,
321 std::size_t size) noexcept
322 : parser(sp, opt, reinterpret_cast<
323 unsigned char*>(buffer), size)
324 {
325 }
326
327 /** Constructor.
328
329 This constructs a new parser which first uses the
330 caller-owned storage `buffer` for temporary storage,
331 falling back to the memory resource `sp` if needed.
332 The parser will use the specified parsing options.
333 \n
334 The parsed value will use the default memory
335 resource for storage. To use a different resource,
336 call @ref reset after construction.
337
338 @par Complexity
339 Constant.
340
341 @par Exception Safety
342 No-throw guarantee.
343
344 @param sp The memory resource to use for
345 temporary storage after `buffer` is exhausted.
346
347 @param opt The parsing options to use.
348
349 @param buffer A buffer for the parser to use for
350 temporary storage. Ownership is not transferred,
351 the caller is responsible for ensuring the lifetime
352 of `buffer` extends until the parser is destroyed.
353 */
354 template<std::size_t N>
355 parser(
356 storage_ptr sp,
357 parse_options const& opt,
358 std::byte(&buffer)[N]) noexcept
359 : parser(std::move(sp),
360 opt, &buffer[0], N)
361 {
362 }
363 #endif
364
365 #ifndef BOOST_JSON_DOCS
366 // Safety net for accidental buffer overflows
367 template<std::size_t N>
368 parser(
369 storage_ptr sp,
370 parse_options const& opt,
371 unsigned char(&buffer)[N],
372 std::size_t n) noexcept
373 : parser(std::move(sp),
374 opt, &buffer[0], n)
375 {
376 // If this goes off, check your parameters
377 // closely, chances are you passed an array
378 // thinking it was a pointer.
379 BOOST_ASSERT(n <= N);
380 }
381
382 #ifdef __cpp_lib_byte
383 // Safety net for accidental buffer overflows
384 template<std::size_t N>
385 parser(
386 storage_ptr sp,
387 parse_options const& opt,
388 std::byte(&buffer)[N], std::size_t n) noexcept
389 : parser(std::move(sp),
390 opt, &buffer[0], n)
391 {
392 // If this goes off, check your parameters
393 // closely, chances are you passed an array
394 // thinking it was a pointer.
395 BOOST_ASSERT(n <= N);
396 }
397 #endif
398 #endif
399
400 /** Reset the parser for a new JSON text.
401
402 This function is used to reset the parser to
403 prepare it for parsing a new complete JSON text.
404 Any previous partial results are destroyed.
405
406 @par Complexity
407 Constant or linear in the size of any previous
408 partial parsing results.
409
410 @par Exception Safety
411 No-throw guarantee.
412
413 @param sp A pointer to the `boost::container::pmr::memory_resource` to
414 use for the resulting @ref value. The parser will acquire shared
415 ownership.
416 */
417 BOOST_JSON_DECL
418 void
419 reset(storage_ptr sp = {}) noexcept;
420
421 /** Parse a buffer containing a complete JSON text.
422
423 This function parses a complete JSON text contained
424 in the specified character buffer. Additional
425 characters past the end of the complete JSON text
426 are ignored. The function returns the actual
427 number of characters parsed, which may be less
428 than the size of the input. This allows parsing
429 of a buffer containing multiple individual JSON texts
430 or containing different protocol data:
431
432 @par Example
433 @code
434 parser p; // construct a parser
435 size_t n = p.write_some( "[1,2,3] null" ); // parse a complete JSON text
436 assert( n == 8 ); // only some characters consumed
437 value jv = p.release(); // take ownership of the value
438 @endcode
439
440 @par Complexity
441 Linear in `size`.
442
443 @par Exception Safety
444 Basic guarantee.
445 Calls to `memory_resource::allocate` may throw.
446 Upon error or exception, subsequent calls will
447 fail until @ref reset is called to parse a new JSON text.
448
449 @return The number of characters consumed from
450 the buffer.
451
452 @param data A pointer to a buffer of `size`
453 characters to parse.
454
455 @param size The number of characters pointed to
456 by `data`.
457
458 @param ec Set to the error, if any occurred.
459 */
460 /** @{ */
461 BOOST_JSON_DECL
462 std::size_t
463 write_some(
464 char const* data,
465 std::size_t size,
466 system::error_code& ec);
467
468 BOOST_JSON_DECL
469 std::size_t
470 write_some(
471 char const* data,
472 std::size_t size,
473 std::error_code& ec);
474 /** @} */
475
476 /** Parse a buffer containing a complete JSON text.
477
478 This function parses a complete JSON text contained
479 in the specified character buffer. Additional
480 characters past the end of the complete JSON text
481 are ignored. The function returns the actual
482 number of characters parsed, which may be less
483 than the size of the input. This allows parsing
484 of a buffer containing multiple individual JSON texts
485 or containing different protocol data:
486
487 @par Example
488 @code
489 parser p; // construct a parser
490 size_t n = p.write_some( "[1,2,3] null" ); // parse a complete JSON text
491 assert( n == 8 ); // only some characters consumed
492 value jv = p.release(); // take ownership of the value
493 @endcode
494
495 @par Complexity
496 Linear in `size`.
497
498 @par Exception Safety
499 Basic guarantee.
500 Calls to `memory_resource::allocate` may throw.
501 Upon error or exception, subsequent calls will
502 fail until @ref reset is called to parse a new JSON text.
503
504 @return The number of characters consumed from
505 the buffer.
506
507 @param data A pointer to a buffer of `size`
508 characters to parse.
509
510 @param size The number of characters pointed to
511 by `data`.
512
513 @throw `boost::system::system_error` Thrown on error.
514 */
515 BOOST_JSON_DECL
516 std::size_t
517 write_some(
518 char const* data,
519 std::size_t size);
520
521 /** Parse a buffer containing a complete JSON text.
522
523 This function parses a complete JSON text contained
524 in the specified character buffer. Additional
525 characters past the end of the complete JSON text
526 are ignored. The function returns the actual
527 number of characters parsed, which may be less
528 than the size of the input. This allows parsing
529 of a buffer containing multiple individual JSON texts
530 or containing different protocol data:
531
532 @par Example
533 @code
534 parser p; // construct a parser
535 size_t n = p.write_some( "[1,2,3] null" ); // parse a complete JSON text
536 assert( n == 8 ); // only some characters consumed
537 value jv = p.release(); // take ownership of the value
538 @endcode
539
540 @par Complexity
541 Linear in `size`.
542
543 @par Exception Safety
544 Basic guarantee.
545 Calls to `memory_resource::allocate` may throw.
546 Upon error or exception, subsequent calls will
547 fail until @ref reset is called to parse a new JSON text.
548
549 @return The number of characters consumed from
550 the buffer.
551
552 @param s The character string to parse.
553
554 @param ec Set to the error, if any occurred.
555 */
556 /** @{ */
557 std::size_t
558 2 write_some(
559 string_view s,
560 system::error_code& ec)
561 {
562 2 return write_some(
563 2 s.data(), s.size(), ec);
564 }
565
566 std::size_t
567 2 write_some(
568 string_view s,
569 std::error_code& ec)
570 {
571 2 return write_some(
572 2 s.data(), s.size(), ec);
573 }
574 /** @} */
575
576 /** Parse a buffer containing a complete JSON text.
577
578 This function parses a complete JSON text contained
579 in the specified character buffer. Additional
580 characters past the end of the complete JSON text
581 are ignored. The function returns the actual
582 number of characters parsed, which may be less
583 than the size of the input. This allows parsing
584 of a buffer containing multiple individual JSON texts
585 or containing different protocol data:
586
587 @par Example
588 @code
589 parser p; // construct a parser
590 size_t n = p.write_some( "[1,2,3] null" ); // parse a complete JSON text
591 assert( n == 8 ); // only some characters consumed
592 value jv = p.release(); // take ownership of the value
593 @endcode
594
595 @par Complexity
596 Linear in `size`.
597
598 @par Exception Safety
599 Basic guarantee.
600 Calls to `memory_resource::allocate` may throw.
601 Upon error or exception, subsequent calls will
602 fail until @ref reset is called to parse a new JSON text.
603
604 @return The number of characters consumed from
605 the buffer.
606
607 @param s The character string to parse.
608
609 @throw `boost::system::system_error` Thrown on error.
610 */
611 std::size_t
612 4 write_some(
613 string_view s)
614 {
615 4 return write_some(
616 2 s.data(), s.size());
617 }
618
619 /** Parse a buffer containing a complete JSON text.
620
621 This function parses a complete JSON text contained
622 in the specified character buffer. The entire
623 buffer must be consumed; if there are additional
624 characters past the end of the complete JSON text,
625 the parse fails and an error is returned.
626
627 @par Example
628 @code
629 parser p; // construct a parser
630 size_t n = p.write( "[1,2,3]" ); // parse a complete JSON text
631 assert( n == 7 ); // all characters consumed
632 value jv = p.release(); // take ownership of the value
633 @endcode
634
635 @par Complexity
636 Linear in `size`.
637
638 @par Exception Safety
639 Basic guarantee.
640 Calls to `memory_resource::allocate` may throw.
641 Upon error or exception, subsequent calls will
642 fail until @ref reset is called to parse a new JSON text.
643
644 @return The number of characters consumed from
645 the buffer.
646
647 @param data A pointer to a buffer of `size`
648 characters to parse.
649
650 @param size The number of characters pointed to
651 by `data`.
652
653 @param ec Set to the error, if any occurred.
654 */
655 /** @{ */
656 BOOST_JSON_DECL
657 std::size_t
658 write(
659 char const* data,
660 std::size_t size,
661 system::error_code& ec);
662
663 BOOST_JSON_DECL
664 std::size_t
665 write(
666 char const* data,
667 std::size_t size,
668 std::error_code& ec);
669 /** @} */
670
671 /** Parse a buffer containing a complete JSON text.
672
673 This function parses a complete JSON text contained
674 in the specified character buffer. The entire
675 buffer must be consumed; if there are additional
676 characters past the end of the complete JSON text,
677 the parse fails and an error is returned.
678
679 @par Example
680 @code
681 parser p; // construct a parser
682 size_t n = p.write( "[1,2,3]" ); // parse a complete JSON text
683 assert( n == 7 ); // all characters consumed
684 value jv = p.release(); // take ownership of the value
685 @endcode
686
687 @par Complexity
688 Linear in `size`.
689
690 @par Exception Safety
691 Basic guarantee.
692 Calls to `memory_resource::allocate` may throw.
693 Upon error or exception, subsequent calls will
694 fail until @ref reset is called to parse a new JSON text.
695
696 @return The number of characters consumed from
697 the buffer.
698
699 @param data A pointer to a buffer of `size`
700 characters to parse.
701
702 @param size The number of characters pointed to
703 by `data`.
704
705 @throw `boost::system::system_error` Thrown on error.
706 */
707 BOOST_JSON_DECL
708 std::size_t
709 write(
710 char const* data,
711 std::size_t size);
712
713 /** Parse a buffer containing a complete JSON text.
714
715 This function parses a complete JSON text contained
716 in the specified character buffer. The entire
717 buffer must be consumed; if there are additional
718 characters past the end of the complete JSON text,
719 the parse fails and an error is returned.
720
721 @par Example
722 @code
723 parser p; // construct a parser
724 size_t n = p.write( "[1,2,3]" ); // parse a complete JSON text
725 assert( n == 7 ); // all characters consumed
726 value jv = p.release(); // take ownership of the value
727 @endcode
728
729 @par Complexity
730 Linear in `size`.
731
732 @par Exception Safety
733 Basic guarantee.
734 Calls to `memory_resource::allocate` may throw.
735 Upon error or exception, subsequent calls will
736 fail until @ref reset is called to parse a new JSON text.
737
738 @return The number of characters consumed from
739 the buffer.
740
741 @param s The character string to parse.
742
743 @param ec Set to the error, if any occurred.
744 */
745 /** @{ */
746 std::size_t
747 2001508 write(
748 string_view s,
749 system::error_code& ec)
750 {
751 2001508 return write(
752 2001507 s.data(), s.size(), ec);
753 }
754
755 std::size_t
756 3 write(
757 string_view s,
758 std::error_code& ec)
759 {
760 3 return write(
761 3 s.data(), s.size(), ec);
762 }
763 /** @} */
764
765 /** Parse a buffer containing a complete JSON text.
766
767 This function parses a complete JSON text contained
768 in the specified character buffer. The entire
769 buffer must be consumed; if there are additional
770 characters past the end of the complete JSON text,
771 the parse fails and an error is returned.
772
773 @par Example
774 @code
775 parser p; // construct a parser
776 size_t n = p.write( "[1,2,3]" ); // parse a complete JSON text
777 assert( n == 7 ); // all characters consumed
778 value jv = p.release(); // take ownership of the value
779 @endcode
780
781 @par Complexity
782 Linear in `size`.
783
784 @par Exception Safety
785 Basic guarantee.
786 Calls to `memory_resource::allocate` may throw.
787 Upon error or exception, subsequent calls will
788 fail until @ref reset is called to parse a new JSON text.
789
790 @return The number of characters consumed from
791 the buffer.
792
793 @param s The character string to parse.
794
795 @throw `boost::system::system_error` Thrown on error.
796 */
797 std::size_t
798 8 write(
799 string_view s)
800 {
801 8 return write(
802 4 s.data(), s.size());
803 }
804
805 /** Return the parsed JSON text as a @ref value.
806
807 This returns the parsed value, or throws
808 an exception if the parsing is incomplete or
809 failed. It is necessary to call @ref reset
810 after calling this function in order to parse
811 another JSON text.
812
813 @par Complexity
814 Constant.
815
816 @return The parsed value. Ownership of this
817 value is transferred to the caller.
818
819 @throw `boost::system::system_error` Thrown on failure.
820 */
821 BOOST_JSON_DECL
822 value
823 release();
824 };
825
826 } // namespace json
827 } // namespace boost
828
829 #endif
830