Trait conch_parser::ast::builder::Builder [−] [src]

pub trait Builder {
    type Command;
    type CommandList;
    type ListableCommand;
    type PipeableCommand;
    type CompoundCommand;
    type Word;
    type Redirect;
    type Error;
    fn complete_command(
        &mut self, 
        pre_cmd_comments: Vec<Newline>, 
        list: Self::CommandList, 
        separator: SeparatorKind, 
        cmd_comment: Option<Newline>
    ) -> Result<Self::Command, Self::Error>;

    fn and_or_list(
        &mut self, 
        first: Self::ListableCommand, 
        rest: Vec<(Vec<Newline>, AndOr<Self::ListableCommand>)>
    ) -> Result<Self::CommandList, Self::Error>;

    fn pipeline(
        &mut self, 
        bang: bool, 
        cmds: Vec<(Vec<Newline>, Self::PipeableCommand)>
    ) -> Result<Self::ListableCommand, Self::Error>;

    fn simple_command(
        &mut self, 
        redirects_or_env_vars: Vec<RedirectOrEnvVar<Self::Redirect, String, Self::Word>>, 
        redirects_or_cmd_words: Vec<RedirectOrCmdWord<Self::Redirect, Self::Word>>
    ) -> Result<Self::PipeableCommand, Self::Error>;

    fn brace_group(
        &mut self, 
        cmds: CommandGroup<Self::Command>, 
        redirects: Vec<Self::Redirect>
    ) -> Result<Self::CompoundCommand, Self::Error>;

    fn subshell(
        &mut self, 
        cmds: CommandGroup<Self::Command>, 
        redirects: Vec<Self::Redirect>
    ) -> Result<Self::CompoundCommand, Self::Error>;

    fn loop_command(
        &mut self, 
        kind: LoopKind, 
        guard_body_pair: GuardBodyPairGroup<Self::Command>, 
        redirects: Vec<Self::Redirect>
    ) -> Result<Self::CompoundCommand, Self::Error>;

    fn if_command(
        &mut self, 
        fragments: IfFragments<Self::Command>, 
        redirects: Vec<Self::Redirect>
    ) -> Result<Self::CompoundCommand, Self::Error>;

    fn for_command(
        &mut self, 
        fragments: ForFragments<Self::Word, Self::Command>, 
        redirects: Vec<Self::Redirect>
    ) -> Result<Self::CompoundCommand, Self::Error>;

    fn case_command(
        &mut self, 
        fragments: CaseFragments<Self::Word, Self::Command>, 
        redirects: Vec<Self::Redirect>
    ) -> Result<Self::CompoundCommand, Self::Error>;

    fn compound_command_into_pipeable(
        &mut self, 
        cmd: Self::CompoundCommand
    ) -> Result<Self::PipeableCommand, Self::Error>;

    fn function_declaration(
        &mut self, 
        name: String, 
        post_name_comments: Vec<Newline>, 
        body: Self::CompoundCommand
    ) -> Result<Self::PipeableCommand, Self::Error>;

    fn comments(&mut self, comments: Vec<Newline>) -> Result<(), Self::Error>;

    fn word(
        &mut self, 
        kind: ComplexWordKind<Self::Command>
    ) -> Result<Self::Word, Self::Error>;

    fn redirect(
        &mut self, 
        kind: RedirectKind<Self::Word>
    ) -> Result<Self::Redirect, Self::Error>;
}

A trait which defines an interface which the parser defined in the parse module uses to delegate Abstract Syntax Tree creation. The methods defined here correspond to their respectively named methods on the parser, and accept the relevant data for each shell command type.

Associated Types

The type which represents a complete, top-level command.

The type which represents an and/or list of commands.

The type which represents a command that can be used in an and/or command list.

The type which represents a command that can be used in a pipeline.

The type which represents compound commands like if, case, for, etc.

The type which represents shell words, which can be command names or arguments.

The type which represents a file descriptor redirection.

A type for returning custom parse/build errors.

Required Methods

Invoked once a complete command is found. That is, a command delimited by a newline, semicolon, ampersand, or the end of input.

Arguments

  • pre_cmd_comments: any comments that appear before the start of the command
  • list: an and/or list of commands previously generated by the same builder
  • separator: indicates how the command was delimited
  • cmd_comment: a comment that appears at the end of the command

Invoked when multiple commands are parsed which are separated by && or ||. Typically after the first command is run, each of the following commands may or may not be executed, depending on the exit status of the previously executed command.

Arguments

  • first: the first command before any && or || separator
  • rest: A collection of comments after the last separator and the next command.

Invoked when a pipeline of commands is parsed. A pipeline is one or more commands where the standard output of the previous typically becomes the standard input of the next.

Arguments

  • bang: the presence of a ! at the start of the pipeline, typically indicating that the pipeline's exit status should be logically inverted.
  • cmds: a collection of tuples which are any comments appearing after a pipe token, followed by the command itself, all in the order they were parsed

Invoked when the "simplest" possible command is parsed: an executable with arguments.

Arguments

  • redirects_or_env_vars: redirections or environment variables that occur before any command
  • redirects_or_cmd_words: redirections or any command or argument

Invoked when a non-zero number of commands were parsed between balanced curly braces. Typically these commands should run within the current shell environment.

Arguments

  • cmds: the commands that were parsed between braces
  • redirects: any redirects to be applied over the entire group of commands

Invoked when a non-zero number of commands were parsed between balanced parentheses. Typically these commands should run within their own environment without affecting the shell's global environment.

Arguments

  • cmds: the commands that were parsed between parens
  • redirects: any redirects to be applied over the entire group of commands

Invoked when a loop command like while or until is parsed. Typically these commands will execute their body based on the exit status of their guard.

Arguments

  • kind: the type of the loop: while or until
  • guard: commands that determine how long the loop will run for
  • body: commands to be run every iteration of the loop
  • redirects: any redirects to be applied over all commands part of the loop

Invoked when an if conditional command is parsed. Typically an if command is made up of one or more guard-body pairs, where the body of the first successful corresponding guard is executed. There can also be an optional else part to be run if no guard is successful.

Arguments

  • fragments: parsed fragments relating to a shell if command.
  • redirects: any redirects to be applied over all commands within the if command

Invoked when a for command is parsed. Typically a for command binds a variable to each member in a group of words and invokes its body with that variable present in the environment. If no words are specified, the command will iterate over the arguments to the script or enclosing function.

Arguments

  • fragments: parsed fragments relating to a shell for command.
  • redirects: any redirects to be applied over all commands within the for command

Invoked when a case command is parsed. Typically this command will execute certain commands when a given word matches a pattern.

Arguments

  • fragments: parsed fragments relating to a shell case command.
  • redirects: any redirects to be applied over all commands part of the case block

Bridges the gap between a PipeableCommand and a CompoundCommand since CompoundCommands are typically PipeableCommands as well.

Arguments

cmd: The CompoundCommand to convert into a PipeableCommand

Invoked when a function declaration is parsed. Typically a function declaration overwrites any previously defined function within the current environment.

Arguments

  • name: the name of the function to be created
  • post_name_comments: any comments appearing after the function name but before the body
  • body: commands to be run when the function is invoked

Invoked when only comments are parsed with no commands following. This can occur if an entire shell script is commented out or if there are comments present at the end of the script.

Arguments

  • comments: the parsed comments

Invoked when a word is parsed.

Arguments

  • kind: the type of word that was parsed

Invoked when a redirect is parsed.

Arguments

  • kind: the type of redirect that was parsed

Implementors