Expand description
poshtree turns PowerShell source into a syntax tree and back again,
without losing a byte.
The default front-end is v2. Its lexer keeps whitespace, newlines, and
comments as trivia attached to the tokens, so reconstructing the stream
reproduces the source exactly, even for malformed input. A native
recursive-descent parser builds a tree where every node carries a byte
Span and a TokenRange; on top of that sit byte-level text edits
(v2::TextEdit) for minimal-diff rewriting and a width-aware formatter
(v2::format_source). It has no dependencies.
A legacy v1 front-end (a lexer, a recursive-descent parser building an
abstract syntax tree, and an unparser) stays available behind an opt-in
feature for code that still uses it. It is off by default and owns the
crate’s only dependency, regex.
Versioning works by addition: a breaking change ships as a sibling version
module instead of altering the published one, so pinned code keeps
compiling. Turn features off to compile just one front-end
(default-features = false, features = ["v1"]).
§PowerShell conformance
The v2 parser follows PowerShell’s documented operator precedence
(about_Operator_Precedence), including the comma operator, which binds
tighter than -f, arithmetic, comparison, and logical operators and looser
only than casts, index, member access, subexpressions, and the unary
operators. So 1,2,1+2 parses as (1,2,1)+2 (the array 1,2,1 with 2
appended), as in PowerShell, and a comma-separated argument to a format
string ("{0} {1}" -f $a, $b) is grouped into one array before -f is
applied. An array used as a parameter default must be parenthesized
(param($x = (1, 2))) or use @(...), since a bare top-level comma in a
parameter list separates parameters.
§Quick start
use poshtree::v2::parse;
let out = parse("$x = 1 + 2 | Write-Output\n");
assert!(out.errors.is_empty());
// A malformed construct becomes an error node, so there is always a tree.
let mut nodes = 0;
out.script.walk(&mut |_| nodes += 1);
assert!(nodes > 0);Re-exports§
pub use encoding::decode_bytes;pub use encoding::strip_bom;