diff options
Diffstat (limited to 'src/poem/elements/verse.rs')
| -rw-r--r-- | src/poem/elements/verse.rs | 174 |
1 files changed, 106 insertions, 68 deletions
diff --git a/src/poem/elements/verse.rs b/src/poem/elements/verse.rs index b4f41ba..1c5bcc1 100644 --- a/src/poem/elements/verse.rs +++ b/src/poem/elements/verse.rs @@ -16,27 +16,83 @@ use std::path::Path; use std::process::{Child, Command, Output, Stdio}; use std::sync::{Arc, Mutex}; -/// A [Stanza] and it's [meter](Rune) +/// A [Stanza] and its [meter](Rune) /// -/// In addition to a [Stanza] and a [meter](Rune), this also holds a [bool] -/// value called `couplet`, indicating that it needs to accept input on `STDIN` -/// from the previous [Verse]. +/// In addition to a [Stanza] and a [meter](Rune), this also holds a +/// [bool] value called `couplet`, indicating that it needs to accept +/// input on `STDIN` from the previous [Verse]. #[derive(Debug, Clone)] pub struct Verse { + /// A command and its arguments (also see [Stanza]) pub stanza: Stanza, + + /// Denote the couplet status (for piping text in/out) + /// + /// * `0`: Not a couplet + /// * `1`: Left side of a couplet + /// * `2`: Right side of a couplet + /// * `3`: Both sides of a couplet + /// + /// ``` + /// ls | grep Ca | lolcat + /// ^ ^ ^ + /// | | 2: right side of a couplet + /// | 3: both sides of a couplet + /// 1: left side of a couplet + /// ``` pub couplet: u8, + + /// A list of IO operations to be performed + /// + /// For instance, read into STDIN, write STDOUT to a file, etc. May + /// be empty. Also see [Rune] for more details. pub io: Vec<Rune>, + + /// Input paths + /// + /// A list of files to read into STDIN, may be empty. pub ip: Stanza, + + /// Output paths + /// + /// A list of files to send STDOUT to, may be empty. pub op: Stanza, + + /// Error paths + /// + /// A list of files to send STDERR to, may be empty. pub ep: Stanza, + + /// Internal poems (i.e. 'ls \`ls\`') + /// + /// A list of poems to evaluate before evaluating this one. pub poems: Vec<Poem>, + + /// Interpret how to handle a poem after forking to its command + /// + /// * `None`: Indicates the end of a poem + /// * `Couplet`: Pipe the output of this command into the next (`|`) + /// * `Quiet`: Fork the called process into the background (`&`) + /// * `And`: Run the next command, only if this one succeeds (`&&`) + /// * `Continue`: Run the next command, regardless of whether or not + /// this command succeeds (`;` or a newline in a file) + /// + /// Also see [Rune] for more details. pub meter: Rune, } +/// Granularity for [spellcheck()][Verse::spellcheck] +/// +/// Indicates if a given [verb][Verse::verb] exists, and where. #[derive(Debug, Clone)] pub enum Spelling { + /// The [verb][Verse::verb] is a full path, and that path exists FullPath, + + /// The [verb][Verse::verb] is on the `$PATH` OnPath(usize), + + /// The [verb][Verse::verb] is a built-in shell command BuiltIn(usize), } @@ -59,42 +115,8 @@ impl Forkable<Anthology> for Anthology { impl Verse { /// Create a new [Verse] /// - /// Returns a new [Verse], with an empty [Stanza], a meter of [Rune::None], - /// and `couplet` set to 0. - /// - /// # Fields - /// stanza - The command (a `verb()` and a `clause()`) - /// couplet - Indicates couplet status - /// 0: Not a couplet (`cat Cargo.toml`) - /// 1: Left side of a couplet (`cat Cargo.toml | ...`) - /// 2: Right side of a couplet (`... | lolcat`) - /// 3: Sandwiched between couplets (`... | grep Ca | ...`) - /// io - A list of IO operations ([Rune::Read], [Rune::Write], etc.) - /// ip - A list of filenames for reading into STDIN when: - /// [Rune::Read] - /// is specified - /// op - A list of filenames for redirecting STDOUT to when: - /// [Rune::Write], - /// [Rune::WriteAll], - /// [Rune::Addendum], - /// and/or [Rune::AddendumAll] - /// is specified - /// ep - A list of filenames for redirecting STDERR to when: - /// [Rune::Write2], - /// [Rune::WriteAll], - /// [Rune::Addendum2], - /// and/or [Rune::AddendumAll] - /// is specified - /// poems - Internal commands to run before the [Verse] is recited - /// ([Rune::Poem]). - /// meter - Determines how the verse is recited in relation to the other - /// verses in the [Poem]. - /// [Rune::None] -> Run the command and print the output - /// [Rune::Couplet] -> Pipe the output of this verse into the next - /// [Rune::Quiet] -> Run in the background - /// [Rune::And] -> Run the next verse only if this verse succeeds - /// [Rune::Continue] -> Run the next verse, regardless of whether - /// or not this verse succeeds + /// Returns a new [Verse], with an empty [Stanza], a meter of + /// [Rune::None], and `couplet` set to 0. pub fn new() -> Self { Verse { stanza: Stanza::new(), @@ -153,11 +175,11 @@ impl Verse { /// Push a word to the [Verse]'s [Stanza] /// - /// Push a word to the [Verse]'s [Stanza], or one of its IO channels. If - /// `word` is empty, this function will simply return without performing - /// any operations. A channel of [None] will push to the [Verse]'s - /// [Stanza], while IO [Rune]s will determine which IO channel a word will - /// get pushed onto. + /// Push a word to the [Verse]'s [Stanza], or one of its IO + /// channels. If `word` is empty, this function will simply return + /// without performing any operations. A channel of [None] will push + /// to the [Verse]'s [Stanza], while IO [Rune]s will determine which + /// IO channel a word will get pushed onto. /// /// # Arguments /// word - The word to push onto the [Stanza]/channel @@ -194,35 +216,50 @@ impl Verse { word.clear(); } - /// Check if the `verb()` exists in the `$PATH` + /// Check if the [verb][Verse::verb] exists /// - /// First checks if the `verb()` is a relative or full path. If it is, - /// check whether or not it exists. If it does exist, return true, - /// otherwise seeif the `verb()` is cached in our list of binaries. Search is - /// done in $PATH order. + /// First checks if the [verb][Verse::verb] is a built-in shell + /// command. Then checks if the [verb][Verse::verb] is on the + /// `$PATH`. If not, then the [verb][Verse::verb] is a either a full + /// path, or it does not exist on the system. /// /// # Examples /// ``` - /// let bins = vec!["cargo", "ruby", "cat"] - /// .into_iter() - /// .map(String::from) - /// .collect<Vec<String>>(); + /// let command_full_path = vec!["/bin/ls"] + /// .into_iter() + /// .map(String::from) + /// .collect<Vec<String>>(); /// - /// let command_success = vec!["cargo", "build", "--release"] + /// let command_on_path = vec!["cargo", "build", "--release"] /// .into_iter() /// .map(String::from) /// .collect<Vec<String>>(); /// - /// let command_fail = vec!["make", "-j8"] - /// .into_iter() - /// .map(String::from) - /// .collect<Vec<String>>(); + /// let command_built_in = vec!["alias", "g=git"] + /// .into_iter() + /// .map(String::from) + /// .collect<Vec<String>>(); + /// + /// let command_no_exist = vec!["thisdoesntexist"] + /// .into_iter() + /// .map(String::from) + /// .collect<Vec<String>>(); + /// + /// let verse = Verse::new(); + /// verse.stanza = Stanza::new(command_full_path); + /// verse.spellcheck(&env.bins); // -> Some(Spelling::FullPath) + /// + /// let verse = Verse::new(); + /// verse.stanza = Stanza::new(command_on_path); + /// verse.spellcheck(&env.bins); // -> Some(Spelling::OnPath) /// - /// let stanza_success = Stanza::new(command_success); - /// let stanza_fail = Stanza::new(command_fail); + /// let verse = Verse::new(); + /// verse.stanza = Stanza::new(command_built_in); + /// verse.spellcheck(&env.bins); // -> Some(Spelling::BuiltIn) /// - /// stanza_success.spellcheck(bins) // -> Some(i) - /// stanza_fail.spellcheck(bins) // -> None + /// let verse = Verse::new(); + /// verse.stanza = Stanza::new(command_no_exist); + /// verse.spellcheck(&env.bins); // -> None /// ``` pub fn spellcheck(&self, bins: &Vec<String>) -> Option<Spelling> { // An empty verb (i.e. the empty string) cannot be a program, so @@ -261,11 +298,12 @@ impl Verse { /// Run a command /// - /// The [Poem]::recite() function calls this [Verse::incant] function for - /// each verse it contains. This function handles the actual setup and - /// spawning (forking) of a new process specified in the [Verse]. It will - /// also run IO operations for the verse, and setup appropriate coupling, - /// as per the [Verse]'s own details, contained throughout its fields. + /// The [recite()][crate::poem::recite] function calls this + /// [incant()][Verse::incant] function for each verse it contains. + /// This function handles the actual setup and spawning (forking) of + /// a new process specified in the [Verse]. It will also run IO + /// operations for the verse, and setup appropriate coupling, as per + /// the [Verse]'s own details, contained throughout its fields. pub fn incant( &mut self, out: &mut Vec<u8>, |