Command Line help page; $datum, $isfirstzone, $islastzone

Help/markdown/$datum.md

@@ -0,0 +1,50 @@
+[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md)
+
+# $datum
+
+## Purpose
+
+Get the string the caller passed with `nlp -DATUM value`, or with `datum=` from Python or Node.js. Use it to let one analyzer serve several callers: the output format they want, a mode, a customer name.
+
+## Syntax
+
+```
+returnedString = variableType("$datum")
+```
+
+```
+returnedString - type: str
+
+variableType - type: G
+```
+
+## Returns
+
+The string passed with `-DATUM`, or 0 if none was passed.
+
+## Remarks
+
+The value is set for one run (from the command line) or one `analyze()` call (from Python or Node.js); it does not carry over to the next call.
+
+## Example
+
+```
+@CODE
+    if (G("$datum") == "json")
+        G("format") = "json";
+    else
+        G("format") = "text";
+@@CODE
+```
+
+```
+nlp -ANA myanalyzer -WORK C:\nlp-engine -DATUM json input\text.txt
+```
+
+```
+NLPPlus.analyze(text, "myanalyzer", datum="json")
+```
+
+## See Also
+
+[Command Line](vscode/commandline.md), [$dev]($dev.md), [Special Variables](NLP_PP_Stuff/Special_Variables.md#table)

Help/markdown/$isfirstzone.md

@@ -0,0 +1,44 @@
+[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md)
+
+# $isfirstzone
+
+## Purpose
+
+In zone mode, check whether the zone being run is the first one. Use it for per-document setup in a pass that runs once per zone.
+
+## Syntax
+
+```
+returnedBoolean = variableType("$isfirstzone")
+```
+
+```
+returnedBoolean - type: bool
+
+variableType - type: G
+```
+
+## Returns
+
+1 while the first zone runs, else 0. Outside zone mode, and in the passes before the `zone` line or after the `endzone` line, it is 0.
+
+## Remarks
+
+A pass after a `zone` line in `analyzer.seq` runs once per zone, so its `@CODE` runs once per zone too. Code that should run once per document goes before the `zone` line, or is guarded by `$isfirstzone`.
+
+With `nlp -ZONES 40-45` (engine 4.2.50), only those zones run, and `$isfirstzone` is 1 in zone 40, the first zone that runs.
+
+**NEW 4.2.47**
+
+## Example
+
+```
+@CODE
+    if (G("$isfirstzone"))
+        "summary.txt" << "zone\twords\n";
+@@CODE
+```
+
+## See Also
+
+[$islastzone]($islastzone.md), [$isfirstfile]($isfirstfile.md), [Large Files](vscode/largefiles.md), [Special Variables](NLP_PP_Stuff/Special_Variables.md#table)

Help/markdown/$islastzone.md

@@ -0,0 +1,45 @@
+[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md)
+
+# $islastzone
+
+## Purpose
+
+In zone mode, check whether the zone being run is the last one. Use it for wrap-up work in a pass that runs once per zone.
+
+## Syntax
+
+```
+returnedBoolean = variableType("$islastzone")
+```
+
+```
+returnedBoolean - type: bool
+
+variableType - type: G
+```
+
+## Returns
+
+1 while the last zone runs, else 0. Outside zone mode, and in the passes before the `zone` line or after the `endzone` line, it is 0.
+
+## Remarks
+
+For whole-document work, the passes after an `endzone` line are usually the better place: they run once, after the last zone, on the zone nodes and the whole knowledge base. Use `$islastzone` when the wrap-up belongs in the same pass as the per-zone work.
+
+With `nlp -ZONES 40-45` (engine 4.2.50), only those zones run, and `$islastzone` is 1 in zone 45, the last zone that runs.
+
+**NEW 4.2.47**
+
+## Example
+
+```
+@CODE
+    G("zones")++;
+    if (G("$islastzone"))
+        "summary.txt" << G("zones") << " zones\n";
+@@CODE
+```
+
+## See Also
+
+[$isfirstzone]($isfirstzone.md), [$islastfile]($islastfile.md), [Large Files](vscode/largefiles.md), [Special Variables](NLP_PP_Stuff/Special_Variables.md#table)

Help/markdown/NLP_PP_Stuff/Special_Variables.md

@@ -52,9 +52,12 @@ A consolidated table of NLP++ special variables is provided below. Each item in
 | [**$dev**](../$dev.md) | G | Check if the engine was run with **-DEV**. Returns 1 under -DEV, else 0. Use it to gate an analyzer's own diagnostic passes on what the caller asked for. **NEW 3.8.4** |
 | [**$os**](../$os.md) | G | Operating system the engine runs on: `windows`, `linux` or `macos`. **NEW 4.2.15** |
 | [**$silent**](../$silent.md) | G | Check if the engine was run with **-SILENT**. Returns 1 under -SILENT, else 0. Note -SILENT also suppresses the analyzer's own output files. **NEW 3.8.4** |
+| [**$datum**](../$datum.md) | G | The string passed with **-DATUM** (or `datum=` from Python or Node.js), such as the output format the caller wants; 0 if none. |
 | [**$isdirrun**](../$isdirrun.md) | G | Check if the engine is processing a directory of files instead of an individual file. Returns 1 if it is analyzing a directory, else 0. **NEW 1.26.0** |
 | [**$isfirstfile**](../$isfirstfile.md) | G | Check if is first file processed in a directory. Returns 1 if it is the first file, else 0. **NEW 1.24.0** |
 | [**$islastfile**](../$islastfile.md) | G | Check if is last file processed in a directory. Returns 1 if it is the last file, else 0. **NEW 1.24.0** |
+| [**$isfirstzone**](../$isfirstzone.md) | G | In zone mode, 1 while the first zone runs, else 0. **NEW 4.2.47** |
+| [**$islastzone**](../$islastzone.md) | G | In zone mode, 1 while the last zone runs, else 0. **NEW 4.2.47** |
 | [**$allcaps**](../$allcaps.md) [**$uppercase**](../$uppercase.md) | **N** | Check if token underlying node is all uppercase. Returns 1 if token is all uppercase. If multiple words (even if all are all-caps), returns 0. WARN: Not identical to the **uppercase**() PRE Action. |
 | [**$lowercase**](../$lowercase.md) | **N** | Check if token underlying node is all lowercase. Returns 1 if token is all lowercase If multiple words (even if all are all-caps), returns 0. WARN: Not identical to the **lowercase**() PRE Action. |
 | [**$cap**](../$cap.md) | **N** | Check if token underlying node is a capitalized word. Returns 1 if token is a capitalized word. WARN: Not identical to the **cap**() PRE Action. |

Help/markdown/index.md

@@ -96,7 +96,10 @@ to a topic.
         - [$passnum]($passnum.md)
         - [$rulenum]($rulenum.md)
       - **Run Mode Variables**
+        - [$datum]($datum.md)
         - [$dev]($dev.md)
+        - [$isfirstzone]($isfirstzone.md)
+        - [$islastzone]($islastzone.md)
         - [$os]($os.md)
         - [$silent]($silent.md)
       - **Test Variables**
@@ -613,7 +616,7 @@ above. They are grouped here so that every page remains reachable from this inde
 
 ### Run Mode Variables
 
-[$dev]($dev.md)  |  [$os]($os.md)  |  [$silent]($silent.md)
+[$datum]($datum.md)  |  [$dev]($dev.md)  |  [$isfirstzone]($isfirstzone.md)  |  [$islastzone]($islastzone.md)  |  [$os]($os.md)  |  [$silent]($silent.md)
 
 ### Control Flow Keywords
 

Help/markdown/vscode/commandline.md

@@ -0,0 +1,133 @@
+# Command Line
+
+`nlp.exe` (`nlp` on Linux and macOS) runs an analyzer from a terminal, a script or
+CI. VS Code runs it for you; this page is for running it yourself. `nlp --help`
+prints the same list.
+
+[← Back to Help home](home.md)
+
+## Usage
+
+```
+nlp -ANA <analyzer> [-WORK <engine folder>] [options] <input> [<outdir>]
+nlp -ANA <analyzer> [-WORK <engine folder>] [options] -STDIN
+nlp --help | --version
+```
+
+A typical run, from anywhere:
+
+```
+nlp -ANA C:\analyzers\myanalyzer -WORK C:\nlp-engine C:\analyzers\myanalyzer\input\text.txt
+```
+
+Switches are not case-sensitive (`-dev` is `-DEV`). An unknown switch, or a switch
+missing its value, stops the run with a message and exit status 1.
+
+## Running
+
+| Switch | What it does |
+|---|---|
+| `-ANA analyzer` | The analyzer folder: a path, or a name under `<engine folder>/analyzers`. Required. |
+| `-WORK folder` | The **engine folder**, the one holding `data/` and `analyzers/`. Default: the current folder. Point it at the analyzer folder instead and the engine prints "ERROR IN ANALYZER INIT" and runs only the tokenizer. |
+| `-IN input` | The input file, or a folder of them (a folder run). Or give it as the first plain argument. |
+| `-OUT folder` | The folder for this run's logs and trees, in place of `<input>_log`; made if missing (engine 4.2.51). Or give it as the second plain argument. |
+| `-STDIN` | Load the analyzer once, then analyze one input file path per line of standard input; a blank line or the end of input ends the run. See [$isdirrun](../$isdirrun.md). |
+| `-DATUM value` | A string the analyzer reads as [`G("$datum")`](../$datum.md), such as the output format the caller wants. |
+
+Each input's logs and trees go in `<input>_log` next to the input, or in the
+`-OUT` folder. Files the analyzer writes itself (`"out.txt" << ...`) go there too.
+
+## Debugging
+
+| Switch | What it does |
+|---|---|
+| `-DEV` | Write logs and the parse tree after every pass, as `ana001.tree`, `ana002.tree` and so on. Slow on large inputs: about 3.6 times as long on parse-en-us. The analyzer can test it with [`$dev`](../$dev.md). |
+| `-SILENT` | Write no logs or output files, not even the analyzer's own. See [`$silent`](../$silent.md). |
+| `-DEBUG port` | Wait for a rule debugger on `127.0.0.1:port`, then run under it; VS Code attaches this way. See [Version 4: debuggable](announcements/2026-09-27-version-4-debuggable.md). |
+| `-DICTSOURCE` | Nodes built from `.dict` entries get `dictfile` and `dictline` attributes naming the entry's file and line. See [The analyzer sequence](../VisualText_Basics/About_the_analyzer_sequence.md). |
+
+## Limits and zone mode
+
+| Switch | What it does |
+|---|---|
+| `-TIMELIMIT seconds` | Stop an input's analysis that runs longer, at its next while turn or pass; the run then exits 2. |
+| `-ZONES 40-45` | Zone mode: run only these zones. A zone (`7`), a range (`40-45`) or a list (`3,40-45`), counted from 1 as in the `z040-ana###.tree` names; the other zones get only the passes before the `zone` line (engine 4.2.50). See [Large Files](largefiles.md). |
+
+## Compiled analyzers
+
+| Switch | What it does |
+|---|---|
+| `-COMPILE` | Generate C++ for the analyzer and its knowledge base. Does not analyze. |
+| `-COMPILEKB` | Generate C++ for the knowledge base only. |
+| `-COMPILEANA` | Generate C++ for the analyzer only. |
+| `-COMPILED` | Run the compiled analyzer (the `bin/run` and `bin/kb` libraries) instead of its `.nlp` files. |
+| `-INTERP` | Run the analyzer from its `.nlp` files. The default. |
+
+See [Compiling Analyzers](compiling.md) for building the libraries.
+
+## Other
+
+| Switch | What it does |
+|---|---|
+| `--help` | Print the switches and exit. |
+| `--version` | Print the engine version, such as `4.2.51`, and exit. |
+
+## Environment
+
+| Variable | What it does |
+|---|---|
+| `NLP_REC_LIMIT=N` | A region of a `rec` pass may match N times plus N/50 per node before it is stopped; N is 1000 by default, and 0 lifts the limit. See [Large Files](largefiles.md#safety-limits). |
+
+## Exit status
+
+| Status | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | Bad arguments, or a missing analyzer, input or output folder. Before engine 4.2.51 a missing input file exited 0. |
+| 2 | A run stopped at `-TIMELIMIT`. |
+
+The largest input the engine accepts is 2,000,000,000 bytes; a larger one is
+refused with a message.
+
+## Examples
+
+Debug one input:
+
+```
+nlp -ANA myanalyzer -WORK C:\nlp-engine -DEV input\text.txt
+```
+
+Analyze every file of a folder, loading the analyzer once:
+
+```
+nlp -ANA myanalyzer -WORK C:\nlp-engine input
+```
+
+Stream a list of files, in order:
+
+```
+dir /b /s C:\corpus\*.txt | nlp -ANA myanalyzer -WORK C:\nlp-engine -STDIN
+find corpus -name '*.txt' | sort | nlp -ANA myanalyzer -WORK ~/nlp-engine -STDIN
+```
+
+Ask for JSON, and give up after a minute:
+
+```
+nlp -ANA myanalyzer -WORK C:\nlp-engine -DATUM json -TIMELIMIT 60 input\text.txt
+```
+
+Rerun zones 40 to 45 of a large document with full trees, into a folder of their own:
+
+```
+nlp -ANA parse-en-us -WORK C:\nlp-engine -ZONES 40-45 -DEV -OUT C:\debug\z40 book.txt
+```
+
+From Python or Node.js, the same engine runs through the `NLPPlus` and `nlpplus`
+packages; see [Calling Analyzers from Python & Node.js](packages.md).
+
+## See also
+
+[Large Files](largefiles.md) &nbsp;|&nbsp;
+[Compiling Analyzers](compiling.md) &nbsp;|&nbsp;
+[Special variables](../NLP_PP_Stuff/Special_Variables.md) &nbsp;|&nbsp;
+[Calling Analyzers from Python & Node.js](packages.md)

Help/markdown/vscode/help-tree.json

@@ -20,6 +20,7 @@
     { "label": "Compiling Analyzers", "page": "vscode/compiling", "icon": "gear" },
     { "label": "Lazy Loading", "page": "vscode/lazyload", "icon": "symbol-array" },
     { "label": "Large Files", "page": "vscode/largefiles", "icon": "file-binary" },
+    { "label": "Command Line", "page": "vscode/commandline", "icon": "terminal" },
     {
       "label": "NLP++", "icon": "symbol-namespace",
       "children": [

Help/markdown/vscode/home.md

@@ -38,6 +38,7 @@ the logic is human-written code you can read, [test](testing.md), and ship.
 - **[Regression Testing](testing.md)** — set up golden-file regression tests so you catch changes in your analyzer's output.
 - **[Lazy Loading](lazyload.md)** — keep startup fast and memory low by loading knowledge-base data only when it's needed.
 - **[Large Files](largefiles.md)** — analyze large inputs one zone at a time (forms, sections, paragraphs) with zone mode, and keep large dictionaries and KBs fast with lazy loading.
+- **[Command Line](commandline.md)** — every `nlp.exe` switch, the exit codes, and examples for running an analyzer from a terminal, a script or CI.
 
 ## What's new — Version Notes
 

Help/markdown/vscode/largefiles.md

@@ -321,6 +321,7 @@ covers this in full; in short:
 ## See also
 
 [Lazy Loading](lazyload.md)  | 
+[Command Line](commandline.md)  | 
 [The analyzer sequence](../VisualText_Basics/About_the_analyzer_sequence.md)  | 
 [Special variables](../NLP_PP_Stuff/Special_Variables.md)  | 
 [$isfirstfile](../$isfirstfile.md)  |  [$islastfile](../$islastfile.md)  |