Introduction¶
Synopsis¶
The C++ library lorina implements parsers for simple file formats used in logic synthesis and formal verification. A callback mechanism in form of customizable visitor classes allows users to react on parsed primitives and parse errors.
The library consists of several independent parsers. Each parser has
its own header file that contains a reader function
read_<format>
and a reader visitor <format>_reader
, where
<format>
has to be substituted with the format to be parsed. The
reader visitor class <format>_reader
provides a set of default
implementations of virtual on_<primitive>
methods called by the
parser. Each callback method corresponds to an event point defined
by the implementation of the parsing algorithm, e.g., the completion
of the parsing of the format’s header information, or a certain input
or gate definition.
The read_<format>
function can either be used to open and parse a
file provided by name (const std::string& filename
) or to parse
tokens from an input stream (std::istream& in
):
/* read file */
const std::string filename = ...;
read_<format>( filename, <format>_reader() );
/* read istream */
std::ifstream in( filename.c_str(), std::ifstream::in );
read_<format>( in, <format>_reader() );
Customization¶
The default behavior of any reader visitor can be customized by
deriving from a reader visitor and overriding its virtual callback
methods. In the following code snippet, the class
print_bench_input_decl
derives from bench_reader
and
customizes the behavior of the on_input
event point:
class print_bench_input_decl : public bench_reader
{
public:
void on_input( const std::string& name ) const override
{
std::cout << "INPUT: " << name << std::endl;
}
};
Diagnostics¶
To reduce code and executable size, error handling is implemented via return codes and a lightweight callback visitor mechanism (instead of C++ exceptions). This allows users to embed lorina into their projects even when C++ exceptions are globally disabled.
All reader functions read_<format>
either return
return_code::success
if parsing has been successful or otherwise
return_code::parse_error
. The diagnostic engine additionally
allows users to react on parse errors. Diagnostics are automatically
activated by providing a pointer to a diagnostic_engine
as a third
parameter to a reader function:
diagnostic_engine diag;
return_code result = read_<format>( filename, <format>_reader(), &diag );
The parse error event points and the corresponding error messages
are specified by the respective parsing algorithm. The default
behavior of the diagnostic engine can be customized (similarly to the
reader visitors) by deriving from diagnostic_engine and overriding
its virtual callback method emit
.