Nodes and paths

Node types, paths, and the lower-level node parser.

class BaseNode : public snt::dip::Node, public std::enable_shared_from_this<BaseNode>

#include <node_base.h>

Subclassed by snt::dip::CaseNode, snt::dip::ValueNode

Public Types

using PointerType = std::shared_ptr<BaseNode>

using ListType = std::deque<BaseNode::PointerType>

Public Functions

inline BaseNode()

BaseNode(const BaseNode &other) = default

inline BaseNode(const NodeDtype dt)

inline BaseNode(const Parser &parser, const NodeDtype dt)

~BaseNode() override = default

virtual ListType parse(Environment &env)

Parse the supplied expression.

Parameters:: env – Environment providing symbols and configuration.

virtual bool set_property(PropertyType property, val::Array::StringType &values, std::string &units)

virtual std::string to_string(const core::StringFormatType &format = core::StringFormatType()) const

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

virtual BaseNode::PointerType clone(const Path &pth, std::optional<size_t> indent = std::nullopt) const

Clone node with all its settings

Parameters:

pth – Path of the cloned node
indent – Indent of the cloned node

Returns:

BaseNode pointer of the cloned node

Public Members

NodeDtype dtype

size_t branch_id

size_t case_id

std::string schema_id: Definition that supplied this node, when generated by a schema.

class BooleanNode : public snt::dip::ValueNode 

#include <node_boolean.h>

DIPL value node containing boolean data.

Public Functions

BooleanNode(const BooleanNode &other)

Copy a Boolean node.

Parameters:: other – Node to copy.

inline BooleanNode(const Path &pth, val::BaseValue::PointerType val): Construct a Boolean node at a path from an existing value.

inline BooleanNode(Parser &parser): Construct a Boolean node from parser input.

virtual BaseNode::ListType parse(Environment &env) override

Parse the supplied expression.

Parameters:: env – Environment providing symbols and configuration.

virtual BaseNode::PointerType clone(const Path &pth, std::optional<size_t> indent = std::nullopt) const override

Clone node with all its settings

Parameters:

pth – Path of the cloned node
indent – Indent of the cloned node

Returns:

BaseNode pointer of the cloned node

virtual void validate_options() const override

virtual std::string to_string(const core::StringFormatType &format = core::StringFormatType()) const override

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

Public Static Functions

static ValueNode::PointerType is_node(Parser &parser)

Return a Boolean node when the parser is positioned at a Boolean literal.

Parameters:: parser – Parser state to inspect.

class CaseNode : public snt::dip::BaseNode 

#include <node_case.h>

Conditional branch node in a DIPL hierarchy.

Public Functions

inline CaseNode(Parser &parser)

virtual BaseNode::ListType parse(Environment &env) override

Parse the supplied expression.

Parameters:: env – Environment providing symbols and configuration.

Public Members

bool value

size_t case_id

CaseType case_type

Public Static Functions

static BaseNode::PointerType is_node(Parser &parser)

class FloatNode : public snt::dip::ValueNode 

#include <node_float.h>

DIPL value node containing floating-point data.

Public Functions

FloatNode(const FloatNode &other)

Copy a floating-point node.

Parameters:: other – Node to copy.

inline FloatNode(const Path &pth, const core::DataType vdt): Construct a floating-point node with a path and data type flag.

inline FloatNode(const Path &pth, val::BaseValue::PointerType val): Construct a floating-point node from a value at a path.

inline FloatNode(const Path &pth, val::BaseValue::PointerType val, std::optional<puq::Quantity> quant): Construct a floating-point node with an optional quantity.

FloatNode(Parser &parser): Construct a floating-point node from parser input.

virtual BaseNode::ListType parse(Environment &env) override

Parse the supplied expression.

Parameters:: env – Environment providing symbols and configuration.

virtual BaseNode::PointerType clone(const Path &pth, std::optional<size_t> indent = std::nullopt) const override

Clone node with all its settings

Parameters:

pth – Path of the cloned node
indent – Indent of the cloned node

Returns:

BaseNode pointer of the cloned node

virtual std::string to_string(const core::StringFormatType &format = core::StringFormatType()) const override

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

Public Static Functions

static ValueNode::PointerType is_node(Parser &parser)

Return a floating-point node when the parser is positioned at a numeric literal.

Parameters:: parser – Parser state to inspect.

Public Static Attributes

static constexpr size_t max_float_size

class IntegerNode : public snt::dip::ValueNode 

#include <node_integer.h>

DIPL value node containing integer data.

Public Functions

IntegerNode(const IntegerNode &other)

Copy an integer node.

Parameters:: other – Node to copy.

inline IntegerNode(const Path &pth, const core::DataType vdt): Construct an integer node with a path and data type flag.

inline IntegerNode(const Path &pth, val::BaseValue::PointerType val): Construct an integer node from a value at a path.

inline IntegerNode(const Path &pth, val::BaseValue::PointerType val, std::optional<puq::Quantity> quant): Construct an integer node with an optional quantity.

IntegerNode(Parser &parser): Construct an integer node from parser input.

virtual BaseNode::ListType parse(Environment &env) override

Parse the supplied expression.

Parameters:: env – Environment providing symbols and configuration.

virtual BaseNode::PointerType clone(const Path &pth, std::optional<size_t> indent = std::nullopt) const override

Clone node with all its settings

Parameters:

pth – Path of the cloned node
indent – Indent of the cloned node

Returns:

BaseNode pointer of the cloned node

virtual std::string to_string(const core::StringFormatType &format = core::StringFormatType()) const override

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

Public Static Functions

static ValueNode::PointerType is_node(Parser &parser)

Return an integer node when the parser is positioned at an integer literal.

Parameters:: parser – Parser state to inspect.

Public Static Attributes

static constexpr size_t max_int_size

class Node

#include <node.h>

Subclassed by snt::dip::BaseNode, snt::dip::Parser

Public Functions

inline Node()

Node(const Node &other) = default

inline Node(const Line &l)

inline Node(const std::string &nm)

virtual ~Node() = default

Public Members

Line line: source code line information; in Python this were ‘code’ & ‘source’ variables

size_t indent: indent of a node

Path path: fully qualified node path

std::array<std::string, 3> dtype_raw: data type properties (unsigned/type/precision)

val::Array::StringType value_raw: raw value string(s)

val::Array::ShapeType value_shape: shape of an array value

ValueOrigin value_origin: origin of the value; in Python there were separate variables: value_ref, value_expr, value_func

val::Array::RangeType value_slice: slice of an injected node value

std::string units_raw: raw units string

val::Array::RangeType dimension: list of array dimensions

std::vector<std::string> schemas: list of parsed schemas

class Parser : public snt::dip::Node 

#include <parser.h>

Public Functions

inline Parser(const Line &l)

bool do_continue()

bool kwd_case()

bool kwd_unit()

bool kwd_source()

bool kwd_schema()

bool kwd_override()

bool kwd_property(PropertyType &ptype)

bool part_trim()

bool part_indent()

bool part_path(const bool required = true)

bool part_schema()

Parse schema specifier after group node path

Returns:: True if schema was parsed; otherwise, false.

bool part_type(const bool required = true)

Parse node type

Parameters:: required – Specifies if this part is required
Returns:: True if type was parsed; otherwise, false.

bool part_literal()

Parse literal node values from a string

Returns:: True if literal was successfully parsed; otherwise, false.

bool part_dimension()

bool part_equal(const bool required = true)

bool part_reference()

bool part_expression()

bool part_function()

bool part_array()

bool part_string()

bool part_keyword(const bool required = true, const char delimiter = ' ')

Parse a keyword from a code

Parameters:

required – Specifies if keyword is required or not
delimiter – Trailing character after a keyword

Returns:

True if the keyword was successfully parsed; otherwise, false.

bool part_none()

Parse none value from a code

Returns:: True if the none value was successfully parsed; otherwise, false.

bool part_number(const bool required = true, const char delimiter = ' ')

Parse a number from a code

Parameters:

required – Specifies if number is required or not
delimiter – Trailing character after a number

Returns:

True if the number was successfully parsed; otherwise, false.

bool part_value()

Parse node value

Returns:: True if the value was successfully parsed; otherwise, false.

bool part_slice()

bool part_format()

bool part_units(const char delimiter = ' ')

Parse units from a code

Parameters:: delimiter – Leading character before an unit expression

bool part_comment()

bool part_delimiter(const char symbol, const bool required = true)

Public Members

std::string code: in Python this was ‘ccode’, the original ‘code’ is now in the ‘line’ struct

std::string comment: parsed comment

std::array<std::string, 3> formatting

Public Static Functions

static void encode_escape_symbols(std::string &str)

static void decode_escape_symbols(std::string &str)

class Path

#include <path.h>

This class manages fully qualified node paths

Public Types

enum class Kind

List of collection types

Values:

enumerator None: Node is not a collection.

enumerator Empty: Path is empty, or root.

enumerator Group: Simple node or group.

enumerator Map: Map items are associated with a key.

enumerator List: List items are ordered by indexes.

enumerator Item: Item in a map or list collection.

enumerator Root: Path points to some hierarchy root (with a trailing .)

Public Functions

Path() = default: Class constructor

Path(const std::string &path)

Class constructor

Parameters:: path – Path that will be parsed

Path resolve(const std::string &path)

Create absolute path from a relative path.

Each leading dot moves one level up. A single “.” refers to the current path.

Examples: “.” -> foo.bar.baz “.snap.crackle” -> foo.bar.snap.crackle “..snap.crackle” -> foo.snap.crackle

Parameters:: path – Relative path
Returns:: Absolute path

std::string basename() const

Return name of the last node in the path

For a path foo.bar.baz, baz string will be returned.

Returns:: String with the last name

Path root() const

Return root of the node in the path

For a path foo.bar.baz, foo.bar. path will be returned.

Returns:: Root path

Path parent() const

Return parent of the node in the path

For a path foo.bar.baz, foo.bar path will be returned.

Returns:: Parent path

Public Members

std::string name: fully qualified node path

Kind kind: kind of a path

std::vector<Path::CollectionAccess> collections: list of collection access pairs derived from a node name

Public Static Attributes

static std::unordered_map<Kind, std::string> KindNames

struct CollectionAccess

#include <path.h>

Collection node information

Public Members

std::string path: Paths leading to a collection.

std::string item: Item value.

Kind kind: Kind of a collection path.

class StringNode : public snt::dip::ValueNode 

#include <node_string.h>

DIPL value node containing string data.

Public Functions

StringNode(const StringNode &other)

Copy a string node.

Parameters:: other – Node to copy.

inline StringNode(const Path &pth, val::BaseValue::PointerType val): Construct a string node from a value at a path.

inline StringNode(Parser &parser): Construct a string node from parser input.

virtual BaseNode::ListType parse(Environment &env) override

Parse the supplied expression.

Parameters:: env – Environment providing symbols and configuration.

virtual BaseNode::PointerType clone(const Path &pth, std::optional<size_t> indent = std::nullopt) const override

Clone node with all its settings

Parameters:

pth – Path of the cloned node
indent – Indent of the cloned node

Returns:

BaseNode pointer of the cloned node

virtual bool set_property(PropertyType property, val::Array::StringType &values, std::string &units) override

virtual void validate_format() const override

virtual std::string to_string(const core::StringFormatType &format = core::StringFormatType()) const override

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

Public Static Functions

static ValueNode::PointerType is_node(Parser &parser)

Return a string node when the parser is positioned at a string literal.

Parameters:: parser – Parser state to inspect.

struct ValueMetadata

#include <node_value.h>

Metadata attached to a value node or schema definition.

Public Functions

bool set_property(PropertyType property, const val::Array::StringType &values): Assign a ? metadata property; return false for directives and other properties.

Public Members

std::string description: Value or schema description.

std::string authors: Publication authors.

std::string title: Publication title.

std::string journal: Publication journal.

std::string year: Publication year.

std::string volume: Publication volume.

std::string issue: Publication issue.

std::string pages: Publication pages.

std::string doi: Publication DOI.

std::string url: Online URL of the publication.

std::string version: Publication version.

std::string created: Date of creation.

std::string modified: Date of modification.

std::string license: License of the value or schema.

std::string rationale: Why the selected value is appropriate.

std::vector<std::string> native: Native target name(s)

std::vector<std::string> conflicts: Incompatible paths or capabilities.

std::vector<std::string> implies: Implied paths or capabilities.

std::vector<std::string> see: Related paths.

std::vector<std::string> example: Recommended example values.

std::string recommended_range: Advisory, non-enforcing range.

std::string performance_impact: Computational-cost implication.

std::string scientific_impact: Modelling implication.

std::string deprecated: Deprecation notice.

std::string replacement: Replacement path.

std::string since: Introducing schema/software version.

std::string category: Documentation grouping.

std::string visibility: Documentation/UI visibility.

class ValueNode : public snt::dip::BaseNode 

#include <node_value.h>

Subclassed by snt::dip::BooleanNode, snt::dip::FloatNode, snt::dip::IntegerNode, snt::dip::StringNode

Public Types

using PointerType = std::shared_ptr<ValueNode>

using ListType = std::deque<ValueNode::PointerType>

Public Functions

inline ValueNode(): Construct an empty value node.

ValueNode(const ValueNode &other)

Copy a value node.

Parameters:: other – Node whose metadata and value are copied.

inline ValueNode(const core::DataType vdt)

Construct a value node with a declared value data type.

Parameters:: vdt – Data type of the stored value.

inline ValueNode(const Parser &parser, const NodeDtype dt, const core::DataType vdt = core::DataType::None)

Construct a value node from parser state.

Parameters:

parser – Parser providing node metadata.
dt – DIP node data type.
vdt – Stored value data type.

ValueNode(const BaseNode::PointerType other, const NodeDtype dt, const core::DataType vdt = core::DataType::None)

Construct a value node by copying another node’s value.

Parameters:

other – Source node.
dt – DIP node data type.
vdt – Stored value data type.

ValueNode(const ValueNode::PointerType other, const NodeDtype dt)

Construct a value node from an existing value node.

Parameters:

other – Source node.
dt – DIP node data type.

ValueNode(const Path &pth, const core::DataType vdt, const NodeDtype dt = NodeDtype::None)

Construct a value node at a path with a value data type.

Parameters:

pth – Node path.
vdt – Stored value data type.
dt – DIP node data type.

ValueNode(const Path &pth, val::BaseValue::PointerType val, const NodeDtype dt, std::optional<puq::Quantity> unt = std::nullopt)

Construct a value node at a path from a value and optional units.

Parameters:

pth – Node path.
val – Stored value.
dt – DIP node data type.
unt – Optional physical quantity units.

~ValueNode() override = default

val::BaseValue::PointerType parse_function(Environment &env, const std::string &name, std::optional<std::string_view> units) const

val::BaseValue::PointerType parse_reference(Environment &env, std::string query, std::optional<std::string_view> units, ValueOrigin origin) const

val::BaseValue::PointerType parse_expression(Environment &env, const std::string &expression, std::optional<std::string_view> units, const NodeDtype ntype) const

val::BaseValue::PointerType cast_value() const

val::BaseValue::PointerType cast_value(const val::Array::StringType &value_input, const val::Array::ShapeType &shape) const

void set_value(val::BaseValue::PointerType value_input = nullptr)

Replace the node’s stored value and update its value metadata.

Parameters:: value_input – Owned VAL value; nullptr clears the current value.

void set_units(const std::optional<puq::Quantity> &units_input = std::nullopt)

Replace the physical quantity metadata associated with the node.

Parameters:: units_input – Quantity metadata to assign; std::nullopt removes the units.

void apply_override(const BaseNode::PointerType &node, Environment &env): Evaluate an override against this declaration without evaluating its original value.

void validate_modification(const BaseNode::PointerType &node) const: Check that a subsequent declaration preserves the node type.

virtual void modify_value(const BaseNode::PointerType &node, Environment &env)

virtual bool set_property(PropertyType property, val::Array::StringType &values, std::string &units) override

inline virtual std::string to_string(const core::StringFormatType &format = core::StringFormatType()) const override

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

void validate_constant() const

void validate_definition() const

void validate_condition(Environment &env) const

virtual void validate_options() const

virtual void validate_format() const

Public Members

core::DataType value_dtype

val::BaseValue::PointerType value

std::optional<puq::Quantity> units

val::Array::StringType tags: Explicit node labels used for discovery and selection.

bool constant

bool override: Value was selected by an explicit $override.

Line override_line: Source of the effective override value.

std::vector<Line> modification_lines: Applied value modifications in evaluation order.

std::string table_path: Parent table when this value is a parsed table column.

size_t table_column_index: Position in the original table header.

std::string condition

std::vector<OptionStruct> options

std::string format

ValueMetadata metadata: Metadata on this value node, including schema member metadata.

struct OptionStruct

#include <node_value.h>

Public Members

val::BaseValue::PointerType value

std::string value_raw

std::string units_raw

struct ValueNodeData

#include <node_value.h>

Structure that holds value node data

This structure is used in solvers as a lightweight value node data

Public Members

val::BaseValue::PointerType value: Node value.

std::optional<puq::Quantity> units: Node quantity.