Merge branch 'feature/replace-nth-match' of https://github.com/daddel80/notepadpp-multireplace into feature/replace-nth-match

Author: daddel80

README.md

@@ -22,6 +22,7 @@ MultiReplace is a Notepad++ plugin that allows users to create, store, and manag
     - [lvars](#lvarsfilepath)
     - [lkp](#lkpkey-hpath-inner)
     - [fmtN](#fmtnnum-maxdecimals-fixeddecimals)
+  - [Preloading Variables](#preloading-variables)
   - [Operators](#operators)
   - [If-Then Logic](#if-then-logic)
   - [DEBUG option](#debug-option)
@@ -174,19 +175,13 @@ Initializes custom variables for use in various commands, extending beyond stand
 
 Custom variables maintain their values throughout a single Replace-All or within a list of multiple Replace operations. Thus, they can transfer values from one list entry to subsequent ones. They reset at the start of each new document in **'Replace All in All Open Documents'**.
 
+> **Tip**: To learn how to preload variables using an empty Find field before the main replacement process starts, see [Preloading Variables](#preloading-variables).
+
 | **Find**        | **Replace**                                                                                                                            | **Before**                                     | **After**                                              | **Regex** | **Scope CSV** | **Description**                                                                                                              |
 |-----------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|--------------------------------------------------------|----------|--------------|------------------------------------------------------------------------------------------------------------------------------|
 | `(\d+)`         | `vars({COL2=0,COL4=0}); cond(LCNT==4, COL2+COL4);`<br>`if COL==2 then COL2=CAP1 end;`<br>`if COL==4 then COL4=CAP1 end;`               | `1,20,text,2,0`<br>`2,30,text,3,0`<br>`3,40,text,4,0` | `1,20,text,2,22.0`<br>`2,30,text,3,33.0`<br>`3,40,text,4,44.0` | Yes      | Yes          | Tracks values from columns 2 and 4, sums them, and updates the result for the 4th match in the current line.                |
 | `\d{2}-[A-Z]{3}`| `vars({MATCH_PREV=''}); cond(LCNT==1,'Moved', MATCH_PREV); MATCH_PREV=MATCH;`                                                           | `12-POV,00-PLC`<br>`65-SUB,00-PLC`<br>`43-VOL,00-PLC`  | `Moved,12-POV`<br>`Moved,65-SUB`<br>`Moved,43-VOL`      | Yes      | No           | Uses `MATCH_PREV` to track the first match in the line and shift it to the 2nd (`LCNT`) match during replacements.           |
 
-An empty Find string (`*(empty)*`) can be used to set variables for the entire Find and Replace list without being tied to a specific Find action. This entry does **not** match any text but is executed once at the beginning of the **'Replace'** or **'Replace All'** process when **'Use List'** is enabled. It allows the Replace field to run initialization commands like `vars()` for the entire operation. This entry is always executed first, regardless of its position in the list.
-
-| **Find**           | **Replace**                                                                                                             | **Description/Expected Output**                                                                                                       |
-|--------------------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| *(empty)*          | `vars({ `<br>`VpersonName = FNAME:sub(1, (FNAME:find(" - ", 1, true) or 0) - 1),`<br>`Vdepartment = FNAME:sub((FNAME:find(" - ", 1, true) or #FNAME + 1) + 3, (FNAME:find(".", 1, true) or 0) - 1) })` | Extracts `VpersonName` and `Vdepartment` from the active document’s filename in the format `<Name> - <Department>.xml` using the `vars` action. Triggered only once at the start of the replace process when **Find** is empty. |
-| `personname`       | `set(VpersonName)`                                                                                                       | Replaces `personname` with the content of the variable `VpersonName`, previously initialized by the `vars` action.                     |
-| `department`       | `set(Vdepartment)`                                                                                                       | Replaces `department` with the content of the variable `Vdepartment`, previously initialized by the `vars` action.                     |
-
 <br>
 
 #### **lvars(filePath)**
@@ -198,10 +193,10 @@ The parameter **filePath** must specify a valid path to a file. Supported path f
 - Forward Slashes: `"C:/path/to/file.vars"`
 - Long Bracket String: `[[C:\path\to\file.vars]]`
 
-**Example File:**
+** File:**
 ```lua
 -- Local variables remain private
-local PATH = [[C:\Data\Projects\Example\]]
+local PATH = [[C:\Data\Projects\\]]
 
 -- Only the returned variables are accessible in Replace operations
 return {
@@ -212,14 +207,15 @@ return {
 }
 ```
 
+> **Tip**: To learn how to preload variables using an empty Find field before the main replacement process starts, see [Preloading Variables](#preloading-variables).
+
 | Find          | Replace                                                                       | Regex | Scope CSV | Description                                                                                          |
 |---------------|-------------------------------------------------------------------------------|-------|-----------|------------------------------------------------------------------------------------------------------|
 | *(empty)*     | `lvars([[C:\tmp\m\Vars.vars]])`                                              | No    | No        | Loads variables such as `userName = "Alice"` and `threshold = 10` from `myVars.vars`.               |
 | `Hello`       | `set(userName)`                                                              | No    | No        | Replaces `Hello` with the value of the variable `userName`, e.g., `"Alice"`.                        |
 | `(\d+)`       | `cond(threshold > 5, "Above", "Below")`                                      | Yes   | No        | Replaces the match based on the condition evaluated using the variable `threshold`.                 |
 
 **Key Points**
-- **Initialization**: An empty Find string (*(empty)*) initializes variables globally at the start of the Replace or Replace All process when "Use List" is enabled. This initialization occurs only once, regardless of its position in the list.
 - **Conditional Loading**: Variables can be loaded conditionally by placing lvars(filePath) alongside a specific Find pattern. In this case, the variables are only initialized when the pattern matches.
 - **Local vs. Returned Variables**: Only variables explicitly included in the return table of the .vars file are available for use. Any local variables remain private to the file.
 
@@ -290,6 +286,24 @@ Formats numbers based on precision (maxDecimals) and whether the number of decim
 
 <br>
 
+### **Preloading Variables**
+MultiReplace supports **predefining or loading variables** before any replacements occur. By separating initialization from the actual replacements, operations stay clean and maintainable.
+
+#### 🔹 **How it works:**
+- **Place `vars()` or `lvars()` next to an empty Find field.**
+- This entry does **not** search for matches but runs before replacements begin.
+- It ensures that **variables are loaded once**, regardless of their position in the list.
+
+**Examples**  
+
+| **Find**    | **Replace**                                                 | **Description** |
+|--------------|------------------------------------------------------------|----------------|
+| *(empty)*   | `vars({prefix = "ID_"})`                                    | Sets `prefix = "ID_"` before replacements. |
+| *(empty)*   | `lvars([[C:\path\to\myVars.vars]])`                         | Loads external variables from a file. |
+| `(\d+)`     | `set(prefix .. CAP1)`                                       | Uses `prefix` from initialization (e.g., `123` → `ID_123`). |
+
+<br>
+
 ### Operators 
 | Type        | Operators                     |
 |-------------|-------------------------------|