conch-parser

A Rust library for parsing Unix shell commands.

Quick Start

First, add this to your Cargo.toml:

[dependencies]
conch-parser = "0.1.0"

Next, you can get started with:

extern crate conch_parser;

use conch_parser::lexer::Lexer;
use conch_parser::parse::DefaultParser;

fn main() {
    // Initialize our token lexer and shell parser with the program's input
    let lex = Lexer::new("echo foo bar".chars());
    let parser = DefaultParser::new(lex);

    // Parse our input!
    for t in parser {
        println!("{:?}", t);
    }
}

About

This library offers parsing shell commands as defined by the POSIX.1-2008 standard. The parser remains agnostic to the final AST representation by passing intermediate results to an AST Builder, allowing for easy changes to the final AST structure without having to walk and transform an entire AST produced by the parser. See the documentation for more information.

Goals

• Provide shell command parser which is correct and efficient, and agnostic to the final AST representation
• Parsing should never require any form of runtime, thus no part of the source should have to be executed or evaluated when parsing

Non-goals

• 100% POSIX.1-2008 compliance: the standard is used as a baseline for implementation and features may be further added (or dropped) based on what makes sense or is most useful
• Feature parity with all major shells: unless a specific feature is widely used (and considered common) or another compelling reason exists for inclusion. However, this is not to say that the library will never support extensions for adding additional syntax features.

Supported grammar

• Conditional lists (foo && bar || baz)
• Pipelines (! foo | bar)
• Compound commands
  • Brace blocks ({ foo; })
  • Subshells ($(foo))
  • for / case / if / while / until
• Function declarations
• Redirections
• Heredocs
• Comments
• Parameters ($foo, $@, etc.)
• Parameter substitutions (${foo:-bar})
• Quoting (single, double, backticks, escaping)
• Arithmetic substitutions
  • Common arithmetic operations required by the standard
  • Variable expansion
  • Other inner abitrary parameter/substitution expansion

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.