diff --git a/Help/markdown/$datum.md b/Help/markdown/$datum.md new file mode 100644 index 0000000..68cb433 --- /dev/null +++ b/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) diff --git a/Help/markdown/$isfirstzone.md b/Help/markdown/$isfirstzone.md new file mode 100644 index 0000000..65e114b --- /dev/null +++ b/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) diff --git a/Help/markdown/$islastzone.md b/Help/markdown/$islastzone.md new file mode 100644 index 0000000..bd90f39 --- /dev/null +++ b/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) diff --git a/Help/markdown/NLP_PP_Stuff/Special_Variables.md b/Help/markdown/NLP_PP_Stuff/Special_Variables.md index 0e7a8e7..3c5b98b 100644 --- a/Help/markdown/NLP_PP_Stuff/Special_Variables.md +++ b/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. | diff --git a/Help/markdown/index.md b/Help/markdown/index.md index bc0a660..f80453d 100644 --- a/Help/markdown/index.md +++ b/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 diff --git a/Help/markdown/vscode/commandline.md b/Help/markdown/vscode/commandline.md new file mode 100644 index 0000000..017e14f --- /dev/null +++ b/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 [-WORK ] [options] [] +nlp -ANA [-WORK ] [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 `/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 `_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 `_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)  |  +[Compiling Analyzers](compiling.md)  |  +[Special variables](../NLP_PP_Stuff/Special_Variables.md)  |  +[Calling Analyzers from Python & Node.js](packages.md) diff --git a/Help/markdown/vscode/help-tree.json b/Help/markdown/vscode/help-tree.json index 7016234..8588336 100644 --- a/Help/markdown/vscode/help-tree.json +++ b/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": [ diff --git a/Help/markdown/vscode/home.md b/Help/markdown/vscode/home.md index d12c48f..4b3a1d0 100644 --- a/Help/markdown/vscode/home.md +++ b/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 diff --git a/Help/markdown/vscode/largefiles.md b/Help/markdown/vscode/largefiles.md index 1c071c5..147eb12 100644 --- a/Help/markdown/vscode/largefiles.md +++ b/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)  |