Added leading collection types to `SqlDocBuilder

Author: RPG-Alex

src/comments.rs

@@ -387,7 +387,7 @@ impl Comments {
         Self::new(comments)
     }
 
-    /// Collapse this collection separate with `\n` into a single a single comment.
+    /// Collapse this collection of comments and separate each comment with `\n` as a single [`Comment`].
     #[must_use]
     pub fn collapse_comments(self) -> Option<Comment> {
         let mut iter = self.comments.into_iter();

src/docs.rs

@@ -5,7 +5,11 @@ use std::path::{Path, PathBuf};
 
 use sqlparser::ast::{Ident, ObjectName, ObjectNamePart, Spanned, Statement};
 
-use crate::{ast::ParsedSqlFile, comments::Comments, error::DocError};
+use crate::{
+    ast::ParsedSqlFile,
+    comments::{Comments, LeadingCommentCapture},
+    error::DocError,
+};
 
 /// Structure for containing the `name` of the `Column` and an [`Option`] for
 /// the comment as a [`String`]
@@ -214,7 +218,11 @@ impl SqlFileDoc {
     /// # Errors
     /// - Returns [`DocError::InvalidObjectName`] if the table name has no identifier components.
     /// - May also propagate other [`DocError`] variants from lower layers in the future.
-    pub fn from_parsed_file(file: &ParsedSqlFile, comments: &Comments) -> Result<Self, DocError> {
+    pub fn from_parsed_file(
+        file: &ParsedSqlFile,
+        comments: &Comments,
+        capture: LeadingCommentCapture,
+    ) -> Result<Self, DocError> {
         let mut tables = Vec::new();
         for statement in file.statements() {
             #[allow(clippy::single_match)]
@@ -224,7 +232,8 @@ impl SqlFileDoc {
                     let mut column_docs = Vec::new();
                     for column in &table.columns {
                         let column_start = column.span().start.line;
-                        let column_leading = comments.leading_comment(column_start);
+                        let column_leading =
+                            comments.leading_comments(column_start, capture).collapse_comments();
                         let column_name = column.name.value.clone();
                         let column_doc = match column_leading {
                             Some(col_comment) => {
@@ -491,10 +500,11 @@ CREATE TABLE posts (
         let set = SqlSource::sql_sources(&base, &[])?;
         let parsed_set = ParsedSqlFileSet::parse_all(set)?;
         let expected_values = expect_values();
+        let capture = crate::comments::LeadingCommentCapture::default();
 
         for file in parsed_set.files() {
             let comments = Comments::parse_all_comments_from_file(file)?;
-            let docs = SqlFileDoc::from_parsed_file(file, &comments);
+            let docs = SqlFileDoc::from_parsed_file(file, &comments, capture);
             let filename = file
                 .file()
                 .path()

src/sql_doc.rs

@@ -8,7 +8,7 @@ use std::{
 
 use crate::{
     ast::ParsedSqlFile,
-    comments::Comments,
+    comments::{Comments, LeadingCommentCapture},
     docs::{SqlFileDoc, TableDoc},
     error::DocError,
     files::SqlFiles,
@@ -29,14 +29,17 @@ pub struct SqlDocBuilder<'a> {
     source: SqlFileDocSource<'a>,
     /// The list of Paths to be ignored for parsing purposes.
     deny: Vec<String>,
-    /// Struct for tracking the settings for flattening multiline comments
+    /// Tracks the chosen setting for flattening multiline comments
     multiline_flat: MultiFlatten,
+    /// Tracks the chosen setting for leading comment collection
+    leading_type: LeadingCommentCapture,
 }
 
 /// Enum for multiline comment flattening.
-#[derive(Debug, Eq, PartialEq)]
+#[derive(Debug, Default, Eq, PartialEq)]
 pub enum MultiFlatten {
     /// Default option, retains multiline structure with `\n`
+    #[default]
     NoFlat,
     /// Sets multiline comments to be flattened and combined without adding formatting
     FlattenWithNone,
@@ -67,15 +70,17 @@ impl SqlDoc {
         SqlDocBuilder {
             source: SqlFileDocSource::Dir(root.as_ref().to_path_buf()),
             deny: Vec::new(),
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         }
     }
     /// Method for generating builder from a [`Path`] of a single file
     pub fn from_path<P: AsRef<Path> + ?Sized>(path: &P) -> SqlDocBuilder<'_> {
         SqlDocBuilder {
             source: SqlFileDocSource::File(path.as_ref().to_path_buf()),
             deny: Vec::new(),
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         }
     }
 
@@ -86,29 +91,32 @@ impl SqlDoc {
                 paths.iter().map(|p| p.as_ref().to_path_buf()).collect(),
             ),
             deny: Vec::new(),
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         }
     }
 
     /// Creates a builder from SQL text (no filesystem path is associated) from a [`str`]
     #[must_use]
-    pub const fn builder_from_str(content: &str) -> SqlDocBuilder<'_> {
+    pub fn builder_from_str(content: &str) -> SqlDocBuilder<'_> {
         SqlDocBuilder {
             source: SqlFileDocSource::FromString(content),
             deny: Vec::new(),
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         }
     }
 
     /// Creates a builder from a vec of tuples containing the `sql` as [`String`] and the path as [`PathBuf`]
     #[must_use]
-    pub const fn builder_from_strs_with_paths(
+    pub fn builder_from_strs_with_paths(
         string_with_path: &[(String, PathBuf)],
     ) -> SqlDocBuilder<'_> {
         SqlDocBuilder {
             source: SqlFileDocSource::FromStringsWithPaths(string_with_path),
             deny: Vec::new(),
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         }
     }
 
@@ -196,25 +204,47 @@ impl SqlDocBuilder<'_> {
         self
     }
 
-    /// Method for flattening the multiline comments without additional formatting
+    /// Flattens the multiline comments without additional formatting
     #[must_use]
     pub fn flatten_multiline(mut self) -> Self {
         self.multiline_flat = MultiFlatten::FlattenWithNone;
         self
     }
 
-    /// Method for flattening the multiline comments with [`String`] containing additional leading line formatting to add, such as punctuation.
+    /// Flattens the multiline comments with [`String`] containing additional leading line formatting to add, such as punctuation.
     #[must_use]
     pub fn flatten_multiline_with(mut self, suffix: &str) -> Self {
         self.multiline_flat = MultiFlatten::Flatten(suffix.to_owned());
         self
     }
-    /// Method to set multiline comments to preserve multiple lines
+    /// Preserves multiline comments line structure
     #[must_use]
     pub fn preserve_multiline(mut self) -> Self {
         self.multiline_flat = MultiFlatten::NoFlat;
         self
     }
+
+    /// Collects only the comment on preceding lines
+    #[must_use]
+    pub const fn collect_single_nearest(mut self) -> Self {
+        self.leading_type = LeadingCommentCapture::SingleNearest;
+        self
+    }
+
+    /// Collects All valid comments on preceding lines
+    #[must_use]
+    pub const fn collect_all_leading(mut self) -> Self {
+        self.leading_type = LeadingCommentCapture::AllLeading;
+        self
+    }
+
+    /// Collects all single line comments at most one multiline comment
+    #[must_use]
+    pub const fn collect_all_single_one_multi(mut self) -> Self {
+        self.leading_type = LeadingCommentCapture::AllSingleOneMulti;
+        self
+    }
+
     /// Builds the [`SqlDoc`]
     ///
     ///
@@ -313,15 +343,17 @@ fn generate_docs_from_file<P: AsRef<Path>>(source: P) -> Result<SqlFileDoc, DocE
     let file = SqlSource::from_path(source.as_ref())?;
     let parsed_file = ParsedSqlFile::parse(file)?;
     let comments = Comments::parse_all_comments_from_file(&parsed_file)?;
-    let docs = SqlFileDoc::from_parsed_file(&parsed_file, &comments)?;
+    let docs =
+        SqlFileDoc::from_parsed_file(&parsed_file, &comments, LeadingCommentCapture::default())?;
     Ok(docs)
 }
 
 fn generate_docs_str(content: &str, path: Option<PathBuf>) -> Result<SqlFileDoc, DocError> {
     let dummy_file = SqlSource::from_str(content.to_owned(), path);
     let parsed_sql = ParsedSqlFile::parse(dummy_file)?;
     let comments = Comments::parse_all_comments_from_file(&parsed_sql)?;
-    let docs = SqlFileDoc::from_parsed_file(&parsed_sql, &comments)?;
+    let docs =
+        SqlFileDoc::from_parsed_file(&parsed_sql, &comments, LeadingCommentCapture::default())?;
     Ok(docs)
 }
 
@@ -346,6 +378,7 @@ mod tests {
 
     use crate::{
         SqlDoc,
+        comments::LeadingCommentCapture,
         docs::{ColumnDoc, TableDoc},
         error::DocError,
         sql_doc::{MultiFlatten, SqlDocBuilder},
@@ -568,7 +601,8 @@ mod tests {
         let expected_builder = SqlDocBuilder {
             source: crate::sql_doc::SqlFileDocSource::File(PathBuf::from("path")),
             deny: vec!["path1".to_owned(), "path2".to_owned()],
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         };
         assert_eq!(actual_builder, expected_builder);
     }
@@ -744,7 +778,8 @@ mod tests {
         let expected = SqlDocBuilder {
             source: crate::sql_doc::SqlFileDocSource::FromString(content),
             deny: vec![],
-            multiline_flat: MultiFlatten::NoFlat,
+            multiline_flat: MultiFlatten::default(),
+            leading_type: LeadingCommentCapture::default(),
         };
 
         assert_eq!(actual, expected);