implemented column() to return a ColumnDoc for a specified column

Author: RPG-Alex

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "sql_docs"
-version = "1.0.4"
+version = "1.0.5"
 edition = "2024"
 description = "A crate for parsing comments from sql files and using them for documentation generation"
 documentation = "https://docs.rs/sql_docs"
@@ -25,6 +25,7 @@ fuzzing = []
 sqlparser = "0.60.0"
 
 
+
 [lints.rust]
 missing_docs = "forbid"
 unreachable_patterns = "forbid"

Cargo.toml

@@ -125,6 +125,28 @@ impl TableDoc {
         &mut self.columns
     }
 
+    /// Method for finding a specific [`ColumnDoc`] from `schema` and table `name`
+    ///
+    /// # Parameters
+    /// - the column's `name` as a [`str`]
+    ///
+    /// # Errors
+    /// - Will return [`DocError::ColumnNotFound`] if the expected table is not found
+    pub fn column(&self, column: &str) -> Result<&ColumnDoc, DocError> {
+        let matches = self
+            .columns
+            .iter()
+            .filter(|col_doc| col_doc.name() == column)
+            .collect::<Vec<&ColumnDoc>>();
+        match matches.as_slice() {
+            [] => Err(DocError::ColumnNotFound { name: column.to_owned() }),
+            [only] => Ok(*only),
+            _ => Err(DocError::DuplicateColumnsFound {
+                columns: matches.into_iter().cloned().collect(),
+            }),
+        }
+    }
+
     /// Getter method for retrieving the table's [`Path`]
     #[must_use]
     pub fn path(&self) -> Option<&Path> {
@@ -851,7 +873,7 @@ CREATE TABLE posts (
         assert_eq!(got, expected);
     }
     #[test]
-    fn table_doc_path_getter_returns_expected_value() {
+    fn test_table_doc_path_getter_returns_expected_value() {
         let mut table = TableDoc::new(None, "users".to_owned(), None, Vec::new(), None);
         assert_eq!(table.path(), None);
         let pb = PathBuf::from("some/dir/file.sql");
@@ -861,4 +883,25 @@ CREATE TABLE posts (
         table.set_path(no_path);
         assert_eq!(table.path(), None);
     }
+
+    #[test]
+    fn test_table_doc_column() {
+        let table = TableDoc::new(
+            None,
+            "users".to_owned(),
+            None,
+            vec![
+                ColumnDoc::new("id".to_owned(), None),
+                ColumnDoc::new("username".to_owned(), None),
+            ],
+            None,
+        );
+
+        let col = table.column("id").unwrap_or_else(|_| panic!("Column 'id' should exist"));
+        assert_eq!(col.name(), "id");
+
+        let missing = table.column("nope");
+        assert!(missing.is_err());
+        assert!(matches!(missing, Err(DocError::ColumnNotFound { name }) if name == "nope"));
+    }
 }

src/docs.rs

@@ -1,6 +1,9 @@
 //! Error types returned by this crate’s public APIs.
 
-use crate::{comments::CommentError, docs::TableDoc};
+use crate::{
+    comments::CommentError,
+    docs::{ColumnDoc, TableDoc},
+};
 use core::fmt;
 use sqlparser::parser::ParserError;
 use std::{error, fmt::Debug};
@@ -29,11 +32,21 @@ pub enum DocError {
         /// The name of the table that was not found
         name: String,
     },
+    /// Column not found when searching [`crate::docs::TableDoc`]
+    ColumnNotFound {
+        /// The name of the column not found
+        name: String,
+    },
     /// Duplicate tables with same name were found when searching [`crate::SqlDoc`]
     DuplicateTablesFound {
         /// `Vec` of the [`TableDoc`] for each duplicate table found
         tables: Vec<TableDoc>,
     },
+    /// Duplicate columns with same name were found when searching a single [`TableDoc`]
+    DuplicateColumnsFound {
+        /// `Vec` of the [`crate::docs::ColumnDoc`] for each duplicate table found
+        columns: Vec<ColumnDoc>,
+    },
 }
 
 impl fmt::Display for DocError {
@@ -48,13 +61,21 @@ impl fmt::Display for DocError {
                 write!(f, "{message} at line {line}, column {column}")
             }
             Self::TableNotFound { name } => write!(f, "Table not found in SqlDoc: {name}"),
+            Self::ColumnNotFound { name } => write!(f, "Column not found in TableDoc: {name}"),
             Self::DuplicateTablesFound { tables } => {
                 writeln!(f, "Duplicate tables found:")?;
                 for t in tables {
                     writeln!(f, "{t}")?;
                 }
                 Ok(())
             }
+            Self::DuplicateColumnsFound { columns } => {
+                writeln!(f, "Duplicate columns found:")?;
+                for t in columns {
+                    writeln!(f, "{t}")?;
+                }
+                Ok(())
+            }
         }
     }
 }
@@ -67,7 +88,9 @@ impl error::Error for DocError {
             Self::SqlParserError(e) => Some(e),
             Self::InvalidObjectName { .. }
             | Self::TableNotFound { .. }
-            | Self::DuplicateTablesFound { .. } => None,
+            | Self::ColumnNotFound { .. }
+            | Self::DuplicateTablesFound { .. }
+            | Self::DuplicateColumnsFound { .. } => None,
         }
     }
 }
@@ -222,4 +245,34 @@ mod tests {
         let dup = DocError::DuplicateTablesFound { tables: vec![] };
         assert!(dup.source().is_none());
     }
+
+    #[test]
+    fn test_doc_error_display_column_not_found() {
+        let e = DocError::ColumnNotFound { name: "id".to_string() };
+        assert_eq!(e.to_string(), "Column not found in TableDoc: id");
+    }
+
+    #[test]
+    fn test_doc_error_display_duplicate_columns_found() {
+        use crate::docs::ColumnDoc;
+
+        let c1 = ColumnDoc::new("dup_col".to_string(), None);
+        let c2 = ColumnDoc::new("dup_col".to_string(), None);
+        let e = DocError::DuplicateColumnsFound { columns: vec![c1, c2] };
+
+        let s = e.to_string();
+        assert!(s.contains("Duplicate columns found:"), "output was: {s}");
+        assert!(s.contains("dup_col"), "output was: {s}");
+    }
+
+    #[test]
+    fn test_doc_error_source_none_for_column_variants() {
+        use std::error::Error as _;
+
+        let not_found = DocError::ColumnNotFound { name: "x".to_string() };
+        assert!(not_found.source().is_none());
+
+        let dup = DocError::DuplicateColumnsFound { columns: vec![] };
+        assert!(dup.source().is_none());
+    }
 }