openswmm::components Namespace Reference

Classes
struct	ComponentConfigSections
struct	ProcessComponentEntry
class	ProcessComponentRegistry
	Process-global id → entry table. More...

Typedefs
using	ComponentConfigApply
using	ComponentConfigSave
	Save hook (IO3a): render this component's CURRENT engine state back to config-file text — the inverse of ComponentConfigApply.

Functions
std::string	parse_component_config_stream (std::istream &in, const std::string &label, ComponentConfigSections &out)
	Append parsed bracketed sections from the current stream position.
std::string	parse_component_config_text (const std::string &text, const std::string &label, ComponentConfigSections &out)
	Parse component configuration text using the same section/comment rules as files.
std::string	read_component_config (const std::string &path, const std::string &base_dir, ComponentConfigSections &out)
	Clear sections, resolve a UTF-8 config path and parse the component dialect.
std::vector< std::string >	resolve_process_components (SimulationContext &ctx, const std::string &base_dir)
	Validate specs, parse each config and apply implemented builtin hooks in order.

Typedef Documentation

ComponentConfigApply

using openswmm::components::ComponentConfigApply

Initial value:

 
    std::function<void(SimulationContext& ctx, const ProcessComponentSpec& spec,
                       const ComponentConfigSections& config, std::vector<std::string>& errors)>

Apply hook: consume the parsed config into engine state. Push diagnostics into errors (fatal) — never throw.

ComponentConfigSave

using openswmm::components::ComponentConfigSave

Initial value:

 
    std::function<std::string(const SimulationContext& ctx, const ProcessComponentSpec& spec)>

Save hook (IO3a): render this component's CURRENT engine state back to config-file text — the inverse of ComponentConfigApply.

Until this existed, swmm_model_write emitted the [PROCESS_COMPONENTS] config= PATH and copied the file the model was read from, but nothing rewrote its CONTENT. So every edit made through a C API or the GUI — a [HEAT_SOURCES] temperature, a reaction expression — was silently lost on save, while a hand-edit of the same file persisted. InpWriter's own comment states the intended division ("the component config FILES are each component's own to write, never ours"); this is the hook that lets a component honour it.

Returns

the complete config-file text, or empty to decline — an empty return means "I have nothing to serialize", and the writer falls back to the IO3 carry-alongside copy. Declining is how a component that has not implemented saving yet stays correct rather than truncating its own file to nothing.

Note

ctx is CONST. A save must not mutate the model it is describing; that is the property that makes writing twice give the same file.

Function Documentation

parse_component_config_stream()

std::string openswmm::components::parse_component_config_stream	(	std::istream &	in,
		const std::string &	label,
		ComponentConfigSections &	out )

Append parsed bracketed sections from the current stream position.

Parameters

[in,out]	in	Borrowed stream consumed until getline ends or a syntax error.
	label	Source text used only in diagnostics.
[in,out]	out	Existing sections are not cleared here; accepted sections append. A nested PROCESS_COMPONENTS section or content before the first recognized header returns an error with earlier appended data retained.

Returns

Empty on accepted input, including an empty file. Header tags are uppercase but not internally trimmed; unknown/repeated tags are retained, trailing text after a closing bracket is ignored, and stream badbit is not separately diagnosed.

Here is the caller graph for this function:

parse_component_config_text()

std::string openswmm::components::parse_component_config_text	(	const std::string &	text,
		const std::string &	label,
		ComponentConfigSections &	out )

Parse component configuration text using the same section/comment rules as files.

Parameters

	text	Borrowed complete text copied into an input stream.
	label	Diagnostic source label also stored as out.source_path.
[out]	out	Sections cleared before parsing; a rejected document can retain its successfully parsed prefix.

Returns

Empty on accepted syntax, otherwise a fatal section/nesting diagnostic. Semicolon comments are stripped without quote awareness; blank/comment-only lines are skipped, tags uppercased, repeated sections retained and pre-section content rejected. General unknown tags are accepted for component-specific validation.

Here is the call graph for this function:

read_component_config()

std::string openswmm::components::read_component_config	(	const std::string &	path,
		const std::string &	base_dir,
		ComponentConfigSections &	out )

Clear sections, resolve a UTF-8 config path and parse the component dialect.

Parameters

	path	Config filename; relative paths join base_dir when nonempty.
	base_dir	Parent-input directory, or empty to use process working directory. Resolution does not force absolute/canonical form.
[out]	out	Sections cleared immediately and source_path set to effective UTF-8 spelling, even on failure. Parsing errors can leave a retained prefix.

Returns

Empty on success, otherwise missing/unreadable/section/nesting diagnostic. No recursive component registration is permitted. Stream read failure after opening is not separately checked; filesystem/allocation exceptions propagate.

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_process_components()

std::vector< std::string > openswmm::components::resolve_process_components	(	SimulationContext &	ctx,
		const std::string &	base_dir )

Validate specs, parse each config and apply implemented builtin hooks in order.

Parameters

[in,out]	ctx	Engine state holding process_component_specs and hook targets. Duplicate exact IDs are detected before any hook; then specs are handled in order. Unknown/planned/path-like IDs, absent config and parser errors append diagnostics and continue. Successfully parsed specs retain resolved_config_path before apply.
	base_dir	Parent input directory for relative config paths; empty uses cwd.

Returns

Collected errors, empty when no errors were appended. Earlier successful hook mutations are retained after later errors; no rollback or exception catch is provided. A registered implemented entry must have a nonnull apply callable. This resolver still refuses library-path specs independently of the discovery catalogue.

Here is the call graph for this function: