feat!: Simplify explode (no more explode_from_scoper), improve docs

src/actions/mod.rs

@@ -44,6 +44,7 @@ where
 }
 
 /// Any [`Action`] that can be boxed.
+// https://www.reddit.com/r/rust/comments/droxdg/why_arent_traits_impld_for_boxdyn_trait/
 impl Action for Box<dyn Action> {
     fn act(&self, input: &str) -> String {
         self.as_ref().act(input)

src/actions/replace/mod.rs

@@ -12,7 +12,7 @@ use super::Action;
 /// use srgn::scoping::{view::ScopedViewBuilder, regex::Regex};
 ///
 /// let scoper = Regex::new(RegexPattern::new(r"[^a-zA-Z0-9]+").unwrap());
-/// let mut view = ScopedViewBuilder::new("hyphenated-variable-name").explode_from_scoper(
+/// let mut view = ScopedViewBuilder::new("hyphenated-variable-name").explode(
 ///     &scoper
 /// ).build();
 ///
@@ -31,7 +31,7 @@ use super::Action;
 /// // A Unicode character class category. See also
 /// // https://github.com/rust-lang/regex/blob/061ee815ef2c44101dba7b0b124600fcb03c1912/UNICODE.md#rl12-properties
 /// let scoper = Regex::new(RegexPattern::new(r"\p{Emoji}").unwrap());
-/// let mut view = ScopedViewBuilder::new("Party! 😁 💃 🎉 🥳 So much fun! ╰(°▽°)╯").explode_from_scoper(
+/// let mut view = ScopedViewBuilder::new("Party! 😁 💃 🎉 🥳 So much fun! ╰(°▽°)╯").explode(
 ///     &scoper
 /// ).build();
 ///

src/main.rs

@@ -9,6 +9,8 @@ use srgn::actions::Titlecase;
 use srgn::actions::Upper;
 #[cfg(feature = "symbols")]
 use srgn::actions::{Symbols, SymbolsInversion};
+use srgn::scoping::literal::LiteralError;
+use srgn::scoping::regex::RegexError;
 use srgn::{
     actions::Action,
     scoping::{
@@ -19,7 +21,7 @@ use srgn::{
         },
         literal::Literal,
         regex::Regex,
-        view::{ScopedViewBuilder, ScoperBuildError},
+        view::ScopedViewBuilder,
         Scoper,
     },
 };
@@ -67,7 +69,7 @@ fn main() -> Result<(), String> {
     debug!("Building view.");
     let mut builder = ScopedViewBuilder::new(&buf);
     for scoper in scopers {
-        builder = builder.explode(|s| scoper.scope(s));
+        builder = builder.explode(&scoper);
     }
     let mut view = builder.build();
     debug!("Done building view: {view:?}");
@@ -110,6 +112,25 @@ fn main() -> Result<(), String> {
     Ok(())
 }
 
+#[derive(Debug)]
+pub enum ScoperBuildError {
+    EmptyScope,
+    RegexError(RegexError),
+    LiteralError(LiteralError),
+}
+
+impl From<LiteralError> for ScoperBuildError {
+    fn from(e: LiteralError) -> Self {
+        Self::LiteralError(e)
+    }
+}
+
+impl From<RegexError> for ScoperBuildError {
+    fn from(e: RegexError) -> Self {
+        Self::RegexError(e)
+    }
+}
+
 fn assemble_scopers(args: &cli::Cli) -> Result<Vec<Box<dyn Scoper>>, ScoperBuildError> {
     let mut scopers: Vec<Box<dyn Scoper>> = Vec::new();
 

src/scoping/literal.rs

@@ -88,7 +88,7 @@ mod tests {
     ) {
         let builder = crate::scoping::view::ScopedViewBuilder::new(input);
         let literal = Literal::try_from(literal.to_owned()).unwrap();
-        let actual = builder.explode_from_scoper(&literal).build();
+        let actual = builder.explode(&literal).build();
 
         assert_eq!(actual, expected);
     }

src/scoping/mod.rs

@@ -1,15 +1,28 @@
 //! Items for defining the scope actions are applied within.
 
-use self::scope::ROScopes;
+use crate::scoping::scope::ROScopes;
+#[cfg(doc)]
+use crate::scoping::{scope::Scope, view::ScopedView};
 use std::fmt;
 
+/// Create views using programming language grammar-aware types.
 pub mod langs;
+/// Create views using string literals.
 pub mod literal;
+/// Create views using regular expressions.
 pub mod regex;
+/// [`Scope`] and its various wrappers.
 pub mod scope;
+/// [`ScopedView`] and its related types.
 pub mod view;
 
+/// An item capable of scoping down a given input into individual scopes.
 pub trait Scoper {
+    /// Scope the given `input`.
+    ///
+    /// After application, the returned scopes are a collection of either in-scope or
+    /// out-of-scope parts of the input. Assembling them back together should yield the
+    /// original input.
     fn scope<'viewee>(&self, input: &'viewee str) -> ROScopes<'viewee>;
 }
 
@@ -18,3 +31,19 @@ impl fmt::Debug for dyn Scoper {
         f.debug_struct("Scoper").finish()
     }
 }
+
+impl<T> Scoper for T
+where
+    T: Fn(&str) -> ROScopes,
+{
+    fn scope<'viewee>(&self, input: &'viewee str) -> ROScopes<'viewee> {
+        self(input)
+    }
+}
+
+// https://www.reddit.com/r/rust/comments/droxdg/why_arent_traits_impld_for_boxdyn_trait/
+impl Scoper for Box<dyn Scoper> {
+    fn scope<'viewee>(&self, input: &'viewee str) -> ROScopes<'viewee> {
+        self.as_ref().scope(input)
+    }
+}

src/scoping/regex.rs

@@ -210,7 +210,7 @@ mod tests {
     ) {
         let builder = crate::scoping::view::ScopedViewBuilder::new(input);
         let regex = Regex::new(RegexPattern::new(pattern).unwrap());
-        let actual = builder.explode_from_scoper(&regex).build();
+        let actual = builder.explode(&regex).build();
 
         assert_eq!(actual, expected);
     }