sipha-core 0.2.0

Core foundation types and traits for sipha - minimal dependencies, no parsing logic
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# sipha-core

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Repository](https://img.shields.io/badge/github-sipha-blue)](https://github.com/NyalephTheCat/sipha)
[![Crates.io](https://img.shields.io/crates/v/sipha-core)](https://crates.io/crates/sipha-core)
[![docs.rs](https://docs.rs/sipha-core/badge.svg)](https://docs.rs/sipha-core)

Core parsing infrastructure for sipha - provides grammar-based parsing, CST construction, and error handling.

## Overview

`sipha-core` is the foundation of the sipha parser ecosystem. It provides:

- **Grammar-based parsing** with support for complex grammars
- **Pratt parsing** for operator precedence handling
- **Concrete Syntax Tree (CST)** construction preserving all syntax information
- **Memoization** for efficient parsing
- **Error recovery** with sync tokens
- **Rich error diagnostics** with source code context
- **Visitor pattern** for tree traversal
- **CST rewriting** capabilities

## Quick Start

Add `sipha-core` to your `Cargo.toml`:

```toml
[dependencies]
sipha-core = "0.1.1"
```

With optional features:

```toml
[dependencies]
sipha-core = { version = "0.1.1", features = ["serde", "color", "diagnostics"] }
```

## Features

- `default`: Includes `serde`, `color`, and `diagnostics` features
- `serde`: Enables serialization of grammar rules and CST nodes
- `color`: Adds color support for error output
- `diagnostics`: Enables rich error diagnostics with miette integration

## Example

```rust
use sipha_core::{
    cst::{NodeArena, RawNodeId},
    helpers,
    parser::Parser,
    span::Span,
    state::ParserState,
    token::Token,
    traits::TokenKind,
};

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
enum MyToken {
    Ident,
    Plus,
}

impl TokenKind for MyToken {
    fn is_trivia(&self) -> bool {
        false
    }
}

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
enum MyRule {
    Expr,
}

let mut parser = Parser::create();
parser.register_rule(
    MyRule::Expr,
    helpers::seq(vec![
        helpers::token(MyToken::Ident),
        helpers::token(MyToken::Plus),
        helpers::token(MyToken::Ident),
    ]),
);

let tokens = vec![
    Token::create(MyToken::Ident, Span::new(0..1), "a", Vec::new(), Vec::new()),
    Token::create(MyToken::Plus, Span::new(1..2), "+", Vec::new(), Vec::new()),
    Token::create(MyToken::Ident, Span::new(2..3), "b", Vec::new(), Vec::new()),
];

let mut arena: NodeArena<MyToken, MyRule, RawNodeId> = NodeArena::new();
let mut state = ParserState::new(&tokens, &mut arena, false, ());

match parser.parse_rule(MyRule::Expr, &mut state) {
    Ok(_) => println!("Parsed successfully!"),
    Err(e) => eprintln!("Parse error: {:?}", e),
}
```

## Documentation

For more information, see:
- [Architecture Guide](../docs/ARCHITECTURE.md)
- [Performance Guide](../docs/PERFORMANCE.md)
- [FAQ](../docs/FAQ.md)

## License

This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.

## See Also

- [sipha](https://crates.io/crates/sipha) - Umbrella crate with feature flags
- [sipha-analysis](https://crates.io/crates/sipha-analysis) - Grammar analysis utilities
- [sipha-lsp](https://crates.io/crates/sipha-lsp) - Language Server Protocol support
- [sipha-fmt](https://crates.io/crates/sipha-fmt) - Source code formatting utilities