Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Protected Member Functions | List of all members
Teuchos::Reader Class Reference

The main class for users to read text using TeuchosParser. More...

#include <Teuchos_Reader.hpp>

Inherited by Teuchos::DebugReader, Teuchos::MathExpr::CalcReader, Teuchos::MathExpr::SymbolSetReader, Teuchos::regex::Reader, and Teuchos::YAMLParameterList::Reader.

Public Member Functions

virtual ~Reader ()
 Virtual destructor, allows polymorphism. More...
 
 Reader (ReaderTablesPtr tables_in)
 Constructor: accepts an RCP to ReaderTables. More...
 
void read_stream (any &result, std::istream &stream, std::string const &stream_name_in)
 The main method for reading a stream of text. More...
 
void read_string (any &result, std::string const &string, std::string const &string_name)
 A convenience method for reading a string. More...
 
void read_file (any &result, std::string const &file_name)
 A convenience method for reading a file. More...
 

Protected Member Functions

virtual void at_shift (any &result, int token, std::string &text)
 User-overridable SHIFT (token) method. More...
 
virtual void at_reduce (any &result, int production, std::vector< any > &rhs)
 User-overridable REDUCE (production) method. More...
 

Detailed Description

The main class for users to read text using TeuchosParser.

This is the most important user-facing class in TeuchosParser. A Reader represents the use of a set of ReaderTables to read (parse) a given stream of text. In most cases, users should create their own class deriving from Teuchos::Reader, and override the Reader::at_shift and Reader::at_reduce methods to implement the mechanics of their custom parser.

To use Reader, it must be given an RCP to a set of ReaderTables. In most cases, ReaderTables are constructed automatically from a Language using the make_reader_tables function. Notice that ReaderTables only have to be constructed once, and can be used simultaneously by multiple Readers. A Reader can only operate on one stream of text at a time, and contains all the variable parser state.

The Reader also provides some error reporting capability. If the text stream being read is valid as defined by the Language, the Teuchos::ParserFail exception will be thrown with a descriptive string. It is strongly recommended that code using Reader catch this exception and display its what() message to the console.

Classes deriving from Teuchos::Reader are also strongly recommended to throw the Teuchos::ParserFail exception class (or a class derived from it) to indicate that the text stream being read is invalid, usually due to constraints that can't be expressed in the Teuchos::Language.

Definition at line 85 of file Teuchos_Reader.hpp.

Constructor & Destructor Documentation

virtual Teuchos::Reader::~Reader ( )
inlinevirtual

Virtual destructor, allows polymorphism.

Definition at line 89 of file Teuchos_Reader.hpp.

Teuchos::Reader::Reader ( ReaderTablesPtr  tables_in)

Constructor: accepts an RCP to ReaderTables.

The set of streams accepted by this Reader is dictated solely by the contents of the ReaderTables, and any additional checking implemented in derived classes. ReaderTables should be constructed from a Language using make_reader_tables.

Definition at line 211 of file Teuchos_Reader.cpp.

Member Function Documentation

void Teuchos::Reader::read_stream ( any result,
std::istream &  stream,
std::string const &  stream_name_in 
)

The main method for reading a stream of text.

Parameters
resultA reference to the Teuchos::any result object. If the stream is accepted, this will be the result of the Reader::at_reduce call which reduced the root nonterminal of the Language.
streamThe input stream of text to be read.
name_inThe name of the stream. This name is only used for error reporting.

Definition at line 242 of file Teuchos_Reader.cpp.

void Teuchos::Reader::read_string ( any result,
std::string const &  string,
std::string const &  string_name 
)

A convenience method for reading a string.

This method calls Teuchos::Parser::read_stream

Definition at line 308 of file Teuchos_Reader.cpp.

void Teuchos::Reader::read_file ( any result,
std::string const &  file_name 
)

A convenience method for reading a file.

This method calls Teuchos::Parser::read_stream

Definition at line 313 of file Teuchos_Reader.cpp.

void Teuchos::Reader::at_shift ( any result,
int  token,
std::string &  text 
)
protectedvirtual

User-overridable SHIFT (token) method.

This method will be called when the lexer (ReaderTables::lexer) accepts a token in the text stream. The default implementation does nothing.

Parameters
resultA reference to the Teuchos::any result object. The contents of this object are user-defined, and will be passed later to the (rhs) argument of Reader::at_reduce when this token is reduced along with other Language symbols into a nonterminal.
tokenAn integer index denoting which token was accepted. This is the index of the token in the Language::tokens vector.
textThe full text which matched the token's regular expression. This is a non-const reference so that users may do things like move or swap it directly into the result object. Teuchos::Reader will find the longest substring accepted by the Teuchos::ReaderTables::lexer starting from its current stream position, then repeat from the new stream position.

Definition at line 321 of file Teuchos_Reader.cpp.

void Teuchos::Reader::at_reduce ( any result,
int  production,
std::vector< any > &  rhs 
)
protectedvirtual

User-overridable REDUCE (production) method.

This method will be called when the lexer (ReaderTables::lexer) accepts a token in the text stream. The default implementation does nothing.

Parameters
resultA reference to the Teuchos::any result object. The contents of this object are user-defined, and mayb be passed later to the (rhs) argument of Reader::at_reduce when this nonterminal is reduced along with other Language symbols into a nonterminal, of it will be assigned to the result value of Teuchos::Reader::read_stream itself iff the LHS of (production) is the root nonterminal.
tokenAn integer index denoting which production was reduced. This is the index of the production in the Language::productions vector.
textA vector containing the result objects associated with each RHS symbol in the production. These objects are the result of either previous calls to Reader::at_shift (if their associated symbol is a token) or Reader::at_reduce (if the associated symbol is a nonterminal). This is a non-const reference so that users may do things like move or swap it (or its elements) directly into the result object.

Definition at line 324 of file Teuchos_Reader.cpp.


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