From bfbd1c10f3090af77d1b81e6d10a196dd287fe4f Mon Sep 17 00:00:00 2001 From: Apisit Ritreungroj Date: Thu, 14 Mar 2024 15:18:52 +0700 Subject: [PATCH] docs: ast --- src/analyzer/indexer.rs | 14 ++++++++++++++ src/analyzer/mod.rs | 32 ++++++-------------------------- src/ast/enums.rs | 10 +++++++++- src/ast/indexes.rs | 13 +++++++++++++ src/ast/meta.rs | 16 ---------------- src/ast/mod.rs | 2 -- src/ast/project.rs | 7 +++++++ src/ast/refs.rs | 1 + src/ast/schema.rs | 2 +- src/ast/table.rs | 18 +++++++++--------- src/ast/table_group.rs | 12 ++++++------ src/ast/unit.rs | 21 ++++++++++++++++++++- 12 files changed, 86 insertions(+), 62 deletions(-) delete mode 100644 src/ast/meta.rs diff --git a/src/analyzer/indexer.rs b/src/analyzer/indexer.rs index 24a18d9..b903dac 100644 --- a/src/analyzer/indexer.rs +++ b/src/analyzer/indexer.rs @@ -9,6 +9,7 @@ use alloc::string::{ use super::*; +/// Represents tables and enums within a given schema name. #[derive(Debug, PartialEq, Clone, Default)] pub struct IndexedSchemaBlock { /// Indexed table names and associated columns @@ -17,6 +18,8 @@ pub struct IndexedSchemaBlock { enum_map: BTreeMap>, } +/// Represents various types of items for indexing identifiers +/// including aliases, schema groupings, and table groups. #[derive(Debug, PartialEq, Clone, Default)] pub struct Indexer { /// Indexed table groups map. @@ -522,3 +525,14 @@ impl From for IndexedRef { } } } + +/// Represents indexed meta data during parsing. +#[derive(Debug, PartialEq, Clone, Default)] +pub struct TableIndexer { + /// A list of primary column names (composition applicable). + pub pk_list: Vec, + /// A list of column names with unique constraint (composition applicable). + pub unique_list: Vec>, + /// A list of indexed column names (composition applicable). + pub indexed_list: Vec<(Vec, Option)>, +} diff --git a/src/analyzer/mod.rs b/src/analyzer/mod.rs index ce17625..bcfeea5 100644 --- a/src/analyzer/mod.rs +++ b/src/analyzer/mod.rs @@ -232,7 +232,7 @@ pub fn analyze(schema_block: &SchemaBlock) -> AnalyzerResult { } } - // validate table type + // validate table column types let tables = tables .into_iter() .map(|table| { @@ -242,11 +242,10 @@ pub fn analyze(schema_block: &SchemaBlock) -> AnalyzerResult { .map(|col| { let type_name = col.r#type.type_name; - if type_name == ColumnTypeName::Undef { - unreachable!("undef field type must not appear"); - } - let type_name = match type_name { + ColumnTypeName::Undef => { + unreachable!("undef field type must not appear"); + } ColumnTypeName::Raw(raw_type) => { match ColumnTypeName::from_str(&raw_type) { Ok(type_name) => { @@ -332,16 +331,7 @@ pub fn analyze(schema_block: &SchemaBlock) -> AnalyzerResult { Value::String(val) => { let err = Err::InvalidDefaultValue { raw_value: val.clone(), raw_type: col.r#type.raw.clone() }; - if !matches!( - type_name, - ColumnTypeName::Bit - | ColumnTypeName::Varbit - | ColumnTypeName::Char - | ColumnTypeName::VarChar - | ColumnTypeName::Enum(_) - ) { - throw_err(err.clone(), &span_range, input)?; - } + // TODO: validate which type can be strings // validate fixed and variable length data type match type_name { @@ -361,17 +351,7 @@ pub fn analyze(schema_block: &SchemaBlock) -> AnalyzerResult { Value::Integer(val) => { let err = Err::DataTypeExceeded { raw_type: col.r#type.raw.clone() }; - if !matches!( - type_name, - ColumnTypeName::SmallSerial - | ColumnTypeName::Serial - | ColumnTypeName::BigSerial - | ColumnTypeName::SmallInt - | ColumnTypeName::Integer - | ColumnTypeName::BigInt - ) { - throw_err(Err::InvalidDefaultValue { raw_value: val.to_string(), raw_type: col.r#type.raw.clone() }, &span_range, input)?; - } + // TODO: validate which type can be numbers match type_name { ColumnTypeName::SmallInt diff --git a/src/ast/enums.rs b/src/ast/enums.rs index 2130264..939aefa 100644 --- a/src/ast/enums.rs +++ b/src/ast/enums.rs @@ -3,14 +3,18 @@ use alloc::vec::Vec; use super::*; +/// Represents a top-level block of enum. #[derive(Debug, Clone, Default)] pub struct EnumBlock { /// The range of the span in the source text. pub span_range: SpanRange, + /// The identifier of the enum block including schema (optional) and name. pub ident: EnumIdent, + /// The list of variants of the enums. pub values: Vec, } +/// Represents an enum value or variant. #[derive(Debug, Clone, Default)] pub struct EnumValue { /// The range of the span in the source text. @@ -19,6 +23,7 @@ pub struct EnumValue { pub settings: Option, } +/// Represents settings of an enum value or variant. #[derive(Debug, Clone, Default)] pub struct EnumValueSettings { /// The range of the span in the source text. @@ -29,10 +34,13 @@ pub struct EnumValueSettings { pub note: Option, } +/// Represents an enum identifier including schema (optional) and name. #[derive(Debug, Clone, Default)] pub struct EnumIdent { /// The range of the span in the source text. pub span_range: SpanRange, - pub name: Ident, + /// The schema of the enum. pub schema: Option, + /// The name of the enum. + pub name: Ident, } diff --git a/src/ast/indexes.rs b/src/ast/indexes.rs index 526a0b7..38e55cf 100644 --- a/src/ast/indexes.rs +++ b/src/ast/indexes.rs @@ -4,6 +4,8 @@ use core::str::FromStr; use super::*; +/// Represents an indexes block inside a table block. +/// Indexes allow users to quickly locate and access the data. Users can define single or multi-column indexes. #[derive(Debug, Clone, Default)] pub struct IndexesBlock { /// The range of the span in the source text. @@ -12,6 +14,7 @@ pub struct IndexesBlock { pub defs: Vec, } +/// Represents an indexes definition or each item in an indexes block. #[derive(Debug, Clone, Default)] pub struct IndexesDef { /// The range of the span in the source text. @@ -22,10 +25,12 @@ pub struct IndexesDef { pub settings: Option, } +/// Represents settings of an indexes definition. #[derive(Debug, Clone, Default)] pub struct IndexesSettings { /// The range of the span in the source text. pub span_range: SpanRange, + /// A vector of key and optional value pairs representing attributes of the indexes definition. pub attributes: Vec, /// A Type of index (btree, gin, gist, hash depending on DB). pub r#type: Option, @@ -39,17 +44,25 @@ pub struct IndexesSettings { pub name: Option, } +/// Represents the type of column for indexing. #[derive(Debug, Clone)] pub enum IndexesColumnType { + /// Represents a column name with the given identifier. String(Ident), + /// Represents an expression with the given literal expression. Expr(Literal), } +/// Represents different types of indexes that can be used. #[derive(Debug, PartialEq, Eq, Clone)] pub enum IndexesType { + /// Represents a B-tree index. BTree, + /// Represents a GIN (Generalized Inverted Index) index. Gin, + /// Represents a GiST (Generalized Search Tree) index. Gist, + /// Represents a hash index. Hash, } diff --git a/src/ast/meta.rs b/src/ast/meta.rs deleted file mode 100644 index 511869d..0000000 --- a/src/ast/meta.rs +++ /dev/null @@ -1,16 +0,0 @@ -use alloc::collections::BTreeSet; -use alloc::string::String; -use alloc::vec::Vec; - -use super::IndexesType; - -/// A struct representing indexed meta data during parsing. -#[derive(Debug, PartialEq, Clone, Default)] -pub struct TableIndexer { - /// A list of primary column names (composition applicable). - pub pk_list: Vec, - /// A list of column names with unique constraint (composition applicable). - pub unique_list: Vec>, - /// A list of indexed column names (composition applicable). - pub indexed_list: Vec<(Vec, Option)>, -} diff --git a/src/ast/mod.rs b/src/ast/mod.rs index cc14f21..880f69e 100644 --- a/src/ast/mod.rs +++ b/src/ast/mod.rs @@ -2,7 +2,6 @@ pub(crate) type SpanRange = Range; mod enums; mod indexes; -mod meta; mod project; mod refs; mod schema; @@ -14,7 +13,6 @@ use core::ops::Range; pub use enums::*; pub use indexes::*; -pub use meta::*; pub use project::*; pub use refs::*; pub use schema::*; diff --git a/src/ast/project.rs b/src/ast/project.rs index aefc0e0..3288b55 100644 --- a/src/ast/project.rs +++ b/src/ast/project.rs @@ -4,6 +4,7 @@ use core::str::FromStr; use super::*; +/// Represents different types of databases. #[derive(Debug, Clone, Default)] pub enum DatabaseType { #[default] @@ -28,11 +29,17 @@ impl FromStr for DatabaseType { } } +/// Represents a project block for grouping various tables. #[derive(Debug, Clone, Default)] pub struct ProjectBlock { + /// Range of the span in the source text. pub span_range: SpanRange, + /// Properties associated with the project block. pub properties: Vec, + /// An identifier of the project block. pub ident: Ident, + /// The database type associated with the project block. pub database_type: DatabaseType, + /// The note block associated with the project block. pub note: Option, } diff --git a/src/ast/refs.rs b/src/ast/refs.rs index 2c5a379..928b279 100644 --- a/src/ast/refs.rs +++ b/src/ast/refs.rs @@ -105,6 +105,7 @@ impl ToString for ReferentialAction { pub struct RefSettings { /// The range of the span in the source text. pub span_range: SpanRange, + /// A vector of key and optional value pairs representing attributes of the ref. pub attributes: Vec, pub on_delete: Option, pub on_update: Option, diff --git a/src/ast/schema.rs b/src/ast/schema.rs index 04aa0fa..e8c33be 100644 --- a/src/ast/schema.rs +++ b/src/ast/schema.rs @@ -2,7 +2,7 @@ use alloc::vec::Vec; use super::*; -/// An entire structure of a parsed DBML file. +/// Represents the entire structure of a parsed DBML file. #[derive(Debug, Clone, Default)] pub struct SchemaBlock<'a> { /// The span range of the entire parsed DBML structure in the source text. diff --git a/src/ast/table.rs b/src/ast/table.rs index 35862da..e085f60 100644 --- a/src/ast/table.rs +++ b/src/ast/table.rs @@ -4,16 +4,16 @@ use core::str::FromStr; use super::*; -/// A struct representing a block of table. +/// Represents a block of table. #[derive(Debug, Clone, Default)] pub struct TableBlock { /// The range of the span in the source text. pub span_range: SpanRange, /// Columns or fields of the table. pub cols: Vec, - /// Identifier for the table. + /// The identifier for the table. pub ident: TableIdent, - /// The note for the table. + /// The note block associated with the table block. pub note: Option, /// The indexes block. pub indexes: Option, @@ -21,16 +21,16 @@ pub struct TableBlock { pub settings: Option, } -/// A struct representing settings of the table. +/// Represents settings of the table. #[derive(Debug, Clone, Default)] pub struct TableSettings { /// The range of the span in the source text. pub span_range: SpanRange, - /// A vector of key-value pairs representing properties of the table. + /// A vector of key and optional value pairs representing attributes of the table. pub attributes: Vec, } -/// A struct representing a single column or field of the table. +/// Represents a single column or field of the table. #[derive(Debug, Clone, Default)] pub struct TableColumn { /// The range of the span in the source text. @@ -43,7 +43,7 @@ pub struct TableColumn { pub settings: Option, } -/// A struct representing details of the table column. +/// Represents details of the table column. #[derive(Debug, Clone, Default)] pub struct ColumnType { /// The range of the span in the source text. @@ -164,7 +164,7 @@ impl FromStr for ColumnTypeName { } } -/// A struct representing settings of a column. +/// Represents settings of a column. #[derive(Debug, Clone, Default)] pub struct ColumnSettings { /// The range of the span in the source text. @@ -187,7 +187,7 @@ pub struct ColumnSettings { pub refs: Vec, } -/// A struct representing a table identifier. +/// Represents a table identifier. #[derive(Debug, Clone, Default)] pub struct TableIdent { /// The range of the span in the source text. diff --git a/src/ast/table_group.rs b/src/ast/table_group.rs index 1f38fff..c71fe24 100644 --- a/src/ast/table_group.rs +++ b/src/ast/table_group.rs @@ -2,24 +2,24 @@ use alloc::vec::Vec; use super::*; -/// A table group allowing to group the related or associated tables together. +/// Represents a table group allowing to group the related or associated tables together. #[derive(Debug, Clone, Default)] pub struct TableGroupBlock { /// The range of the span in the source text. pub span_range: SpanRange, - /// A name of a table group + /// The name of a table group pub ident: Ident, - /// A list of tables inside a group. + /// The list of table identifiers inside the group. pub items: Vec, } -/// An associated table inside a table group. +/// Represents an associated table identifier listed inside a table group. #[derive(Debug, Clone, Default)] pub struct TableGroupItem { /// The range of the span in the source text. pub span_range: SpanRange, - /// A Table schema. + /// The table schema. pub schema: Option, - /// A Table name or alias. + /// The table name or alias. pub ident_alias: Ident, } diff --git a/src/ast/unit.rs b/src/ast/unit.rs index 0450e26..d2c9a7c 100644 --- a/src/ast/unit.rs +++ b/src/ast/unit.rs @@ -6,35 +6,51 @@ use core::str::FromStr; use super::SpanRange; -/// A String literal. +/// Represents a string literal. #[derive(Debug, Clone)] pub struct Literal { + /// The range of the span in the source text. pub span_range: SpanRange, + /// The value associated with the literal. pub raw: String, + /// The value associated with the literal. pub value: Value, } +/// Represents an identifier. #[derive(Debug, Clone, Default)] pub struct Ident { + /// The range of the span in the source text. pub span_range: SpanRange, + /// The raw string value of the identifier. pub raw: String, + /// The string representation of the identifier. pub to_string: String, } +/// Represents an attribute with a key-value pair. It can have solely key without specified any value. #[derive(Debug, Clone, Default)] pub struct Attribute { + /// The range of the span in the source text. pub span_range: SpanRange, + /// The key of the attribute. pub key: Ident, + /// The value associated with the attribute, if any. pub value: Option, } +/// Represents a key-value property. #[derive(Debug, Clone)] pub struct Property { + /// The range of the span in the source text. pub span_range: SpanRange, + /// Identifier representing the key of the property. pub key: Ident, + /// Literal value associated with the property. pub value: Literal, } +/// Represents whether a value is explicitly specified as either null or not null. #[derive(Debug, PartialEq, Eq, Clone)] pub enum Nullable { NotNull, @@ -82,8 +98,11 @@ impl ToString for Value { } } +/// Represents a note block. #[derive(Debug, Clone)] pub struct NoteBlock { + /// The range of the span in the source text. pub span_range: SpanRange, + /// The literal value associated with the note block. It must be a string literal. pub value: Literal, }