Parsing and querying

Load DIPL definitions, evaluate environments, and retrieve values.

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::SourcePathPolicy

How source paths are written into a DIPH5 source manifest.

Values:

enumerator Preserve: Write source paths as recorded during parsing or loading.

enumerator RelativeToSnapshot: Write file paths relative to the output DIPH5 directory.

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 JSON_METADATA

enumerator TOML

enumerator YAML

enum class snt::dip::DependencyEventKind

Values:

enumerator Value

enumerator Condition

enumerator Decision

enum class snt::dip::SourceEntityKind

A live DIP entity whose source can be inspected. For Path, source_name selects a named source; an empty source_name selects the evaluated project. ProjectEntry uses index instead of name.

Values:

enumerator Path

enumerator NamedSource

enumerator Schema

enumerator Unit

enumerator ProjectEntry

enum class snt::dip::SourceLocationRole

Values:

enumerator Source

enumerator Declaration

enumerator Modification

enumerator Override

enumerator Definition

enumerator Registration

enum class snt::dip::ValueChangeKind

Owned, read-only facts about one evaluated value.

Values:

enumerator Declaration

enumerator Modification

enumerator Override

enum class snt::dip::OverrideTargetKind

What an override may target in this evaluated model. This is a static guide, not validation of a proposed value or a substitute for preview.

Values:

enumerator Unavailable

enumerator ExistingValue

enumerator ExistingItem

enumerator NewItem

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 Labels

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_LABELS

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

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

Environment snt::dip::open_artifact(const std::filesystem::path &path, bool record_dependency_graph = false, bool retain_block_inputs = false): Load a project, DIPL file, or DIPH5 snapshot into a new environment. .dipt is table input within DIPL, not a standalone environment. Recording is opt-in for parsed sources; snapshots retain their saved graph state regardless of record_dependency_graph. Parsed string blocks are retained only when retain_block_inputs is true for a live parse.

void snt::dip::reload_artifact(Environment &current, const std::filesystem::path &path, bool record_dependency_graph = false, bool retain_block_inputs = false): Replace the current environment only after the new artifact loads successfully. Pass recording options again when refreshing a parsed source.

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.

PreviewResult snt::dip::preview(const std::filesystem::path &input, const std::vector<PreviewOverride> &overrides, bool record_dependency_graph = false, const ComparisonOptions &options = {}): Evaluate independent baseline and candidate parses without writing outputs.

struct BlockInput

#include <block_input.h>

Original string literal parsed into an array or table during a live parse.

Public Types

enum class Kind

Values:

enumerator Array

enumerator Table

Public Members

Kind kind

std::string path

std::string code

std::string source_name

std::size_t source_line

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 direct named children of the root, a group, or a collection item. Dotted paths without an explicit group node are traversable as implied groups.

Returns:: A map keyed by direct child name; throws for list and map cursors.

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, or nullptr for a DIPL none 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.

ValueMetadata get_metadata() const: Return effective metadata on a value, explicit group, collection, or collection item.

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

struct DependencyEdge

#include <dependency_graph.h>

An evaluated read of a DIP value or raw source. IDs use ?path, source?path, or source? for an entire raw source.

Public Members

std::string target

std::string request

std::string operand: EXS operand text when this read came from an expression.

struct DependencyEvent

#include <dependency_graph.h>

One evaluation of a value, validation condition, or branch decision.

Public Members

std::string owner

DependencyEventKind kind

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

std::vector<std::string> controlled_by: Active branch decision IDs for a value event.

std::string expression

std::optional<exs::CompositionGraph> composition

std::vector<DependencyEdge> reads

class DependencyGraph

#include <dependency_graph.h>

Retains evaluation order and provides effective forward and reverse links.

Public Functions

inline const DependencyEvent *latest(std::string_view owner, DependencyEventKind kind) const: Latest event for this owner and kind.

inline std::vector<DependencyEdge> dependencies(std::string_view owner) const: Effective reads of the value, excluding superseded declarations.

inline std::vector<std::string> referenced_by(std::string_view target) const: Value nodes whose current evaluation read the target.

Public Members

bool recorded: True when DIP captured this graph during parsing.

std::vector<DependencyEvent> events

struct DependencyNeighbor

#include <inspection.h>

One distinct value or source adjacent to a selected dependency-graph ID. request and operand describe the first effective read connecting the pair.

Public Members

std::string id

std::string request

std::string operand

struct DependencyNeighborhood

#include <inspection.h>

Local effective dependency graph for a value or source ID. Dependencies combine value and condition reads in that order, once per target. Readers are values whose latest evaluation reads the selected ID. The latest value and condition events remain separate so clients can inspect both expressions.

Public Members

std::string id

bool recorded

std::vector<DependencyNeighbor> dependencies

std::vector<DependencyNeighbor> readers

std::optional<DependencyEvent> value_event

std::optional<DependencyEvent> condition_event

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_string(const std::string &source_code, const std::string &source_name): Add in-memory DIPL code with a stable source name for diagnostics.

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 an unwrapped $override body. Value paths resolve to existing targets; terminal collection item groups may create schema-backed items. An empty or comment-only body makes no changes.

void add_override_string(const std::string &source_code, const std::string &source_name): Add an override body with a stable source name for diagnostics.

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_project(const ProjectBundle &bundle): Evaluate a self-contained text bundle with the normal DIPfile rules.

void add_project(const ProjectInput &project): Register a project entirely from memory, without filesystem access.

inline void set_project_file_reader(ProjectFileReader reader)

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(bool record_dependency_graph = false, bool retain_block_inputs = false): Parse DIPL code lines and return an environment with registered schemas. Dependency recording and retention of parsed string blocks are opt-in.

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 void set_project_file_reader(ProjectFileReader reader): File access used by DIPfile registrations and $source nodes.

inline const ProjectFileReader &project_file_reader() const

inline std::string read_project_file(const std::filesystem::path &path) const

inline void set_dependency_recording(bool enabled): Enable graph capture for this parse.

inline void set_dependency_graph(DependencyGraph graph): Restore a graph from a versioned snapshot.

exs::CompositionGraph *active_composition(const std::string &expression): Attach the operation tree produced by the numerical or logical solver.

void set_active_dependency_owner(std::string owner)

void set_value_controls(const std::string &owner, const std::vector<size_t> &case_ids)

void record_import_origin(const std::string &source_node_id)

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

inline const std::optional<OutputPlan> &output_plan() const

inline void set_output_plan(OutputPlan plan)

inline const std::filesystem::path &source_path_base() const: Base directory for relative source paths in a loaded snapshot.

inline const std::vector<ProjectEntry> &project_entries() const: Registrations from parsed DIPfiles. Snapshot loading does not restore these entries.

inline void record_project_entry(ProjectEntry entry)

inline const std::map<std::string, BlockInput> &block_inputs() const: String blocks from a live parse. Snapshots retain values, not source text.

inline bool block_input_recording() const

inline void set_block_input_recording(bool enabled)

void record_block_input(const BaseNode &declared, const BaseNode &input, const std::string &path): Capture the effective source literal after successful evaluation.

inline void erase_block_input(const std::string &path)

inline const ExplicitDeclarations &declarations() const: Explicit declarations in the evaluated scope.

inline void record_declaration(const std::string &path, const Line &line)

inline const std::vector<SchemaApplicationEvent> &schema_applications() const: Evaluation-order schema applications. Snapshots do not retain this history.

inline void record_schema_application(std::string path, std::string schema_name, bool inherited, const Line &line)

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 save(const std::filesystem::path &file, const SnapshotSaveOptions &options) const: Save with an explicit policy for source paths in the DIPH5 manifest.

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, std::string_view operand = {}) 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

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 DependencyScope

#include <environment.h>

Scope one parser evaluation. Restores the previous context on exit.

Public Functions

DependencyScope(Environment &env, std::string owner, DependencyEventKind kind, std::optional<core::SourceLocation> location = std::nullopt)

~DependencyScope()

DependencyScope(const DependencyScope&) = delete

DependencyScope &operator=(const DependencyScope&) = delete

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.

class ExplicitDeclarations

#include <declarations.h>

Explicit path declarations in one evaluated source scope. Inferred parent paths are intentionally absent. The first active declaration is retained.

Public Functions

inline void record(const std::string &path, const Line &line)

inline std::optional<Line> find(const std::string &path) const

struct InspectedSourceLocation

#include <inspection.h>

A semantic source location. When embedded text has a host registration, source and line identify that physical location while logical_source_name and logical_line retain the original declaration. All lines are one-based.

Public Members

SourceLocationRole role

SourceInfo source

std::size_t line

std::string logical_source_name

std::size_t logical_line

std::size_t modification_index

bool embedded_registration

bool source_text_available: Parsed text is retained in this environment.

struct InspectionCapabilities

#include <inspection.h>

Supported inspection operations and retained facts at a DIP path.

Public Members

bool hasValue

bool hasChildren

bool hasSource

bool hasProvenance

bool hasTabularData

bool hasArrayData

bool hasReferenceGraph

bool sourceEditable

bool directlyWritable

class Inspector

#include <inspector.h>

Read-only queries over one evaluated environment. The environment must outlive this view. Value and description results are owned; graph and retained block references belong to the environment.

Public Functions

inline explicit Inspector(const Environment &env)

Inspector(Environment&&) = delete

Inspector(const Environment&&) = delete

ValueNode::ListType select(const std::string &query = "?", const TagFilter &tags = {}) const: Select independent value snapshots in environment order. ? selects all values; ?path selects one, and ?path. selects a subtree. Tag filters match explicit tags.

std::vector<std::string> select_paths(const std::string &query = "?", const TagFilter &tags = {}) const: Select matching path names without cloning values or arrays.

inline Cursor cursor(std::string_view path) const: Traverse a known path without cloning the underlying value.

ValueInspection value(std::string_view path) const: Owned value and its type, shape, units, metadata, provenance, and applied changes.

std::vector<ValueInspection> values() const: All evaluated values, each with its full path.

ValueSummary value_summary(std::string_view path) const: Type, shape, element count, units, and metadata without copying value data.

val::BaseValue::PointerType value_slice(std::string_view path, const val::Array::RangeType &ranges) const: Inclusive zero-based ranges from an evaluated in-memory value; no lazy DIPH5 I/O.

TableInspection table(std::string_view path) const: Row count and ordered column metadata without copying table cells.

std::vector<TableInspection> tables() const: All evaluated tables in environment order.

inline std::vector<SourceInfo> sources() const: Source manifest entries, including source-level metadata.

inline std::optional<SourceInfo> source(std::string_view name) const: Find one source by its DIPL source name.

InspectionCapabilities capabilities(std::string_view path) const: Available facts and operations for a value, group, collection, table, or named-source path.

OverrideContract override_contract(std::string_view path) const: Static override target and known constraints; preview decides candidate validity.

SchemaHierarchyInspection schema_hierarchy() const: Reusable schema definitions and evaluated application sites.

std::vector<InspectedSourceLocation> source_locations(const SourceEntity &entity) const: Semantic source locations in precedence order; retained source text may be unavailable.

const std::map<std::string, BlockInput> &block_inputs() const: Original array/table string blocks retained by an opt-in live parse; empty for snapshots.

const BlockInput *block_input(std::string_view path) const: A retained block by evaluated path, or nullptr when unavailable.

SemanticDescription describe(std::string_view path, std::size_t max_value_elements = 16) const: Bounded semantic description of one value, group, collection, or table.

SemanticList list_descriptions(const std::string &query = "?", const TagFilter &tags = {}, std::size_t limit = 100, std::size_t max_value_elements = 0) const: Bounded descriptions selected by a ? query and tags; includes the total match count.

inline const DependencyGraph &graph() const: Recorded evaluation events and effective dependency queries. Empty when capture was disabled.

DependencyNeighborhood dependency_neighborhood(std::string_view path) const: One-hop inputs and readers of a path, with latest value and condition events.

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)

struct OverrideContract

#include <inspection.h>

Public Members

std::string path

OverrideTargetKind kind

std::string reason: Stable reason when unavailable.

std::string resolved_path: New list items receive the next index at this moment.

core::DataType declared_type

std::optional<val::Array::ShapeType> current_shape: Evaluated shape, not declared bounds.

std::optional<std::string> units

std::vector<std::string> enforced_options

std::vector<std::string> option_labels

std::string enforced_condition

std::vector<std::string> item_schemas

bool snapshot_input: A snapshot has no parser input to preview directly.

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

Parser exceptions occurs when internal DIP parsers fails

struct PreviewOverride

#include <preview.h>

Public Types

enum class Kind

Values:

enumerator Text

enumerator File

Public Members

Kind kind

std::string input

struct PreviewResult

#include <preview.h>

Public Members

bool baseline_valid

bool candidate_valid

std::vector<core::Diagnostic> baseline_diagnostics

std::vector<core::Diagnostic> candidate_diagnostics

std::vector<std::string> accepted_override_targets

ComparisonResult comparison

struct ProjectEntry

#include <environment.h>

One DIPfile registration, retained in manifest order for live inspection.

Public Types

enum class Kind

Values:

enumerator Unit

enumerator Source

enumerator Schema

enumerator Code

enumerator Override

Public Members

Kind kind

std::string name: Public name, when the entry has one.

std::string value: Declared unit, path, or inline text.

std::string resolved_path: Absolute file path for file entries; empty for inline entries.

std::string source_name: DIPfile source identity.

size_t line: One-based DIPfile assignment line.

struct ProjectInput

#include <dip.h>

Text-backed project registrations, processed in DIPfile phase order.

Public Members

std::vector<ProjectText> units

std::vector<ProjectText> schemas

std::vector<ProjectText> code

std::vector<ProjectText> overrides

struct ProjectText

#include <dip.h>

Public Members

std::string name

std::string text

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 SchemaApplicationEvent

#include <environment.h>

One schema relationship observed while evaluating a live input.

Public Members

std::string path

std::string schema_name

bool inherited_from_collection

core::SourceLocation origin

struct SchemaApplicationInspection

#include <inspection.h>

Public Members

std::string path

std::string kind

std::vector<std::string> schema_ids

std::optional<bool> inherited_from_collection: Unknown for legacy snapshots.

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

struct SchemaDefinitionInspection

#include <inspection.h>

Public Members

std::string id: Registered, project-scoped schema name.

std::string name

ValueMetadata metadata

core::SourceLocation origin

std::vector<SchemaMemberInspection> members

struct SchemaHierarchyInspection

#include <inspection.h>

Definitions and evaluated application sites. Snapshot applications are reconstructed from retained associations and are explicitly incomplete.

Public Members

bool definitions_available

bool applications_complete

std::vector<SchemaDefinitionInspection> definitions

std::vector<SchemaApplicationInspection> applications

std::vector<SchemaValueAssociation> values

std::map<std::string, SourceInfo> sources: Resolve origin source IDs to physical source identities.

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.

struct SchemaMemberInspection

#include <inspection.h>

A declared schema member. Children preserve source declaration order.

Public Members

std::string name

std::string relative_path

std::string kind

std::string type

std::string units

val::Array::RangeType dimensions

std::vector<std::string> schema_refs

std::vector<std::string> options

std::vector<std::string> option_labels

std::string condition

ValueMetadata metadata

core::SourceLocation origin

std::vector<SchemaMemberInspection> members

struct SchemaValueAssociation

#include <inspection.h>

Public Members

std::string path

std::vector<std::string> applied_schema_ids

std::optional<std::string> contributing_schema_id

struct SemanticDescription

#include <semantic.h>

Bounded, owned description of one evaluated path. Values use DIPL text.

Public Members

std::string path

std::string kind

std::string declared_type

std::string stored_type

val::Array::ShapeType shape

std::size_t elements

std::optional<std::string> value_text

std::string value_unavailable_reason

std::optional<std::string> units

ValueMetadata metadata

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

bool overridden

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

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

bool source_text_available

std::vector<std::string> enforced_options

std::vector<std::string> option_labels: Parallel to enforced_options when labels are declared.

std::string enforced_condition

bool dependencies_recorded

std::vector<DependencyEdge> dependencies

struct SemanticList

#include <semantic.h>

Public Members

std::vector<SemanticDescription> items

std::size_t total

struct SnapshotSaveOptions

#include <environment.h>

Public Members

SourcePathPolicy source_paths

const OutputPlan *output_plan: Optional resolved adapter mappings.

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 SourceEntity

#include <inspection.h>

Public Members

SourceEntityKind kind

std::string name

std::string source_name

std::size_t index

struct SourceInfo

#include <environment.h>

Durable identity and source-level metadata 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

ValueMetadata metadata

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

ValueMetadata metadata

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.

struct ValueSummary

#include <inspection.h>

Value facts without copying its potentially large array. Accepts an evaluated path or a source-qualified source?path ID.

Public Members

std::string path

core::DataType type

val::Array::ShapeType shape

std::size_t elements

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

ValueMetadata metadata

std::string table_path