diff options
| -rw-r--r-- | src/poem/elements/verse.rs | 65 |
1 files changed, 61 insertions, 4 deletions
diff --git a/src/poem/elements/verse.rs b/src/poem/elements/verse.rs index b0d451b..5694b55 100644 --- a/src/poem/elements/verse.rs +++ b/src/poem/elements/verse.rs @@ -31,7 +31,41 @@ impl Verse { /// Create a new [Verse] /// /// Returns a new [Verse], with an empty [Stanza], a meter of [Rune::None], - /// and `couplet` set to `false`. + /// 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 pub fn new() -> Self { Verse { stanza: Stanza::new(), @@ -90,9 +124,25 @@ impl Verse { /// Push a word to the [Verse]'s [Stanza] /// - /// Push a word to the [Stanza] after performing a few extra checks, such - /// as whether or not the word is empty, or if the word should be - /// interpreted as an environment variable. + /// 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 + /// channel - Specifiy which channel to use + /// + /// # Examples + /// ``` + /// word.push("c"); + /// word.push("a"); + /// word.push("t"); + /// verse.add(&mut word, None); // Pushes onto [Stanza] + /// verse.add(&mut word, Some(Rune::Write)); // Pushes onto [op] + /// verse.add(&mut word, Some(Rune::WriteAll)); // Pushes onto [op], [ep] + /// ``` pub fn add(&mut self, word: &mut Word, channel: Option<Rune>) { // Do nothing if the stack is empty if word.is_empty() { @@ -172,6 +222,13 @@ impl Verse { true } + /// 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. pub fn incant( &mut self, out: &mut Vec<u8>, |