130 lines
3.5 KiB
Markdown
130 lines
3.5 KiB
Markdown
# 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.*
|