Trait Builder

pub trait Builder {
    type Command;
    type CommandList;
    type ListableCommand;
    type PipeableCommand;
    type CompoundCommand;
    type Word;
    type Redirect;
    type Error;

    // Required methods
    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.

Required Associated Types

type Command

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

type CommandList

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

type ListableCommand

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

type PipeableCommand

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

type CompoundCommand

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

type Word

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

type Redirect

The type which represents a file descriptor redirection.

type Error

A type for returning custom parse/build errors.

Required Methods

fn complete_command( &mut self, pre_cmd_comments: Vec<Newline>, list: Self::CommandList, separator: SeparatorKind, cmd_comment: Option<Newline>, ) -> Result<Self::Command, Self::Error>

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

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

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.

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

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

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>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Invoked when a word is parsed.

Arguments

• kind: the type of word that was parsed

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

Invoked when a redirect is parsed.

Arguments

• kind: the type of redirect that was parsed

Implementations on Foreign Types

impl<'a, T: Builder + ?Sized> Builder for &'a mut T

type Command = <T as Builder>::Command

type CommandList = <T as Builder>::CommandList

type ListableCommand = <T as Builder>::ListableCommand

type PipeableCommand = <T as Builder>::PipeableCommand

type CompoundCommand = <T as Builder>::CompoundCommand

type Word = <T as Builder>::Word

type Redirect = <T as Builder>::Redirect

type Error = <T as Builder>::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>

impl<T: Builder + ?Sized> Builder for Box<T>

type Command = <T as Builder>::Command

type CommandList = <T as Builder>::CommandList

type ListableCommand = <T as Builder>::ListableCommand

type PipeableCommand = <T as Builder>::PipeableCommand

type CompoundCommand = <T as Builder>::CompoundCommand

type Word = <T as Builder>::Word

type Redirect = <T as Builder>::Redirect

type Error = <T as Builder>::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>

Implementors

impl Builder for EmptyBuilder

type Command = ()

type CommandList = ()

type ListableCommand = ()

type PipeableCommand = ()

type CompoundCommand = ()

type Word = ()

type Redirect = ()

type Error = Void

impl<T, W, C, F> Builder for CoreBuilder<T, W, C, F>

where T: From<String>, W: From<ShellWord<T, W, C>>, C: From<Command<AndOrList<ListableCommand<PipeableCommand<T, Box<SimpleCommand<T, W, Redirect<W>>>, Box<ShellCompoundCommand<T, W, C>>, F>>>>>, F: From<ShellCompoundCommand<T, W, C>>,

type Command = C

type CommandList = AndOrList<<CoreBuilder<T, W, C, F> as Builder>::ListableCommand>

type ListableCommand = ListableCommand<<CoreBuilder<T, W, C, F> as Builder>::PipeableCommand>

type PipeableCommand = PipeableCommand<T, Box<SimpleCommand<T, W, Redirect<W>>>, Box<CompoundCommand<CompoundCommandKind<T, W, C>, Redirect<W>>>, F>

type CompoundCommand = CompoundCommand<CompoundCommandKind<T, <CoreBuilder<T, W, C, F> as Builder>::Word, <CoreBuilder<T, W, C, F> as Builder>::Command>, Redirect<<CoreBuilder<T, W, C, F> as Builder>::Word>>

type Word = W

type Redirect = Redirect<<CoreBuilder<T, W, C, F> as Builder>::Word>

type Error = Void

impl<T: From<String>> Builder for AtomicDefaultBuilder<T>

type Command = AtomicTopLevelCommand<T>

type CommandList = AndOrList<<AtomicDefaultBuilder<T> as Builder>::ListableCommand>

type ListableCommand = ListableCommand<<AtomicDefaultBuilder<T> as Builder>::PipeableCommand>

type PipeableCommand = PipeableCommand<T, Box<SimpleCommand<T, <AtomicDefaultBuilder<T> as Builder>::Word, Redirect<<AtomicDefaultBuilder<T> as Builder>::Word>>>, Box<CompoundCommand<CompoundCommandKind<T, <AtomicDefaultBuilder<T> as Builder>::Word, <AtomicDefaultBuilder<T> as Builder>::Command>, Redirect<<AtomicDefaultBuilder<T> as Builder>::Word>>>, Arc<CompoundCommand<CompoundCommandKind<T, <AtomicDefaultBuilder<T> as Builder>::Word, <AtomicDefaultBuilder<T> as Builder>::Command>, Redirect<<AtomicDefaultBuilder<T> as Builder>::Word>>>>

type CompoundCommand = CompoundCommand<CompoundCommandKind<T, <AtomicDefaultBuilder<T> as Builder>::Word, <AtomicDefaultBuilder<T> as Builder>::Command>, Redirect<<AtomicDefaultBuilder<T> as Builder>::Word>>

type Word = AtomicTopLevelWord<T>

type Redirect = Redirect<<AtomicDefaultBuilder<T> as Builder>::Word>

type Error = Void

impl<T: From<String>> Builder for DefaultBuilder<T>

type Command = TopLevelCommand<T>

type CommandList = AndOrList<<DefaultBuilder<T> as Builder>::ListableCommand>

type ListableCommand = ListableCommand<<DefaultBuilder<T> as Builder>::PipeableCommand>

type PipeableCommand = PipeableCommand<T, Box<SimpleCommand<T, <DefaultBuilder<T> as Builder>::Word, Redirect<<DefaultBuilder<T> as Builder>::Word>>>, Box<CompoundCommand<CompoundCommandKind<T, <DefaultBuilder<T> as Builder>::Word, <DefaultBuilder<T> as Builder>::Command>, Redirect<<DefaultBuilder<T> as Builder>::Word>>>, Rc<CompoundCommand<CompoundCommandKind<T, <DefaultBuilder<T> as Builder>::Word, <DefaultBuilder<T> as Builder>::Command>, Redirect<<DefaultBuilder<T> as Builder>::Word>>>>

type CompoundCommand = CompoundCommand<CompoundCommandKind<T, <DefaultBuilder<T> as Builder>::Word, <DefaultBuilder<T> as Builder>::Command>, Redirect<<DefaultBuilder<T> as Builder>::Word>>

type Word = TopLevelWord<T>

type Redirect = Redirect<<DefaultBuilder<T> as Builder>::Word>

type Error = Void