From 54081c1b0f2b88386de85e4243fb27426af3abd3 Mon Sep 17 00:00:00 2001
From: Filip Tibell <filip.tibell@gmail.com>
Date: Sat, 20 Apr 2024 22:54:12 +0200
Subject: [PATCH] Add docs on public functions, fix captures being returned
 even if not found

---
 src/lune/builtins/regex/captures.rs | 18 +++++++++++++++---
 src/lune/builtins/regex/matches.rs  |  6 ++++++
 src/lune/builtins/regex/regex.rs    |  7 +++++++
 3 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/lune/builtins/regex/captures.rs b/src/lune/builtins/regex/captures.rs
index 4dc67da..a1283e9 100644
--- a/src/lune/builtins/regex/captures.rs
+++ b/src/lune/builtins/regex/captures.rs
@@ -16,14 +16,26 @@ self_cell! {
     }
 }
 
+/**
+    A wrapper over the `regex::Captures` struct that can be used from Lua.
+*/
 pub struct LuaCaptures {
     inner: LuaCapturesInner,
 }
 
 impl LuaCaptures {
-    pub fn new(pattern: &Regex, text: String) -> Self {
-        Self {
-            inner: LuaCapturesInner::new(Arc::from(text), |owned| pattern.captures(owned.as_str())),
+    /**
+        Create a new `LuaCaptures` instance from a `Regex` pattern and a `String` text.
+
+        Returns `Some(_)` if captures were found, `None` if no captures were found.
+    */
+    pub fn new(pattern: &Regex, text: String) -> Option<Self> {
+        let inner =
+            LuaCapturesInner::new(Arc::from(text), |owned| pattern.captures(owned.as_str()));
+        if inner.borrow_dependent().is_some() {
+            Some(Self { inner })
+        } else {
+            None
         }
     }
 
diff --git a/src/lune/builtins/regex/matches.rs b/src/lune/builtins/regex/matches.rs
index 60348e8..d3b1fa9 100644
--- a/src/lune/builtins/regex/matches.rs
+++ b/src/lune/builtins/regex/matches.rs
@@ -3,6 +3,9 @@ use std::{ops::Range, sync::Arc};
 use mlua::prelude::*;
 use regex::Match;
 
+/**
+    A wrapper over the `regex::Match` struct that can be used from Lua.
+*/
 pub struct LuaMatch {
     text: Arc<String>,
     start: usize,
@@ -10,6 +13,9 @@ pub struct LuaMatch {
 }
 
 impl LuaMatch {
+    /**
+        Create a new `LuaMatch` instance from a `String` text and a `regex::Match`.
+    */
     pub fn new(text: Arc<String>, matched: Match) -> Self {
         Self {
             text,
diff --git a/src/lune/builtins/regex/regex.rs b/src/lune/builtins/regex/regex.rs
index b255caa..b40331d 100644
--- a/src/lune/builtins/regex/regex.rs
+++ b/src/lune/builtins/regex/regex.rs
@@ -5,11 +5,18 @@ use regex::Regex;
 
 use super::{captures::LuaCaptures, matches::LuaMatch};
 
+/**
+    A wrapper over the `regex::Regex` struct that can be used from Lua.
+*/
+#[derive(Debug, Clone)]
 pub struct LuaRegex {
     inner: Regex,
 }
 
 impl LuaRegex {
+    /**
+        Create a new `LuaRegex` instance from a `String` pattern.
+    */
     pub fn new(pattern: String) -> LuaResult<Self> {
         Regex::new(&pattern)
             .map(|inner| Self { inner })