0
# Rest Entry Patterns
1

2
Pattern matching system for "..." rest entries in navigation configurations. Rest entries provide powerful filtering and inclusion capabilities, supporting glob patterns, regular expressions, and structural flattening options for flexible navigation control.
3

4
## Capabilities
5

6
### Rest Item Classes
7

8
Core classes that handle rest entry parsing, pattern matching, and filtering logic.
9

10
```python { .api }
11
class MetaNavRestItem(MetaNavItem):
12
    """
13
    Handles "..." rest entries with patterns and filters.
14
    
15
    Rest entries allow including remaining files/directories with optional
16
    filtering using glob patterns or regular expressions.
17
    
18
    Attributes:
19
        type (RestType): Type of pattern matching (GLOB, REGEX, ALL)
20
        pattern (str): Pattern string for filtering
21
        flat (bool): Whether to flatten nested structure
22
    
23
    Args:
24
        value (str): Rest entry string with optional pattern/flags
25
    """
26
    
27
    def __init__(self, value: str): ...
28
    
29
    def matches(self, path: str) -> bool:
30
        """
31
        Check if a file path matches this rest item's pattern.
32
        
33
        Args:
34
            path (str, optional): File path to test against pattern
35
            
36
        Returns:
37
            bool: True if path matches the pattern criteria
38
        """
39
    
40
    @staticmethod
41
    def is_rest(item: Any) -> bool:
42
        """
43
        Check if an item represents a rest entry.
44
        
45
        Args:
46
            item (Any): Item to test
47
            
48
        Returns:
49
            bool: True if item is a rest entry string
50
        """
51

52
class RestType(Enum):
53
    """
54
    Types of rest pattern matching.
55
    
56
    Values:
57
        GLOB: Glob pattern matching with wildcards
58
        REGEX: Regular expression pattern matching
59
        ALL: Include all remaining items (no filtering)
60
    """
61
    GLOB = "glob"
62
    REGEX = "regex"
63
    ALL = "all"
64
```
65

66
### Rest Item Collection
67

68
Container class for managing multiple rest entries with different pattern types and processing order.
69

70
```python { .api }
71
class RestItemList:
72
    """
73
    Container for rest items with pattern and all categories.
74
    
75
    Separates pattern-based rest items from catch-all rest items
76
    and provides ordered iteration for processing.
77
    """
78
    
79
    def __init__(self): ...
80
    
81
    def append(self, item: MetaNavRestItem):
82
        """
83
        Add a rest item to the collection.
84
        
85
        Args:
86
            item (MetaNavRestItem): Rest item to add
87
        """
88
    
89
    def __iter__(self) -> Iterator[MetaNavRestItem]:
90
        """
91
        Iterate over rest items in processing order.
92
        
93
        Pattern items are processed first, then catch-all items.
94
        
95
        Returns:
96
            Iterator[MetaNavRestItem]: Rest items in processing order
97
        """
98
    
99
    def __len__(self) -> int:
100
        """
101
        Get total number of rest items.
102
        
103
        Returns:
104
            int: Total count of pattern and all rest items
105
        """
106
```
107

108
### Usage Examples
109

110
Basic rest entry usage:
111

112
```yaml
113
# .pages
114
nav:
115
  - introduction.md
116
  - ...  # Include all remaining files here
117
  - conclusion.md
118
```
119

120
Advanced rest entries with patterns:
121

122
```yaml
123
# .pages
124
nav:
125
  - overview.md
126
  
127
  # Glob pattern matching
128
  - ... | glob=tutorial-*.md  # Files like tutorial-01.md, tutorial-basic.md
129
  - ... | glob=api/**/*.md    # All markdown files in api/ subdirectories
130
  
131
  # Regular expression matching  
132
  - ... | regex=test.*\.md    # Files matching regex pattern
133
  - ... | regex=^guide-      # Files starting with "guide-"
134
  
135
  # Flattening nested structure
136
  - ... | flat               # Flatten all remaining items
137
  - ... | flat | glob=*.md   # Flatten and filter by pattern
138
  
139
  # Multiple rest entries
140
  - ... | glob=beginner-*.md # Beginner tutorials first
141
  - ... | glob=advanced-*.md # Advanced tutorials second
142
  - ...                      # Everything else last
143
  
144
  - summary.md
145
```
146

147
Pattern matching examples:
148

149
```python
150
# Glob patterns (using wcmatch.glob)
151
"..." | glob=*.md          # All .md files in current directory
152
"..." | glob=**/*.py       # All .py files recursively
153
"..." | glob=test-*.md     # Files starting with "test-"
154
"..." | glob=**/index.md   # All index.md files anywhere
155

156
# Regular expressions (using re.search)
157
"..." | regex=test.*\.md   # Files matching regex
158
"..." | regex=^api-        # Files starting with "api-" 
159
"..." | regex=v\d+\.md$    # Files like v1.md, v2.md, etc.
160

161
# Flattening behavior
162
"..." | flat               # Remove directory structure, include files directly
163
"..." | flat | glob=*.md   # Flatten structure and filter by glob pattern
164
```
165

166
Rest entry syntax patterns:
167

168
```yaml
169
# All rest entry variations
170
nav:
171
  - ...                           # Include all remaining (RestType.ALL)
172
  - ... | flat                   # Include all, flatten structure  
173
  - ... | glob=pattern           # Filter with glob pattern (RestType.GLOB)
174
  - ... | regex=pattern          # Filter with regex (RestType.REGEX)
175
  - ... | flat | glob=pattern    # Flatten and filter with glob
176
  - ... | flat | regex=pattern   # Flatten and filter with regex
177
```
178

179
## Pattern Matching Details
180

181
### Glob Pattern Support
182
Uses the `wcmatch` library with `GLOBSTAR` flag support:
183
- `*` matches any characters except path separators
184
- `**` matches any characters including path separators (recursive)
185
- `?` matches any single character except path separators
186
- `[...]` matches any character in brackets
187
- `{a,b}` matches either `a` or `b` (brace expansion)
188

189
### Regular Expression Support
190
Uses Python's `re.search()` with `PurePath.as_posix()` normalized paths:
191
- Full regex syntax support
192
- Path separators normalized to forward slashes
193
- Case-sensitive matching (use `(?i)` flag for case-insensitive)
194
- Matches anywhere in the path (not anchored by default)
195

196
### Flattening Behavior
197
The `flat` flag affects how nested directory structures are handled:
198
- **Without flat**: Maintains directory hierarchy in navigation
199
- **With flat**: Extracts files from subdirectories and includes them directly
200
- **Flat + patterns**: Apply pattern matching to flattened file list
201

202
## Processing Order
203

204
Rest entries are processed in a specific order to ensure predictable results:
205

206
1. **Pattern-based rest entries** (GLOB and REGEX types) are processed first
207
2. **Catch-all rest entries** (ALL type) are processed last
208
3. **Within each type**, rest entries are processed in the order they appear
209
4. **Files can only match one rest entry** - first match wins
210
5. **Remaining unmatched files** are handled by catch-all entries
211

212
This ordering allows for sophisticated filtering pipelines where specific patterns capture targeted files before general catch-all entries process the remainder.