Struct SqlDoc

Source

pub struct SqlDoc { /* private fields */ }

Expand description

Top-level documentation object containing all discovered TableDoc entries.

Implementations§

Source §

impl SqlDoc

Source

pub fn new(tables: Vec<TableDoc>) -> Self

Method for creating a new SqlDoc

Source

pub fn from_dir<P: AsRef<Path> + ?Sized>(root: &P) -> SqlDocBuilder<'_>

Creates an SqlDocBuilder that will scan a directory for SQL files and build an SqlDoc.

This is the most convenient entry point when you have a folder of .sql files. The returned builder can be further configured with builder methods before calling SqlDocBuilder::build.

§Parameters

root: Path to the directory containing SQL files.

§Examples

use sql_docs::sql_doc::SqlDoc;

let doc = SqlDoc::from_dir("migrations")
    .deny("migrations/old/ignore.sql")
    .build()
    .unwrap();

// Work with table docs
let users = doc.table("users", None).unwrap();
assert_eq!(users.name(), "users");

Source

pub fn from_path<P: AsRef<Path> + ?Sized>(path: &P) -> SqlDocBuilder<'_>

Creates an SqlDocBuilder from a single SQL file on disk.

Use this when you want documentation for one specific file. The resulting tables will have their path stamped from the provided file path (see tests such as build_sql_doc_from_file).

§Parameters

path: Path to a single SQL file.

§Examples

use sql_docs::sql_doc::SqlDoc;

let doc = SqlDoc::from_path("schema.sql")
    .build()
    .unwrap();

let t = doc.table("users", None).unwrap();
assert_eq!(t.name(), "users");

Source

pub fn from_paths<P: AsRef<Path>>(paths: &[P]) -> SqlDocBuilder<'_>

Creates an SqlDocBuilder from an explicit list of SQL file paths.

This is useful when the files you want are scattered across directories, or when you already have an exact list (e.g. selected by another tool). Each parsed table will have its path stamped based on the file it came from (see test_build_sql_doc_from_paths).

§Parameters

paths: Slice of paths to SQL files.

§Examples

use sql_docs::sql_doc::SqlDoc;

let paths = vec!["one.sql", "two.sql"];
let doc = SqlDoc::from_paths(&paths)
    .build()
    .unwrap();

assert!(doc.table("users", None).is_ok());
assert!(doc.table("posts", None).is_ok());

Source

pub fn builder_from_str(content: &str) -> SqlDocBuilder<'_>

Creates an SqlDocBuilder from raw SQL text.

This does not associate any filesystem path with the input, so discovered tables will have path == None (see test_builder_from_str_no_path_has_none_path).

This is handy for:

tests
parsing SQL from a network source
parsing SQL assembled in-memory

§Parameters

content: SQL text to parse.

§Examples

use sql_docs::sql_doc::SqlDoc;

let sql = r#"
    -- Users table
    CREATE TABLE users (id INTEGER PRIMARY KEY);
"#;

let doc = SqlDoc::builder_from_str(sql).build().unwrap();
let users = doc.table("users", None).unwrap();

// No backing file path when built from a string:
assert_eq!(users.path(), None);

Source

pub fn builder_from_strs_with_paths( string_with_path: &[(String, PathBuf)], ) -> SqlDocBuilder<'_>

Creates an SqlDocBuilder from from raw SQL text while preserving an associated path.

Each tuple is interpreted as:

String: the SQL text to parse
PathBuf: the path to associate with that SQL text

§Parameters

string_with_path: Slice of (sql, path) pairs, where sql is the SQL text and path is the path that should be attached to any discovered tables.

§Examples

use std::path::PathBuf;
use sql_docs::sql_doc::SqlDoc;

let sql_users = "CREATE TABLE users (id INTEGER PRIMARY KEY);".to_owned();
let sql_posts = "CREATE TABLE posts (id INTEGER PRIMARY KEY);".to_owned();

let p1 = PathBuf::from("a/users.sql");
let p2 = PathBuf::from("b/posts.sql");

let inputs = vec![(sql_users, p1.clone()), (sql_posts, p2.clone())];

let doc = SqlDoc::builder_from_strs_with_paths(&inputs).build().unwrap();

let users = doc.table("users", None).unwrap();
let posts = doc.table("posts", None).unwrap();

assert_eq!(users.path(), Some(p1.as_path()));
assert_eq!(posts.path(), Some(p2.as_path()));

Source

pub fn table( &self, name: &str, schema: Option<&str>, ) -> Result<&TableDoc, DocError>

Method for finding a specific TableDoc by name

§Parameters

the table name as a str
the table schema as Option of str

§Errors

Will return DocError::TableNotFound if the expected table is not found
Will return DocError::TableWithSchemaNotFound if the table name exists but no table matches the given schema
Will return DocError::DuplicateTablesFound if more than one matching table is found

Source