Rest Entry Patterns

class MetaNavRestItem(MetaNavItem):
    """
    Handles "..." rest entries with patterns and filters.
    
    Rest entries allow including remaining files/directories with optional
    filtering using glob patterns or regular expressions.
    
    Attributes:
        type (RestType): Type of pattern matching (GLOB, REGEX, ALL)
        pattern (str): Pattern string for filtering
        flat (bool): Whether to flatten nested structure
    
    Args:
        value (str): Rest entry string with optional pattern/flags
    """
    
    def __init__(self, value: str): ...
    
    def matches(self, path: str) -> bool:
        """
        Check if a file path matches this rest item's pattern.
        
        Args:
            path (str, optional): File path to test against pattern
            
        Returns:
            bool: True if path matches the pattern criteria
        """
    
    @staticmethod
    def is_rest(item: Any) -> bool:
        """
        Check if an item represents a rest entry.
        
        Args:
            item (Any): Item to test
            
        Returns:
            bool: True if item is a rest entry string
        """

class RestType(Enum):
    """
    Types of rest pattern matching.
    
    Values:
        GLOB: Glob pattern matching with wildcards
        REGEX: Regular expression pattern matching
        ALL: Include all remaining items (no filtering)
    """
    GLOB = "glob"
    REGEX = "regex"
    ALL = "all"

class RestItemList:
    """
    Container for rest items with pattern and all categories.
    
    Separates pattern-based rest items from catch-all rest items
    and provides ordered iteration for processing.
    """
    
    def __init__(self): ...
    
    def append(self, item: MetaNavRestItem):
        """
        Add a rest item to the collection.
        
        Args:
            item (MetaNavRestItem): Rest item to add
        """
    
    def __iter__(self) -> Iterator[MetaNavRestItem]:
        """
        Iterate over rest items in processing order.
        
        Pattern items are processed first, then catch-all items.
        
        Returns:
            Iterator[MetaNavRestItem]: Rest items in processing order
        """
    
    def __len__(self) -> int:
        """
        Get total number of rest items.
        
        Returns:
            int: Total count of pattern and all rest items
        """

# .pages
nav:
  - introduction.md
  - ...  # Include all remaining files here
  - conclusion.md

# .pages
nav:
  - overview.md
  
  # Glob pattern matching
  - ... | glob=tutorial-*.md  # Files like tutorial-01.md, tutorial-basic.md
  - ... | glob=api/**/*.md    # All markdown files in api/ subdirectories
  
  # Regular expression matching  
  - ... | regex=test.*\.md    # Files matching regex pattern
  - ... | regex=^guide-      # Files starting with "guide-"
  
  # Flattening nested structure
  - ... | flat               # Flatten all remaining items
  - ... | flat | glob=*.md   # Flatten and filter by pattern
  
  # Multiple rest entries
  - ... | glob=beginner-*.md # Beginner tutorials first
  - ... | glob=advanced-*.md # Advanced tutorials second
  - ...                      # Everything else last
  
  - summary.md

# Glob patterns (using wcmatch.glob)
"..." | glob=*.md          # All .md files in current directory
"..." | glob=**/*.py       # All .py files recursively
"..." | glob=test-*.md     # Files starting with "test-"
"..." | glob=**/index.md   # All index.md files anywhere

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

# Flattening behavior
"..." | flat               # Remove directory structure, include files directly
"..." | flat | glob=*.md   # Flatten structure and filter by glob pattern

# All rest entry variations
nav:
  - ...                           # Include all remaining (RestType.ALL)
  - ... | flat                   # Include all, flatten structure  
  - ... | glob=pattern           # Filter with glob pattern (RestType.GLOB)
  - ... | regex=pattern          # Filter with regex (RestType.REGEX)
  - ... | flat | glob=pattern    # Flatten and filter with glob
  - ... | flat | regex=pattern   # Flatten and filter with regex