Rosetta  2020.37
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
basic::Emitter Class Referenceabstract

Lightweight class to ease writting YAML documents (http://yaml.org) More...

#include <Emitter.hh>

Inheritance diagram for basic::Emitter:
Inheritance graph
[legend]

Public Member Functions

 Emitter (std::ostream &out)
 
 ~Emitter () override
 
void flush ()
 Flush the underlying output stream. More...
 
template<typename T >
void write (T const &data)
 Write method for use inside lists / arrays. More...
 
void start_list (bool indent=true)
 Write method for use inside lists / arrays. More...
 
void start_map (bool indent=true)
 Write method for use inside lists / arrays. More...
 
template<typename T >
void write (std::string const &label, T const &data)
 Write method for use inside maps / dicts / objects. More...
 
void start_list (std::string const &label, bool indent=true)
 Write method for use inside maps / dicts / objects. More...
 
void start_list (const char *label, bool indent=true)
 Write method for use inside maps / dicts / objects. More...
 
void start_map (std::string const &label, bool indent=true)
 Write method for use inside maps / dicts / objects. More...
 
void start_map (const char *label, bool indent=true)
 Write method for use inside maps / dicts / objects. More...
 
void end_list ()
 Counterpart to start_list() – writes closing bracket. More...
 
void end_map ()
 Counterpart to start_map() – writes closing brace. More...
 
void end (size_t desired_depth=0)
 By default, closes all open maps/lists, ending the document. More...
 
int depth () const
 Number of closing brackets/braces required to end document (non-negative) More...
 
void set_indent (int num_spaces)
 Number of spaces used for indenting. Default is one. More...
 
virtual void start_doc ()=0
 Start a new document, ending the previous one first if necessary. A no-op for some types of output (e.g. JSON) that don't allow multiple documents. More...
 
- Public Member Functions inherited from utility::VirtualBase
 VirtualBase ()=default
 Default constructor. More...
 
virtual ~VirtualBase ()=default
 The virtual destructor is one of the main reasons for the VirtualBase class. More...
 
 VirtualBase (VirtualBase const &)=default
 
 VirtualBase (VirtualBase &&)=default
 
VirtualBaseoperator= (VirtualBase const &)=default
 
VirtualBaseoperator= (VirtualBase &&)=default
 

Protected Member Functions

 Emitter ()
 
 Emitter (Emitter const &)
 
bool assert_in (bool in_map, std::string const &msg)
 Check that we're in the expected context (either map or list) More...
 
void write_label (std::string const &label)
 Write the key part of a key-value pair. More...
 
void write_raw (bool b)
 
void write_raw (int i)
 
void write_raw (long l)
 
void write_raw (float f)
 
void write_raw (double d)
 
void write_raw (std::string const &s)
 
std::string escape_string (std::string const &s, bool &needs_quotes_out)
 Converts special characters (newlines, etc) to escape codes (
, etc). More...
 
virtual std::string quote_string (std::string const &s)=0
 Quotes strings as much as needed for this format (e.g. always for JSON). More...
 
virtual void do_indent (bool write_comma=true)=0
 Handle pretty-printing indentation. Don't want to use commas for opening/closing brace/bracket. More...
 
virtual void write_list_marker ()=0
 Used for traditional YAML output, writes the "-" marker. More...
 
virtual void start_raw (bool is_map, bool indent)=0
 Actual implementation of start_map() and start_list(). More...
 
virtual void end_raw ()=0
 Actual implementation of end_map() and end_list(). More...
 

Protected Attributes

std::ostream & out_
 
std::string indent_str_
 
std::vector< boolin_map_
 
std::vector< boolfirst_
 
std::vector< boolindent_
 
std::vector< intindent_depth_
 

Detailed Description

Lightweight class to ease writting YAML documents (http://yaml.org)

YAML is a structured data format, a more human-readable alternative to XML.

I use the terms "map" and "list" here, but you may also see "mapping" and "sequence". The former is a series of key : value pairs, while the latter is a simple series of items. This class is not entirely able to enforce the generation of valid YAML – you can still e.g. write a key : value pair in the middle of a list. It will print a warning message but will otherwise try to continue on.

YAML documents have optional explicit start/end markers; if the emitter supports them, they will be auto-generated when the class is initialized and when you're finished and you call end().

Whitespace is YAML documents is semi-significant. By default, this class will try to pretty-print, showing the depth of nesting through indentation. When starting a new list or map, you can request that it not be indented (i.e., be printed all on one line), but all lists and maps nested inside it will also be printed without linebreaks, regardless of the requested indentation. YAML refers to these two styles as "block" and "flow", respectively.

Constructor & Destructor Documentation

basic::Emitter::Emitter ( std::ostream &  out)
inline
basic::Emitter::~Emitter ( )
inlineoverride
basic::Emitter::Emitter ( )
protected
basic::Emitter::Emitter ( Emitter const &  )
protected

Member Function Documentation

bool basic::Emitter::assert_in ( bool  in_map,
std::string const &  msg 
)
inlineprotected

Check that we're in the expected context (either map or list)

References in_map_, and basic::Warning().

Referenced by end_list(), end_map(), start_list(), start_map(), and write().

int basic::Emitter::depth ( ) const
inline

Number of closing brackets/braces required to end document (non-negative)

References in_map_.

Referenced by basic::YamlEmitter::do_indent(), basic::JsonEmitter::do_indent(), and end().

virtual void basic::Emitter::do_indent ( bool  write_comma = true)
protectedpure virtual

Handle pretty-printing indentation. Don't want to use commas for opening/closing brace/bracket.

Implemented in basic::JsonEmitter, and basic::YamlEmitter.

Referenced by start_list(), start_map(), and write().

void basic::Emitter::end ( size_t  desired_depth = 0)

By default, closes all open maps/lists, ending the document.

References depth(), and end_raw().

Referenced by basic::YamlEmitter::start_doc(), and basic::JsonEmitter::start_doc().

void basic::Emitter::end_list ( )

Counterpart to start_list() – writes closing bracket.

References assert_in(), and end_raw().

void basic::Emitter::end_map ( )

Counterpart to start_map() – writes closing brace.

References assert_in(), and end_raw().

virtual void basic::Emitter::end_raw ( )
protectedpure virtual

Actual implementation of end_map() and end_list().

Implemented in basic::JsonEmitter, and basic::YamlEmitter.

Referenced by end(), end_list(), and end_map().

std::string basic::Emitter::escape_string ( std::string const &  s,
bool needs_quotes_out 
)
protected

Converts special characters (newlines, etc) to escape codes (
, etc).

Anything but the most basic characters needs to be quoted and escaped. For normal YAML, very simple text can be output without quotes, though.

Parameters
needs_quotes_outwill be set to true if string contains "special" characters.

References fmt::hex(), basic::options::OptionKeys::out::file::o, and basic::options::OptionKeys::in::file::s.

Referenced by basic::YamlEmitter::quote_string(), and basic::JsonEmitter::quote_string().

void basic::Emitter::flush ( )
inline

Flush the underlying output stream.

References out_.

virtual std::string basic::Emitter::quote_string ( std::string const &  s)
protectedpure virtual

Quotes strings as much as needed for this format (e.g. always for JSON).

Implemented in basic::JsonEmitter, and basic::YamlEmitter.

Referenced by write_label(), and write_raw().

void basic::Emitter::set_indent ( int  num_spaces)
inline

Number of spaces used for indenting. Default is one.

References indent_str_, and basic::options::OptionKeys::in::file::s.

virtual void basic::Emitter::start_doc ( )
pure virtual

Start a new document, ending the previous one first if necessary. A no-op for some types of output (e.g. JSON) that don't allow multiple documents.

Implemented in basic::JsonEmitter, and basic::YamlEmitter.

void basic::Emitter::start_list ( bool  indent = true)

Write method for use inside lists / arrays.

References assert_in(), do_indent(), and start_raw().

Referenced by start_list().

void basic::Emitter::start_list ( std::string const &  label,
bool  indent = true 
)
inline

Write method for use inside maps / dicts / objects.

References binder::indent(), and start_list().

void basic::Emitter::start_list ( const char *  label,
bool  indent = true 
)

Write method for use inside maps / dicts / objects.

References assert_in(), do_indent(), start_raw(), and write_label().

void basic::Emitter::start_map ( bool  indent = true)

Write method for use inside lists / arrays.

References assert_in(), do_indent(), and start_raw().

Referenced by start_map().

void basic::Emitter::start_map ( std::string const &  label,
bool  indent = true 
)
inline

Write method for use inside maps / dicts / objects.

References binder::indent(), and start_map().

void basic::Emitter::start_map ( const char *  label,
bool  indent = true 
)

Write method for use inside maps / dicts / objects.

References assert_in(), do_indent(), start_raw(), and write_label().

virtual void basic::Emitter::start_raw ( bool  is_map,
bool  indent 
)
protectedpure virtual

Actual implementation of start_map() and start_list().

Implemented in basic::JsonEmitter, and basic::YamlEmitter.

Referenced by start_list(), and start_map().

template<typename T >
void basic::Emitter::write ( T const &  data)

Write method for use inside lists / arrays.

References assert_in(), do_indent(), write_list_marker(), and write_raw().

template<typename T >
void basic::Emitter::write ( std::string const &  label,
T const &  data 
)

Write method for use inside maps / dicts / objects.

References assert_in(), do_indent(), write_label(), and write_raw().

void basic::Emitter::write_label ( std::string const &  label)
inlineprotected

Write the key part of a key-value pair.

References out_, and quote_string().

Referenced by start_list(), start_map(), and write().

virtual void basic::Emitter::write_list_marker ( )
protectedpure virtual

Used for traditional YAML output, writes the "-" marker.

Implemented in basic::JsonEmitter, and basic::YamlEmitter.

Referenced by write().

void basic::Emitter::write_raw ( bool  b)
inlineprotected

References out_.

Referenced by write().

void basic::Emitter::write_raw ( int  i)
inlineprotected

References out_.

void basic::Emitter::write_raw ( long  l)
inlineprotected
void basic::Emitter::write_raw ( float  f)
inlineprotected

References demo.D060_Folding::f, and out_.

void basic::Emitter::write_raw ( double  d)
inlineprotected

References out_.

void basic::Emitter::write_raw ( std::string const &  s)
inlineprotected

References out_, and quote_string().

Member Data Documentation

std::vector<bool> basic::Emitter::first_
protected
std::vector<bool> basic::Emitter::in_map_
protected
std::vector<bool> basic::Emitter::indent_
protected
std::vector<int> basic::Emitter::indent_depth_
protected
std::string basic::Emitter::indent_str_
protected
std::ostream& basic::Emitter::out_
protected

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