Rosetta 3.3
Public Member Functions | Protected Member Functions | Protected Attributes
basic::Emitter Class Reference

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

#include <Emitter.hh>

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

List of all members.

Public Member Functions

 Emitter (std::ostream &out)
virtual ~Emitter ()
void flush ()
 Flush the underlying output stream.
template<typename T >
void write (T const &data)
 Write method for use inside lists / arrays.
void start_list (bool indent=true)
 Write method for use inside lists / arrays.
void start_map (bool indent=true)
 Write method for use inside lists / arrays.
template<typename T >
void write (std::string const &label, T const &data)
 Write method for use inside maps / dicts / objects.
void start_list (std::string const &label, bool indent=true)
 Write method for use inside maps / dicts / objects.
void start_list (const char *label, bool indent=true)
 Write method for use inside maps / dicts / objects.
void start_map (std::string const &label, bool indent=true)
 Write method for use inside maps / dicts / objects.
void start_map (const char *label, bool indent=true)
 Write method for use inside maps / dicts / objects.
void end_list ()
 Counterpart to start_list() -- writes closing bracket.
void end_map ()
 Counterpart to start_map() -- writes closing brace.
void end (size_t desired_depth=0)
 By default, closes all open maps/lists, ending the document.
int depth () const
 Number of closing brackets/braces required to end document (non-negative)
void set_indent (int num_spaces)
 Number of spaces used for indenting. Default is one.
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.

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)
void write_label (std::string const &label)
 Write the key part of a key-value pair.
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).
virtual std::string quote_string (std::string const &s)=0
 Quotes strings as much as needed for this format (e.g. always for JSON).
virtual void do_indent (bool write_comma=true)=0
 Handle pretty-printing indentation. Don't want to use commas for opening/closing brace/bracket.
virtual void write_list_marker ()=0
 Used for traditional YAML output, writes the "-" marker.
virtual void start_raw (bool is_map, bool indent)=0
 Actual implementation of start_map() and start_list().
virtual void end_raw ()=0
 Actual implementation of end_map() and end_list().

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]
virtual basic::Emitter::~Emitter ( ) [inline, virtual]
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 
) [inline, protected]

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::JsonEmitter::do_indent(), basic::YamlEmitter::do_indent(), and end().

virtual void basic::Emitter::do_indent ( bool  write_comma = true) [protected, pure virtual]

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

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

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(), end_raw(), and color_pdb::i.

Referenced by basic::JsonEmitter::start_doc(), and basic::YamlEmitter::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 ( ) [protected, pure virtual]

Actual implementation of end_map() and end_list().

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

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 color_pdb::i, basic::options::OptionKeys::out::file::o, and basic::options::OptionKeys::in::file::s.

Referenced by basic::JsonEmitter::quote_string(), and basic::YamlEmitter::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) [protected, pure virtual]

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

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

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 color_pdb::i, 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::YamlEmitter, and basic::JsonEmitter.

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_list ( std::string const &  label,
bool  indent = true 
) [inline]

Write method for use inside maps / dicts / objects.

References start_list().

Referenced by start_list().

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

Write method for use inside lists / arrays.

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

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

Write method for use inside maps / dicts / objects.

References start_map().

Referenced by 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().

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

Write method for use inside lists / arrays.

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

virtual void basic::Emitter::start_raw ( bool  is_map,
bool  indent 
) [protected, pure virtual]

Actual implementation of start_map() and start_list().

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

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) [inline, protected]

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 ( ) [protected, pure virtual]

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

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

Referenced by write().

void basic::Emitter::write_raw ( double  d) [inline, protected]
void basic::Emitter::write_raw ( std::string const &  s) [inline, protected]

References out_, and quote_string().

void basic::Emitter::write_raw ( long  l) [inline, protected]
void basic::Emitter::write_raw ( int  i) [inline, protected]

References color_pdb::i, and out_.

void basic::Emitter::write_raw ( bool  b) [inline, protected]

References out_.

Referenced by write().

void basic::Emitter::write_raw ( float  f) [inline, protected]

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:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines