rapidyaml  0.12.1
parse and emit YAML, and do it fast
Classes | Public Types | List of all members
c4::yml::ParseEngine< EventHandler > Class Template Reference
Parse utilities

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...
 
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
 
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
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
  • extra::EventHandlerInts is the handler responsible for emitting integer-coded events. It is intended for implementing fully-conformant parsing in other programming languages (integration is currently under work for YamlScript and go-yaml). It is not part of the library and is not installed.

Definition at line 259 of file parse_engine.hpp.

Member Typedef Documentation

◆ handler_type

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

Definition at line 263 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 297 of file parse_engine.def.hpp.

298  : m_options(opts)
299  , m_evt_handler(evt_handler)
300  , m_pending_anchors()
301  , m_pending_tags()
302  , m_has_directives_yaml(false)
303  , m_has_directives(false)
304  , m_doc_empty(true)
305  , m_prev_colon(npos)
306  , m_prev_val_end(npos)
307  , m_encoding(NOBOM)
308  , m_newline_offsets()
309  , m_newline_offsets_size(0)
310  , m_newline_offsets_capacity(0)
311 {
312  _RYML_CHECK_BASIC(evt_handler);
313 }
c4::yml::npos
@ npos
a null string position
Definition: common.hpp:258
c4::yml::NOBOM
@ NOBOM
No Byte Order Mark was found.
Definition: common.hpp:263

◆ ~ParseEngine()

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

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

291 {
292  _free();
293  _clr();
294 }

◆ ParseEngine() [2/3]

template<class EventHandler >
c4::yml::ParseEngine< EventHandler >::ParseEngine ( ParseEngine< EventHandler > &&  that)
noexcept

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

317  : m_options(that.m_options)
318  , m_evt_handler(that.m_evt_handler)
319  , m_pending_anchors(that.m_pending_anchors)
320  , m_pending_tags(that.m_pending_tags)
321  , m_has_directives_yaml(that.m_has_directives_yaml)
322  , m_has_directives(that.m_has_directives)
323  , m_doc_empty(that.m_doc_empty)
324  , m_prev_colon(npos)
325  , m_prev_val_end(npos)
326  , m_encoding(NOBOM)
327  , m_newline_offsets(that.m_newline_offsets)
328  , m_newline_offsets_size(that.m_newline_offsets_size)
329  , m_newline_offsets_capacity(that.m_newline_offsets_capacity)
330 {
331  that._clr();
332 }

◆ ParseEngine() [3/3]

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

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

336  : m_options(that.m_options)
337  , m_evt_handler(that.m_evt_handler)
338  , m_pending_anchors(that.m_pending_anchors)
339  , m_pending_tags(that.m_pending_tags)
340  , m_has_directives_yaml(that.m_has_directives_yaml)
341  , m_has_directives(that.m_has_directives)
342  , m_doc_empty(that.m_doc_empty)
343  , m_prev_colon(npos)
344  , m_prev_val_end(npos)
345  , m_encoding(NOBOM)
346  , m_newline_offsets()
347  , m_newline_offsets_size()
348  , m_newline_offsets_capacity()
349 {
350  if(that.m_newline_offsets_capacity)
351  {
352  _resize_locations(that.m_newline_offsets_capacity);
353  _RYML_CHECK_BASIC_(m_evt_handler->m_stack.m_callbacks, m_newline_offsets_capacity == that.m_newline_offsets_capacity);
354  memcpy(m_newline_offsets, that.m_newline_offsets, that.m_newline_offsets_size * sizeof(size_t));
355  m_newline_offsets_size = that.m_newline_offsets_size;
356  }
357 }

Member Function Documentation

◆ operator=() [1/2]

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

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

361 {
362  _free();
363  m_options = (that.m_options);
364  m_evt_handler = that.m_evt_handler;
365  m_pending_anchors = that.m_pending_anchors;
366  m_pending_tags = that.m_pending_tags;
367  m_has_directives_yaml = that.m_has_directives_yaml;
368  m_has_directives = that.m_has_directives;
369  m_doc_empty = that.m_doc_empty;
370  m_prev_colon = that.m_prev_colon;
371  m_prev_val_end = that.m_prev_val_end;
372  m_encoding = that.m_encoding;
373  m_newline_offsets = (that.m_newline_offsets);
374  m_newline_offsets_size = (that.m_newline_offsets_size);
375  m_newline_offsets_capacity = (that.m_newline_offsets_capacity);
376  that._clr();
377  return *this;
378 }

◆ operator=() [2/2]

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

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

382 {
383  if(&that != this)
384  {
385  _free();
386  m_options = (that.m_options);
387  m_evt_handler = that.m_evt_handler;
388  m_pending_anchors = that.m_pending_anchors;
389  m_pending_tags = that.m_pending_tags;
390  m_has_directives_yaml = that.m_has_directives_yaml;
391  m_has_directives = that.m_has_directives;
392  m_doc_empty = that.m_doc_empty;
393  m_prev_colon = that.m_prev_colon;
394  m_prev_val_end = that.m_prev_val_end;
395  m_encoding = that.m_encoding;
396  if(that.m_newline_offsets_capacity > m_newline_offsets_capacity)
397  _resize_locations(that.m_newline_offsets_capacity);
398  _RYML_CHECK_BASIC_(m_evt_handler->m_stack.m_callbacks, m_newline_offsets_capacity >= that.m_newline_offsets_capacity);
399  _RYML_CHECK_BASIC_(m_evt_handler->m_stack.m_callbacks, m_newline_offsets_capacity >= that.m_newline_offsets_size);
400  memcpy(m_newline_offsets, that.m_newline_offsets, that.m_newline_offsets_size * sizeof(size_t));
401  m_newline_offsets_size = that.m_newline_offsets_size;
402  }
403  return *this;
404 }

◆ 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 302 of file parse_engine.hpp.

303  {
304  _RYML_ASSERT_BASIC(m_evt_handler);
305  m_evt_handler->m_stack.reserve(capacity);
306  }

◆ 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 310 of file parse_engine.hpp.

311  {
312  _resize_locations(num_source_lines);
313  }

◆ 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 323 of file parse_engine.hpp.

323 { return m_options; }

◆ callbacks()

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

Get the current callbacks in the parser.

Definition at line 326 of file parse_engine.hpp.

326 { _RYML_ASSERT_BASIC(m_evt_handler); return m_evt_handler->m_stack.m_callbacks; }

◆ 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 329 of file parse_engine.hpp.

329 { return m_evt_handler->m_curr ? m_evt_handler->m_curr->pos.name : csubstr{}; }

◆ source()

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

Get the latest YAML buffer parsed by this object.

Definition at line 332 of file parse_engine.hpp.

332 { return m_evt_handler ? m_evt_handler->m_src : csubstr{}; }

◆ 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 336 of file parse_engine.hpp.

336 { return m_encoding != NOBOM ? m_encoding : UTF8; }
c4::yml::UTF8
@ UTF8
UTF8.
Definition: common.hpp:264

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 338 of file parse_engine.hpp.

338 { _RYML_ASSERT_BASIC(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 339 of file parse_engine.hpp.

339 { return m_newline_offsets_capacity; }

◆ 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

◆ 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

◆ 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.

◆ 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]valmust 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: