Application adapters

enum class snt::dip::ExistingOutputPolicy

How a runner handles files already present at registered output paths.

Values:

enumerator Reject

Reject every existing destination (default).

enumerator ReplaceRegistered

Replace regular files registered for this run only.

enumerator SyncRegistered

Also remove files recorded by the previous sync run but not planned now.

OutputPlan snt::dip::resolve_output_plan(const Environment &env, const Adapter &adapter)

Resolve and validate an adapter’s output plan without writing files.

std::vector<std::filesystem::path> snt::dip::run_adapter(const Environment &env, const Adapter &adapter, const std::filesystem::path &output_dir, const std::filesystem::path &snapshot = {}, ExistingOutputPolicy policy = ExistingOutputPolicy::Reject)

Plan, validate, and write adapter outputs below output_dir. Existing destinations are rejected by default. ReplaceRegistered replaces only registered regular files after all outputs are staged, and restores them if publication fails. SyncRegistered records the current paths and removes previously recorded files that are no longer planned. snapshot is an optional relative DIPH5 path below the same directory. Returns written paths in registration order.

inline std::vector<std::filesystem::path> snt::dip::run_adapter(const Environment &env, const Adapter &adapter, const std::filesystem::path &output_dir, ExistingOutputPolicy policy)

Run without a snapshot while specifying an existing-output policy.

std::vector<std::filesystem::path> snt::dip::run_adapter_project(const std::filesystem::path &project, const Adapter &adapter, const std::filesystem::path &output_dir, const std::filesystem::path &snapshot = {}, ExistingOutputPolicy policy = ExistingOutputPolicy::Reject)

Parse a DIPfile and run the adapter on its evaluated environment.

inline std::vector<std::filesystem::path> snt::dip::run_adapter_project(const std::filesystem::path &project, const Adapter &adapter, const std::filesystem::path &output_dir, ExistingOutputPolicy policy)

Run a project without saving a snapshot while specifying an existing-output policy.

std::vector<std::filesystem::path> snt::dip::run_adapter_snapshot(const std::filesystem::path &input, const Adapter &adapter, const std::filesystem::path &output_dir, const std::filesystem::path &snapshot = {}, ExistingOutputPolicy policy = ExistingOutputPolicy::Reject)

Load a DIPH5 environment and run the adapter on its retained values and metadata.

inline std::vector<std::filesystem::path> snt::dip::run_adapter_snapshot(const std::filesystem::path &input, const Adapter &adapter, const std::filesystem::path &output_dir, ExistingOutputPolicy policy)

Run from a DIPH5 input without saving another snapshot while specifying a policy.

class Adapter

#include <adapter.h>

Application-specific conversion of evaluated DIPL values to output files.

Public Functions

virtual ~Adapter() = default

inline virtual void describe_outputs(const Environment&, OutputPlan&) const

Declare typed native mappings after DIPL evaluation and value overrides.

inline virtual void plan(const Environment&, AdapterContext&) const

Select values, validate them for the target application, and register its files.

inline virtual void plan_resolved(const Environment &env, const OutputPlan&, AdapterContext &context) const

Consume the resolved plan; the default preserves existing adapters.

class AdapterContext

#include <adapter.h>

Collects files requested by one adapter run. Paths are relative to the output directory.

Public Types

using StreamWriter = std::function<void(std::ostream&)>

Public Functions

void add_text(std::filesystem::path path, std::string content)

Register UTF-8 or other application-defined text without changing its contents.

void add_binary(std::filesystem::path path, std::vector<std::uint8_t> content)

Register raw bytes without encoding or newline conversion.

void add_stream(std::filesystem::path path, StreamWriter writer)

The writer is called once, after all output paths have been validated.

struct OutputMapping

#include <output_plan.h>

One adapter-owned mapping resolved against an evaluated environment.

Public Members

std::string id

std::string target

std::string key

std::string source_path

Empty for a value calculated by the adapter.

std::string rule

Stable, human-readable rule or callback name.

std::string origin

Adapter/profile declaration identity.

std::vector<std::string> replacements

Previous declaration origins.

std::vector<std::string> dependencies

bool active

ValueNode::PointerType value

Typed copy, outside Environment::nodes.

class OutputPlan

#include <output_plan.h>

Validated, ordered output mappings. Tags are only used by adapters to discover nodes.

Public Functions

void add_node(const Environment &env, std::string id, std::string target, std::string key, std::string source_path, bool active = true, std::string rule = {}, std::string origin = {}, std::vector<std::string> dependencies = {})

void replace_node(const Environment &env, std::string id, std::string target, std::string key, std::string source_path, bool active = true, std::string rule = {}, std::string origin = {}, std::vector<std::string> dependencies = {})

void add_value(std::string id, std::string target, std::string key, ValueNode::PointerType value, bool active = true, std::string rule = {}, std::string origin = {}, std::vector<std::string> dependencies = {})

void replace_value(std::string id, std::string target, std::string key, ValueNode::PointerType value, bool active = true, std::string rule = {}, std::string origin = {}, std::vector<std::string> dependencies = {})

void validate() const

Check active native-key collisions after all deliberate replacements.

inline const std::vector<OutputMapping> &mappings() const

std::vector<OutputMapping> select(const std::string &target, bool active_only = false) const

void restore(OutputMapping mapping)

Restore a validated mapping from a versioned DIPH5 snapshot.