Module yash_syntax::syntax

Expand description

Shell command language syntax.

This module contains types that represent abstract syntax trees (ASTs) of the shell language.

Some types in this module has the type parameter <H = HereDoc>. As a user of ASTs, you will never have to specify the parameter other than the default HereDoc. The parameter with non-default types is used internally by the parser to create intermediate ASTs that lack sub-trees for here-documents, as the contents of here-documents have to be parsed separately from the normal flow of source code.

Syntactic elements

The AST type that represents the whole shell script is List, which is a vector of Items. An Item is a possibly asynchronous AndOrList, which is a sequence of conditionally executed Pipelines. A Pipeline is a sequence of Commands separated by |.

There are several types of Commands, namely SimpleCommand, CompoundCommand and FunctionDefinition, where CompoundCommand in turn comes in many variants.

Lexical elements

Tokens that make up commands may contain quotations and expansions. A Word, a sequence of WordUnits, represents such a token that appears in a simple command and some kinds of other commands.

In some contexts, tilde expansion and single- and double-quotes are not recognized while other kinds of expansions are allowed. Such part is represented as Text, a sequence of TextUnits.

Parsing

Most AST types defined in this module implement the FromStr trait, which means you can easily get an AST out of source code by calling parse on a &str. However, all locations in ASTs constructed this way will only have unknown source.

use std::str::FromStr;
let list: List = "diff foo bar; echo $?".parse().unwrap();
assert_eq!(list.to_string(), "diff foo bar; echo $?");

use yash_syntax::source::Source;
let word: Word = "foo".parse().unwrap();
assert_eq!(word.location.code.source, Source::Unknown);

To include substantial source information in the AST, you need to prepare a lexer with source information and then use it to parse the source code. See the parser module for details.

Displaying

Most AST types support the Display trait, which allows you to convert an AST to a source code string. Note that the Display trait implementations always produce single-line source code with here-document contents omitted. To pretty-format an AST in multiple lines with here-document contents included, you can use … TODO TBD.