cli.h File Reference

Command-line interface for the unified Harmony executable. More...

#include <filesystem>
#include <functional>
#include <optional>
#include <string>
#include <vector>

Include dependency graph for cli.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	CliOptions

Typedefs
using	ExampleFn = std::function< void(bool plotting_enabled)>

Functions
void	initCliPaths (const char *argv0)
	Resolve executable location for repo-root detection (call once from main).
std::optional< std::filesystem::path >	harmonyRepoRoot ()
	Detected Harmony repository root, if any.
CliOptions	parseCli (int argc, char *argv[])
	Parse argc/argv into CliOptions.
void	printCliHelp ()
	Print usage text to stdout.
void	listCppExamples ()
	List registered C++ examples.
std::vector< std::string >	cppExampleNames ()
	Registered C++ example names (sorted).
void	listJsonFiles (const std::vector< std::filesystem::path > &searchPaths)
	List JSON files found under configured search paths.
std::vector< std::filesystem::path >	discoverJsonFiles (const std::vector< std::filesystem::path > &searchPaths)
	Discover .json files under searchPaths (sorted, unique).
bool	validateJsonFile (const std::filesystem::path &jsonPath, std::string &errorOut)
	Parse and schema-validate a JSON simulation file.
int	runCppExample (const std::string &name, bool plot, bool verbose)
	Run a named C++ example.
int	runJsonSimulation (const std::filesystem::path &jsonPath, bool verbose, bool plot=true, bool waitForPlotClose=true)
	Run a JSON simulation file.
std::vector< std::filesystem::path >	builtinJsonSearchPaths ()
	Built-in JSON search directories (used when env/CLI overrides are unset).
std::vector< std::filesystem::path >	jsonSearchPathsFromEnvironment ()
	Paths from HARMONY_JSON_PATH, or empty if the variable is unset.
std::vector< std::filesystem::path >	defaultJsonSearchPaths ()
	Default paths: HARMONY_JSON_PATH if set, otherwise builtinJsonSearchPaths.
std::vector< std::filesystem::path >	buildJsonSearchPaths (const std::vector< std::filesystem::path > &jsonPathOverrides, const std::vector< std::filesystem::path > &extraSearchPaths)
	Build the effective JSON search path list for one invocation.
std::filesystem::path	resolveJsonPath (const std::string &input, const std::vector< std::filesystem::path > &searchPaths)
	Resolve a JSON path (absolute, relative, or filename in search paths).
void	printJsonNotFoundHelp (const std::string &input, const std::vector< std::filesystem::path > &searchPaths)
	Print why a JSON file was not found (search paths, repo root, env).

Detailed Description

Command-line interface for the unified Harmony executable.

Typedef Documentation

ExampleFn

using ExampleFn = std::function<void(bool plotting_enabled)>

Function Documentation

buildJsonSearchPaths()

std::vector< std::filesystem::path > buildJsonSearchPaths	(	const std::vector< std::filesystem::path > &	jsonPathOverrides,
		const std::vector< std::filesystem::path > &	extraSearchPaths
	)

Build the effective JSON search path list for one invocation.

Parameters

jsonPathOverrides	If non-empty, replaces defaults (--json-path).
extraSearchPaths	Appended after defaults (--search-path).

References builtinJsonSearchPaths(), and jsonSearchPathsFromEnvironment().

Referenced by parseCli().

builtinJsonSearchPaths()

std::vector< std::filesystem::path > builtinJsonSearchPaths

(

)

Built-in JSON search directories (used when env/CLI overrides are unset).

Referenced by buildJsonSearchPaths(), and defaultJsonSearchPaths().

cppExampleNames()

std::vector< std::string > cppExampleNames

(

)

Registered C++ example names (sorted).

Referenced by listCppExamples().

defaultJsonSearchPaths()

std::vector< std::filesystem::path > defaultJsonSearchPaths

(

)

Default paths: HARMONY_JSON_PATH if set, otherwise builtinJsonSearchPaths.

References builtinJsonSearchPaths(), and jsonSearchPathsFromEnvironment().

discoverJsonFiles()

std::vector< std::filesystem::path > discoverJsonFiles

(

const std::vector< std::filesystem::path > &

searchPaths

)

Discover .json files under searchPaths (sorted, unique).

harmonyRepoRoot()

std::optional< std::filesystem::path > harmonyRepoRoot

(

)

Detected Harmony repository root, if any.

Referenced by listJsonFiles(), printJsonNotFoundHelp(), and resolveJsonPath().

initCliPaths()

void initCliPaths

(

const char *

argv0

)

Resolve executable location for repo-root detection (call once from main).

Referenced by main(), and runHarmonyLauncher().

jsonSearchPathsFromEnvironment()

std::vector< std::filesystem::path > jsonSearchPathsFromEnvironment

(

)

Paths from HARMONY_JSON_PATH, or empty if the variable is unset.

Referenced by buildJsonSearchPaths(), and defaultJsonSearchPaths().

listCppExamples()

void listCppExamples

(

)

List registered C++ examples.

References cppExampleNames().

Referenced by main().

listJsonFiles()

void listJsonFiles

(

const std::vector< std::filesystem::path > &

searchPaths

)

List JSON files found under configured search paths.

References harmonyRepoRoot().

Referenced by main().

parseCli()

CliOptions parseCli	(	int	argc,
		char *	argv[]
	)

Parse argc/argv into CliOptions.

References buildJsonSearchPaths(), CliOptions::Cpp, CliOptions::extraSearchPaths, CliOptions::Help, CliOptions::Json, CliOptions::jsonPathOverrides, CliOptions::ListCpp, CliOptions::ListJson, CliOptions::mode, CliOptions::plot, CliOptions::searchPaths, CliOptions::target, and CliOptions::verbose.

Referenced by main().

printCliHelp()

void printCliHelp

(

)

Print usage text to stdout.

References printHarmonyBanner().

Referenced by main().

printJsonNotFoundHelp()

void printJsonNotFoundHelp	(	const std::string &	input,
		const std::vector< std::filesystem::path > &	searchPaths
	)

Print why a JSON file was not found (search paths, repo root, env).

References harmonyRepoRoot().

Referenced by main().

resolveJsonPath()

std::filesystem::path resolveJsonPath	(	const std::string &	input,
		const std::vector< std::filesystem::path > &	searchPaths
	)

Resolve a JSON path (absolute, relative, or filename in search paths).

References harmonyRepoRoot().

Referenced by main().

runCppExample()

int runCppExample	(	const std::string &	name,
		bool	plot,
		bool	verbose
	)

Run a named C++ example.

Returns

0 on success, non-zero on failure.

Referenced by main().

runJsonSimulation()

int runJsonSimulation	(	const std::filesystem::path &	jsonPath,
		bool	verbose,
		bool	plot = true,
		bool	waitForPlotClose = true
	)

Run a JSON simulation file.

Returns

0 on success, non-zero on failure.

Parameters

waitForPlotClose

When true (CLI default), block until the plot window closes.

References SimulationBuilder::buildFromJSON(), Network::printConnections(), Network::printElements(), SimulationBuilder::runComputationsWithStatus(), visualization_is_running(), and visualization_wait().

Referenced by main().

validateJsonFile()

bool validateJsonFile	(	const std::filesystem::path &	jsonPath,
		std::string &	errorOut
	)

Parse and schema-validate a JSON simulation file.

References JsonValidator::validateRoot().