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
• 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 &
• 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
• Command
  Element of a pipe sequence
• CompoundCommand
  Command that contains other commands
• 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.