# Real-World ShellSpec Patterns Analysis

Based on analysis of 24 official ShellSpec example files from test/spec/, this document captures the comprehensive patterns discovered and how they've been integrated into the grammar.

## Key Findings from Official Examples

### 1. Hook Statement Patterns

**Discovery**: ShellSpec uses both block-style hooks (with End) and statement-style hooks (without End)

**Statement-style hooks** (newly supported):

- `Before 'setup'` - Single function call
- `Before 'setup1' 'setup2'` - Multiple function calls
- `After 'cleanup'` - Cleanup functions
- `Before 'value=10'` - Inline code execution

**Grammar Implementation**: Added `shellspec_hook_statement` rule to handle Before/After statements without End blocks.

### 2. Directive Patterns

**Discovery**: ShellSpec has several directive-style statements that don't follow the typical block structure

**Include directive**:

- `Include ./lib.sh` - Include external scripts
- `Include ./support/custom_matcher.sh`

**Conditional Skip**:

- `Skip if "reason" condition` - Skip with conditions
- `Skip if 'function returns "skip"' [ "$(conditions)" = "skip" ]` - Complex conditions

**Grammar Implementation**: Added `shellspec_directive_statement` rule for Include and conditional Skip patterns.

### 3. Data Block Complexity (Future Enhancement)

**Discovery**: Data blocks have sophisticated syntax not yet fully supported:

- `Data:raw` and `Data:expand` modifiers for variable expansion control
- `Data | filter` syntax for piping data through filters
- `#|content` line prefix syntax for multi-line data
- Function-based data: `Data function_name`
- String-based data: `Data 'string content'`

**Current Status**: Basic Data blocks work as utility blocks, but advanced syntax requires future enhancement.

### 4. Top-Level Examples

**Discovery**: ShellSpec allows It/Example/Specify blocks at the top level without requiring Describe/Context wrapping.

**Pattern**:

```shellspec
It 'is simple'
  When call echo 'ok'
  The output should eq 'ok'
End
```

**Grammar Implementation**: Already supported through existing `shellspec_it_block` rule.

### 5. Complex Nesting and Context Switching

**Discovery**: Real-world examples show sophisticated nesting:

- Describe > Context > It hierarchies
- Mixed hook scoping (hooks defined at different nesting levels)
- Before/After hooks with multiple arguments for setup chains
- Comments and shellcheck directives intermixed

## Grammar Enhancements Made

### New Rules Added

1. `shellspec_hook_statement` - For Before/After without End
2. `shellspec_directive_statement` - For Include and conditional Skip
3. Enhanced conflicts array to handle new statement types

### Test Coverage Added

- 63 total tests (as of 2025-12-11; originally 59, up from 53)
- New `real_world_patterns.txt` test file
- 6 additional tests covering hook statements, directives, and complex patterns
- 4 additional tests for Data block modifiers (added 2025-12-11)

## Integration Status

✅ **Fully Integrated**:

- Hook statements (Before/After without End)
- Include directive
- Conditional Skip statements
- Top-level It blocks

⚠️ **Partially Supported**:

- Data blocks (basic functionality works, advanced syntax needs work)
- Complex conditional expressions in Skip

🔄 **Future Enhancements Needed**:

- Data block modifiers (:raw, :expand)
- Data block filters (| syntax)
- Data block #| line syntax
- More sophisticated conditional parsing for Skip

## Real-World Usage Patterns Observed

1. **Hook Chains**: Multiple Before/After hooks for complex setup/teardown
2. **Conditional Logic**: Heavy use of conditional Skip statements
3. **External Dependencies**: Frequent use of Include for modular test organization
4. **Mixed Context**: ShellSpec blocks mixed with regular bash functions and variables
5. **Assertion Patterns**: Consistent use of When/The assertion syntax
6. **Descriptive Strings**: Heavy use of descriptive string literals for test names

## Grammar Statistics

- **Block types**: 5 (Describe, Context, It, Hook, Utility)
- **Statement types**: 2 (Hook statements, Directives)
- **Keywords supported**: 25+ ShellSpec keywords
- **Test coverage**: 100% (63/63 tests passing as of 2025-12-11)
- **Conflict warnings**: 5 (optimized from 13, all necessary)

## Recommendations for Future Development

1. **Priority 1**: Implement advanced Data block syntax for better real-world compatibility
2. **Priority 2**: Enhance conditional Skip parsing to handle complex bash expressions
3. **Priority 3**: Optimize conflict declarations to reduce parser warnings
4. **Priority 4**: Add support for ShellSpec assertion syntax (When/The statements)