initial: nsParser plugin 1.0.1

2026-04-29 23:20:16 +02:00
commit 63ae7540e0
29 changed files with 3022 additions and 0 deletions
@@ -0,0 +1,129 @@
+# nsParser NSIS Plugin
+
+Native C plugin for NSIS to extract values from large files, bypassing the NSIS_MAX_STRLEN limit (1 KB).
+
+---
+
+## Problem Solved
+
+NSIS's built-in string functions are limited to `NSIS_MAX_STRLEN` (typically 1024 bytes). When reading configuration files, JSON, or INI files larger than this limit, the string is silently truncated.
+
+`nsParser` solves this by reading only the specific value requested, without loading the entire file into a string.
+
+---
+
+## Build
+
+### Prerequisites
+
+- **Visual Studio 2022** (with "Desktop development with C++" workload)
+- **Python 3.x**
+
+### Build script
+
+```powershell
+python build_plugin.py
+```
+
+### Build options
+
+```powershell
+python build_plugin.py --configs x86-unicode      # Single architecture (x86-ansi|x86-unicode|x64-unicode|all)
+python build_plugin.py --vs-version 2026          # Specific toolset (auto|2022|2026)
+python build_plugin.py --clean                    # Clean dist/ before build
+python build_plugin.py --rebuild                  # Force full rebuild
+python build_plugin.py --verbosity detailed       # Extended MSBuild output
+python build_plugin.py --install-dir "C:\NSIS\Plugins"  # Copy to additional NSIS directory
+python build_plugin.py --list                     # List available configurations
+```
+
+---
+
+## Usage in NSIS
+
+```nsis
+!addplugindir "plugins\x86-unicode"
+
+Section
+  nsParser::Extract "C:\config.ini" "key" $0
+  DetailPrint "Value: $0"
+SectionEnd
+```
+
+---
+
+## API
+
+### `nsParser::Extract`
+
+```nsis
+nsParser::Extract "FilePath" "Key" $OutputVar
+```
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `FilePath` | Full path to the file to parse |
+| `Key`      | Key to search for (e.g. `version`, `path`) |
+| `$OutputVar` | Variable to receive the extracted value |
+
+**Search logic:**
+
+The plugin searches for the pattern `Key=Value` or `Key = Value` in the file. If found, returns the value trimmed of leading/trailing whitespace. If not found, returns an empty string.
+
+**Buffer:**
+
+The value is extracted with a buffer of 32768 bytes, well beyond the NSIS_MAX_STRLEN limit. This allows reading long paths and embedded JSON strings.
+
+---
+
+## Advantages
+
+- No dependency on the NSIS string size limit
+- Reads only the requested value (efficient on large files)
+- Handles `key=value` and `key = value` formats
+- Thread-safe (no global state)
+- Small binary size
+
+---
+
+## Technical Implementation
+
+The plugin is written in C and uses a direct file reader via `ReadFile` (Win32). The algorithm:
+
+1. Opens the file with `CreateFile` (read-only, shared)
+2. Reads the file in 8192-byte blocks
+3. Scans each block for the pattern `Key=` or `Key =`
+4. Extracts the value up to the first newline (`\n` or `\r\n`)
+5. Trims leading/trailing whitespace
+6. Returns the result via the NSIS stack
+
+### Visual Studio configurations
+
+| Configuration | Architecture | Output |
+|---------------|--------------|--------|
+| Release-x86-ansi | x86 ANSI | `plugins/x86-ansi/nsParser.dll` |
+| Release-x86-unicode | x86 Unicode | `plugins/x86-unicode/nsParser.dll` |
+| Release-amd64-unicode | x64 Unicode | `plugins/amd64-unicode/nsParser.dll` |
+
+---
+
+## File Structure
+
+```
+nsParser/
+ build_plugin.py          # Unified build script
+ src/
+    nsParser.c           # Plugin source code
+    nsParser.vcxproj     # VS2022 project (x86-ansi, x86-unicode, amd64-unicode)
+    nsParser.sln         # VS2022 solution
+ dist/
+     x86-ansi/
+     x86-unicode/
+     amd64-unicode/
+```
+
+---
+
+*See [README_IT.md](README_IT.md) for the Italian version.*