From ad58df114217d3da835542ae1d261b17f942dfaf Mon Sep 17 00:00:00 2001
From: vodofrede <frederik@palmoe.dk>
Date: Wed, 24 May 2023 22:24:43 +0200
Subject: [PATCH] v1.3

---
 Cargo.toml         |  4 ++--
 README.md          | 48 ++++++++++++++++++++++++++++------------------
 src/bin/sandbox.rs |  5 +++++
 src/lib.rs         |  6 ++++--
 4 files changed, 40 insertions(+), 23 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 53ad526..0ae8c5f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,8 +1,8 @@
 [package]
 name = "eyes"
-version = "1.3.1"
+version = "1.3"
 edition = "2018"
-description = "A simpler way to parse using human-readable templates"
+description = "Parse and convert strings using human-readable templates."
 license="BSD-3-Clause"
 homepage = "https://git.palmoe.dk/vodofrede/eyes/"
 repository = "https://git.palmoe.dk/vodofrede/eyes/"
diff --git a/README.md b/README.md
index 2d6f109..247be5e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # eyes
 
-A simpler way to parse using human-readable templates.
+Parse and convert strings using human-readable templates.
 
 The crate's primary purpose is parsing challenge inputs for [Advent of Code](https://adventofcode.com) challenges. It currently provides limited functionality, but more options may be added provided they are useful additions for parsing slightly more complicated formats.
 
@@ -13,32 +13,42 @@ The only special characters in templates are curly brackets ('{}'). These act as
 ## Examples:
 
 ```rust
-#[macro_use] extern crate eyes; // not normally necessary
-fn main() {
-    let input = "#lol @ 338,7643: 20.2x24.5";
-    let template = "#{} @ {},{}: {}x{}";
+use eyes::parse;
 
-    let (id, x, y, w, h) = eyes::parse!(input, template, String, isize, isize, f64, f64);
+let input = "#lol @ 338,7643: 20.2x24.5";
+let template = "#{} @ {},{}: {}x{}";
+let (id, x, y, w, h) = parse!(input, template, String, isize, isize, f64, f64);
 
-    assert_eq!((id.as_str(), x, y, w, h), ("lol", 338, 7643, 20.2, 24.5));
-}
+assert_eq!((id.as_str(), x, y, w, h), ("lol", 338, 7643, 20.2, 24.5));
 ```
 
-**eyes** will try to expand capture groups, so that the following example also works as expected:
+**eyes** will match capture groups greedily and expand them as far as possible, so that the following example also works as expected:
 
 ```rust
-#[macro_use] extern crate eyes; // not normally necessary
-fn main() {
-    let input = "turn off 660,55 through 986,197";
-    let template = "{} {},{} through {},{}";
+use eyes::parse;
 
-    let (op, x1, y1, x2, y2) = eyes::parse!(input, template, String, usize, usize, usize, usize);
+let input = "turn off 660,55 through 986,197";
+let template = "{} {},{} through {},{}";
+let (op, x1, y1, x2, y2) = parse!(input, template, String, usize, usize, usize, usize);
 
-    assert_eq!(
-        (op.as_str(), x1, y1, x2, y2),
-        ("turn off", 660, 55, 986, 197)
-    );
-}
+assert_eq!(
+    (op.as_str(), x1, y1, x2, y2),
+    ("turn off", 660, 55, 986, 197)
+);
 ```
 
 Notice that "turn off" is captured correctly, even though it contains a space.
+
+For error handling, the [`try_parse`] macro is provided which can be very useful in parsing potentially malformed input:
+
+```rust
+use eyes::try_parse;
+
+let input = "1 2\n3,4\n5 6";
+let result = input
+    .lines()
+    .filter_map(|line| try_parse!(line, "{} {}", i64, i64))
+    .collect::<Vec<_>>();
+
+assert_eq!(vec![(1, 2), (5, 6)], result);
+```
diff --git a/src/bin/sandbox.rs b/src/bin/sandbox.rs
index e5c42a1..f011c54 100644
--- a/src/bin/sandbox.rs
+++ b/src/bin/sandbox.rs
@@ -1,7 +1,12 @@
+use eyes::parse;
+
 fn main() {
     if let Some((a, b, c)) = eyes::try_parse!("1 2,3", "{} {},{}", u8, u8, u8) {
         assert!(a == 1 && b == 2 && c == 3);
     } else {
         unreachable!("This should not happen, as the pattern is matchable to the input");
     }
+
+    let input = "1,2, 3";
+    parse!(input, "{},{}, {}", i64, i64, i64);
 }
diff --git a/src/lib.rs b/src/lib.rs
index 4cf2664..47965bc 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -5,7 +5,7 @@
 
 /// A list of captures, created by calling [`Captures::new()`] with the input and template strings.
 ///
-/// An easier way to use this struct is with the [`eyes::parse`] and [`eyes::try_parse`] macros, which allow for automatic type conversion of captures.
+/// An easier way to use this struct is with the [`parse`] and [`try_parse`] macros, which allow for automatic type conversion of captures.
 pub struct Captures<'a> {
     captures: Vec<&'a str>,
 }
@@ -137,7 +137,9 @@ macro_rules! try_parse {
 #[macro_export]
 macro_rules! parse {
     ($input: expr, $pattern: tt, $($type:ty),*) => {
-        $crate::try_parse!($input, $pattern, $($type),*).unwrap()
+        {
+            $crate::try_parse!($input, $pattern, $($type),*).unwrap()
+        }
     };
 }