This is the main driver of parsing logic: it scans the YAML or JSON source for tokens, and emits the appropriate sequence of parsing events to its event handler. More...

#include <parse_engine.hpp>

Public Types
using	handler_type = EventHandler

Public Member Functions
construction and assignment
	ParseEngine (EventHandler *evt_handler, ParserOptions opts={})

	~ParseEngine ()

	ParseEngine (ParseEngine &&) noexcept

	ParseEngine (ParseEngine const &)

ParseEngine &	operator= (ParseEngine &&) noexcept

ParseEngine &	operator= (ParseEngine const &)

modifiers
void	reserve_stack (id_type capacity)
	Reserve a certain capacity for the parsing stack. More...

void	reserve_locations (size_t num_source_lines)
	Reserve a certain capacity for the array used to track node locations in the source buffer. More...

void	reserve_filter_arena (size_t)

getters
ParserOptions const &	options () const
	Get the options used to build this parser object. More...

Callbacks const &	callbacks () const
	Get the current callbacks in the parser. More...

csubstr	filename () const
	Get the name of the latest file parsed by this object. More...

csubstr	source () const
	Get the latest YAML buffer parsed by this object. More...

Encoding_e	encoding () const
	Get the encoding of the latest YAML buffer parsed by this object. More...

id_type	stack_capacity () const

size_t	locations_capacity () const

size_t	filter_arena_capacity () const

parse methods
void	parse_in_place_ev (csubstr filename, substr src)
	parse YAML in place, emitting events to the current handler More...

void	parse_json_in_place_ev (csubstr filename, substr src)
	parse JSON in place, emitting events to the current handler More...

locations
Location	location (Tree const &tree, id_type node_id) const
	Get the location of a node of the last tree to be parsed by this parser. More...

Location	location (ConstNodeRef node) const
	Get the location of a node of the last tree to be parsed by this parser. More...

csubstr	location_contents (Location const &loc) const
	Get the string starting at a particular location, to the end of the parsed source buffer. More...

Location	val_location (const char *val) const
	Given a pointer to a buffer position, get the location. More...

scalar filtering
FilterResult	filter_scalar_plain (csubstr scalar, substr dst, size_t indentation)
	filter a plain scalar More...

FilterResult	filter_scalar_plain_in_place (substr scalar, size_t cap, size_t indentation)
	filter a plain scalar in place More...

FilterResult	filter_scalar_squoted (csubstr scalar, substr dst)
	filter a single-quoted scalar More...

FilterResult	filter_scalar_squoted_in_place (substr scalar, size_t cap)
	filter a single-quoted scalar in place More...

FilterResult	filter_scalar_dquoted (csubstr scalar, substr dst)
	filter a double-quoted scalar More...

FilterResultExtending	filter_scalar_dquoted_in_place (substr scalar, size_t cap)
	filter a double-quoted scalar in place More...

FilterResult	filter_scalar_block_literal (csubstr scalar, substr dst, size_t indentation, BlockChomp_e chomp)
	filter a block-literal scalar More...

FilterResult	filter_scalar_block_literal_in_place (substr scalar, size_t cap, size_t indentation, BlockChomp_e chomp)
	filter a block-literal scalar in place More...

FilterResult	filter_scalar_block_folded (csubstr scalar, substr dst, size_t indentation, BlockChomp_e chomp)
	filter a block-folded scalar More...

FilterResult	filter_scalar_block_folded_in_place (substr scalar, size_t cap, size_t indentation, BlockChomp_e chomp)
	filter a block-folded scalar in place More...

Detailed Description

template<class EventHandler>
class c4::yml::ParseEngine< EventHandler >

This is the main driver of parsing logic: it scans the YAML or JSON source for tokens, and emits the appropriate sequence of parsing events to its event handler.

The parse engine itself has no special limitations, and can accomodate containers as keys; it is the event handler may introduce additional constraints.

There are two implemented handlers (see Event Handlers, which has important notes about the event model):

EventHandlerTree is the handler responsible for creating the ryml Tree
EventHandlerYamlStd is the handler responsible for emitting standardized YAML test suite events, used (only) in the CI of this project. This is not part of the library and is not installed.

Definition at line 292 of file parse_engine.hpp.

Member Typedef Documentation

◆ handler_type

template<class EventHandler >

using c4::yml::ParseEngine< EventHandler >::handler_type = EventHandler

Definition at line 296 of file parse_engine.hpp.

Constructor & Destructor Documentation

◆ ParseEngine() [1/3]

template<class EventHandler >

c4::yml::ParseEngine< EventHandler >::ParseEngine	(	EventHandler *	evt_handler,
		ParserOptions	opts = `{}`
	)

Definition at line 257 of file parse_engine.def.hpp.

     : m_options(opts)
     , m_file()
     , m_buf()
     , m_evt_handler(evt_handler)
     , m_pending_anchors()
     , m_pending_tags()
     , m_was_inside_qmrk(false)
     , m_doc_empty(false)
     , m_encoding(NOBOM)
     , m_newline_offsets()
     , m_newline_offsets_size(0)
     , m_newline_offsets_capacity(0)
     , m_newline_offsets_buf()
 {
     RYML_CHECK(evt_handler);
 }

◆ ~ParseEngine()

template<class EventHandler >

c4::yml::ParseEngine< EventHandler >::~ParseEngine

Definition at line 250 of file parse_engine.def.hpp.

 {
     _free();
     _clr();
 }

◆ ParseEngine() [2/3]

template<class EventHandler >

c4::yml::ParseEngine< EventHandler >::ParseEngine ( ParseEngine< EventHandler > && that )

noexcept

Definition at line 276 of file parse_engine.def.hpp.

     : m_options(that.m_options)
     , m_file(that.m_file)
     , m_buf(that.m_buf)
     , m_evt_handler(that.m_evt_handler)
     , m_pending_anchors(that.m_pending_anchors)
     , m_pending_tags(that.m_pending_tags)
     , m_was_inside_qmrk(false)
     , m_doc_empty(false)
     , m_encoding(NOBOM)
     , m_newline_offsets(that.m_newline_offsets)
     , m_newline_offsets_size(that.m_newline_offsets_size)
     , m_newline_offsets_capacity(that.m_newline_offsets_capacity)
     , m_newline_offsets_buf(that.m_newline_offsets_buf)
 {
     that._clr();
 }

◆ ParseEngine() [3/3]

template<class EventHandler >

c4::yml::ParseEngine< EventHandler >::ParseEngine ( ParseEngine< EventHandler > const & that )

Definition at line 295 of file parse_engine.def.hpp.

     : m_options(that.m_options)
     , m_file(that.m_file)
     , m_buf(that.m_buf)
     , m_evt_handler(that.m_evt_handler)
     , m_pending_anchors(that.m_pending_anchors)
     , m_pending_tags(that.m_pending_tags)
     , m_was_inside_qmrk(false)
     , m_doc_empty(false)
     , m_encoding(NOBOM)
     , m_newline_offsets()
     , m_newline_offsets_size()
     , m_newline_offsets_capacity()
     , m_newline_offsets_buf()
 {
     if(that.m_newline_offsets_capacity)
     {
         _resize_locations(that.m_newline_offsets_capacity);
         _RYML_CB_CHECK(m_evt_handler->m_stack.m_callbacks, m_newline_offsets_capacity == that.m_newline_offsets_capacity);
         memcpy(m_newline_offsets, that.m_newline_offsets, that.m_newline_offsets_size * sizeof(size_t));
         m_newline_offsets_size = that.m_newline_offsets_size;
     }
 }

Member Function Documentation

◆ operator=() [1/2]

template<class EventHandler >

ParseEngine< EventHandler > & c4::yml::ParseEngine< EventHandler >::operator= ( ParseEngine< EventHandler > && that )

noexcept

Definition at line 320 of file parse_engine.def.hpp.

 {
     _free();
     m_options = (that.m_options);
     m_file = (that.m_file);
     m_buf = (that.m_buf);
     m_evt_handler = that.m_evt_handler;
     m_pending_anchors = that.m_pending_anchors;
     m_pending_tags = that.m_pending_tags;
     m_was_inside_qmrk = that.m_was_inside_qmrk;
     m_doc_empty = that.m_doc_empty;
     m_encoding = that.m_encoding;
     m_newline_offsets = (that.m_newline_offsets);
     m_newline_offsets_size = (that.m_newline_offsets_size);
     m_newline_offsets_capacity = (that.m_newline_offsets_capacity);
     m_newline_offsets_buf = (that.m_newline_offsets_buf);
     that._clr();
     return *this;
 }

◆ operator=() [2/2]

template<class EventHandler >

ParseEngine< EventHandler > & c4::yml::ParseEngine< EventHandler >::operator= ( ParseEngine< EventHandler > const & that )

Definition at line 341 of file parse_engine.def.hpp.

 {
     if(&that != this)
     {
         _free();
         m_options = (that.m_options);
         m_file = (that.m_file);
         m_buf = (that.m_buf);
         m_evt_handler = that.m_evt_handler;
         m_pending_anchors = that.m_pending_anchors;
         m_pending_tags = that.m_pending_tags;
         m_was_inside_qmrk = that.m_was_inside_qmrk;
         m_doc_empty = that.m_doc_empty;
         m_encoding = that.m_encoding;
         if(that.m_newline_offsets_capacity > m_newline_offsets_capacity)
             _resize_locations(that.m_newline_offsets_capacity);
         _RYML_CB_CHECK(m_evt_handler->m_stack.m_callbacks, m_newline_offsets_capacity >= that.m_newline_offsets_capacity);
         _RYML_CB_CHECK(m_evt_handler->m_stack.m_callbacks, m_newline_offsets_capacity >= that.m_newline_offsets_size);
         memcpy(m_newline_offsets, that.m_newline_offsets, that.m_newline_offsets_size * sizeof(size_t));
         m_newline_offsets_size = that.m_newline_offsets_size;
         m_newline_offsets_buf = that.m_newline_offsets_buf;
     }
     return *this;
 }

◆ reserve_stack()

template<class EventHandler >

void c4::yml::ParseEngine< EventHandler >::reserve_stack ( id_type capacity )

inline

Reserve a certain capacity for the parsing stack.

This should be larger than the expected depth of the parsed YAML tree.

The parsing stack is the only (potential) heap memory used directly by the parser.

If the requested capacity is below the default stack size of 16, the memory is used directly in the parser object; otherwise it will be allocated from the heap.

Note: this reserves memory only for the parser itself; all the allocations for the parsed tree will go through the tree's allocator (when different).; for maximum efficiency, the tree and the arena can (and should) also be reserved.

Definition at line 335 of file parse_engine.hpp.

     {
         m_evt_handler->m_stack.reserve(capacity);
     }

Referenced by sample::sample_global_allocator(), sample::sample_parse_reuse_parser(), and sample::sample_parse_reuse_tree_and_parser().

◆ reserve_locations()

template<class EventHandler >

void c4::yml::ParseEngine< EventHandler >::reserve_locations ( size_t num_source_lines )

inline

Reserve a certain capacity for the array used to track node locations in the source buffer.

Definition at line 342 of file parse_engine.hpp.

     {
         _resize_locations(num_source_lines);
     }

Referenced by sample::sample_location_tracking().

◆ reserve_filter_arena()

template<class EventHandler >

void c4::yml::ParseEngine< EventHandler >::reserve_filter_arena ( size_t )

inline

Definition at line 348 of file parse_engine.hpp.

348 {}

◆ options()

template<class EventHandler >

ParserOptions const& c4::yml::ParseEngine< EventHandler >::options ( ) const

inline

Get the options used to build this parser object.

Definition at line 358 of file parse_engine.hpp.

358 { return m_options; }

Referenced by sample::sample_location_tracking().

◆ callbacks()

template<class EventHandler >

Callbacks const& c4::yml::ParseEngine< EventHandler >::callbacks ( ) const

inline

Get the current callbacks in the parser.

Definition at line 361 of file parse_engine.hpp.

361 { RYML_ASSERT(m_evt_handler); return m_evt_handler->m_stack.m_callbacks; }

Referenced by c4::yml::parse_in_arena(), c4::yml::parse_in_place(), c4::yml::parse_json_in_arena(), and c4::yml::parse_json_in_place().

◆ filename()

template<class EventHandler >

csubstr c4::yml::ParseEngine< EventHandler >::filename ( ) const

inline

Get the name of the latest file parsed by this object.

Definition at line 364 of file parse_engine.hpp.

364 { return m_file; }

◆ source()

template<class EventHandler >

csubstr c4::yml::ParseEngine< EventHandler >::source ( ) const

inline

Get the latest YAML buffer parsed by this object.

Definition at line 367 of file parse_engine.hpp.

367 { return m_buf; }

◆ encoding()

template<class EventHandler >

Encoding_e c4::yml::ParseEngine< EventHandler >::encoding ( ) const

inline

Get the encoding of the latest YAML buffer parsed by this object.

If no encoding was specified, UTF8 is assumed as per the YAML standard.

Definition at line 371 of file parse_engine.hpp.

371 { return m_encoding != NOBOM ? m_encoding : UTF8; }

c4::yml::UTF8

@ UTF8

Definition: common.hpp:429

References c4::yml::NOBOM, and c4::yml::UTF8.

◆ stack_capacity()

template<class EventHandler >

id_type c4::yml::ParseEngine< EventHandler >::stack_capacity ( ) const

inline

Definition at line 373 of file parse_engine.hpp.

373 { RYML_ASSERT(m_evt_handler); return m_evt_handler->m_stack.capacity(); }

◆ locations_capacity()

template<class EventHandler >

size_t c4::yml::ParseEngine< EventHandler >::locations_capacity ( ) const

inline

Definition at line 374 of file parse_engine.hpp.

374 { return m_newline_offsets_capacity; }

◆ filter_arena_capacity()

template<class EventHandler >

size_t c4::yml::ParseEngine< EventHandler >::filter_arena_capacity ( ) const

inline

Definition at line 377 of file parse_engine.hpp.

377 { return 0u; }

◆ parse_in_place_ev()

template<class EventHandler >

void c4::yml::ParseEngine< EventHandler >::parse_in_place_ev	(	csubstr	filename,
		substr	src
	)

parse YAML in place, emitting events to the current handler

Referenced by c4::yml::parse_in_place().

◆ parse_json_in_place_ev()

template<class EventHandler >

void c4::yml::ParseEngine< EventHandler >::parse_json_in_place_ev	(	csubstr	filename,
		substr	src
	)

parse JSON in place, emitting events to the current handler

Referenced by c4::yml::parse_json_in_place().

◆ location() [1/2]

template<class EventHandler >

Location c4::yml::ParseEngine< EventHandler >::location	(	Tree const &	tree,
		id_type	node_id
	)		const

Get the location of a node of the last tree to be parsed by this parser.

Referenced by sample::sample_location_tracking(), and sample::sample_quick_overview().

◆ location() [2/2]

template<class EventHandler >

Location c4::yml::ParseEngine< EventHandler >::location ( ConstNodeRef node ) const

Get the location of a node of the last tree to be parsed by this parser.

◆ location_contents()

template<class EventHandler >

csubstr c4::yml::ParseEngine< EventHandler >::location_contents ( Location const & loc ) const

Get the string starting at a particular location, to the end of the parsed source buffer.

Referenced by sample::sample_location_tracking(), and sample::sample_quick_overview().

◆ val_location()

template<class EventHandler >

Location c4::yml::ParseEngine< EventHandler >::val_location ( const char * val ) const

Given a pointer to a buffer position, get the location.

Parameters

[in] val must be pointing to somewhere in the source buffer that was last parsed by this object.

◆ filter_scalar_plain()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_plain	(	csubstr	scalar,
		substr	dst,
		size_t	indentation
	)

filter a plain scalar

◆ filter_scalar_plain_in_place()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_plain_in_place	(	substr	scalar,
		size_t	cap,
		size_t	indentation
	)

filter a plain scalar in place

◆ filter_scalar_squoted()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_squoted	(	csubstr	scalar,
		substr	dst
	)

filter a single-quoted scalar

◆ filter_scalar_squoted_in_place()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_squoted_in_place	(	substr	scalar,
		size_t	cap
	)

filter a single-quoted scalar in place

◆ filter_scalar_dquoted()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_dquoted	(	csubstr	scalar,
		substr	dst
	)

filter a double-quoted scalar

◆ filter_scalar_dquoted_in_place()

template<class EventHandler >

FilterResultExtending c4::yml::ParseEngine< EventHandler >::filter_scalar_dquoted_in_place	(	substr	scalar,
		size_t	cap
	)

filter a double-quoted scalar in place

◆ filter_scalar_block_literal()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_block_literal	(	csubstr	scalar,
		substr	dst,
		size_t	indentation,
		BlockChomp_e	chomp
	)

filter a block-literal scalar

◆ filter_scalar_block_literal_in_place()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_block_literal_in_place	(	substr	scalar,
		size_t	cap,
		size_t	indentation,
		BlockChomp_e	chomp
	)

filter a block-literal scalar in place

◆ filter_scalar_block_folded()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_block_folded	(	csubstr	scalar,
		substr	dst,
		size_t	indentation,
		BlockChomp_e	chomp
	)

filter a block-folded scalar

◆ filter_scalar_block_folded_in_place()

template<class EventHandler >

FilterResult c4::yml::ParseEngine< EventHandler >::filter_scalar_block_folded_in_place	(	substr	scalar,
		size_t	cap,
		size_t	indentation,
		BlockChomp_e	chomp
	)

filter a block-folded scalar in place

The documentation for this class was generated from the following files:

/home/docs/checkouts/readthedocs.org/user_builds/rapidyaml/checkouts/v0.8.0/src/c4/yml/fwd.hpp
/home/docs/checkouts/readthedocs.org/user_builds/rapidyaml/checkouts/v0.8.0/src/c4/yml/parse_engine.hpp
/home/docs/checkouts/readthedocs.org/user_builds/rapidyaml/checkouts/v0.8.0/src/c4/yml/parse_engine.def.hpp

Public Types

Public Member Functions

Detailed Description

template<class EventHandler> class c4::yml::ParseEngine< EventHandler >

Member Typedef Documentation

◆ handler_type

Constructor & Destructor Documentation

◆ ParseEngine() [1/3]

◆ ~ParseEngine()

◆ ParseEngine() [2/3]

◆ ParseEngine() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ reserve_stack()

◆ reserve_locations()

◆ reserve_filter_arena()

◆ options()

◆ callbacks()

◆ filename()

◆ source()

◆ encoding()

◆ stack_capacity()

◆ locations_capacity()

◆ filter_arena_capacity()

◆ parse_in_place_ev()

◆ parse_json_in_place_ev()

◆ location() [1/2]

◆ location() [2/2]

◆ location_contents()

◆ val_location()

◆ filter_scalar_plain()

◆ filter_scalar_plain_in_place()

◆ filter_scalar_squoted()

◆ filter_scalar_squoted_in_place()

◆ filter_scalar_dquoted()

◆ filter_scalar_dquoted_in_place()

◆ filter_scalar_block_literal()

◆ filter_scalar_block_literal_in_place()

◆ filter_scalar_block_folded()

◆ filter_scalar_block_folded_in_place()

template<class EventHandler>
class c4::yml::ParseEngine< EventHandler >