From b8338719e2cc2138bc67c10ad56fb707f5e3b546 Mon Sep 17 00:00:00 2001 From: Rory Dudley Date: Sun, 30 Jun 2024 20:09:26 -0600 Subject: Add/update doc comments This patch update a ton of the documentation comments throughout the codebase, refactoring some areas, and adding new comments to others. --- src/poem/anthology.rs | 57 ++++++++++++- src/poem/anthology/alias.rs | 4 +- src/poem/anthology/cd.rs | 9 +- src/poem/anthology/export.rs | 4 +- src/poem/anthology/source.rs | 4 +- src/poem/anthology/which.rs | 12 +++ src/poem/elements/rune.rs | 116 +++++++++++++++----------- src/poem/elements/stanza.rs | 12 +-- src/poem/elements/verse.rs | 174 ++++++++++++++++++++++++--------------- src/poem/elements/verse/logic.rs | 14 ++++ src/poem/elements/word.rs | 3 +- src/poem/read.rs | 39 +++++++-- src/poem/recite.rs | 11 +-- 13 files changed, 314 insertions(+), 145 deletions(-) (limited to 'src/poem') diff --git a/src/poem/anthology.rs b/src/poem/anthology.rs index 086864c..0026b8d 100644 --- a/src/poem/anthology.rs +++ b/src/poem/anthology.rs @@ -15,7 +15,8 @@ static INDEX: [&str; 8] = [ /// Lookup the index of a built-in command /// -/// Looks up the index of a built-in command in [INDEX], accounting for aliases. +/// Looks up the index of a built-in command in [INDEX], accounting for +/// aliases. /// /// # Aliases /// * quit -> exit @@ -29,34 +30,67 @@ pub fn lookup(verb: &str) -> Option { INDEX.iter().position(|v| v.to_string() == verb) } +/// Dummy interface for STDIN +/// +/// A helper struct for dealing with STDIN in built-in commands. +/// Currently, there are no built-in commands that actually use this, +/// but it needs to exist for the `incant!()` macro to function +/// properly. See [Anthology] for more details. #[derive(Debug, PartialEq, Eq, Clone)] pub struct AnthologyStdin { + /// Bytes data: Vec, } impl AnthologyStdin { + /// Create a new instance of AnthologyStdin pub fn new() -> Self { AnthologyStdin { data: Vec::new() } } + /// Return a mutable version of self pub fn as_mut(&mut self) -> Option<&mut Self> { Some(self) } + /// Write bytes specified by data into STDIN pub fn write_all(&mut self, data: &[u8]) -> Result<(), io::Error> { self.data.append(&mut data.to_vec()); Ok(()) } } +/// Interface for built-in commands +/// +/// The implementation of [Anthology] is designed to mimic +/// [std::process::Command], in order to avoid code redundancy. The +/// internal structure of [Anthology] is fairly irrelevant to this +/// `impl`, with the exception of the `stdin`, and `output` fields. In +/// addition to the documentation below, it may also be helpful to read +/// through the `incant!()` macro, so see how processes are actually +/// forked. #[derive(Debug, Clone)] pub struct Anthology { + /// Name of the built-in command (see [lookup()] and/or [INDEX]) verb: String, + + /// Arguments to pass to the built-in command clause: Option>, + + /// Indicates STDIN should be read in (but no built-ins use STDIN) uin: bool, + + /// Indicates STDOUT should be captured uout: bool, + + /// Indicates STDERR should be captured uerr: bool, + + /// Compatability with [std::process::Command] pub stdin: AnthologyStdin, + + /// Stores the built-in output (return code, STDOUT, STDERR), also + /// needed for compatability with [std::process::Command] output: Option, } @@ -110,11 +144,28 @@ impl Anthology { self.uerr = true; } + /// Set the process group + /// + /// This is only needed if a process is forked into the background. + /// Technically this is possible with the built-ins, but not really + /// useful, so this function simply does nothing. As a result, + /// built-ins that get forked into the background always return + /// immediately. pub fn process_group(&mut self, _id: usize) {} + + /// Get the process id + /// + /// This is only needed if a process is forked into the background. + /// Will always return `0` for built-in commands. Also see + /// [process_group()][Anthology::process_group]. pub fn id(&mut self) -> i32 { 0 } + /// Run a built-in command + /// + /// Runs a built-in command based on the `verb`, appropriately + /// passing arguments and [Environment] fields as necessary. pub fn spawn(&mut self, env: &mut Environment) -> Result { // Incant the built-in and set the output self.output = Some(match self.verb.as_str() { @@ -132,6 +183,10 @@ impl Anthology { Ok(self.clone()) } + /// Get the output of a built-in + /// + /// Return the [Output] of a built-in command. This function needed + /// for compatibility with [std::process::Command]. pub fn wait_with_output(&self) -> Result { match &self.output { Some(output) => Ok(output.clone()), diff --git a/src/poem/anthology/alias.rs b/src/poem/anthology/alias.rs index 0746b59..fdd1224 100644 --- a/src/poem/anthology/alias.rs +++ b/src/poem/anthology/alias.rs @@ -5,8 +5,8 @@ use std::process::{ExitStatus, Output}; /// alias /// -/// The builtin `alias` command. Used to monikers for other verbs, or entire -/// verses. +/// The builtin `alias` command. Used to monikers for other verbs, or +/// entire verses. /// /// # Shell Example /// ```sh diff --git a/src/poem/anthology/cd.rs b/src/poem/anthology/cd.rs index bdf04f6..4427536 100644 --- a/src/poem/anthology/cd.rs +++ b/src/poem/anthology/cd.rs @@ -5,13 +5,16 @@ use std::process::{ExitStatus, Output}; /// cd /// /// The builtin `cd` command. Used to change directories. This must be -/// implemented by the shell, since the `pwd` is context sensitive within a -/// process. If no arguments are given, `cd` will take the user back to their -/// home directory (i.e. `~`). +/// implemented by the shell, since the present working directory +/// (`pwd`) is context sensitive within a process. If no arguments are +/// given, `cd` will take the user back to their home directory (i.e. +/// `~` / `$HOME`). /// /// # Shell Example /// ```sh /// cd ~/.config # Change into /home//.config +/// cd / # Change into the root directory +/// cd # Change into the home directory /// ``` pub fn incant(clause: &Option>, uerr: bool) -> Output { let status; diff --git a/src/poem/anthology/export.rs b/src/poem/anthology/export.rs index 35a24ae..4c8e46d 100644 --- a/src/poem/anthology/export.rs +++ b/src/poem/anthology/export.rs @@ -5,8 +5,8 @@ use std::process::{ExitStatus, Output}; /// export /// -/// The builtin `export` command. Used to set global environment variables for -/// the current instance of the shell. +/// The builtin `export` command. Used to set global environment +/// variables for the current instance of the shell. /// /// # Aliases /// * export diff --git a/src/poem/anthology/source.rs b/src/poem/anthology/source.rs index 0ed759c..fc27caf 100644 --- a/src/poem/anthology/source.rs +++ b/src/poem/anthology/source.rs @@ -6,8 +6,8 @@ use std::process::{ExitStatus, Output}; /// source /// -/// The builtin `source` command. Used to change the shell's global environment -/// state via a `.sh` or `.dwvsh` file. +/// The built-in `source` command. Used to change the shell's global +/// environment state via a `.sh` or `.dwvsh` file. /// /// # Shell Examples /// ```sh diff --git a/src/poem/anthology/which.rs b/src/poem/anthology/which.rs index 0872dda..9a1708a 100644 --- a/src/poem/anthology/which.rs +++ b/src/poem/anthology/which.rs @@ -4,6 +4,18 @@ use crate::poem::Verse; use std::os::unix::process::ExitStatusExt; use std::process::{ExitStatus, Output}; +/// which +/// +/// The built-in `which` command. Used to check what program would be +/// called when not providing a full path. On Linux, it seems most +/// distros ship with a standalone `which` program. BSD systems, on the +/// other hand, tend to just use the shell built-in. +/// +/// # Shell Examples +/// ```sh +/// which ls # -> /bin/ls +/// which exit # -> shell built-in command +/// ``` pub fn incant(clause: &Option>, uout: bool, uerr: bool, env: &Environment) -> Output { let mut status = 0; let mut out: Vec = Vec::new(); diff --git a/src/poem/elements/rune.rs b/src/poem/elements/rune.rs index 688043d..64e3326 100644 --- a/src/poem/elements/rune.rs +++ b/src/poem/elements/rune.rs @@ -2,57 +2,75 @@ use core::fmt; /// Describes one or two characters from the input /// -/// [Rune]s are a way to mark special characters from the input string (i.e. -/// poetry). Some [Rune]s are special--as they denote the end of a [Verse]-- -/// and are refered to as a Meter. For instance, `Addendum`, `Couplet`, -/// `Quiet`, and `And`, are all meters. Meters also determine how the -/// [Stanza][super::stanza::Stanza] should be interpreted. For instance, a -/// [Stanza][super::stanza::Stanza] that is piped needs to have -/// its `STDOUT` captured (rather than printing out to the terminal), and -/// subsequently sent to the next [Verse] in the [Poem][super::super::Poem]. -/// -/// # Values -/// * `None` - A shell command with no additional actions (the end of a poem) -/// * `Pause` - The space character, to dilineate words (` `) -/// * `Path` - The forward slash character, to dilineate paths (`/`) -/// * `Remark` - Indicates a single line comment (`#`) -/// * `String` - Interpret all character as one large -/// [Word][super::word::Word] (`'` or `"`) -/// * `Poem` - A subcommand to run first (`\``) -/// * `Read` - Read files into STDIN (`<`) -/// * `Write` - Write STDOUT to a file (`>`) -/// * `Write2` - Write STDERR to a file (`2>`) -/// * `WriteAll` - Write both STDOUT and STDERR to a file (`&>`) -/// * `Addendum` - Append STDOUT to a file (`>>`) -/// * `Addendum2` - Append STDERR to a file (`2>>`) -/// * `AddendumAll` - Append both STDOUT and STDERR to a file (`&>>`) -/// * `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` - String commands together on a single line (`;`) -/// * `Home` - Interpret `~` as `$HOME` -/// * `Else` - Any other character +/// [Rune]s are a way to mark special characters from the input string +/// (i.e. poetry). Some [Rune]s are special--as they denote the end of a +/// [Verse][crate::poem::Verse]--and are refered to as a Meter. For +/// instance, `Addendum`, `Couplet`, `Quiet`, and `And`, are all meters. +/// Meters also determine how the [Stanza][super::stanza::Stanza] should +/// be interpreted. For instance, a [Stanza][super::stanza::Stanza] that +/// is piped needs to have its `STDOUT` captured (rather than printing +/// out to the terminal), and subsequently sent to the next +/// [Verse][crate::poem::Verse] in the [Poem][super::super::Poem]. #[derive(Debug, PartialEq, Eq, Copy, Clone)] pub enum Rune { - None, // No meter (the end of a poem) - Pause, // A space - Path, // A forward slash - Remark, // A comment - String, // Interpret the following as one large [Word] - Poem, // Run a sub-poem before the main one - Read, // Read files into STDIN - Write, // Send STDOUT to a file - Write2, // Send STDERR to a file - WriteAll, // Send STDOUT and STDERR to a file - Addendum, // Append STDOUT to a file - Addendum2, // Append STDERR to a file - AddendumAll, // Append STDOUT and STDERR to a file - Couplet, // Pipe the output of this command into the next - Quiet, // Fork the command into the background - And, // Run the next command only if this succeeds - Continue, // Run the next command, even if this doesn't succeed - Home, // Interpret '~' as $HOME - Else, // Any other character + /// A shell command with no additional actions (the end of a poem) + None, + + /// The space character, to dilineate words (`' '`) + Pause, + + /// The forward slash character, to dilineate paths (`/`) + Path, + + /// Indicates a single line comment (`#`) + Remark, + + /// Interpret all characters as one large [Word][super::word::Word] + /// (`'` or `"`) + String, + + /// A subcommand to run first (`\``) + Poem, + + /// Read files into STDIN (`<`) + Read, + + /// Write STDOUT to a file (`>`) + Write, + + /// Write STDERR to a file (`2>`) + Write2, + + /// Write both STDOUT and STDERR to a file (`&>`) + WriteAll, + + /// Append STDOUT to a file (`>>`) + Addendum, + + /// Append STDERR to a file (`2>>`) + Addendum2, + + /// Append both STDOUT and STDERR to a file (`&>>`) + AddendumAll, + + /// Pipe the output of this command into the next (`|`) + Couplet, + + /// Fork the called process into the background (`&`) + Quiet, + + /// Run the next command, only if this one succeeds (`&&`) + And, + + /// Run the next command, regardless of whether or not this command + /// succeeds (`;` or a newline in a file) + Continue, + + /// Interpret `~` as `$HOME` + Home, + + /// Any other character + Else, } impl fmt::Display for Rune { diff --git a/src/poem/elements/stanza.rs b/src/poem/elements/stanza.rs index d58d080..b5acf32 100644 --- a/src/poem/elements/stanza.rs +++ b/src/poem/elements/stanza.rs @@ -1,10 +1,10 @@ /// The actionable part of a [Verse][super::verse::Verse] /// -/// Each [Stanza] has two parts, a `verb()` and a `clause()`. The `verb()` is -/// the program, or path to the program to call, while the `clause()` contains -/// arguments to pass to that program. +/// Each [Stanza] has two parts, a `verb()` and a `clause()`. The +/// `verb()` is the program, or path to the program to call, while the +/// `clause()` contains arguments to pass to that program. /// -/// The [Stanza] is just stored as a [Vec] of [String]s, where the verb is the -/// first entry in the vector (i.e. `stanza[0]`) and the clause the the -/// remainder of the vector (i.e. `stanza[1..]`). +/// The [Stanza] is just stored as a [Vec] of [String]s, where the verb +/// is the first entry in the vector (i.e. `stanza[0]`) and the clause +/// the the remainder of the vector (i.e. `stanza[1..]`). pub type Stanza = Vec; 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, + + /// 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, + + /// 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 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>(); + /// let command_full_path = vec!["/bin/ls"] + /// .into_iter() + /// .map(String::from) + /// .collect>(); /// - /// let command_success = vec!["cargo", "build", "--release"] + /// let command_on_path = vec!["cargo", "build", "--release"] /// .into_iter() /// .map(String::from) /// .collect>(); /// - /// let command_fail = vec!["make", "-j8"] - /// .into_iter() - /// .map(String::from) - /// .collect>(); + /// let command_built_in = vec!["alias", "g=git"] + /// .into_iter() + /// .map(String::from) + /// .collect>(); + /// + /// let command_no_exist = vec!["thisdoesntexist"] + /// .into_iter() + /// .map(String::from) + /// .collect>(); + /// + /// 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) -> Option { // 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, diff --git a/src/poem/elements/verse/logic.rs b/src/poem/elements/verse/logic.rs index f5efdee..e7ed4df 100644 --- a/src/poem/elements/verse/logic.rs +++ b/src/poem/elements/verse/logic.rs @@ -1,3 +1,17 @@ +/// Spawn a program +/// +/// This macro provides a common interface for running system programs, +/// as well as built-in shell commands. This is possible, since the +/// shell's homebrew facilities for running built-ins mimic the +/// interface of [std::process::Command]. See +/// [crate::poem::anthology::Anthology] for the implementation details. +/// +/// First, the macro sets the arguments for the command. Next, it +/// determines the whether or not text should be piped in/out of the +/// command. The process is spawned, then it determines what to do based +/// on the [crate::poem::elements::verse::Verse]'s meter (wait, fork to +/// background, or capture STDOUT). Finally, the macro performs any IO +/// functions (i.e. writing/appending STDOUT or STDERR to a file). #[macro_export] macro_rules! incant { ($verb:expr, $command:expr, $out:expr, $pids:expr, $env:expr, $self:expr) => {{ diff --git a/src/poem/elements/word.rs b/src/poem/elements/word.rs index dd088e0..f51dc7d 100644 --- a/src/poem/elements/word.rs +++ b/src/poem/elements/word.rs @@ -1,2 +1,3 @@ -/// A (typically) space dilineated piece of a [Stanza][super::stanza::Stanza] +/// A (typically) space dilineated piece of a +/// [Stanza][super::stanza::Stanza] pub type Word = Vec; diff --git a/src/poem/read.rs b/src/poem/read.rs index 0418738..6d7550b 100644 --- a/src/poem/read.rs +++ b/src/poem/read.rs @@ -8,10 +8,35 @@ use crate::compose::Environment; use crate::{poem, remark, string}; use parse::next; +/// Custom errors for the parser ([read()][crate::poem::read]) #[derive(Debug, PartialEq, Eq)] pub enum Mishap { + /// Generic parser error ParseMishap(usize, usize, char), + + /// IO operation parse errors + /// + /// Raised when an IO operation is specified, but a filepath was not + /// given. + /// + /// # Examples + /// ```sh + /// cat < # No file specified for Rune::Read + /// cat file.txt >> # No file specified for Rune::Addendum + /// ``` IOMishap(usize, usize, char), + + /// Missing end character + /// + /// Some [Rune]s consists of two characters, that may contain other + /// characters between them (i.e. [String][Rune::String]). This is + /// raised when the ending character was left out. + /// + /// # Examples + /// ```sh + /// echo 'Hello # Ending ' character is missing + /// mv file.txt hello.txt" # Beginning " character is missing + /// ``` PartialMishap(usize, usize, char), } @@ -55,13 +80,14 @@ impl Appendable for Poem { /// Push a [Verse] to the [Poem] /// - /// Push a [Verse] to the [Poem] after checking that the [Verse] is not - /// empty. It also: + /// Push a [Verse] to the [Poem] after checking that the [Verse] is + /// not empty. It also: /// - sets the meter of the [Verse], /// - determines the couplet status of the [Verse], /// - and checks for aliases associated the the [Verse]'s verb. /// - /// Once the [Verse] is pushed to the [Poem], the verse stack is cleared. + /// Once the [Verse] is pushed to the [Poem], the verse stack is + /// cleared. /// /// # Examples /// ``` @@ -157,9 +183,10 @@ impl Readable for Poem { /// Parse a [Poem] from a raw [String] input /// /// Takes a shell command/program or file and converts it to a - /// machine-runnable [Poem]. If there is a parse error, [Poem::read] may - /// return a [Mishap]. See [Poem::recite][super::recite] or [Verse::incant] - /// for how each [Verse] in a [Poem] is called. + /// machine-runnable [Poem]. If there is a parse error, + /// [read()][Poem::read] may return a [Mishap]. See + /// [recite()][crate::poem::recite] or [incant()][Verse::incant] for + /// how each [Verse] in a [Poem] is called. fn read(poetry: String, env: &mut Environment) -> Result { // Get all the characters in the input string as an iterator let mut chars = poetry.chars().into_iter(); diff --git a/src/poem/recite.rs b/src/poem/recite.rs index 7ceecca..89f71c8 100644 --- a/src/poem/recite.rs +++ b/src/poem/recite.rs @@ -17,11 +17,12 @@ pub trait Reciteable { impl Reciteable for Poem { /// Recite a [Poem] /// - /// Runs the commands specified in all verses for a given [Poem]. See - /// [crate::poem::Verse::incant] for more details on how processes are - /// forked. In addition to running each [crate::poem::Verse], - /// [Poem::recite] also checks for the presence of environment variables, - /// as well as sub-poems, before running the [crate::poem::Verse]'s + /// Runs the commands specified in all verses for a given [Poem]. + /// See [incant()][crate::poem::Verse::incant] for more details on + /// how processes are forked. In addition to running each + /// [Verse][crate::poem::Verse], [recite()][Poem::recite] also + /// checks for the presence of environment variables, as well as + /// internal poems, before running the [Verse][crate::poem::Verse]'s /// [Stanza]. fn recite(&self, env: &mut Environment) -> Result, io::Error> { // Variable for storing the output of a piped verse -- cgit v1.2.3