Merge pull request #17 from ECP-Solutions/spread_and_rest_operators_support

## Summary
ASF v2.0.8 introduces modern JavaScript-style spread/rest operators (`...`) and array destructuring assignments, significantly enhancing array manipulation capabilities and function parameter handling.

---

## Highlights

- **Added**
    - Spread/rest operator (`...`) support:
```javascript
        // Spread in array literals
        arr1 = [1, 2, 3];
        arr2 = [0, ...arr1, 4, 5]; // => [0, 1, 2, 3, 4, 5]
        
        // Spread in function calls
        fun add(a, b, c) { return a + b + c; };
        numbers = [1, 2, 3];
        result = add(...numbers); // => 6
        
        // Rest parameters in functions
        fun sum(first, ...rest) {
            total = first;
            rest.forEach(fun(n) { total = total + n });
            return total;
        };
        sum(1, 2, 3, 4, 5); // => 15
        
        // Spread strings into character arrays
        chars = [...'hello']; // => ['h', 'e', 'l', 'l', 'o']
```
    
    - Array destructuring assignments:
```javascript
        // Basic destructuring
        [a, b, c] = [1, 2, 3]; // a=1, b=2, c=3
        
        // With rest element
        [first, ...rest] = [1, 2, 3, 4, 5];
        // first=1, rest=[2, 3, 4, 5]
        
        // Fewer targets than elements
        [x, y] = [10, 20, 30, 40]; // x=10, y=20
        
        // More targets than elements (assigns Empty)
        [p, q, r] = [100, 200]; // p=100, q=200, r=Empty
        
        // Practical use cases
        [a, b] = [b, a]; // Swap variables
        [head, ...tail] = myArray; // Extract head and tail
        
        // Combine spread and destructuring
        arr1 = [1, 2];
        arr2 = [3, 4];
        [first, ...combined] = [...arr1, ...arr2];
        // first=1, combined=[2, 3, 4]
```

- **Internal core changes**:
    - **Parser** (`ASF_Parser.cls`):
        - Added tokenization for `...` spread/rest operator
        - New token type: `"SPREAD"` with value `"..."`
        
    - **Compiler** (`ASF_Compiler.cls`):
        - Added `IsSpreadToken()` helper function for spread operator detection
        - Rest parameter support in function and method definitions
        - Spread operator handling in array literal compilation (`ParseArrayLiteral`)
        - Spread operator support in function call argument processing
        - Array destructuring pattern detection in `ParseStatementTokensToAST`
        - New AST node type: `"ArrayDestructuring"` with targets collection and optional rest target
        - Compile-time validation:
            - Rest parameter must be last in function signatures
            - Only one rest parameter allowed per function
            - Rest element must be last in destructuring patterns
            - Multiple rest elements not allowed in destructuring patterns
        
    - **VM** (`ASF_VM.cls`):
        - Spread operator evaluation in `EvalArrayNode` with type handling
        - Array expansion for arrays, strings, and scalar values
        - Spread operator support in function call argument expansion
        - Rest parameter handling in function calls with automatic array creation
        - New `"ArrayDestructuring"` case handler in `ExecuteStmtNode`

- **Technical Details**:
    - **Spread/Rest Token Structure**:
```
        Token: ["SPREAD", "..."]
```
    
    - **Rest Parameter AST**:
```
        Function/Method node {
          params: Collection of parameter names
          restParam: String (optional)
          ...
        }
```
    
    - **Array Destructuring AST**:
```
        ArrayDestructuring {
          targets: Collection of Variable nodes
          restTarget: String (optional)
          source: Expression node
        }
```
    
    - **Error Messages**:
        - `"Rest parameter must be last parameter"` - Rest parameter not in final position
        - `"Multiple rest parameters not allowed"` - More than one rest parameter in function
        - `"Rest element must be last in destructuring"` - Rest element not in final position
        - `"Multiple rest elements in destructuring"` - More than one rest element in pattern
        - `"Expected identifier after ... in destructuring"` - Invalid rest syntax
        - `"Cannot destructure non-array value"` - Runtime type validation failure

---

**Full Changelog**: v2.0.7...v2.0.8

Author: ws-garcia

CHANGELOG.md

@@ -2,8 +2,129 @@
 
 All notable changes for ASF. This file combines the release notes from the project's releases.
 
+## [v2.0.8] - 2026-02-01
+https://github.com/ECP-Solutions/ASF/releases/tag/v2.0.8
+
+## Summary
+ASF v2.0.8 introduces modern JavaScript-style spread/rest operators (`...`) and array destructuring assignments, significantly enhancing array manipulation capabilities and function parameter handling.
+
+---
+
+## Highlights
+
+- **Added**
+    - Spread/rest operator (`...`) support:
+```javascript
+        // Spread in array literals
+        arr1 = [1, 2, 3];
+        arr2 = [0, ...arr1, 4, 5]; // => [0, 1, 2, 3, 4, 5]
+        
+        // Spread in function calls
+        fun add(a, b, c) { return a + b + c; };
+        numbers = [1, 2, 3];
+        result = add(...numbers); // => 6
+        
+        // Rest parameters in functions
+        fun sum(first, ...rest) {
+            total = first;
+            rest.forEach(fun(n) { total = total + n });
+            return total;
+        };
+        sum(1, 2, 3, 4, 5); // => 15
+        
+        // Spread strings into character arrays
+        chars = [...'hello']; // => ['h', 'e', 'l', 'l', 'o']
+```
+    
+    - Array destructuring assignments:
+```javascript
+        // Basic destructuring
+        [a, b, c] = [1, 2, 3]; // a=1, b=2, c=3
+        
+        // With rest element
+        [first, ...rest] = [1, 2, 3, 4, 5];
+        // first=1, rest=[2, 3, 4, 5]
+        
+        // Fewer targets than elements
+        [x, y] = [10, 20, 30, 40]; // x=10, y=20
+        
+        // More targets than elements (assigns Empty)
+        [p, q, r] = [100, 200]; // p=100, q=200, r=Empty
+        
+        // Practical use cases
+        [a, b] = [b, a]; // Swap variables
+        [head, ...tail] = myArray; // Extract head and tail
+        
+        // Combine spread and destructuring
+        arr1 = [1, 2];
+        arr2 = [3, 4];
+        [first, ...combined] = [...arr1, ...arr2];
+        // first=1, combined=[2, 3, 4]
+```
+
+- **Internal core changes**:
+    - **Parser** (`ASF_Parser.cls`):
+        - Added tokenization for `...` spread/rest operator
+        - New token type: `"SPREAD"` with value `"..."`
+        
+    - **Compiler** (`ASF_Compiler.cls`):
+        - Added `IsSpreadToken()` helper function for spread operator detection
+        - Rest parameter support in function and method definitions
+        - Spread operator handling in array literal compilation (`ParseArrayLiteral`)
+        - Spread operator support in function call argument processing
+        - Array destructuring pattern detection in `ParseStatementTokensToAST`
+        - New AST node type: `"ArrayDestructuring"` with targets collection and optional rest target
+        - Compile-time validation:
+            - Rest parameter must be last in function signatures
+            - Only one rest parameter allowed per function
+            - Rest element must be last in destructuring patterns
+            - Multiple rest elements not allowed in destructuring patterns
+        
+    - **VM** (`ASF_VM.cls`):
+        - Spread operator evaluation in `EvalArrayNode` with type handling
+        - Array expansion for arrays, strings, and scalar values
+        - Spread operator support in function call argument expansion
+        - Rest parameter handling in function calls with automatic array creation
+        - New `"ArrayDestructuring"` case handler in `ExecuteStmtNode`
+
+- **Technical Details**:
+    - **Spread/Rest Token Structure**:
+```
+        Token: ["SPREAD", "..."]
+```
+    
+    - **Rest Parameter AST**:
+```
+        Function/Method node {
+          params: Collection of parameter names
+          restParam: String (optional)
+          ...
+        }
+```
+    
+    - **Array Destructuring AST**:
+```
+        ArrayDestructuring {
+          targets: Collection of Variable nodes
+          restTarget: String (optional)
+          source: Expression node
+        }
+```
+    
+    - **Error Messages**:
+        - `"Rest parameter must be last parameter"` - Rest parameter not in final position
+        - `"Multiple rest parameters not allowed"` - More than one rest parameter in function
+        - `"Rest element must be last in destructuring"` - Rest element not in final position
+        - `"Multiple rest elements in destructuring"` - More than one rest element in pattern
+        - `"Expected identifier after ... in destructuring"` - Invalid rest syntax
+        - `"Cannot destructure non-array value"` - Runtime type validation failure
+
+---
+
+**Full Changelog**: https://github.com/ECP-Solutions/ASF/compare/v2.0.7...v2.0.8
+
 ## [v2.0.7] - 2026-01-28
-https://github.com/ECP-Solutions/ASF/releases/tag/v2.0.6
+https://github.com/ECP-Solutions/ASF/releases/tag/v2.0.7
 
 ## Summary
 

README.md

@@ -69,7 +69,7 @@ Debug.Print engine.OUTPUT_  ' => 12
 | Feature | Native VBA | ASF |
 |---------|-----------|-----|
 | **Array filtering** | Manual loops with counters | `.filter(fun(x) { return x > 10 })` |
-| **Data transformation** | ReDim + index juggling | `.map(fun(x) { return x * 2 })` |
+| **Data transformation** | ReDim + index juggling | `.map(fun(x) { return x * 2 })`. Array destructuring with rest operator support `[first, second, ...rest] = [1, 2, 3, 4, 5]`|
 | **Regex support** | COM + error-prone patterns | Built-in regex engine with lookarounds |
 | **JSON handling** | Parse character-by-character | Object/array literals: `{a: 1, b: [2, 3]}` |
 | **Classes & inheritance** | ❌ Not inheritance support | Full OOP with `extends` and `super` |
@@ -422,6 +422,38 @@ let activeNames = data.users
 print(activeNames);  // => 'Alice, Charlie'
 ```
 
+#### 6. Spread/rest operator support
+
+```js
+//rest argument
+fun greetAll(greeting, ...names) {
+    result = greeting + ': ';
+    for (name of names) {
+        result = result + name + ', ';
+    };
+    return result.slice(0, -2);
+};
+msg = greetAll('Hello', 'Alice', 'Bob', 'Charlie');
+return msg //=> Hello: Alice, Bob, Charlie
+```
+
+```js
+//spread operator on arrays
+begin = [1]; middle = [2, 3, 4]; end = [5]; combined = [...begin, ...middle, ...end]; 
+print(combined); //=> [ 1, 2, 3, 4, 5 ]
+
+//spread operator on objects
+obj1 = {a: 1, b: 2}; obj2 = {c: 3, ...obj1, d: 4};
+return `${obj2.a}; ${obj2.b}; ${obj2.c}; ${obj2.d}` //=> 1; 2; 3; 4
+```
+
+#### 7. Array destructuring
+
+```js
+[first, second, ...rest] = [1, 2, 3, 4, 5];
+return `${rest}` //=> [ 3, 4, 5 ]
+```
+
 ---
 
 ## Performance & Benchmarks
@@ -812,7 +844,7 @@ When reporting issues, please include:
 
 ## Running the Test Suite
 
-1. Open `ASF v2.0.2.xlsm` workbook
+1. Open `ASF [VERSION NAME].xlsm` workbook
 2. Install [Rubberduck VBA](https://rubberduckvba.com/)
 3. In Rubberduck, navigate to the test explorer
 4. Run all tests - they should pass ✅
@@ -824,6 +856,7 @@ The test suite covers:
 - Arrays & objects (literals, methods, chaining)
 - Classes & inheritance
 - String manipulation
+- Spread/rest operator
 - Regex engine
 - VBA integration
 - Error handling

docs/API.md

@@ -8,7 +8,7 @@ description: "ASF Public API."
 
 # ASF — API Reference
 
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/ECP-Solutions/ASF?style=plastic)](https://github.com/ECP-Solutions/ASF/releases/latest) [![Tests](https://img.shields.io/badge/tests-290%2B-green.svg)](.)  
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/ECP-Solutions/ASF?style=plastic)](https://github.com/ECP-Solutions/ASF/releases/latest) [![Tests](https://img.shields.io/badge/tests-373%2B-green.svg)](.)  
 
 This document describes the runtime API exposed by ASF scripts and the VM builtins/methods available to scripts. It summarizes semantics, signatures, error behavior, and examples.
 

docs/Language reference.md

@@ -395,12 +395,37 @@ let grade = (score >= 90) ? 'A' :
             (score >= 70) ? 'C' : 'F';
 ```
 
+### Spread/rest Operator
+
+```js
+//rest argument
+fun greetAll(greeting, ...names) {
+    result = greeting + ': ';
+    for (name of names) {
+        result = result + name + ', ';
+    };
+    return result.slice(0, -2);
+};
+msg = greetAll('Hello', 'Alice', 'Bob', 'Charlie');
+return msg //=> Hello: Alice, Bob, Charlie
+```
+
+```js
+//spread operator on arrays
+begin = [1]; middle = [2, 3, 4]; end = [5]; combined = [...begin, ...middle, ...end]; 
+print(combined); //=> [ 1, 2, 3, 4, 5 ]
+
+//spread operator on objects
+obj1 = {a: 1, b: 2}; obj2 = {c: 3, ...obj1, d: 4};
+return `${obj2.a}; ${obj2.b}; ${obj2.c}; ${obj2.d}` //=> 1; 2; 3; 4
+```
+
 ### Operator Precedence
 
 From highest to lowest:
 
 1. Parentheses `( )`
-2. Unary `!`, `-`, `typeof`
+2. Unary `!`, `-`, `typeof`, `...`
 3. Exponentiation `^`
 4. Multiplication/Division `*`, `/`, `%`
 5. Addition/Subtraction `+`, `-`
@@ -2907,8 +2932,6 @@ The following words are reserved and cannot be used as variable names:
 
 - No `async/await` support
 - No `Promise` or callback patterns
-- No spread operator (`...`)
-- No destructuring assignment
 - No arrow functions (`=>`)
 - No `const` declaration (use `let`)
 - No `var` (use `let`)

docs/Syntax.md

@@ -8,7 +8,7 @@ description: "ASF syntax."
 
 # ASF — Syntax Reference
 
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/ECP-Solutions/ASF?style=plastic)](https://github.com/ECP-Solutions/ASF/releases/latest) [![Tests](https://img.shields.io/badge/tests-290%2B-green.svg)](.)  
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/ECP-Solutions/ASF?style=plastic)](https://github.com/ECP-Solutions/ASF/releases/latest) [![Tests](https://img.shields.io/badge/tests-373%2B-green.svg)](.)  
 
 This document defines the concrete syntax supported by the Advanced Scripting Framework (ASF) and contains a compact BNF grammar, operator precedence, and examples.