Module syntax

Shell command language syntax

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

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.

Re-exports

pub use TextUnit::*;

pub use WordUnit::*;

pub use Value::*;

Structs

AndOrList

Pipelines separated by && and ||

Assign

Assignment word

BracedParam

Parameter expansion enclosed in braces

CaseItem

Branch item of a case compound command

ElifThen

elif-then clause

EscapedString

String that may contain some escapes

Fd

File descriptor

FullCompoundCommand

Compound command with redirections

FunctionDefinition

Function definition command

HereDoc

Here-document

Item

Element of a List

List

Sequence of and-or lists separated by ; or &

NotLiteral

Error indicating that a syntax element is not a literal

NotSpecialParam

Error that occurs when a character cannot be parsed as a special parameter

Param

Parameter

Pipeline

Commands separated by |

Redir

Redirection

SimpleCommand

Command that involves assignments, redirections, and word expansions

Switch

Parameter expansion modifier that conditionally substitutes the value being expanded

Text

String that may contain some expansions

Trim

Parameter expansion modifier that removes the beginning or end of the value being expanded

Word

Token that may involve expansions and quotes

Enums

AndOr

Condition that decides if a Pipeline in an and-or list should be executed

BackquoteUnit

Element of TextUnit::Backquote

CaseContinuation

Symbol that terminates the body of a case branch and determines what to do after executing it

Command

Element of a pipe sequence

CompoundCommand

Command that contains other commands

EscapeUnit

Element of an EscapedString

ExpansionMode

Expansion style of a simple command word

Modifier

Attribute that modifies a parameter expansion

ParamType

Type of a parameter

RedirBody

Part of a redirection that defines the nature of the resulting file descriptor

RedirOp

Redirection operators

SpecialParam

Special parameter

SwitchCondition

Condition that triggers a switch

SwitchType

Flag that specifies how the value is substituted in a switch

TextUnit

Element of a Text, i.e., something that can be expanded

TrimLength

Flag that specifies pattern matching strategy in a trim

TrimSide

Flag that specifies which side of the expanded value is removed in a trim

Value

Value of an assignment

WordUnit

Element of a Word, i.e., text with quotes and tilde expansion

Traits

MaybeLiteral

Possibly literal syntax element

Unquote

Removing quotes from syntax without performing expansion.