rable 0.1.12

A Rust implementation of the Parable bash parser — complete GNU Bash 5.3-compatible parsing with Python bindings
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

//! # Rable — A complete GNU Bash 5.3-compatible parser
//!
//! Rable parses bash source code into an abstract syntax tree (AST) of [`Node`]
//! values. Each node can be formatted as an S-expression via its [`Display`]
//! implementation, producing output identical to [Parable](https://github.com/ldayton/Parable).
//!
//! # Quick Start
//!
//! ```
//! use rable::{parse, NodeKind};
//!
//! let nodes = parse("echo hello | grep h", false).unwrap();
//! assert_eq!(nodes.len(), 1);
//!
//! // S-expression output via Display
//! let sexp = nodes[0].to_string();
//! assert!(sexp.contains("pipe"));
//! ```
//!
//! # Parsing Options
//!
//! The `extglob` parameter enables extended glob patterns (`@()`, `?()`, `*()`,
//! `+()`, `!()`). Set to `false` for standard bash parsing.
//!
//! ```
//! // Standard parsing
//! let nodes = rable::parse("echo hello", false).unwrap();
//!
//! // With extended globs
//! let nodes = rable::parse("echo @(foo|bar)", true).unwrap();
//! ```
//!
//! # Error Handling
//!
//! Parse errors include line and position information:
//!
//! ```
//! match rable::parse("if", false) {
//!     Ok(_) => unreachable!(),
//!     Err(e) => {
//!         assert_eq!(e.line(), 1);
//!         println!("Error: {e}");
//!     }
//! }
//! ```
//!
//! # Working with the AST
//!
//! The AST uses a [`Node`] struct wrapping a [`NodeKind`] enum with a [`Span`].
//! Pattern matching on `node.kind` is the primary way to inspect nodes:
//!
//! ```
//! use rable::{parse, NodeKind};
//!
//! let nodes = parse("echo hello world", false).unwrap();
//! match &nodes[0].kind {
//!     NodeKind::Command { words, redirects, .. } => {
//!         assert_eq!(words.len(), 3); // echo, hello, world
//!         assert!(redirects.is_empty());
//!     }
//!     _ => panic!("expected Command"),
//! }
//! ```

pub mod ast;
pub mod error;
pub mod token;

// Public for advanced use (S-expression formatting)
pub mod sexp;

// Implementation details — not part of the stable API
pub(crate) mod context;
pub(crate) mod format;
pub(crate) mod lexer;
pub(crate) mod parser;

#[cfg(feature = "python")]
mod python;

// Convenient re-exports
pub use ast::{CasePattern, ListItem, ListOperator, Node, NodeKind, PipeSep, Span};
pub use error::{RableError, Result};
pub use token::{Token, TokenType};

/// Parses a bash source string into a list of top-level AST nodes.
///
/// Each top-level command separated by newlines becomes a separate node.
/// Commands separated by `;` on the same line are grouped into a single
/// [`NodeKind::List`].
///
/// Set `extglob` to `true` to enable extended glob patterns (`@()`, `?()`,
/// `*()`, `+()`, `!()`).
///
/// # Examples
///
/// ```
/// let nodes = rable::parse("echo hello", false).unwrap();
/// assert_eq!(nodes[0].to_string(), "(command (word \"echo\") (word \"hello\"))");
/// ```
///
/// ```
/// // Multiple top-level commands
/// let nodes = rable::parse("echo a\necho b", false).unwrap();
/// assert_eq!(nodes.len(), 2);
/// ```
///
/// # Errors
///
/// Returns [`RableError::Parse`] for syntax errors and
/// [`RableError::MatchedPair`] for unclosed delimiters.
pub fn parse(source: &str, extglob: bool) -> Result<Vec<Node>> {
    let lexer = lexer::Lexer::new(source, extglob);
    let mut parser = parser::Parser::new(lexer);
    parser.parse_all()
}