errors.hpp File Reference

Helpful error message formatting for JSON configuration validation. More...

#include <nlohmann/json.hpp>
#include <sstream>
#include <string>
#include <vector>

Include dependency graph for errors.hpp:

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

Go to the source code of this file.

Functions
std::string	pfc::ui::format_config_error (const std::string &field_name, const std::string &description, const std::string &expected_type, const std::string &actual_value, const std::vector< std::string > &valid_options={}, const std::string &example="")
	Format a helpful configuration error message.
std::string	pfc::ui::get_json_value_string (const nlohmann::json &j, const std::string &field_name)
	Get JSON value as string for error messages.
std::vector< std::string >	pfc::ui::list_valid_field_modifiers ()
	List all registered field modifiers.
std::string	pfc::ui::format_unknown_modifier_error (const std::string &invalid_type, const std::string &context="field modifier")
	Format error for unknown field modifier type.

Detailed Description

Helpful error message formatting for JSON configuration validation.

This module provides utility functions for generating user-friendly error messages when JSON configuration validation fails. The functions format error messages with:

• Field name and human-readable description
• Expected type and constraints
• Actual value provided by user (with type information)
• Valid options (when applicable)
• Working example syntax

These helpers improve the user experience by making configuration errors immediately actionable, reducing debugging time and support burden.

Function Documentation

format_config_error()

std::string pfc::ui::format_config_error ( const std::string &  field_name, const std::string &  description, const std::string &  expected_type, const std::string &  actual_value, const std::vector< std::string > &  valid_options = {}, const std::string &  example = ""  )

inline

Format a helpful configuration error message.

Creates a multi-line error message with complete context about a configuration validation failure. The message includes:

• Field name and what it represents
• Expected type/format with constraints
• Actual value provided (or "missing")
• List of valid options (if applicable)
• Working example syntax (if provided)

Error messages are designed to be:

• Specific: Explain exactly what's wrong
• Contextual: Show what user provided vs. what's expected
• Actionable: List valid options and provide examples
• Concise: Typically < 10 lines

Parameters

field_name	Name of problematic field (e.g., "Lx", "origo")
description	Human-readable description of field purpose
expected_type	Expected type with constraints (e.g., "positive integer")
actual_value	What user provided (use get_json_value_string())
valid_options	List of valid values (empty if not applicable)
example	Working example syntax (empty if not needed)

Returns

Formatted multi-line error message ready for exception

Note

This is a pure function with no side effects

Thread-safe

Time complexity: O(n) where n = number of valid_options

// Example: Missing field
auto msg = format_config_error(
    "Lx", "grid points in X", "positive integer",
    "missing", {}, "\"Lx\": 256"
);
// Output:
// Invalid configuration: Field 'Lx' is missing.
//   Description: grid points in X
//   Expected: positive integer
//   Got: missing
//   Example: "Lx": 256
 
// Example: Invalid enum value
auto msg = format_config_error(
    "origin", "coordinate system origin", "string",
    "\"centre\"", {"center", "corner"}, "\"origin\": \"center\""
);
// Output:
// Invalid configuration: Field 'origin' has invalid value.
//   Description: coordinate system origin
//   Expected: string
//   Got: "centre"
//   Valid options: 'center', 'corner'
//   Example: "origo": "center"

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/ui/errors.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

format_unknown_modifier_error()

std::string pfc::ui::format_unknown_modifier_error ( const std::string &  invalid_type, const std::string &  context = "field modifier"  )

inline

Format error for unknown field modifier type.

Creates a helpful error message when user specifies an unknown field modifier type in JSON configuration. Lists all valid types to help user correct the spelling or choose the right modifier.

Parameters

invalid_type	The type user tried to use
context	Context string (e.g., "field modifier", "initial condition")

Returns

Formatted error message with valid types listed

Note

Calls list_valid_field_modifiers() to get current list

Thread-safe

Time complexity: O(n) where n = number of registered field modifiers

// Example: Unknown modifier type
auto msg = format_unknown_modifier_error("random_seed");
// Output:
// Unknown field modifier type: 'random_seed'
//   Valid types:
//     - constant
//     - single_seed
//     - random_seeds
//     - seed_grid
//     - from_file
//     - fixed
//     - moving
//   Check spelling and see documentation for details.
 
// Example: With custom context
auto msg = format_unknown_modifier_error("foo", "initial condition");
// Output:
// Unknown initial condition type: 'foo'
//   Valid types: ...

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/ui/errors.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_json_value_string()

std::string pfc::ui::get_json_value_string ( const nlohmann::json &  j, const std::string &  field_name  )

inline

Get JSON value as string for error messages.

Extracts the actual value from a JSON object and formats it for display in error messages. Returns "missing" if field doesn't exist, otherwise returns the JSON representation with type information.

Type information helps users understand type mismatches:

• integer: 42 (type: integer)
• float: 256.5 (type: float)
• string: "hello" (type: string)
• boolean: true (type: boolean)
• null: null (type: null)
• array: [1,2,3] (type: array)
• object: {"key":"value"} (type: object)

Parameters

j	JSON object to extract value from
field_name	Field name to look up

Returns

Formatted string describing the value with type

Note

This is a pure function with no side effects

Thread-safe

Time complexity: O(n) where n = size of JSON value when dumping

json j = {{"Lx", 256.5}, {"origin", "center"}};
 
auto lx = get_json_value_string(j, "Lx");
// Returns: "256.5 (type: float)"
 
auto origin = get_json_value_string(j, "origin");
// Returns: "\"center\" (type: string)"
 
auto missing = get_json_value_string(j, "nonexistent");
// Returns: "missing"

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/ui/errors.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

list_valid_field_modifiers()

std::vector< std::string > pfc::ui::list_valid_field_modifiers

(

)

List all registered field modifiers.

Returns a vector of all field modifier type names that can be used in JSON configuration. Includes both initial conditions and boundary conditions.

Initial conditions:

• "constant": Uniform field value
• "single_seed": Single crystalline seed
• "random_seeds": Random seed pattern
• "seed_grid": Regular grid of seeds
• "from_file": Load from binary file

Boundary conditions:

• "fixed": Fixed boundary values
• "moving": Moving boundary

Returns

Vector of registered type names

Note

This function is defined in ui_errors.cpp

Must be kept in sync with FieldModifierInitializer in ui.hpp

Warning

This function is not yet extensible. Custom field modifiers registered by users are not automatically included in this list. Future enhancement: FieldModifierRegistry::get_registered_types()

Time complexity: O(1) - returns fixed list

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/ui/errors.hpp.

Here is the call graph for this function:

Here is the caller graph for this function: