Parsnip Namespace Reference

Serialization and parsing library. More...

Data Structures
class	Exception
	Class representing issues related to serialization & parsing. More...
class	DataRangeError
	DataRangeError indicates a value received in a stream can't be represented. More...
class	Data
	Generic data type. More...
class	DataFormatError
	DataFormatError represents a syntax error in a datastream. More...
class	NoSuchKey
	An element requested from a constant dictionary does not exist. More...
class	IncorrectDataType
	The data's type is inconsistent with the use requested of it. More...
class	IncorrectListSize
	The list size does not meet schema requirements. More...
class	InvalidKey
	They key is not specified in the schema. More...
class	SchemaConflict
	Parsing/command patterns produce schema inconsistency. More...
struct	SchemaBaseDeleter
	Helper functor for schema smart pointers. More...
class	SchemaBaseRef
	Smart pointer for schemas, with unusual ability to be copied. More...
class	Schema
	Schema for one JSON object. More...
class	ArgumentVector
	This class lexically analyzes a string, splitting it up into tokens, which are accessed as a vector. More...
class	ArgvCursor
	An iterator for argument vectors. More...
class	NumberOutOfRange
	NumberOutOfRange: The number was outside the range defined in the command pattern. More...
class	NotNumeric
	Not numeric: A command pattern specified a number, but the token was not valid number. More...
class	InvalidValue
	A token encountered was not one of the expected keywords. More...
class	IncompleteCommand
	More tokens were expected. More...
class	RunOnCommand
	There were extra tokens at the end of the command pattern. More...
class	DuplicateOption
	An option was supplied twice to an iterating option parser. More...
class	NoSchemaDefined
	A schema is not defined for a certain command ID. More...
struct	EvaluatorDeleter
	This does what std::default_delete would do, but is required since we haven't defined Evaluator yet. More...
class	OptionParser
	A class for parsing command line options (name-value pairs, for instance). More...
class	Parser
	A class for parsing command lines. More...
class	Interpreter
class	Dispatcher
class	SchemaSet
	A schema built to validate JSON messages based on command line patterns. More...
class	Evaluator
	Evaluator base class. More...
class	TerminatorEvaluator
	An evaluator representing abrupt end of the command pattern. More...
class	EndOfOptionEvaluator
	An evaluator representing abrupt end of the command pattern. More...
class	ValueEvaluator
	Evaluate a value/fill-in field. More...
class	StringEvaluator
	Evaluate a string value field. More...
class	RegExEvaluator
	Evaluate a string value field. More...
class	RawRemainderEvaluator
	Gather the rest of the command line as an untokenized string. More...
class	IntegerEvaluator
	Evaluate and validate an integral value field. More...
class	RealEvaluator
	Evaluate and validate a numeric value field. More...
class	KeywordEvaluator
	Evaluate a keyword in a command line. More...
class	RemainderEvaluator
	An evaluator that represents the rest of the command line. More...
class	RemainingValuesEvaluator
	Gather the rest of the command line tokens in a list. More...
class	OptionEvaluator
	Evaluate remainder with a different parser. More...
class	SchemaBase
class	UncheckedSchema
	Schema component requiring data be a particular type. More...
class	TypeSchema
	Schema component requiring data be a particular type. More...
class	StringSchema
	Schema component requiring data be a string of characters (no control characters). More...
class	RegExSchema
	Schema component requiring data be a string of characters matching a regular expression. More...
class	KeywordSchema
	Schema component accepting strings with certain values. More...
class	RangeSchema
	Schema component for numeric data, either Integer or Real. More...
class	IntegerSchema
class	OptionSchema
	Schema adapter component that allows use of schemas from option parsers. More...
class	ListSchema
	Schema component for lists. More...
class	DictionarySchema
	Schema component for validating dictionaries. More...
class	ConjunctionSchema
	A meta-schema that determines if any, all, or exactly one or none of its subschemas are valid. More...
class	InvalidSchema
	Parsing/command patterns produce schema inconsistency. More...

Typedefs
using	InputStream = std::istream
using	SchemaRef = std::shared_ptr< class Schema >
using	EvaluatorRef = std::unique_ptr< class Evaluator, EvaluatorDeleter >
using	OptionParserRef = std::shared_ptr< OptionParser >
using	ParserRef = std::shared_ptr< Parser >
using	SchemaSetRef = std::shared_ptr< SchemaSet >
using	SchemaIntegratorCallback = std::function< void(const int, const class DictionarySchema &)>
using	NumberSchema = RangeSchema< double >

Functions
Data	parse_json (std::istream &from, bool check_termination)
	Parse a stream as JSON data. More...
Data	parse_json (const std::string &from)
	Parse a string as a JSON stream. More...
std::ostream &	operator<< (std::ostream &out, const Parsnip::Data &data)
void	parser_assert (bool requirement, const char *explanation)
void	parser_assert (bool requirement, const char *explanation, const std::string &detail)
std::istream::int_type	next_non_whitespace (InputStream &from)
	Read from a stream until a non-whitespace character is found. More...

Variables
const std::string	EmptyString
const char	hex_digits [] = "0123456789abcdef"
	Digits used for encoding/decoding hexadecimal.

Detailed Description

Serialization and parsing library.

Classes providing evaluation for command lines.

The Parser class accepts arrays of strings/command ID combinations (Parser::Definition). From these, it builds a parse tree against which it can subsequently evaluate commands, identifying commands by ID and providing a dictionary the commands parameters. Multiple definition sets can be added to a single parser.

Lexically, commands are split at spaces, unless quoted. Single or double quotes may be used, but must match. Open quotes are only identified at the start of a word, close quotes only at the end of a word. Quotes may be doubled within a quoted span to insert a literal quote.

Statement patterns can be composed of:

Literal:

• keyword – a bare word for matching command pattern. Alternation:
• <name:one|two> – accepts any 1 of the required words in that position Optional:

[name:optional] – accepts an optional word in the current position

• [name:four|five] – accepts 0 or 1 optional words in the current position

[word] – accepts an optional word, named itself, in the current position Fillable fields:

• {name} – accepts any string/number/value in that position
  • {#name:3-5} – Accepts numeric range in that position. See range note below.
• {name...} – accepts the remainder of the command line, raw/unparsed as a single string. Optional remainder fillable fields (only at end of command):
• [{name}] – accepts a single optional value; may be string or numeric fillable.
• [{name}] ... – accepts 0 or more optional values; may be string or numeric fillable.
• [{name...}] – accepts the raw/unparsed remainder, if present. Always string.

Names:

• Must not vary within consistent parsing patterns
• May be reused in different branches; use with care.

Alternation and optional patterns may contain an arbitrary number of possible keywords, Storage behavior:

• Numeric values with ranges are evaluted and stored in the dictionary as their proper type.
• Alternation options are stored as strings.
• Optional keywords are stored as strings when present, otherwise omitted.
• Remainders (parsed form, optional or not) return an array of the appropriate type. No values returns an empty array, rather than the array being omitted.

Ranges:

• If either min or max in range have a decimal point, values are treated as doubles. Otherwise, they are considered integers.
• For integers, if either min or max has a leading zero, it enables radix detection: 0 -> octal, 0x -> hex, otherwise decimal.
• If neither max nor min has a leading 0, only base 10 is accepted.
• Reals are always evaluated base 10.

Examples:

{ CREATE_USER,  "create <rank:admin|guest|user> {username} {password}" }
            -- Recognizes the 3 types of users and requires username & password parameter, nothing more.
{ CREATE_USER_EXTENDED, "create <rank:admin|guest|user> {username} {password} [{additional}] ..." }
            -- Recognizes the 3 types of users and requires username, password, & at least 1 additional parameter.
{ CREATE_USER_OPTIONAL_EXTENDED, "create <rank:admin|guest|user> {user} {password} ... }
            -- Recognizes the 3 types of users, requires username and password, allows additional parameters.
               This definition is incompatible with CREATE_USER above--the parser would error when adding this
               definition.  (There is no way to delineate that command and this command with 0 parameters.)

A completely different approach to the above would be:

{ CREATE_ADMIN_USER,    "create admin {username} {password} ..." },
{ CREATE_STANDARD_USER, "create standard {username} {password} ..." },
{ CREATE_GUEST_USER,    "create guest {username} {password} ..." }
            -- Returns different values for the different user types, so you can determine that
               from the command's enumeration instead of having to further parse. As written, these
               would each allow additional optional parameters beyond username and password.

Since the parse tree is assumed to be hard-coded in your application, this module simply throws a runtime_error it finds problems in the parse definitions.

Options parsing

An option parsers may be used inline or as a remainder handler:

• {name:parser} – accepts one matching sequence in that position
• {name:parser} ... – accepts 0 or more trailing sequences

The option parser must be predefined and registered with the containing Parser prior to adding statements that reference it. Values from within the option parser sequences are stored in a dictionary named name.

• It is an error to specify the same option twice.
• Remainder fill-ins are allowed.

• If the parser name in the fill-in referencing it is written as <name>, the first keyword of each option is are used to select the option parser.

  Example: {options:<my_options>}

  This allows optionals before the option parser, or multiple parallel option parsers. Only one option parser will be used at a time (though an optional non-iterating option parsing could precede a final iterating one).

Function Documentation

next_non_whitespace()

std::istream::int_type Parsnip::next_non_whitespace

(

InputStream &

from

)

Read from a stream until a non-whitespace character is found.

Exceptions

DataFormatError

if EOF is encountered.

parse_json() [1/2]

Data Parsnip::parse_json

(

const std::string &

from

)

Parse a string as a JSON stream.

Parameters

from	The string to parse.

Returns

Data structure accoring to parsed string.

Exceptions

DataFormatError	if JSON is mangled.
DataRangeError	If the stream contains unrepresentable numbers.

parse_json() [2/2]

Data Parsnip::parse_json	(	std::istream &	from,
		bool	check_termination
	)

Parse a stream as JSON data.

Parameters

from	The stream to parse.
check_termination	If true (default), validates stream terminates (EOF) after end of JSON data. If false, stops reading after a complete JSON object has been read.

Returns

Data structure accoring to parsed string.

Exceptions

DataFormatError	if JSON is mangled.
DataRangeError	If the stream contains unrepresentable numbers.