Comment Structure Defined

Author: RPG-Alex

src/ast.rs

@@ -0,0 +1,70 @@
+//! Module for parsing the SQL and then using the resulting AST to walk back and
+//! check for comments
+use std::path::Path;
+
+use sqlparser::{
+    ast::Statement,
+    dialect::GenericDialect,
+    parser::{Parser, ParserError},
+};
+
+use crate::files::{SqlFile, SqlFileSet};
+
+/// A single SQL file plus all [`Statement`].
+pub struct ParsedSqlFile {
+    file: SqlFile,
+    statements: Vec<Statement>,
+}
+
+impl ParsedSqlFile {
+    /// Parses all statements from the specified sql file
+    ///
+    /// # Parameters
+    /// - `file` is the [`SqlFile`] that will be parsed
+    ///
+    /// # Errors
+    /// - [`ParserError`] is returned for any errors parsing
+    pub fn parse(file: SqlFile) -> Result<Self, ParserError> {
+        let dialect = GenericDialect {};
+        let statements = Parser::parse_sql(&dialect, file.content())?;
+        Ok(Self { file, statements })
+    }
+
+    /// Getter method for returning the current object's file's path
+    #[must_use]
+    pub fn path(&self) -> &Path {
+        self.file.path()
+    }
+
+    /// Getter method for returning the vector of all statements [`Statement`]
+    #[must_use]
+    pub fn statements(&self) -> &[Statement] {
+        &self.statements
+    }
+}
+
+/// Struct to contain the vector of parsed SQL files
+pub struct ParsedSqlFileSet {
+    files: Vec<ParsedSqlFile>,
+}
+
+impl ParsedSqlFileSet {
+    /// Method that parses all members in a [`SqlFileSet`]
+    ///
+    /// # Parameters
+    /// - `set` the set of [`SqlFileSet`]
+    ///
+    /// # Errors
+    /// - [`ParserError`] is returned for any errors parsing
+    pub fn parse_all(set: SqlFileSet) -> Result<Self, ParserError> {
+        let files = set.into_iter().map(ParsedSqlFile::parse).collect::<Result<Vec<_>, _>>()?;
+
+        Ok(Self { files })
+    }
+
+    /// Getter method for returning the vector of all [`ParsedSqlFile`]
+    #[must_use]
+    pub fn files(&self) -> &[ParsedSqlFile] {
+        &self.files
+    }
+}

src/comments.rs

@@ -0,0 +1,132 @@
+//! Module for crawling the SQL documents based on the parser and
+//! parsing/extracting the leading comments.
+//!
+//! *leading comment* a comment that
+//! precedes an SQL Statement.
+
+/// Structure for holding a location in the file. Assumes file is first split by
+/// lines and then split by characters (column)
+pub struct Location {
+    line: u64,
+    column: u64,
+}
+
+impl Location {
+    /// Method for instantiating a new [`Location`]
+    ///
+    /// # Parameters
+    /// - line: the [`u64`] value of the line location
+    /// - column: the [`u64`] value of the column location
+    #[must_use]
+    pub const fn new(line: u64, column: u64) -> Self {
+        Self { line, column }
+    }
+
+    /// Getter method for getting the line value
+    #[must_use]
+    pub const fn line(&self) -> u64 {
+        self.line
+    }
+
+    /// Getter method for getting the column value
+    #[must_use]
+    pub const fn column(&self) -> u64 {
+        self.column
+    }
+}
+
+/// A structure for holding the span of comments found
+pub struct CommentSpan {
+    start: Location,
+    end: Location,
+}
+
+impl CommentSpan {
+    /// Method for creating a new instance of the [`CommentSpan`] for a
+    /// comment's span
+    ///
+    /// # Parameters
+    /// - the [`Location`] where the comment starts in the file
+    /// - the [`Location`] where the comment ends in the file
+    #[must_use]
+    pub const fn new(start: Location, end: Location) -> Self {
+        Self { start, end }
+    }
+
+    /// Getter for the start location of a [`CommentSpan`]
+    #[must_use]
+    pub const fn start(&self) -> &Location {
+        &self.start
+    }
+
+    /// Getter for the end location of a [`CommentSpan`]
+    #[must_use]
+    pub const fn end(&self) -> &Location {
+        &self.end
+    }
+}
+
+/// Structure that holds the comment along with its location in the file
+pub struct Comment {
+    comment: String,
+    span: CommentSpan,
+}
+
+impl Comment {
+    /// Method for creating a new [`Comment`] from the comment [`String`] and
+    /// the [`CommentSpan`]
+    ///
+    /// # Parameters
+    /// - the comment as a [`String`]
+    /// - the span of the comment as a [`CommentSpan`]
+    #[must_use]
+    pub const fn new(comment: String, span: CommentSpan) -> Self {
+        Self { comment, span }
+    }
+
+    /// Getter method for retrieving the comment content
+    #[must_use]
+    pub fn comment(&self) -> &str {
+        &self.comment
+    }
+
+    /// Getter method for retrieving the [`CommentSpan`] of the comment
+    #[must_use]
+    pub const fn span(&self) -> &CommentSpan {
+        &self.span
+    }
+}
+
+/// Structure for holding all comments found in the document
+pub struct Comments {
+    comments: Vec<Comment>,
+}
+
+impl Comments {
+    /// Method for generating a new [`Comments`] struct, which sorts comments
+    /// based on their starting span location
+    ///
+    /// # Parameters
+    /// - `comments`: mutable [`Vec<Comment>`] that will be sorted by span start
+    #[must_use]
+    pub fn new(mut comments: Vec<Comment>) -> Self {
+        // Always keep comments ordered by their span
+        comments.sort_by(|a, b| {
+            let a_start = a.span().start();
+            let b_start = b.span().start();
+
+            a_start
+                .line()
+                .cmp(&b_start.line())
+                .then_with(|| a_start.column().cmp(&b_start.column()))
+        });
+
+        Self { comments }
+    }
+
+    /// Getter method for retrieving the Vec of [`Comment`]
+    #[must_use]
+    pub fn comments(&self) -> &[Comment] {
+        &self.comments
+    }
+}

src/files.rs

@@ -157,6 +157,15 @@ impl SqlFileSet {
     }
 }
 
+impl IntoIterator for SqlFileSet {
+    type IntoIter = std::vec::IntoIter<SqlFile>;
+    type Item = SqlFile;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.files_contents.into_iter()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use std::{env, fs};

src/main.rs

@@ -3,8 +3,9 @@ use std::{error::Error, path::Path};
 
 use sqlparser::{dialect::GenericDialect, parser::Parser};
 
+pub mod ast;
+pub mod comments;
 pub mod files;
-pub mod parser;
 fn main() -> Result<(), Box<dyn Error>> {
     let path: &Path = Path::new("/home/alex/Projects/sql-docs/sql_files/");
 
@@ -13,7 +14,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     for sql in sql_file_set.iter() {
         let dialect = GenericDialect {}; // or AnsiDialect, or your own dialect ...
 
-        let ast = Parser::parse_sql(&dialect, sql.content()).unwrap();
+        let ast = Parser::parse_sql(&dialect, sql.content())?;
 
         println!("AST: {ast:?}");
     }