From 19f950018c5049fa7d014003566cb4503c7436af Mon Sep 17 00:00:00 2001 From: agessaman Date: Tue, 12 May 2026 12:08:03 -0700 Subject: [PATCH 1/3] Add bulk region hierarchy command to CLI Add a new command `region bulk` for defining region hierarchies in a single line. This command allows users to create multiple regions in a single message. Updated the documentation to include usage examples and detailed parameter descriptions. --- docs/cli_commands.md | 40 ++++++++++++++++++++++++ src/helpers/CommonCLI.cpp | 64 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index e70ba2172..f96d1005e 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -756,6 +756,46 @@ This document provides an overview of CLI commands that can be sent to MeshCore --- +#### Bulk-define region hierarchy (single line) +**Usage:** +- `region bulk [ ...]` + +**Parameters (tokens):** Space-separated. A logical **cursor** starts at the wildcard `*`. + +- **`name`** — Create `name` as a child of the current cursor (same as `region put name` with that parent). Cursor moves to `name`. +- **`name|jump`** or **`name,jump`** — Create `name` as a child of the current cursor, then move the cursor to `jump` (must already exist: created earlier in this command or already on the node). `jump` is **not** the parent of `name`; use this to pop back up and start another branch. + +**Note:** Same flood defaults as `region put` (flood allowed on each created region). + +**Note:** Does **not** persist to flash. The reply is the region tree (same format as bare `region`) so you can review before **`region save`**. + +**Note:** On error, the reply is a short `Err - ...` message; regions placed before the failure remain (same as a partial chain of `region put`). + +**Note:** Repeater serial accepts one line up to **160 characters** total; split very large trees across multiple `region bulk` commands. + +**Note:** `|` only splits once per token. `region bulk a|b|c|d` is **not** a flat-list shorthand — use `region bulk a|* b|* c|* d|*` for multiple children of `*`. + +**Example — linear chain:** +``` +region bulk west pnw wa w-wa sea +region save +``` + +**Example — branched tree** (equivalent to `region put west` … `region put sw-wa wa`): +``` +region bulk west pnw or pdx|pnw wa sw-wa +region save +``` +Same with comma as jump delimiter: `region bulk west pnw or pdx,pnw wa sw-wa` + +**Example — flat list** (each region child of `*`): +``` +region bulk west|* pnw|* or|* pdx|* wa|* sw-wa +region save +``` + +--- + #### Remove a region **Usage:** - `region remove ` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index b71afc72e..c85d3b005 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -898,6 +898,70 @@ void CommonCLI::handleGetCmd(uint32_t sender_timestamp, char* command, char* rep void CommonCLI::handleRegionCmd(char* command, char* reply) { reply[0] = 0; + // `region bulk ...` — cursor-walk over space-separated tokens (must run before + // parseTextParts, which only keeps 4 segments and mutates the buffer). + char* cmd = command; + while (*cmd == ' ') cmd++; + if (strncmp(cmd, "region bulk", 11) == 0 && (cmd[11] == ' ' || cmd[11] == '\0')) { + char* payload = cmd + 11; + while (*payload == ' ') payload++; + if (*payload == '\0') { + snprintf(reply, 160, "Err - empty bulk"); + return; + } + RegionEntry* cursor = &_region_map->getWildcard(); + char* p = payload; + while (*p) { + while (*p == ' ') p++; + if (*p == '\0') break; + char* tok = p; + while (*p && *p != ' ') p++; + if (*p) *p++ = '\0'; + + char* jump = nullptr; + for (char* q = tok; *q; q++) { + if (*q == '|' || *q == ',') { + *q = '\0'; + jump = q + 1; + break; + } + } + char* name = tok; + while (*name == ' ') name++; + if (jump) { + while (*jump == ' ') jump++; + char* je = jump + strlen(jump); + while (je > jump && je[-1] == ' ') *--je = '\0'; + } + if (*name == '\0') { + snprintf(reply, 160, "Err - empty name"); + return; + } + if (jump && *jump == '\0') { + snprintf(reply, 160, "Err - empty jump"); + return; + } + auto r = _region_map->putRegion(name, cursor->id); + if (r == NULL) { + snprintf(reply, 160, "Err - put failed: %s", name); + return; + } + r->flags = 0; + if (jump) { + auto j = _region_map->findByNamePrefix(jump); + if (j == NULL) { + snprintf(reply, 160, "Err - unknown jump: %s", jump); + return; + } + cursor = j; + } else { + cursor = r; + } + } + _region_map->exportTo(reply, 160); + return; + } + const char* parts[4]; int n = mesh::Utils::parseTextParts(command, parts, 4, ' '); if (n == 1) { From f3c6c3488341723b4f9c20e3d34284cf6925a8c1 Mon Sep 17 00:00:00 2001 From: agessaman Date: Sat, 16 May 2026 10:47:51 -0700 Subject: [PATCH 2/3] Update CLI command from `region bulk` to `region def` --- docs/cli_commands.md | 16 ++++++++-------- src/helpers/CommonCLI.cpp | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index f96d1005e..328734d5b 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -756,9 +756,9 @@ This document provides an overview of CLI commands that can be sent to MeshCore --- -#### Bulk-define region hierarchy (single line) +#### Define region hierarchy (single line) **Usage:** -- `region bulk [ ...]` +- `region def [ ...]` **Parameters (tokens):** Space-separated. A logical **cursor** starts at the wildcard `*`. @@ -771,26 +771,26 @@ This document provides an overview of CLI commands that can be sent to MeshCore **Note:** On error, the reply is a short `Err - ...` message; regions placed before the failure remain (same as a partial chain of `region put`). -**Note:** Repeater serial accepts one line up to **160 characters** total; split very large trees across multiple `region bulk` commands. +**Note:** Repeater serial accepts one line up to **160 characters** total; split very large trees across multiple `region def` commands. -**Note:** `|` only splits once per token. `region bulk a|b|c|d` is **not** a flat-list shorthand — use `region bulk a|* b|* c|* d|*` for multiple children of `*`. +**Note:** `|` only splits once per token. `region def a|b|c|d` is **not** a flat-list shorthand — use `region def a|* b|* c|* d|*` for multiple children of `*`. **Example — linear chain:** ``` -region bulk west pnw wa w-wa sea +region def west pnw wa w-wa sea region save ``` **Example — branched tree** (equivalent to `region put west` … `region put sw-wa wa`): ``` -region bulk west pnw or pdx|pnw wa sw-wa +region def west pnw or pdx|pnw wa sw-wa region save ``` -Same with comma as jump delimiter: `region bulk west pnw or pdx,pnw wa sw-wa` +Same with comma as jump delimiter: `region def west pnw or pdx,pnw wa sw-wa` **Example — flat list** (each region child of `*`): ``` -region bulk west|* pnw|* or|* pdx|* wa|* sw-wa +region def west|* pnw|* or|* pdx|* wa|* sw-wa region save ``` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index c85d3b005..c366d3b87 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -898,15 +898,15 @@ void CommonCLI::handleGetCmd(uint32_t sender_timestamp, char* command, char* rep void CommonCLI::handleRegionCmd(char* command, char* reply) { reply[0] = 0; - // `region bulk ...` — cursor-walk over space-separated tokens (must run before + // `region def ...` — cursor-walk over space-separated tokens (must run before // parseTextParts, which only keeps 4 segments and mutates the buffer). char* cmd = command; while (*cmd == ' ') cmd++; - if (strncmp(cmd, "region bulk", 11) == 0 && (cmd[11] == ' ' || cmd[11] == '\0')) { - char* payload = cmd + 11; + if (strncmp(cmd, "region def", 10) == 0 && (cmd[10] == ' ' || cmd[10] == '\0')) { + char* payload = cmd + 10; while (*payload == ' ') payload++; if (*payload == '\0') { - snprintf(reply, 160, "Err - empty bulk"); + snprintf(reply, 160, "Err - empty def"); return; } RegionEntry* cursor = &_region_map->getWildcard(); From 1296aa77927cf763c32e571fe7f24e0d72b9cb72 Mon Sep 17 00:00:00 2001 From: agessaman Date: Thu, 21 May 2026 19:25:01 -0700 Subject: [PATCH 3/3] Refactor region def with helpers, refine docs Extract the inline cursor-walk in handleRegionCmd into file-local helpers (skipSpaces, rtrimSpaces, takeToken, splitNameJump, processRegionDefSegment), grouped immediately above the consumer. Behavior is identical; addresses PR #2540 review feedback on readability. Tighten the region def docs: collapse five Note callouts into three grouped paragraphs (Behavior / Existing regions / Limits), add a case-sensitivity caveat plus an error example, note the cursor reset between split commands, and use generic placeholder names. --- docs/cli_commands.md | 33 +++++------ src/helpers/CommonCLI.cpp | 117 +++++++++++++++++++------------------- 2 files changed, 77 insertions(+), 73 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 328734d5b..3255fe20c 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -762,35 +762,36 @@ This document provides an overview of CLI commands that can be sent to MeshCore **Parameters (tokens):** Space-separated. A logical **cursor** starts at the wildcard `*`. -- **`name`** — Create `name` as a child of the current cursor (same as `region put name` with that parent). Cursor moves to `name`. -- **`name|jump`** or **`name,jump`** — Create `name` as a child of the current cursor, then move the cursor to `jump` (must already exist: created earlier in this command or already on the node). `jump` is **not** the parent of `name`; use this to pop back up and start another branch. +- **`name`** — Create `name` as a child of the current cursor (equivalent to `region put name` with the cursor as parent). Cursor moves to `name`. +- **`name|jump`** *(or `name,jump`)* — Create `name` as a child of the current cursor, then move the cursor to `jump` (must already exist on the node, or have been created earlier in this command). `jump` is **not** the parent of `name`; use this form to pop back up and start another branch. -**Note:** Same flood defaults as `region put` (flood allowed on each created region). +**Behavior:** Each created region defaults to flood-allowed (same as `region put`). The reply is the resulting region tree (same format as bare `region`); review it before running `region save` to persist. On error, the reply is `Err - ...` and any regions placed before the failure remain on the node, just like a partial chain of `region put`. -**Note:** Does **not** persist to flash. The reply is the region tree (same format as bare `region`) so you can review before **`region save`**. +**Existing regions:** `region def` does not clear the existing tree — if a name already exists, its parent is updated to the current cursor; otherwise a new region is created. To start from scratch, `region remove` the unwanted regions first. -**Note:** On error, the reply is a short `Err - ...` message; regions placed before the failure remain (same as a partial chain of `region put`). +**Limits:** Repeater serial accepts one line up to **160 characters**. For larger trees, split across multiple `region def` commands; the cursor resets to `*` between commands, so lead the next command with `child|ancestor` to reposition. Each token splits at most once on `|` — `region def a|b|c|d` is not a flat-list shorthand; see the flat-list example below. -**Note:** Repeater serial accepts one line up to **160 characters** total; split very large trees across multiple `region def` commands. - -**Note:** `|` only splits once per token. `region def a|b|c|d` is **not** a flat-list shorthand — use `region def a|* b|* c|* d|*` for multiple children of `*`. - -**Example — linear chain:** +**Example — linear chain** (each token becomes a child of the previous): ``` -region def west pnw wa w-wa sea +region def a b c d e region save ``` -**Example — branched tree** (equivalent to `region put west` … `region put sw-wa wa`): +**Example — branched tree** (equivalent to `region put a`, `region put b a`, `region put c b`, `region put d c`, `region put e b`, `region put f e`): ``` -region def west pnw or pdx|pnw wa sw-wa +region def a b c d|b e f region save ``` -Same with comma as jump delimiter: `region def west pnw or pdx,pnw wa sw-wa` -**Example — flat list** (each region child of `*`): +**Example — error and partial state:** ``` -region def west|* pnw|* or|* pdx|* wa|* sw-wa +region def a b c|nope d +``` +The reply is `Err - unknown jump: nope`. `a`, `b`, and `c` were placed before the failure; `d` was not. Run `region` to inspect, then re-run with a corrected jump or repair with `region remove` / `region put`. + +**Example — flat list** (each region a child of `*`). Use `|*` after each token to pop the cursor back to the root before the next token: +``` +region def a|* b|* c|* d|* e|* f region save ``` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index c366d3b87..04904e137 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -895,68 +895,71 @@ void CommonCLI::handleGetCmd(uint32_t sender_timestamp, char* command, char* rep } } +static char* skipSpaces(char* s) { + while (*s == ' ') s++; + return s; +} + +static void rtrimSpaces(char* s) { + char* e = s + strlen(s); + while (e > s && e[-1] == ' ') *--e = '\0'; +} + +static char* takeToken(char** cursor) { + char* p = skipSpaces(*cursor); + if (*p == '\0') { *cursor = p; return nullptr; } + char* tok = p; + while (*p && *p != ' ') p++; + if (*p) *p++ = '\0'; + *cursor = p; + return tok; +} + +static char* splitNameJump(char* tok) { + for (char* q = tok; *q; q++) { + if (*q == '|' || *q == ',') { + *q = '\0'; + char* jump = skipSpaces(q + 1); + rtrimSpaces(jump); + return jump; + } + } + return nullptr; +} + +static bool processRegionDefSegment(RegionMap* map, char* tok, RegionEntry** cursor, char* reply) { + char* jump = splitNameJump(tok); + char* name = skipSpaces(tok); + if (*name == '\0') { snprintf(reply, 160, "Err - empty name"); return false; } + if (jump && *jump == '\0') { snprintf(reply, 160, "Err - empty jump"); return false; } + + RegionEntry* r = map->putRegion(name, (*cursor)->id); + if (r == NULL) { snprintf(reply, 160, "Err - put failed: %s", name); return false; } + r->flags = 0; + + if (jump) { + RegionEntry* j = map->findByNamePrefix(jump); + if (j == NULL) { snprintf(reply, 160, "Err - unknown jump: %s", jump); return false; } + *cursor = j; + } else { + *cursor = r; + } + return true; +} + void CommonCLI::handleRegionCmd(char* command, char* reply) { reply[0] = 0; - // `region def ...` — cursor-walk over space-separated tokens (must run before - // parseTextParts, which only keeps 4 segments and mutates the buffer). - char* cmd = command; - while (*cmd == ' ') cmd++; + // `region def`: must run before parseTextParts mutates the buffer + char* cmd = skipSpaces(command); if (strncmp(cmd, "region def", 10) == 0 && (cmd[10] == ' ' || cmd[10] == '\0')) { - char* payload = cmd + 10; - while (*payload == ' ') payload++; - if (*payload == '\0') { - snprintf(reply, 160, "Err - empty def"); - return; - } - RegionEntry* cursor = &_region_map->getWildcard(); - char* p = payload; - while (*p) { - while (*p == ' ') p++; - if (*p == '\0') break; - char* tok = p; - while (*p && *p != ' ') p++; - if (*p) *p++ = '\0'; + char* payload = skipSpaces(cmd + 10); + rtrimSpaces(payload); + if (*payload == '\0') { snprintf(reply, 160, "Err - empty def"); return; } - char* jump = nullptr; - for (char* q = tok; *q; q++) { - if (*q == '|' || *q == ',') { - *q = '\0'; - jump = q + 1; - break; - } - } - char* name = tok; - while (*name == ' ') name++; - if (jump) { - while (*jump == ' ') jump++; - char* je = jump + strlen(jump); - while (je > jump && je[-1] == ' ') *--je = '\0'; - } - if (*name == '\0') { - snprintf(reply, 160, "Err - empty name"); - return; - } - if (jump && *jump == '\0') { - snprintf(reply, 160, "Err - empty jump"); - return; - } - auto r = _region_map->putRegion(name, cursor->id); - if (r == NULL) { - snprintf(reply, 160, "Err - put failed: %s", name); - return; - } - r->flags = 0; - if (jump) { - auto j = _region_map->findByNamePrefix(jump); - if (j == NULL) { - snprintf(reply, 160, "Err - unknown jump: %s", jump); - return; - } - cursor = j; - } else { - cursor = r; - } + RegionEntry* cursor = &_region_map->getWildcard(); + for (char* tok; (tok = takeToken(&payload)) != nullptr; ) { + if (!processRegionDefSegment(_region_map, tok, &cursor, reply)) return; } _region_map->exportTo(reply, 160); return;