# Wasot Selector Capabilities

## Overview

The Wasot selector system provides CSS-like querying capabilities for Wasot documents. This document outlines what is currently implemented and functional in the selector system.

## Currently Supported Selectors

### 1. Type Selectors

Select blocks by their type name.

**Syntax**: `blocktype`

**Examples**:

- `paragraph` - Selects all paragraph blocks
- `section` - Selects all section blocks  
- `document` - Selects document blocks
- `quote` - Selects quote blocks
- `#` - Selects heading blocks (# is the type name for headings)

**Usage**:

```bash
# Select all paragraphs in a document
wasot select examples/demo.wasot -s "paragraph"

# Select all sections
wasot select examples/demo.wasot -s "section"
```

### 2. Descendant Combinator

Select blocks that are descendants of other blocks.

**Syntax**: `ancestor descendant` (space-separated)

**Examples**:

- `section paragraph` - Selects paragraphs inside sections
- `document section` - Selects sections inside documents
- `quote paragraph` - Selects paragraphs inside quotes

**Usage**:

```bash
# Select paragraphs that are inside sections
wasot select examples/demo.wasot -s "section paragraph"

# Select any block type that's inside a document
wasot select examples/demo.wasot -s "document quote"
```

### 3. Multiple Selectors

Apply multiple independent selectors to the same document.

**Syntax**: Multiple `-s` flags

**Examples**:

```bash
# Select both documents AND quotes (union)
wasot select examples/demo.wasot -s "document" -s "quote"

# Select paragraphs in sections AND standalone quotes
wasot select examples/demo.wasot -s "section paragraph" -s "quote"
```

## Architecture

### AST Structure

The selector parser creates an Abstract Syntax Tree with these core types:

- **`Selector`**: Top-level selector type (Simple, Compound, or Group)
- **`SimpleSelector`**: Basic type selector (e.g., `paragraph`)
- **`CompoundSelector`**: Selector with combinators (e.g., `section paragraph`)
- **`Combinator`**: Currently only `Descendant` (space)

### Event Processing

- Uses streaming event processing - no need to load entire document into memory
- Maintains a block stack to track document hierarchy
- Matches selectors against the event stream as blocks start/finish
- Only outputs complete matched blocks

### Grammar

Uses Pest parser generator with grammar defined in `src/selectors/selectors.pest`:

```pest
selector = { SOI ~ compound_selector ~ EOI }
compound_selector = { simple_selector ~ (combinator_part)* }
simple_selector = { type_selector }
type_selector = { identifier }
combinator_part = { descendant_combinator ~ simple_selector }
descendant_combinator = { WHITESPACE+ }
identifier = @{ (ASCII_ALPHANUMERIC | "_" | "#")+ }
```

## Example Output

Given a Wasot file:

```wasot
.document
.section
..paragraph
This is inside a section
..paragraph  
Another paragraph in section
.quote
..paragraph
This is in a quote
```

**Command**: `wasot select file.wasot -s "section paragraph"`

**Output**:

```wasot
..paragraph
This is inside a section
./

..paragraph
Another paragraph in section
./
```

## Limitations

### Not Yet Implemented

1. **Attribute Selectors**: `[key=value]`, `[key]`
2. **ID Selectors**: `#123` (for Wasot block IDs)
3. **Class Selectors**: `.className` (would map to Wasot arguments)
4. **Child Combinator**: `>` (direct children only)
5. **Sibling Combinators**: `~` (general sibling), `+` (adjacent sibling)
6. **Pseudo-selectors**: `:first-child`, `:last-child`, `:nth-child()`
7. **Pseudo-classes**: `:empty`, `:has()`, `:not()`

### Known Constraints

1. **Type names only**: Currently limited to block type matching
2. **No argument matching**: Cannot select based on block arguments or keyword arguments
3. **No ID matching**: Cannot select blocks by their Wasot IDs (`:123`)
4. **Case sensitive**: Type names must match exactly
5. **Descendant only**: Only supports descendant relationship, not direct child

## Performance Characteristics

- **Memory efficient**: Streaming processing with bounded memory usage
- **Linear time**: O(n) where n is the number of events in the document
- **State tracking**: Maintains block stack proportional to document nesting depth
- **Thread safe**: Can be used in concurrent environments

## Integration Points

### CLI Integration

```bash
wasot select <file> -s "<selector>" [-s "<selector2>"]...
```

### API Integration

```rust
use wasot::selectors::{parse_selector, ast::Selector};
use wasot::consumers::SelectorConsumer;

// Parse selector string to AST
let selector = parse_selector("section paragraph")?;

// Use with event stream
let consumer = SelectorConsumer::new(selectors, output);
// ... process events through consumer
```

## Future Roadmap

Based on the implementation plan in `docs/selector_parser_notes.md`, the next priorities are:

1. **Attribute selectors** - High utility for filtering blocks by arguments
2. **ID selectors** - Important for linking and references  
3. **Child combinator** - More precise relationship matching
4. **Pseudo-selectors** - Position-based selection

The current implementation provides a solid foundation for these future enhancements while delivering immediately useful functionality for the most common selector use cases.

