basic_parser.hpp

100.0% Lines (11/11) 96.9% List of functions (123/127)

[ ] prev/next file

basic_parser.hpp

f(x) Functions (127)

Function Calls Lines Blocks

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