diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a94fed3..4398eb5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -36,3 +36,9 @@ jobs:
run: ./build.sh
- name: Test
run: ctest --test-dir build --output-on-failure --no-tests=error
+ - name: Build and test without yaml-cpp
+ if: matrix.ubuntu == '24.04' && matrix.arch == 'amd64'
+ run: |
+ BUILD_DIR=build-noyaml ./build.sh -Denable_yaml=OFF
+ ctest --test-dir build-noyaml --output-on-failure --no-tests=error \
+ -R '^(helm|behavior_file|bhv_schema|closed_loop_s1_alpha_inline)$'
diff --git a/CMakeLists.txt b/CMakeLists.txt
index ca7663b..75767ec 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -30,6 +30,14 @@ elseif(GOBY_moos_FOUND)
find_package(MOOS 10 QUIET)
endif()
+# YAML behavior files (.bhv.yml); without it, behaviors come from .bhv files or the helm config
+find_package(yaml-cpp QUIET)
+option(enable_yaml "Read YAML behavior files (.bhv.yml)" ${yaml-cpp_FOUND})
+if(enable_yaml AND NOT yaml-cpp_FOUND)
+ message(FATAL_ERROR "enable_yaml is ON but yaml-cpp wasn't found (apt install libyaml-cpp-dev)")
+endif()
+message(STATUS "YAML behavior files (enable_yaml): ${enable_yaml}")
+
include(CTest)
add_subdirectory(src)
diff --git a/README.md b/README.md
index 4a9b6ae..329e925 100644
--- a/README.md
+++ b/README.md
@@ -12,12 +12,14 @@ One way to think of this project is as a generator for the equivalent of the MOO
- src: Source code
- lib: Library source
- interface: Interface messages (Protobuf)
- - helm: The helm, pHelmIvP without MOOS (`ivpico::helm::Helm`)
+ - helm: The helm, pHelmIvP without MOOS (`ivpico::helm::Helm`), and behavior files
- bin: Binary source
+ - bhv: `ivpico_bhv`, for behavior files (`.bhv`, `.bhv.yml`)
- goby: Goby middleware app (`goby_helm_ivp`)
- ros: ROS middleware node
- test: Tests, including replays of MOOS-IvP missions (`test/missions`)
- launch: Example missions
+- share/ivpico: The JSON Schema of `.bhv.yml` files (`bhv.schema.json`)
## Building
@@ -30,6 +32,8 @@ One way to think of this project is as a generator for the equivalent of the MOO
All of these come from [Open Ocean Software](https://github.com/openocean-software/openocean-build)'s continuous builds, with its releases for what they depend on (DCCL, MOOS, ...), at apt.oceansoft.org. `init.sh` adds both if apt can't install the packages already.
+yaml-cpp (`libyaml-cpp-dev`) is optional: without it, behaviors come only from `.bhv` files or the helm configuration (`-Denable_yaml=OFF` leaves it out).
+
`build.sh` then builds IvPico in `build/` and installs it into `build/usr`.
```
@@ -49,6 +53,19 @@ ctest --test-dir build
- Field levels (CORE, ADVANCED, DEVELOPER) and what each adds to `Status` and `HelmConfig`.
- Differences from pHelmIvP: the MOOSDB echo, rejournal, standby helm.
+## Behavior files
+
+*Outline, to be written:*
+
+- Three ways to give the helm its behaviors (`HelmConfig`):
+ - `.bhv` files, MOOS-IvP's own format and the reference;
+ - `.bhv.yml` files: the same content as YAML, checked against `share/ivpico/bhv.schema.json`;
+ - `behaviors`: the same structure inline in the helm configuration.
+- How each is read: everything is converted to `.bhv` text for MOOS-IvP's Populator; with any YAML or inline behaviors, files are read in the order given, not sorted.
+- The `.bhv.yml` format: `initialize`, `initialize_deferred`, `modes`, `behaviors`; common parameters as keys, the behavior's own under `params`; a list where a parameter repeats; `x-` keys and merges (`<<: *name`) for shared settings (merges are shallow, so a behavior's `params` replaces a merged `params`). Example: `launch/goby/alpha/config/alpha.bhv.yml`.
+- `ivpico_bhv`: `convert` (YAML to `.bhv`), `import` (`.bhv` to YAML), `check` (builds the behaviors and reports problems at their YAML line), `schema`.
+- Editor setup: the `# yaml-language-server: $schema=...` line `import` writes.
+
## Goby app
*This section was written by Claude.*
diff --git a/init.sh b/init.sh
index 71575fb..3b403ad 100755
--- a/init.sh
+++ b/init.sh
@@ -35,6 +35,8 @@ apt_install() {
# xz-utils: the replay tests' recorded missions are compressed
packages=(cmake ninja-build g++ git ca-certificates protobuf-compiler libprotobuf-dev xz-utils)
+# optional: YAML behavior files (.bhv.yml), and the test that validates them against the schema
+packages+=(libyaml-cpp-dev python3-jsonschema python3-yaml)
$SUDO apt-get update
apt_install "${packages[@]}"
diff --git a/launch/goby/alpha/config/alpha.bhv b/launch/goby/alpha/config/alpha.bhv
deleted file mode 100644
index 7847455..0000000
--- a/launch/goby/alpha/config/alpha.bhv
+++ /dev/null
@@ -1,91 +0,0 @@
-//-------- FILE: alpha.bhv -------------
-
-initialize DEPLOY = false
-initialize RETURN = false
-
-//----------------------------------------------
-Behavior = BHV_Waypoint
-{
- name = waypt_survey
- pwt = 100
- condition = RETURN = false
- condition = DEPLOY = true
- endflag = RETURN = true
-
- endflag = SUMMARY=speed=$[SPEED],time=$[DUR_RUN_TIME]
-
- configflag = CRUISE_SPD = $[SPEED]
-
- activeflag = INFO=$[OWNSHIP]
- activeflag = INFO=$[BHVNAME]
- activeflag = INFO=$[BHVTYPE]
-
- cycleflag = CINFO=$[OSX],$[OSY]
-
- wptflag = PREV=$(PX),$(PY)
- wptflag = NEXT=$(NX),$(NY)
- wptflag = TEST=$(X),$(Y)
- wptflag = OSPOS=$(OSX),$(OSY)
- wptflag_on_start = true
-
- updates = WPT_UPDATE
- perpetual = true
-
- speed_alt = 1.2
- use_alt_speed = true
- lead = 8
- lead_damper = 1
- lead_to_start = true
- speed = 3 // meters per second
- capture_line = true
- capture_radius = 5.0
- slip_radius = 15.0
- efficiency_measure = all
- polygon = 60,-40:60,-160:150,-160:180,-100:150,-40
-
- order = normal
- repeat = 0
-
- visual_hints = nextpt_color=yellow
- visual_hints = nextpt_vertex_size=8
- visual_hints = nextpt_lcolor=gray70
- visual_hints = vertex_color=dodger_blue, edge_color=white
- visual_hints = vertex_size=5, edge_size=1
-}
-
-//----------------------------------------------
-Behavior=BHV_Waypoint
-{
- name = waypt_return
- pwt = 100
- condition = RETURN = true
- condition = DEPLOY = true
- perpetual = true
- updates = RETURN_UPDATE
- endflag = RETURN = false
- endflag = DEPLOY = false
- endflag = MISSION = complete
-
- speed = 2.0
- capture_radius = 2.0
- slip_radius = 8.0
- points = 0,-20
- }
-
-//----------------------------------------------
-Behavior=BHV_ConstantSpeed
-{
- name = const_speed
- pwt = 200
- condition = SPD=true
- condition = DEPLOY = true
- perpetual = true
- updates = SPEED_UPDATE
- endflag = SPD = false
-
- speed = 0.5
- duration = 10
- duration_reset = CONST_SPD_RESET=true
-
-}
-
diff --git a/launch/goby/alpha/config/alpha.bhv.yml b/launch/goby/alpha/config/alpha.bhv.yml
new file mode 100644
index 0000000..c6fc6c7
--- /dev/null
+++ b/launch/goby/alpha/config/alpha.bhv.yml
@@ -0,0 +1,84 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/GobySoft/IvPico/main/share/ivpico/bhv.schema.json
+# MOOS-IvP's alpha mission: a survey, then a return to 0,-20, as alpha.bhv in
+# ivp/missions/s1_alpha. ivpico_bhv convert writes it as a .bhv file.
+
+initialize:
+ DEPLOY: false
+ RETURN: false
+
+behaviors:
+ - type: BHV_Waypoint
+ name: waypt_survey
+ pwt: 100
+ condition:
+ - RETURN = false
+ - DEPLOY = true
+ updates: WPT_UPDATE
+ perpetual: true
+ endflag:
+ - RETURN = true
+ - SUMMARY=speed=$[SPEED],time=$[DUR_RUN_TIME]
+ activeflag:
+ - INFO=$[OWNSHIP]
+ - INFO=$[BHVNAME]
+ - INFO=$[BHVTYPE]
+ configflag: CRUISE_SPD = $[SPEED]
+ params:
+ cycleflag: CINFO=$[OSX],$[OSY]
+ wptflag:
+ - PREV=$(PX),$(PY)
+ - NEXT=$(NX),$(NY)
+ - TEST=$(X),$(Y)
+ - OSPOS=$(OSX),$(OSY)
+ wptflag_on_start: true
+ speed_alt: 1.2
+ use_alt_speed: true
+ lead: 8
+ lead_damper: 1
+ lead_to_start: true
+ speed: 3
+ capture_line: true
+ capture_radius: 5.0
+ slip_radius: 15.0
+ efficiency_measure: all
+ polygon: 60,-40:60,-160:150,-160:180,-100:150,-40
+ order: normal
+ repeat: 0
+ visual_hints:
+ - nextpt_color=yellow
+ - nextpt_vertex_size=8
+ - nextpt_lcolor=gray70
+ - vertex_color=dodger_blue, edge_color=white
+ - vertex_size=5, edge_size=1
+
+ - type: BHV_Waypoint
+ name: waypt_return
+ pwt: 100
+ condition:
+ - RETURN = true
+ - DEPLOY = true
+ updates: RETURN_UPDATE
+ perpetual: true
+ endflag:
+ - RETURN = false
+ - DEPLOY = false
+ - MISSION = complete
+ params:
+ speed: 2.0
+ capture_radius: 2.0
+ slip_radius: 8.0
+ points: 0,-20
+
+ - type: BHV_ConstantSpeed
+ name: const_speed
+ pwt: 200
+ condition:
+ - SPD=true
+ - DEPLOY = true
+ updates: SPEED_UPDATE
+ duration: 10
+ duration_reset: CONST_SPD_RESET=true
+ perpetual: true
+ endflag: SPD = false
+ params:
+ speed: 0.5
diff --git a/launch/goby/alpha/config/helm_ivp.pb.cfg b/launch/goby/alpha/config/helm_ivp.pb.cfg
index 8d890a1..aba85e4 100644
--- a/launch/goby/alpha/config/helm_ivp.pb.cfg
+++ b/launch/goby/alpha/config/helm_ivp.pb.cfg
@@ -16,7 +16,7 @@ interprocess {
}
helm {
- behavior_file: "config/alpha.bhv"
+ behavior_file: "config/alpha.bhv.yml"
domain { name: "course" low: 0 high: 359 points: 360 }
domain { name: "speed" low: 0 high: 4 points: 41 }
}
diff --git a/share/ivpico/bhv.schema.json b/share/ivpico/bhv.schema.json
new file mode 100644
index 0000000..9f5844b
--- /dev/null
+++ b/share/ivpico/bhv.schema.json
@@ -0,0 +1,89 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://github.com/GobySoft/IvPico/blob/main/share/ivpico/bhv.schema.json",
+ "title": "IvPico behavior file (.bhv.yml)",
+ "description": "MOOS-IvP behaviors, modes and initial variables, as a .bhv file holds them",
+ "type": "object",
+ "additionalProperties": false,
+ "patternProperties": {
+ "^x-": { "description": "Ignored: a place for anchors to merge elsewhere" }
+ },
+ "properties": {
+ "initialize": {
+ "description": "Variables posted when the helm starts (initialize)",
+ "$ref": "#/$defs/variables"
+ },
+ "initialize_deferred": {
+ "description": "Variables posted unless another app has set them (initialize_)",
+ "$ref": "#/$defs/variables"
+ },
+ "modes": {
+ "description": "Hierarchical modes (set), in order",
+ "type": "array",
+ "items": { "$ref": "#/$defs/mode" }
+ },
+ "behaviors": {
+ "type": "array",
+ "items": { "$ref": "#/$defs/behavior" }
+ }
+ },
+ "$defs": {
+ "value": { "type": ["string", "number", "boolean"] },
+ "values": {
+ "oneOf": [
+ { "$ref": "#/$defs/value" },
+ { "type": "array", "items": { "$ref": "#/$defs/value" } }
+ ]
+ },
+ "variables": {
+ "type": "object",
+ "propertyNames": { "pattern": "^[^\\s=,{}]+$" },
+ "additionalProperties": { "$ref": "#/$defs/value" }
+ },
+ "mode": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["set"],
+ "properties": {
+ "set": { "description": "MODE_VAR = value", "type": "string", "pattern": "\\S\\s*=\\s*\\S" },
+ "condition": { "$ref": "#/$defs/values" },
+ "else": { "$ref": "#/$defs/value" }
+ }
+ },
+ "behavior": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type"],
+ "properties": {
+ "type": { "type": "string", "pattern": "^\\S+$" },
+ "name": { "$ref": "#/$defs/value" },
+ "pwt": { "$ref": "#/$defs/value" },
+ "condition": { "$ref": "#/$defs/values" },
+ "updates": { "$ref": "#/$defs/value" },
+ "templating": { "$ref": "#/$defs/value" },
+ "duration": { "$ref": "#/$defs/value" },
+ "duration_status": { "$ref": "#/$defs/value" },
+ "duration_reset": { "$ref": "#/$defs/value" },
+ "duration_idle_decay": { "$ref": "#/$defs/value" },
+ "perpetual": { "$ref": "#/$defs/value" },
+ "nostarve": { "$ref": "#/$defs/values" },
+ "post_mapping": { "$ref": "#/$defs/values" },
+ "comms_policy": { "$ref": "#/$defs/value" },
+ "endflag": { "$ref": "#/$defs/values" },
+ "runflag": { "$ref": "#/$defs/values" },
+ "runxflag": { "$ref": "#/$defs/values" },
+ "activeflag": { "$ref": "#/$defs/values" },
+ "inactiveflag": { "$ref": "#/$defs/values" },
+ "idleflag": { "$ref": "#/$defs/values" },
+ "spawnflag": { "$ref": "#/$defs/values" },
+ "spawnxflag": { "$ref": "#/$defs/values" },
+ "configflag": { "$ref": "#/$defs/values" },
+ "params": {
+ "description": "The behavior's own parameters, in order; a list for a parameter given more than once",
+ "type": "object",
+ "additionalProperties": { "$ref": "#/$defs/values" }
+ }
+ }
+ }
+ }
+}
diff --git a/src/bin/CMakeLists.txt b/src/bin/CMakeLists.txt
index f162b61..85f9804 100644
--- a/src/bin/CMakeLists.txt
+++ b/src/bin/CMakeLists.txt
@@ -1,3 +1,5 @@
+add_subdirectory(bhv)
+
if(GOBY_FOUND)
add_subdirectory(goby)
endif()
diff --git a/src/bin/bhv/CMakeLists.txt b/src/bin/bhv/CMakeLists.txt
new file mode 100644
index 0000000..39231dc
--- /dev/null
+++ b/src/bin/bhv/CMakeLists.txt
@@ -0,0 +1,6 @@
+add_executable(ivpico_bhv ivpico_bhv.cpp)
+target_include_directories(ivpico_bhv PRIVATE ${PROJECT_SOURCE_DIR}/src/lib)
+target_link_libraries(ivpico_bhv PRIVATE ivpico_helm)
+install(TARGETS ivpico_bhv RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(FILES ${PROJECT_SOURCE_DIR}/share/ivpico/bhv.schema.json
+ DESTINATION ${CMAKE_INSTALL_DATADIR}/ivpico)
diff --git a/src/bin/bhv/ivpico_bhv.cpp b/src/bin/bhv/ivpico_bhv.cpp
new file mode 100644
index 0000000..d2aa459
--- /dev/null
+++ b/src/bin/bhv/ivpico_bhv.cpp
@@ -0,0 +1,201 @@
+// Copyright 2026:
+// GobySoft, LLC
+//
+// This file is part of IvPico.
+//
+// IvPico is free software: you can redistribute it and/or modify it under the
+// terms of the GNU General Public License as published by the Free Software
+// Foundation, either version 2 of the License, or (at your option) any later
+// version.
+//
+// IvPico is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with IvPico. If not, see .
+
+#include
+#include
+#include
+#include
+#include
+
+#include "helm/behavior_file.h"
+#include "helm/helm.h"
+
+namespace
+{
+const char* usage = R"(Usage:
+ ivpico_bhv convert [-o ] YAML to the official .bhv
+ ivpico_bhv import [-o ] .bhv to YAML (comments aren't kept)
+ ivpico_bhv check [--domain name:low:high:points]...
+ builds the behaviors and reports problems
+ ivpico_bhv schema the JSON Schema of .bhv.yml files
+)";
+
+const char* schema_url =
+ "https://raw.githubusercontent.com/GobySoft/IvPico/main/share/ivpico/bhv.schema.json";
+
+int fail(const std::string& msg)
+{
+ std::cerr << msg << "\n";
+ return 1;
+}
+
+bool read_file(const std::string& file, std::string& text)
+{
+ std::ifstream in(file);
+ if (!in)
+ return false;
+ std::stringstream s;
+ s << in.rdbuf();
+ text = s.str();
+ return true;
+}
+
+int write_output(const std::string& text, const std::string& output)
+{
+ if (output.empty())
+ {
+ std::cout << text;
+ return 0;
+ }
+ std::ofstream out(output);
+ out << text;
+ return out ? 0 : fail("Couldn't write " + output);
+}
+
+int report(const std::vector& errors)
+{
+ for (const auto& e : errors) std::cerr << e << "\n";
+ return errors.empty() ? 0 : 1;
+}
+
+int convert(const std::string& file, const std::string& output)
+{
+#ifdef HAS_YAML
+ ivp::interface::HelmConfig cfg;
+ cfg.add_behavior_file(file);
+ std::vector errors;
+ const auto combined = ivpico::helm::combine_behaviors(cfg, errors);
+ if (!errors.empty())
+ return report(errors);
+ return write_output(combined.text, output);
+#else
+ (void)file, (void)output;
+ return fail("ivpico_bhv was built without yaml-cpp (enable_yaml), so it can't read YAML");
+#endif
+}
+
+int import(const std::string& file, const std::string& output)
+{
+#ifdef HAS_YAML
+ std::string text;
+ if (!read_file(file, text))
+ return fail("Couldn't read " + file);
+ std::vector errors;
+ const auto set = ivpico::helm::read_bhv(text, file, errors);
+ if (!errors.empty())
+ return report(errors);
+ return write_output(std::string("# yaml-language-server: $schema=") + schema_url + "\n" +
+ ivpico::helm::yaml_text(set),
+ output);
+#else
+ (void)file, (void)output;
+ return fail("ivpico_bhv was built without yaml-cpp (enable_yaml), so it can't write YAML");
+#endif
+}
+
+int check(const std::string& file, const std::vector& domains)
+{
+ ivp::interface::HelmConfig cfg;
+ cfg.add_behavior_file(file);
+ cfg.set_ownship("ownship");
+ for (const auto& d : domains)
+ {
+ std::vector parts;
+ std::stringstream s(d);
+ for (std::string part; std::getline(s, part, ':');) parts.push_back(part);
+ auto& domain = *cfg.add_domain();
+ try
+ {
+ if (parts.size() != 4)
+ throw std::invalid_argument(d);
+ domain.set_name(parts[0]);
+ domain.set_low(std::stod(parts[1]));
+ domain.set_high(std::stod(parts[2]));
+ domain.set_points(std::stoul(parts[3]));
+ }
+ catch (const std::exception&)
+ {
+ return fail("--domain takes name:low:high:points, e.g. course:0:359:360");
+ }
+ }
+ if (domains.empty())
+ {
+ for (const auto& [name, low, high, points] :
+ std::vector>{
+ {"course", 0, 359, 360}, {"speed", 0, 5, 26}, {"depth", 0, 500, 501}})
+ {
+ auto& domain = *cfg.add_domain();
+ domain.set_name(name);
+ domain.set_low(low);
+ domain.set_high(high);
+ domain.set_points(points);
+ }
+ }
+
+ // MOOS-IvP's libraries narrate their work on stdout and stderr
+ std::ostringstream quiet;
+ auto* out = std::cout.rdbuf(quiet.rdbuf());
+ auto* err = std::cerr.rdbuf(quiet.rdbuf());
+ std::vector warnings;
+ {
+ ivpico::helm::Helm helm(cfg);
+ warnings = helm.config_warnings();
+ }
+ std::cout.rdbuf(out);
+ std::cerr.rdbuf(err);
+
+ if (!warnings.empty())
+ return report(warnings);
+ std::cout << file << ": OK\n";
+ return 0;
+}
+} // namespace
+
+int main(int argc, char* argv[])
+{
+ std::vector args(argv + 1, argv + argc);
+ if (args.empty() || args[0] == "-h" || args[0] == "--help")
+ {
+ std::cout << usage;
+ return args.empty() ? 1 : 0;
+ }
+
+ const std::string command = args[0];
+ std::string input, output;
+ std::vector domains;
+ for (std::size_t i = 1; i < args.size(); ++i)
+ {
+ if ((args[i] == "-o" || args[i] == "--domain") && i + 1 < args.size())
+ (args[i] == "-o" ? output : domains.emplace_back()) = args[i + 1], ++i;
+ else if (input.empty() && args[i].rfind("-", 0) != 0)
+ input = args[i];
+ else
+ return fail(std::string("Unexpected argument: ") + args[i] + "\n" + usage);
+ }
+
+ if (command == "schema" && input.empty())
+ return write_output(ivpico::helm::yaml_schema(), output);
+ if (input.empty())
+ return fail(usage);
+ if (command == "convert")
+ return convert(input, output);
+ if (command == "import")
+ return import(input, output);
+ if (command == "check")
+ return check(input, domains);
+ return fail("Unknown command: " + command + "\n" + usage);
+}
diff --git a/src/lib/CMakeLists.txt b/src/lib/CMakeLists.txt
index 10ad4df..21e0b0f 100644
--- a/src/lib/CMakeLists.txt
+++ b/src/lib/CMakeLists.txt
@@ -2,20 +2,31 @@ add_library(ivpico_interface)
protobuf_generate(
TARGET ivpico_interface
LANGUAGE cpp
- PROTOS interface/options.proto interface/ivp.proto interface/config.proto
+ PROTOS interface/options.proto interface/ivp.proto interface/behaviors.proto interface/config.proto
IMPORT_DIRS ${CMAKE_CURRENT_SOURCE_DIR} ${openocean_messages_PROTO_DIR}
PROTOC_OUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
target_include_directories(ivpico_interface PUBLIC $)
target_link_libraries(ivpico_interface PUBLIC openocean_messages::openocean_messages)
add_library(ivpico_helm helm/helm.cpp helm/conversions.cpp helm/status_strings.cpp
- helm/contact_manager.cpp helm/contacts/CMAlert.cpp helm/contacts/PlatformAlertRecord.cpp)
+ helm/contact_manager.cpp helm/contacts/CMAlert.cpp helm/contacts/PlatformAlertRecord.cpp
+ helm/behavior_file.cpp)
target_include_directories(ivpico_helm PUBLIC $)
target_link_libraries(ivpico_helm
PUBLIC ivpico_interface
PRIVATE IVP::helmivp IVP::geodaid IVP::behaviors IVP::contacts IVP::logic IVP::ivpbuild
IVP::ivpsolve IVP::ivpcore IVP::geometry IVP::mbutil)
+if(enable_yaml)
+ target_sources(ivpico_helm PRIVATE helm/behavior_yaml.cpp)
+ target_compile_definitions(ivpico_helm PUBLIC HAS_YAML)
+ if(TARGET yaml-cpp::yaml-cpp)
+ target_link_libraries(ivpico_helm PRIVATE yaml-cpp::yaml-cpp)
+ else()
+ target_link_libraries(ivpico_helm PRIVATE yaml-cpp)
+ endif()
+endif()
+
install(TARGETS ivpico_interface ivpico_helm
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
diff --git a/src/lib/helm/behavior_file.cpp b/src/lib/helm/behavior_file.cpp
new file mode 100644
index 0000000..72b891a
--- /dev/null
+++ b/src/lib/helm/behavior_file.cpp
@@ -0,0 +1,704 @@
+// Copyright 2026:
+// GobySoft, LLC
+//
+// This file is part of IvPico.
+//
+// IvPico is free software: you can redistribute it and/or modify it under the
+// terms of the GNU Lesser General Public License as published by the Free Software
+// Foundation, either version 2.1 of the License, or (at your option) any later
+// version.
+//
+// IvPico is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with IvPico. If not, see .
+
+#include "behavior_file.h"
+
+#include
+#include
+#include
+#include
+
+#include
+
+#include "LogicCondition.h"
+
+using ivp::interface::BehaviorSet;
+using Behavior = ivp::interface::BehaviorSet::Behavior;
+using google::protobuf::FieldDescriptor;
+
+namespace
+{
+std::string strip(const std::string& s)
+{
+ const auto begin = s.find_first_not_of(" \t\r");
+ if (begin == std::string::npos)
+ return "";
+ return s.substr(begin, s.find_last_not_of(" \t\r") - begin + 1);
+}
+
+std::string lower(std::string s)
+{
+ for (auto& c : s) c = static_cast(std::tolower(static_cast(c)));
+ return s;
+}
+
+bool starts_with_nocase(const std::string& s, const std::string& prefix)
+{
+ return s.size() >= prefix.size() && lower(s.substr(0, prefix.size())) == prefix;
+}
+
+bool has_white(const std::string& s) { return s.find_first_of(" \t") != std::string::npos; }
+
+std::string indexed(const std::string& base, int i) { return base + "[" + std::to_string(i) + "]"; }
+
+// The parameters every behavior takes: Behavior's fields other than type and param
+bool is_common(const FieldDescriptor* f) { return f->name() != "type" && f->name() != "param"; }
+
+// MBUtils' parseStringQ: split on sep outside double quotes
+std::vector split_quoted(const std::string& s, char sep)
+{
+ std::vector parts(1);
+ bool quoted = false;
+ for (char c : s)
+ {
+ if (c == '"')
+ quoted = !quoted;
+ if (c == sep && !quoted)
+ parts.emplace_back();
+ else
+ parts.back() += c;
+ }
+ return parts;
+}
+
+// Values the Populator would read differently than given
+void check_value(const std::string& value, const std::string& path,
+ std::vector& errors)
+{
+ if (value.find('\n') != std::string::npos)
+ errors.push_back(path + ": a .bhv value can't span lines");
+ if (value.find("//") != std::string::npos)
+ errors.push_back(path + ": .bhv reads \"//\" as the start of a comment");
+ if (!value.empty() && value.back() == '\\')
+ errors.push_back(path + ": .bhv joins a line ending in \"\\\" to the next");
+ const std::string s = strip(value);
+ if (!s.empty() && (s.front() == '{' || s.front() == '}' || s.back() == '{'))
+ errors.push_back(path + ": .bhv splits a brace at the start or end of a line");
+}
+
+void check_word(const std::string& word, const std::string& what, const std::string& path,
+ std::vector& errors)
+{
+ if (strip(word).empty() || has_white(strip(word)) ||
+ word.find_first_of("={},") != std::string::npos)
+ errors.push_back(path + ": \"" + word + "\" isn't a valid " + what);
+}
+
+// The state machine of Populator_BehaviorSet::handleLine
+class BhvReader
+{
+ public:
+ BhvReader(BehaviorSet& set, const std::string& filename, ivpico::helm::SourceMap* map)
+ : set_(set), filename_(filename), map_(map)
+ {
+ }
+
+ bool handle(std::string line, int line_num)
+ {
+ line_num_ = line_num;
+ const auto comment = line.find("//");
+ if (comment != std::string::npos)
+ line.erase(comment);
+ line = strip(line);
+
+ if (line.empty())
+ {
+ if (mode_ == Mode::MiscDefinedIsh)
+ mode_ = Mode::Top;
+ else if (mode_ == Mode::SetDefinedIsh)
+ close_set();
+ return true;
+ }
+ if (line == "{")
+ {
+ if (mode_ == Mode::Top)
+ mode_ = Mode::MiscDefining;
+ else if (mode_ == Mode::BhvDeclared)
+ mode_ = Mode::BhvDefining;
+ else if (mode_ == Mode::SetDeclared)
+ mode_ = Mode::SetDefining;
+ else
+ return false;
+ return true;
+ }
+ if (line == "}")
+ {
+ if (mode_ == Mode::MiscDefining)
+ mode_ = Mode::MiscDefinedIsh;
+ else if (mode_ == Mode::BhvDefining)
+ mode_ = Mode::Top;
+ else if (mode_ == Mode::SetDefining)
+ mode_ = Mode::SetDefinedIsh;
+ else
+ return false;
+ return true;
+ }
+
+ if (mode_ == Mode::Top || mode_ == Mode::MiscDefinedIsh || mode_ == Mode::SetDefinedIsh)
+ {
+ if (starts_with_nocase(line, "initialize ") || starts_with_nocase(line, "initialize_ "))
+ {
+ if (mode_ == Mode::SetDefinedIsh)
+ close_set();
+ mode_ = Mode::Top;
+ const auto space = line.find(' ');
+ const bool deferred = line.substr(0, space) == "initialize_";
+ for (const auto& item : split_quoted(line.substr(space + 1), ','))
+ {
+ const std::string pair = strip(item);
+ const auto eq = pair.find('=');
+ const std::string left = strip(pair.substr(0, eq));
+ const std::string right =
+ eq == std::string::npos ? "" : strip(pair.substr(eq + 1));
+ if (left.empty() || has_white(left) || right.empty())
+ return false;
+ auto& init = *set_.add_initialize();
+ init.set_var(left);
+ init.set_value(right);
+ init.set_deferred(deferred);
+ note(indexed("initialize", set_.initialize_size() - 1));
+ }
+ return true;
+ }
+ if (starts_with_nocase(line, "behavior"))
+ {
+ if (mode_ == Mode::SetDefinedIsh)
+ close_set();
+ const auto eq = line.find('=');
+ set_.add_behavior()->set_type(eq == std::string::npos ? ""
+ : strip(line.substr(eq + 1)));
+ note(indexed("behavior", set_.behavior_size() - 1));
+ mode_ = Mode::BhvDeclared;
+ return true;
+ }
+ if (starts_with_nocase(line, "set "))
+ {
+ if (mode_ == Mode::SetDefinedIsh)
+ close_set();
+ const std::string head = line.substr(4);
+ const auto eq = head.find('=');
+ const std::string var = strip(head.substr(0, eq));
+ const std::string val = eq == std::string::npos ? "" : strip(head.substr(eq + 1));
+ if (var.empty() || val.empty())
+ return false;
+ pending_mode_ = BehaviorSet::Mode();
+ pending_mode_.set_set(var + " = " + val);
+ pending_line_ = line_num_;
+ mode_ = Mode::SetDeclared;
+ return true;
+ }
+ }
+
+ switch (mode_)
+ {
+ case Mode::MiscDefining: return true;
+ case Mode::SetDefinedIsh:
+ if (has_white(line))
+ return false;
+ pending_mode_.set_else_value(line);
+ pending_else_line_ = line_num_;
+ close_set();
+ return true;
+ case Mode::BhvDefining: add_config(line); return true;
+ case Mode::SetDefining:
+ {
+ LogicCondition condition;
+ condition.setAllowDoubleEquals(false);
+ if (!condition.setCondition(line))
+ return false;
+ pending_mode_.add_condition(line);
+ pending_condition_lines_.push_back(line_num_);
+ return true;
+ }
+ default: return false;
+ }
+ }
+
+ private:
+ enum class Mode
+ {
+ Top,
+ MiscDefining,
+ MiscDefinedIsh,
+ BhvDeclared,
+ BhvDefining,
+ SetDeclared,
+ SetDefining,
+ SetDefinedIsh
+ };
+
+ void note(const std::string& path, int line = 0)
+ {
+ if (map_)
+ (*map_)[path] = {filename_, line ? line : line_num_, 0};
+ }
+
+ void close_set()
+ {
+ const std::string path = indexed("mode", set_.mode_size());
+ *set_.add_mode() = pending_mode_;
+ note(path, pending_line_);
+ for (std::size_t i = 0; i < pending_condition_lines_.size(); ++i)
+ note(indexed(path + ".condition", static_cast(i)), pending_condition_lines_[i]);
+ if (pending_mode_.has_else_value())
+ note(path + ".else_value", pending_else_line_);
+ pending_condition_lines_.clear();
+ mode_ = Mode::Top;
+ }
+
+ void add_config(const std::string& line)
+ {
+ auto& bhv = *set_.mutable_behavior(set_.behavior_size() - 1);
+ const std::string base = indexed("behavior", set_.behavior_size() - 1);
+ const auto eq = line.find('=');
+ const std::string key = strip(line.substr(0, eq));
+ const std::string value = eq == std::string::npos ? "" : strip(line.substr(eq + 1));
+
+ const auto* f = Behavior::descriptor()->FindFieldByName(lower(key));
+ const auto* refl = Behavior::GetReflection();
+ if (f && is_common(f) && f->is_repeated())
+ {
+ refl->AddString(&bhv, f, value);
+ note(indexed(base + "." + f->name(), refl->FieldSize(bhv, f) - 1));
+ }
+ // a common parameter given twice keeps both, as a param
+ else if (f && is_common(f) && !refl->HasField(bhv, f))
+ {
+ refl->SetString(&bhv, f, value);
+ note(base + "." + f->name());
+ }
+ else
+ {
+ auto& param = *bhv.add_param();
+ param.set_key(key);
+ param.set_value(value);
+ note(indexed(base + ".param", bhv.param_size() - 1));
+ }
+ }
+
+ BehaviorSet& set_;
+ std::string filename_;
+ ivpico::helm::SourceMap* map_;
+ Mode mode_{Mode::Top};
+ int line_num_{0};
+ BehaviorSet::Mode pending_mode_;
+ int pending_line_{0};
+ int pending_else_line_{0};
+ std::vector pending_condition_lines_;
+};
+} // namespace
+
+std::string ivpico::helm::SourceLocation::str() const
+{
+ std::string s = file;
+ if (line > 0)
+ s += ":" + std::to_string(line);
+ if (line > 0 && column > 0)
+ s += ":" + std::to_string(column);
+ return s;
+}
+
+std::optional ivpico::helm::locate(const SourceMap& map,
+ std::string path)
+{
+ while (true)
+ {
+ auto it = map.find(path);
+ if (it != map.end())
+ return it->second;
+ const auto cut = path.find_last_of(".[");
+ if (cut == std::string::npos || cut == 0)
+ return std::nullopt;
+ path.erase(cut);
+ }
+}
+
+bool ivpico::helm::is_yaml_file(const std::string& filename)
+{
+ const auto dot = filename.rfind('.');
+ if (dot == std::string::npos)
+ return false;
+ const std::string ext = lower(filename.substr(dot));
+ return ext == ".yml" || ext == ".yaml";
+}
+
+std::vector ivpico::helm::bhv_lines(const BehaviorSet& set,
+ std::vector& errors)
+{
+ std::vector lines;
+ auto add = [&](const std::string& text, const std::string& path)
+ { lines.push_back({text, path}); };
+
+ for (int i = 0; i < set.initialize_size(); ++i)
+ {
+ const auto& init = set.initialize(i);
+ const std::string path = indexed("initialize", i);
+ check_word(init.var(), "variable name", path, errors);
+ check_value(init.value(), path, errors);
+ if (strip(init.value()).empty())
+ errors.push_back(path + ": initialize needs a value");
+ const auto& value = init.value();
+ if (value.find(',') != std::string::npos &&
+ !(value.size() > 1 && value.front() == '"' && value.back() == '"'))
+ errors.push_back(path + ": .bhv splits an initialize value at a comma unless it's "
+ "in double quotes");
+ add(std::string(init.deferred() ? "initialize_ " : "initialize ") + init.var() + " = " +
+ init.value(),
+ path);
+ }
+ if (set.initialize_size())
+ add("", "");
+
+ for (int i = 0; i < set.mode_size(); ++i)
+ {
+ const auto& mode = set.mode(i);
+ const std::string path = indexed("mode", i);
+ const auto eq = mode.set().find('=');
+ if (eq == std::string::npos || strip(mode.set().substr(0, eq)).empty() ||
+ strip(mode.set().substr(eq + 1)).empty())
+ errors.push_back(path + ": set needs \"MODE_VAR = value\"");
+ check_value(mode.set(), path, errors);
+ add("set " + mode.set() + " {", path);
+ for (int j = 0; j < mode.condition_size(); ++j)
+ {
+ const std::string cpath = indexed(path + ".condition", j);
+ check_value(mode.condition(j), cpath, errors);
+ add(" " + mode.condition(j), cpath);
+ }
+ if (mode.has_else_value())
+ {
+ if (strip(mode.else_value()).empty() || has_white(strip(mode.else_value())))
+ errors.push_back(path + ".else_value: the else value must be one word");
+ check_value(mode.else_value(), path + ".else_value", errors);
+ add("} " + mode.else_value(), path + ".else_value");
+ }
+ else
+ {
+ add("}", path);
+ }
+ add("", "");
+ }
+
+ const auto* refl = Behavior::GetReflection();
+ for (int i = 0; i < set.behavior_size(); ++i)
+ {
+ const auto& bhv = set.behavior(i);
+ const std::string path = indexed("behavior", i);
+ check_word(bhv.type(), "behavior type", path, errors);
+ add("Behavior = " + bhv.type(), path);
+ add("{", path);
+ for (int f = 0; f < Behavior::descriptor()->field_count(); ++f)
+ {
+ const auto* field = Behavior::descriptor()->field(f);
+ if (!is_common(field))
+ continue;
+ const std::string fpath = path + "." + field->name();
+ if (field->is_repeated())
+ {
+ for (int j = 0; j < refl->FieldSize(bhv, field); ++j)
+ {
+ const std::string value = refl->GetRepeatedString(bhv, field, j);
+ check_value(value, indexed(fpath, j), errors);
+ add(" " + field->name() + " = " + value, indexed(fpath, j));
+ }
+ }
+ else if (refl->HasField(bhv, field))
+ {
+ const std::string value = refl->GetString(bhv, field);
+ check_value(value, fpath, errors);
+ add(" " + field->name() + " = " + value, fpath);
+ }
+ }
+ for (int j = 0; j < bhv.param_size(); ++j)
+ {
+ const auto& param = bhv.param(j);
+ const std::string ppath = indexed(path + ".param", j);
+ if (strip(param.key()).empty() || param.key().find_first_of("=\n") != std::string::npos)
+ errors.push_back(ppath + ": \"" + param.key() + "\" isn't a valid parameter name");
+ check_value(param.key(), ppath, errors);
+ check_value(param.value(), ppath, errors);
+ add(" " + param.key() + " = " + param.value(), ppath);
+ }
+ add("}", path);
+ add("", "");
+ }
+ return lines;
+}
+
+std::string ivpico::helm::bhv_text(const std::vector& lines)
+{
+ std::string text;
+ for (const auto& line : lines) text += line.text + "\n";
+ return text;
+}
+
+BehaviorSet ivpico::helm::read_bhv(const std::string& text, const std::string& filename,
+ std::vector& errors, SourceMap* map)
+{
+ BehaviorSet set;
+ BhvReader reader(set, filename, map);
+
+ // lines ending in "\" are joined to the next, as fileBufferSlash does
+ std::istringstream in(text);
+ std::string raw;
+ int line_num = 0;
+ while (std::getline(in, raw))
+ {
+ const int first_line = ++line_num;
+ std::string line = strip(raw);
+ while (!line.empty() && line.back() == '\\' && std::getline(in, raw))
+ {
+ ++line_num;
+ line.pop_back();
+ line += strip(raw);
+ }
+
+ // Populator_BehaviorSet::populate's brace separation
+ const bool comment = line.rfind("//", 0) == 0 || line.rfind("#", 0) == 0;
+ std::string pre, post;
+ if (!comment)
+ {
+ if (line.size() > 1 && (line.front() == '{' || line.front() == '}'))
+ {
+ pre = line.substr(0, 1);
+ line.erase(0, 1);
+ }
+ if (line.size() > 1 && line.back() == '{')
+ {
+ post = "{";
+ line.pop_back();
+ }
+ }
+ const bool ok = (pre.empty() || reader.handle(pre, first_line)) &&
+ reader.handle(line, first_line) &&
+ (post.empty() || reader.handle(post, first_line));
+ if (!ok)
+ {
+ errors.push_back(SourceLocation{filename, first_line, 0}.str() +
+ ": can't read the line \"" + strip(raw) + "\"");
+ break;
+ }
+ }
+ return set;
+}
+
+std::string ivpico::helm::yaml_schema()
+{
+ std::string behavior_props =
+ R"json( "type": { "type": "string", "pattern": "^\\S+$" })json";
+ for (int f = 0; f < Behavior::descriptor()->field_count(); ++f)
+ {
+ const auto* field = Behavior::descriptor()->field(f);
+ if (!is_common(field))
+ continue;
+ behavior_props += ",\n \"" + field->name() + "\": { \"$ref\": \"#/$defs/" +
+ (field->is_repeated() ? "values" : "value") + "\" }";
+ }
+ behavior_props += R"json(,
+ "params": {
+ "description": "The behavior's own parameters, in order; a list for a parameter given more than once",
+ "type": "object",
+ "additionalProperties": { "$ref": "#/$defs/values" }
+ })json";
+
+ return R"json({
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://github.com/GobySoft/IvPico/blob/main/share/ivpico/bhv.schema.json",
+ "title": "IvPico behavior file (.bhv.yml)",
+ "description": "MOOS-IvP behaviors, modes and initial variables, as a .bhv file holds them",
+ "type": "object",
+ "additionalProperties": false,
+ "patternProperties": {
+ "^x-": { "description": "Ignored: a place for anchors to merge elsewhere" }
+ },
+ "properties": {
+ "initialize": {
+ "description": "Variables posted when the helm starts (initialize)",
+ "$ref": "#/$defs/variables"
+ },
+ "initialize_deferred": {
+ "description": "Variables posted unless another app has set them (initialize_)",
+ "$ref": "#/$defs/variables"
+ },
+ "modes": {
+ "description": "Hierarchical modes (set), in order",
+ "type": "array",
+ "items": { "$ref": "#/$defs/mode" }
+ },
+ "behaviors": {
+ "type": "array",
+ "items": { "$ref": "#/$defs/behavior" }
+ }
+ },
+ "$defs": {
+ "value": { "type": ["string", "number", "boolean"] },
+ "values": {
+ "oneOf": [
+ { "$ref": "#/$defs/value" },
+ { "type": "array", "items": { "$ref": "#/$defs/value" } }
+ ]
+ },
+ "variables": {
+ "type": "object",
+ "propertyNames": { "pattern": "^[^\\s=,{}]+$" },
+ "additionalProperties": { "$ref": "#/$defs/value" }
+ },
+ "mode": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["set"],
+ "properties": {
+ "set": { "description": "MODE_VAR = value", "type": "string", "pattern": "\\S\\s*=\\s*\\S" },
+ "condition": { "$ref": "#/$defs/values" },
+ "else": { "$ref": "#/$defs/value" }
+ }
+ },
+ "behavior": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type"],
+ "properties": {
+)json" + behavior_props +
+ R"json(
+ }
+ }
+ }
+}
+)json";
+}
+
+bool ivpico::helm::needs_combining(const ivp::interface::HelmConfig& cfg)
+{
+ return cfg.behaviors_size() > 0 ||
+ std::any_of(cfg.behavior_file().begin(), cfg.behavior_file().end(), is_yaml_file);
+}
+
+ivpico::helm::CombinedBehaviors
+ivpico::helm::combine_behaviors(const ivp::interface::HelmConfig& cfg,
+ std::vector& errors)
+{
+ CombinedBehaviors combined;
+ auto add_set = [&](const BehaviorSet& set, const std::string& prefix, const SourceMap* map)
+ {
+ std::vector set_errors;
+ const auto lines = bhv_lines(set, set_errors);
+ auto where = [&](const std::string& path) -> SourceLocation
+ {
+ if (map)
+ if (auto loc = locate(*map, path))
+ return *loc;
+ return {prefix + (path.empty() ? "" : "." + path), 0, 0};
+ };
+ for (const auto& e : set_errors)
+ {
+ const auto colon = e.find(": ");
+ errors.push_back(where(e.substr(0, colon)).str() + e.substr(colon));
+ }
+ for (const auto& line : lines)
+ {
+ combined.text += line.text + "\n";
+ combined.line_locations.push_back(where(line.path));
+ }
+ };
+
+ for (const auto& file : cfg.behavior_file())
+ {
+ std::ifstream in(file);
+ if (!in)
+ {
+ errors.push_back("Could not find File: " + file);
+ continue;
+ }
+ std::stringstream text;
+ text << in.rdbuf();
+
+ if (!is_yaml_file(file))
+ {
+ // lines ending in "\" are joined here, so line numbers stay the file's own
+ std::istringstream lines(text.str());
+ std::string line;
+ int line_num = 0;
+ while (std::getline(lines, line))
+ {
+ const int first_line = ++line_num;
+ std::string joined = strip(line);
+ while (!joined.empty() && joined.back() == '\\' && std::getline(lines, line))
+ {
+ ++line_num;
+ joined.pop_back();
+ joined += strip(line);
+ }
+ combined.text += joined + "\n";
+ combined.line_locations.push_back({file, first_line, 0});
+ }
+ combined.text += "\n";
+ combined.line_locations.push_back({file, 0, 0});
+ continue;
+ }
+#ifdef HAS_YAML
+ SourceMap map;
+ if (auto set = read_yaml(text.str(), file, errors, &map))
+ add_set(*set, file, &map);
+#else
+ errors.push_back(file + ": this IvPico was built without yaml-cpp (enable_yaml), so it "
+ "can't read YAML behavior files");
+#endif
+ }
+ for (int i = 0; i < cfg.behaviors_size(); ++i)
+ add_set(cfg.behaviors(i), "behaviors[" + std::to_string(i) + "]", nullptr);
+ return combined;
+}
+
+std::string ivpico::helm::relocate_warning(const std::string& warning, const std::string& path,
+ const CombinedBehaviors& combined)
+{
+ auto location = [&](unsigned long line) -> std::string
+ {
+ if (line >= 1 && line <= combined.line_locations.size())
+ return combined.line_locations[line - 1].str();
+ return "behaviors";
+ };
+
+ // Populator_BehaviorSet: a line it can't read, numbered from 1
+ const std::string problem = "Problem with line ";
+ const std::string in_file = " in the BehaviorSet file: " + path + " Line: ";
+ const auto in_file_pos = warning.find(in_file);
+ if (warning.rfind(problem, 0) == 0 && in_file_pos != std::string::npos)
+ {
+ const std::string number = warning.substr(problem.size(), in_file_pos - problem.size());
+ if (!number.empty() && std::all_of(number.begin(), number.end(), ::isdigit))
+ return location(std::stoul(number)) + ": can't read the line " +
+ warning.substr(in_file_pos + in_file.size());
+ }
+
+ // BehaviorSet: a parameter the behavior rejected, numbered from 0
+ const std::string prefix = path + ": Line ";
+ if (warning.rfind(prefix, 0) == 0)
+ {
+ const std::string rest = warning.substr(prefix.size());
+ const auto colon = rest.find(": ");
+ if (colon != std::string::npos && colon > 0 &&
+ std::all_of(rest.begin(), rest.begin() + colon, ::isdigit))
+ return location(std::stoul(rest.substr(0, colon)) + 1) + ": the behavior rejected \"" +
+ rest.substr(colon + 2) + "\"";
+ }
+
+ std::string out = warning;
+ for (auto pos = out.find(path); pos != std::string::npos; pos = out.find(path))
+ out.replace(pos, path.size(), "behaviors");
+ return out;
+}
diff --git a/src/lib/helm/behavior_file.h b/src/lib/helm/behavior_file.h
new file mode 100644
index 0000000..22b0cfb
--- /dev/null
+++ b/src/lib/helm/behavior_file.h
@@ -0,0 +1,107 @@
+// Copyright 2026:
+// GobySoft, LLC
+//
+// This file is part of IvPico.
+//
+// IvPico is free software: you can redistribute it and/or modify it under the
+// terms of the GNU Lesser General Public License as published by the Free Software
+// Foundation, either version 2.1 of the License, or (at your option) any later
+// version.
+//
+// IvPico is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with IvPico. If not, see .
+
+#ifndef IVPICO_HELM_BEHAVIOR_FILE_H
+#define IVPICO_HELM_BEHAVIOR_FILE_H
+
+#include