Parsing and querying

Load DIPL definitions, evaluate environments, and retrieve values.

enum class snt::dip::RequestType

Type of an environment request

Values:

enumerator Reference: Search in the node list.

enumerator Function: Search in the function list.

enum class snt::dip::ExportFormat

List of available DIP generators that produce static parameter lists

Values:

enumerator CPP

enumerator C

enumerator FORTRAN

enumerator RUST

enumerator R

enumerator JULIA

enumerator JSON

enumerator TOML

enumerator YAML

enum class snt::dip::ArtifactKind

Classification by conventional filename; it does not validate file contents.

Values:

enumerator Unknown

enumerator Project

enumerator DIPL

enumerator TableText

enumerator DIPH5

enum class snt::dip::ValueChangeKind

Owned, read-only facts about one evaluated value.

Values:

enumerator Declaration

enumerator Modification

enumerator Override

enum class snt::dip::CaseType

Values:

enumerator IF

enumerator ELIF

enumerator ELSE

enumerator END

enum class snt::dip::ValueOrigin

Values:

enumerator Empty

enumerator None

enumerator Keyword

enumerator Boolean

enumerator Number

enumerator String

enumerator Array

enumerator Reference

enumerator ReferenceRaw

enumerator ReferenceRel

enumerator ReferenceSelf

enumerator Function

enumerator FunctionRes

enumerator Expression

enumerator Schema

enum class snt::dip::NodeDtype

Values:

enumerator None

enumerator Empty

enumerator Unit

enumerator Source

enumerator Group

enumerator Case

enumerator Schema

enumerator Override

enumerator Import

enumerator Boolean

enumerator Integer

enumerator Float

enumerator String

enumerator Table

enumerator Deferred

enumerator Modification

enumerator Property

enum class snt::dip::PropertyType

Values:

enumerator None

enumerator Constant

enumerator Condition

enumerator Tags

enumerator Format

enumerator Options

enumerator Description

enumerator Authors

enumerator Title

enumerator Journal

enumerator Year

enumerator Volume

enumerator Issue

enumerator Pages

enumerator DOI

enumerator URL

enumerator Version

enumerator Created

enumerator Modified

enumerator License

enumerator Rationale

enumerator Native

enumerator Requires

enumerator Conflicts

enumerator Implies

enumerator See

enumerator Example

enumerator RecommendedRange

enumerator PerformanceImpact

enumerator ScientificImpact

enumerator Deprecated

enumerator Replacement

enumerator Since

enumerator Category

enumerator Visibility

enumerator Delimiter

constexpr std::string_view snt::dip::ROOT_SOURCE

constexpr std::string_view snt::dip::FILE_SOURCE

constexpr std::string_view snt::dip::STRING_SOURCE

constexpr std::string_view snt::dip::DIRECT_SOURCE

constexpr std::string_view snt::dip::TABLE_SOURCE

constexpr char snt::dip::SEPARATOR_NEWLINE

constexpr char snt::dip::SEPARATOR_DIMENSION

constexpr char snt::dip::SEPARATOR_ARRAY

constexpr char snt::dip::SEPARATOR_SLICE

constexpr char snt::dip::SEPARATOR_TABLE_COLUMNS

constexpr std::string_view snt::dip::SEPARATOR_TABLE_HEADER

constexpr char snt::dip::SIGN_QUERY

constexpr char snt::dip::SIGN_WILDCARD

constexpr char snt::dip::SIGN_NEGATE

constexpr char snt::dip::SIGN_DEFINED

constexpr char snt::dip::SIGN_SEPARATOR

constexpr char snt::dip::SIGN_CONDITION

constexpr char snt::dip::SIGN_ARRAY_OPEN

constexpr char snt::dip::SIGN_ARRAY_CLOSE

constexpr char snt::dip::SIGN_REFERENCE_OPEN

constexpr char snt::dip::SIGN_REFERENCE_CLOSE

constexpr char snt::dip::SIGN_EXPRESSION_OPEN

constexpr char snt::dip::SIGN_EXPRESSION_CLOSE

constexpr char snt::dip::SIGN_EQUAL

constexpr std::string_view snt::dip::SIGN_BLOCK

constexpr std::string_view snt::dip::KEYWORD_NONE

constexpr std::string_view snt::dip::KEYWORD_BOOLEAN

constexpr std::string_view snt::dip::KEYWORD_INTEGER

constexpr std::string_view snt::dip::KEYWORD_FLOAT

constexpr std::string_view snt::dip::KEYWORD_STRING

constexpr std::string_view snt::dip::KEYWORD_TABLE

constexpr std::string_view snt::dip::KEYWORD_MAP

constexpr std::string_view snt::dip::KEYWORD_LIST

constexpr std::string_view snt::dip::KEYWORD_CONSTANT

constexpr std::string_view snt::dip::KEYWORD_CONDITION

constexpr std::string_view snt::dip::KEYWORD_FORMAT

constexpr std::string_view snt::dip::KEYWORD_TAGS

constexpr std::string_view snt::dip::KEYWORD_OPTIONS

constexpr std::string_view snt::dip::KEYWORD_DELIMITER

constexpr std::string_view snt::dip::KEYWORD_DESCRIPTION

constexpr std::string_view snt::dip::KEYWORD_AUTHORS

constexpr std::string_view snt::dip::KEYWORD_TITLE

constexpr std::string_view snt::dip::KEYWORD_JOURNAL

constexpr std::string_view snt::dip::KEYWORD_YEAR

constexpr std::string_view snt::dip::KEYWORD_VOLUME

constexpr std::string_view snt::dip::KEYWORD_ISSUE

constexpr std::string_view snt::dip::KEYWORD_PAGES

constexpr std::string_view snt::dip::KEYWORD_DOI

constexpr std::string_view snt::dip::KEYWORD_URL

constexpr std::string_view snt::dip::KEYWORD_VERSION

constexpr std::string_view snt::dip::KEYWORD_CREATED

constexpr std::string_view snt::dip::KEYWORD_MODIFIED

constexpr std::string_view snt::dip::KEYWORD_LICENSE

constexpr std::string_view snt::dip::KEYWORD_RATIONALE

constexpr std::string_view snt::dip::KEYWORD_NATIVE

constexpr std::string_view snt::dip::KEYWORD_REQUIRES

constexpr std::string_view snt::dip::KEYWORD_CONFLICTS

constexpr std::string_view snt::dip::KEYWORD_IMPLIES

constexpr std::string_view snt::dip::KEYWORD_SEE

constexpr std::string_view snt::dip::KEYWORD_EXAMPLE

constexpr std::string_view snt::dip::KEYWORD_RECOMMENDED_RANGE

constexpr std::string_view snt::dip::KEYWORD_PERFORMANCE_IMPACT

constexpr std::string_view snt::dip::KEYWORD_SCIENTIFIC_IMPACT

constexpr std::string_view snt::dip::KEYWORD_DEPRECATED

constexpr std::string_view snt::dip::KEYWORD_REPLACEMENT

constexpr std::string_view snt::dip::KEYWORD_SINCE

constexpr std::string_view snt::dip::KEYWORD_CATEGORY

constexpr std::string_view snt::dip::KEYWORD_VISIBILITY

constexpr std::string_view snt::dip::KEYWORD_IF

constexpr std::string_view snt::dip::KEYWORD_ELIF

constexpr std::string_view snt::dip::KEYWORD_ELSE

constexpr std::string_view snt::dip::KEYWORD_END

constexpr std::string_view snt::dip::KEYWORD_SOURCE

constexpr std::string_view snt::dip::KEYWORD_UNIT

constexpr std::string_view snt::dip::KEYWORD_SCHEMA

constexpr std::string_view snt::dip::KEYWORD_OVERRIDE

constexpr std::string_view snt::dip::PATTERN_KEYWORD

constexpr std::string_view snt::dip::PATTERN_NUMBER

constexpr std::string_view snt::dip::PATTERN_PATH

constexpr std::string_view snt::dip::FILE_SUFFIX_DIP1: Suffix name of a DIPL file.

constexpr std::string_view snt::dip::FILE_SUFFIX_DIP2: Suffix name of a DIPL file.

constexpr int snt::dip::INDENT_STEP: Number of white spaces in an indent step.

std::unordered_map<ValueOrigin, std::string> snt::dip::ValueOriginNames

std::unordered_map<NodeDtype, std::string> snt::dip::NodeDtypeNames

core::Diagnostic snt::dip::diagnostic_from_exception(const std::exception &error): Convert an existing DIP or core exception without parsing its formatted what() text. The code identifies the exception category; individual messages do not yet have codes.

ArtifactKind snt::dip::detect_artifact(const std::filesystem::path &path)

Environment snt::dip::open_artifact(const std::filesystem::path &path): Load a project, DIPL file, or DIPH5 snapshot into a new environment. .dipt is table input within DIPL, not a standalone environment.

void snt::dip::reload_artifact(Environment &current, const std::filesystem::path &path): Replace the current environment only after the new artifact loads successfully.

ValueInspection snt::dip::inspect_value(const Environment &env, std::string_view path)

std::vector<ValueInspection> snt::dip::inspect_values(const Environment &env): Values in environment order, each retaining its fully qualified path.

InspectionCapabilities snt::dip::inspect_capabilities(const Environment &env, std::string_view path): Works for evaluated value paths, groups, and collection paths.

TableInspection snt::dip::inspect_table(const Environment &env, std::string_view path)

std::vector<TableInspection> snt::dip::inspect_tables(const Environment &env)

val::BaseValue::PointerType snt::dip::read_value_slice(const Environment &env, std::string_view path, const val::Array::RangeType &ranges): Read an in-memory value slice without first cloning the whole array. Ranges are zero-based and inclusive. This does not perform lazy DIPH5 I/O.

class Cursor

#include <cursor.h>

Access a known environment path; the cursor must not outlive its environment.

Public Functions

explicit Cursor(const Environment *env, std::string_view path = "")

std::unordered_map<std::string, Cursor> children() const

Return cursors for named children when group traversal is implemented.

Note

Group-child traversal is currently not implemented.

Returns:: A map keyed by child name.

std::vector<Cursor> elements() const

Return cursors for elements of the current sequence node in index order.

Returns:: A vector of element cursors; throws if the cursor is not a sequence.

std::unordered_map<std::string, Cursor> items() const

Return cursors for entries of the current mapping node.

Returns:: A map keyed by entry name; throws if the cursor is not a mapping.

bool has_item(const std::string &item) const

Test if keyed item exists for the current path

Returns:: true if item exists, false if not

const std::string &get_path() const

Get current cursor path

Returns:: Fully qualified path of the cursor

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

Return the value stored at this path.

Returns:: A newly allocated VAL value; throws when the path is absent or not a value node.

std::optional<puq::Quantity> get_units() const

Return the physical quantity metadata attached to the value at this path.

Returns:: The quantity metadata, or std::nullopt when the node has no units.

dip::ValueNode::PointerType get_node() const

Get the environment-owned value node at the current cursor path. Unlike Environment::select(), this is not an independent snapshot.

Returns:: A value node pointer

Provenance get_provenance() const

Return source and citation provenance for the value at this path.

The source manifest entry is present when the environment has a registered source (after parsing) or a DIPH5 v2 source manifest.

val::Array::ShapeType get_shape() const

Get shape of a value node at the current cursor path

Returns:: Shape array of a value node

const Path::Kind get_kind() const

Get path kind of the current cursor

Returns:: Cursor path kind

const std::string to_string() const

Get string representation of the cursor

Returns:: String representation of a cursor

template<typename T> inline T as() const

Cast cursor as a specific scalar/array/vector type

Template Parameters:: Expected – value type

Cursor operator[](std::string_view path) const

Get cursor from a fully qualified path, its part, or a keyed item from a map collection

Parameters:: path – Relative path, map key, or child name.
Returns:: Cursor at the given path

Cursor operator[](size_t index) const

Select indexed item from a list collection

Parameters:: index – Zero-based list index.
Returns:: Item cursor at the given index

class DIP

#include <dip.h>

Public Functions

DIP(): Empty class constructor

DIP(const Source &src)

Class constructor with a specified source

Parameters:: src – Source of the parent DIP class

void add_string(const std::string &source_code)

Add DIPL code from a string

Parameters:: source_code – Text with a DIPL code

void add_schema_string(const std::string &name, const std::string &source_code): Register a named schema body without a $schema wrapper. Leading ? metadata properties describe the schema definition; properties beneath a value node describe that value in every instance. The schema is available in the Environment::schemas registry after parse().

void add_schema_file(const std::string &name, const std::filesystem::path &source_file): Register a named schema body from a file, with the same rules as add_schema_string().

void add_override_string(const std::string &source_code): Atomically register value-only modifications from an unwrapped $override body. Dotted paths and nested prefixes resolve to existing targets, including active conditional nodes. An empty or comment-only body makes no changes.

void add_override_file(const std::filesystem::path &source_file): Register an unwrapped override body from a file, retaining its source path. An empty or comment-only file makes no changes.

void add_file(const std::filesystem::path &source_file, std::string source_name = {}, bool absolute = false)

Add DIPL code from a file

Parameters:

source_file – File name of a DIPL code file
source_name – Specific source name of the nodes
absolute –

void add_source(const std::string &source_name, const std::string &source_file)

Add DIPL source

Parameters:

source_name – Name of the new source
source_file – File name of a DIPL source file

void add_unit(const std::string &unit_name, const std::string &unit_expression)

Add unit definition

Parameters:

unit_name – Name of the new units
unit_expression – Unit definition

void add_project(const std::filesystem::path &project_file)

Add a DIP project manifest.

The manifest is ordinary DIPL containing units[], sources[], schemas[], overrides[], and ordered code[] records. Each schemas[] item has a name and exactly one file or string body, without a $schema wrapper. Each overrides[] item has a file containing an unwrapped $override body. Schemas and overrides are registered before model evaluation. Relative paths are resolved from the manifest’s directory.

Parameters:: project_file – Path to the DIPfile manifest.

void add_function_value(const std::string &name, FunctionList::DataFunctionType func)

Add function that returns a value

Parameters:

name – Name of the function
func – Function pointer

void add_function_nodes(const std::string &name, FunctionList::NodesFunctionType func)

Add function that returns list of nodes

Parameters:

name – Name of the function
func – Function pointer

Environment parse(): Parse DIPL code lines and return an environment with registered schemas.

std::string to_string()

Get a string representation of the current DIPL instance

Returns:: String representation of this class

class Environment

#include <environment.h>

Object of this class holds the whole DIP parsing environment

Public Functions

Environment(): Constructor of the Environment class

inline bool is_loaded_snapshot() const: Whether this environment was loaded from a DIPH5 snapshot.

void load(const std::filesystem::path &file)

Load evaluated DIP nodes from a DIPH5 file. Reusable schema definitions are not reconstructed; descriptive schema provenance is restored.

Parameters:: file – File name of the environment file

void save(const std::filesystem::path &file) const

Save evaluated DIP nodes to a DIPH5 file. The schema trace manifest is saved with schema descriptions and source provenance, but reusable definitions are not.

Parameters:: file – File name of the environment file

void generate(ExportFormat format, const std::filesystem::path &file) const

Generate static parameter lists from the environment nodes

Parameters:

format – Output format of a generated parameter list
file – File name of the generated parameter list

std::vector<SourceInfo> get_source_manifest() const

Return durable source identities for the parsed or loaded environment.

Parsed environments derive the manifest from their registered sources; loaded DIPH5 environments return the manifest stored in the file.

std::optional<SourceInfo> get_source_info(const std::string &name) const: Return the durable identity of a named DIPL source, when available.

void set_source_manifest(std::vector<SourceInfo> manifest): Replace persisted source-manifest information during environment loading. This does not recreate executable source definitions or source code.

std::vector<TraceInfo> get_trace_manifest() const: Return durable identities for registered units, schemas, and functions.

void set_trace_manifest(std::vector<TraceInfo> manifest): Replace persisted trace-registry information during environment loading.

std::vector<SchemaInfo> get_schema_manifest() const: Return schema descriptions and source provenance without executable definitions.

void set_schema_manifest(std::vector<SchemaInfo> manifest): Replace persisted schema provenance during DIPH5 loading.

std::vector<SchemaInfo> get_applied_schemas(const std::string &path) const: Return schemas applied along a value or collection path, in path order.

std::optional<SchemaInfo> get_contributing_schema(const std::string &path) const: Return the schema that supplied a value node, if known.

std::string request_code(const std::string &source_name) const

Get a source code

Parameters:: source_name – Name of a source
Returns:: Source code

ValueNodeData request_node_data(const std::string &request, const RequestType rtype = RequestType::Reference) const

Get node data (value + units) from a reference or a function based on a request expression

Parameters:

request – Request expression
rtype – Request type: reference, or function

Returns:

Selected value node data

val::BaseValue::PointerType request_value(const std::string &request, const RequestType rtype = RequestType::Reference, const std::optional<std::string_view> to_unit = std::nullopt) const

Get value from a reference or a function based on a request expression

Parameters:

request – Request expression
rtype – Request type: reference, or function
to_unit – Request values with a specific unit

Returns:

Selected ArrayValue object (in specified units)

ValueNode::ListType request_group(const std::string &request, const RequestType rtype = RequestType::Reference, const std::vector<std::string> &tags = {}) const

Request nodes from a reference or function. Reference results are snapshots with paths relative to the requested root. Tag filtering uses any-match semantics; an empty tag list imposes no restriction. Empty results throw.

Parameters:

request – Request expression
rtype – Request type: reference, or function
tags – Tags of which at least one must occur on each returned node

Returns:

Group of selected nodes

ValueNode::ListType select(const std::string &request = "?", const TagFilter &tags = {}) const: Select independent snapshots with original fully qualified paths in environment order. ? selects all values, ?path an exact value, and ?path. a subtree, including its value-bearing root and collection members. Each path is returned once. Filters combine with AND and match explicit, non-inherited tags. Selection does not modify the environment. No matches returns an empty list. Source-qualified queries are also supported.

std::unordered_map<std::string, ValueNode::ListType> request_map(const std::string &request, const RequestType rtype = RequestType::Reference, const std::vector<std::string> &tags = {}) const

Get a keyed collection of nodes from a reference or a function based on a request expression

Parameters:

request – Request expression
rtype – Request type: reference, or function
tags – List of tags that filter selected set

Returns:

Keyed collection of nodes

std::vector<ValueNode::ListType> request_list(const std::string &request, const RequestType rtype = RequestType::Reference, const std::vector<std::string> &tags = {}) const

Get a indexed collection of nodes from a reference or a function based on a request expression

Parameters:

request – Request expression
rtype – Request type: reference, or function
tags – List of tags that filter selected set

Returns:

Indexed collection of nodes

val::BaseValue::PointerType get_value(size_t index) const

Get parsed node value at the specific index

Parameters:: index – Index of a node
Returns:: ArrayValue of a selected node

ValueNode::PointerType get_node(const std::string &path) const

Get an environment-owned pointer to a node with a specific name. The pointer refers to the stored node, unlike the snapshots from select().

Parameters:: path – Path name of a searched node
Returns:: Pointer to a selected node

const std::string to_string() const

Represent environment as a string

Returns:: String representation of an environment

Cursor operator[](std::string_view path) const

Get cursor from a fully qualified path

Parameters:: path – Relative or fully qualified DIPL path.
Returns:: Cursor at the given path

Public Members

NodeList<ValueNode> nodes: List of parsed nodes.

HierarchyList hierarchy: List of node hierarchy (parent nodes)

BranchingList branching: List of code branching (case, else)

SourceList sources: List of code sources.

UnitList units: List of custom units.

SchemaList schemas: Reusable definitions; not restored from DIPH5.

OverrideList overrides: Collected value modifications for initial evaluation.

FunctionList functions: List of functions.

class EnvironmentException : public snt::dip::Exception : #include <exceptions.h>

Environment exceptions signal problems with DIP environments

class Exception : public snt::core::ExceptionBase<dip::ExceptionInfo>

#include <exceptions.h>

Subclassed by snt::dip::EnvironmentException, snt::dip::IOException, snt::dip::MissingException, snt::dip::ParserException, snt::dip::PybindException, snt::dip::SolverException, snt::dip::SyntaxException, snt::dip::UnitException

Public Functions

inline explicit Exception(dip::ExceptionInfo info)

inline explicit Exception(std::string message, std::string details, std::string suggestion, std::string origin_file, size_t origin_line, std::optional<Line> location_line = std::nullopt)

struct ExceptionInfo : public snt::core::ExceptionInfo

#include <exceptions.h>

Public Members

std::optional<core::SourceLocation> location: DIPL code line where exception occured.

struct InspectionCapabilities

#include <inspection.h>

Supported inspection operations and retained facts at a DIP path. hasReferenceGraph is false until dependency recording is implemented.

Public Members

bool hasValue

bool hasChildren

bool hasSource

bool hasProvenance

bool hasTabularData

bool hasArrayData

bool hasReferenceGraph

bool sourceEditable

bool directlyWritable

class IOException : public snt::dip::Exception : #include <exceptions.h>

In/Out exceptions is triggered by problems with a file system (e.g. missing files, timeouts, …)

struct Line

#include <settings.h>

Public Functions

inline std::string to_string()

Public Members

std::string code

Source source

class MissingException : public snt::dip::Exception 

#include <exceptions.h>

Missing exception is triggered when functionality is not implemented yet

Public Functions

inline MissingException(std::string message, std::string file, std::size_t line, std::optional<Line> location_line = std::nullopt)

class ParserException : public snt::dip::Exception : #include <exceptions.h>

Parser exceptions occurs when internal DIP parsers fails

struct Provenance

#include <cursor.h>

Read-only provenance associated with the value selected by a cursor.

Public Members

std::string source_name

size_t source_line

std::string source_code

ValueMetadata metadata

std::optional<SourceInfo> source

std::optional<SourceInfo> override_source: Source of an applied override, if any.

size_t override_line

std::string override_code

class PybindException : public snt::dip::Exception : #include <exceptions.h>

Pybind exceptions are thrown during incorrect Python binding

struct SchemaInfo

#include <environment.h>

Descriptive schema provenance; contains no reusable schema nodes.

Public Members

std::string id

std::string name

std::string source_name

size_t source_line

ValueMetadata metadata

std::optional<SourceInfo> source: Source identity and fingerprint when available.

class SolverException : public snt::dip::Exception : #include <exceptions.h>

Solver exceptions occurs when solver cannot process an expression

struct Source

#include <settings.h>

Public Members

std::string name

size_t line_number

struct SourceInfo

#include <environment.h>

Durable identity information for one DIPL source.

The digest covers the exact UTF-8 bytes parsed by DIP. It is a fingerprint, not embedded source content.

Public Members

std::string name

std::string path

std::string parent_name

size_t parent_line

std::string hash_algorithm

std::string hash

class SyntaxException : public snt::dip::Exception : #include <exceptions.h>

Syntax exceptions are triggered by incorrect DIPL syntax

struct TableColumnInspection

#include <inspection.h>

Metadata for a table column; values remain in the environment.

Public Members

size_t index

std::string name

std::string path

core::DataType type

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

ValueMetadata metadata

struct TableInspection

#include <inspection.h>

A read-only view of an evaluated DIPL table.

Public Members

std::string path

size_t rows

std::vector<TableColumnInspection> columns

struct TagFilter

#include <environment.h>

Forward declaring.

Match explicitly assigned node tags; fields combine with AND.

Public Functions

bool matches(const std::vector<std::string> &tags) const: Empty filter fields impose no restriction.

Public Members

std::vector<std::string> all: Require every listed tag.

std::vector<std::string> any: Require at least one listed tag.

std::vector<std::string> none: Reject nodes with any listed tag.

struct TraceInfo

#include <environment.h>

Durable identity information for one registered DIPL construct.

Public Members

std::string id: Internal trace identifier, e.g. DIP0_UNIT0.

std::string name: Registered public name.

std::string kind: “unit”, “schema”, “function_value”, or “function_nodes”.

class UnitException : public snt::dip::Exception : #include <exceptions.h>

Unit exceptions indicate problems with units, conversions and operations

struct ValueChange

#include <inspection.h>

Public Members

ValueChangeKind kind

core::SourceLocation location

struct ValueInspection

#include <inspection.h>

Public Members

std::string path

core::DataType type

val::Array::ShapeType shape

val::BaseValue::PointerType value

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

ValueMetadata metadata

std::vector<std::string> tags

Provenance provenance

core::SourceLocation declaration_location

std::optional<core::SourceLocation> override_location

std::vector<SchemaInfo> applied_schemas

std::optional<SchemaInfo> contributing_schema

std::string table_path: Empty unless the value is a table column.

std::vector<ValueChange> changes: Applied changes in evaluation order.