Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@inoas
inoas committed Jun 21, 2024
1 parent a1333f4 commit 665773a
Show file tree
Hide file tree
Showing 5 changed files with 128 additions and 18 deletions.
138 changes: 124 additions & 14 deletions src/cake/query/combined.gleam
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,21 +16,27 @@ import cake/internal/query.{
type Combined, type Comment, type Epilog, type Limit, type Offset,
type OrderBy, type OrderByDirection, type Query, type Select, Combined,
CombinedQuery, Comment, Epilog, ExceptAll, ExceptDistinct, IntersectAll,
IntersectDistinct, NoComment, NoEpilog, OrderBy, OrderByColumn, UnionAll,
UnionDistinct,
IntersectDistinct, NoComment, NoEpilog, NoLimit, NoOffset, NoOrderBy, OrderBy,
OrderByColumn, UnionAll, UnionDistinct,
}
import gleam/string

/// Creates a `Query` from a `Combined` query.
///
pub fn to_query(combined_query qry: Combined) -> Query {
qry |> CombinedQuery
}

// ▒▒▒ Combined Kind ▒▒▒

/// Creates a `UNION` query out of two queries as a `Combined` query.
///
pub fn union(query_a qry_a: Select, query_b qry_b: Select) -> Combined {
UnionDistinct |> query.combined_query_new([qry_a, qry_b])
}

/// Creates a `UNION` query out of two or more queries as a `Combined` query.
///
pub fn union_many(
query_a qry_a: Select,
query_b qry_b: Select,
Expand All @@ -39,10 +45,17 @@ pub fn union_many(
UnionDistinct |> query.combined_query_new([qry_a, qry_b, ..mr_qrys])
}

/// Creates a `UNION ALL` query out of two queries as a `Combined` query.
///
pub fn union_all(query_a qry_a: Select, query_b qry_b: Select) -> Combined {
UnionAll |> query.combined_query_new([qry_a, qry_b])
}

/// Creates a `UNION ALL` query out of two or more queries as a `Combined`
/// query.
///
/// NOTICE: Not supported by SQLite.
///
pub fn union_all_many(
query_a qry_a: Select,
query_b qry_b: Select,
Expand All @@ -51,10 +64,14 @@ pub fn union_all_many(
UnionAll |> query.combined_query_new([qry_a, qry_b, ..mr_qrys])
}

/// Creates an `EXCEPT` query out of two queries as a `Combined` query.
///
pub fn except(query_a qry_a: Select, query_b qry_b: Select) -> Combined {
ExceptDistinct |> query.combined_query_new([qry_a, qry_b])
}

/// Creates an `EXCEPT` query out of two or more queries as a `Combined` query.
///
pub fn except_many(
query_a qry_a: Select,
query_b qry_b: Select,
Expand All @@ -63,12 +80,17 @@ pub fn except_many(
ExceptDistinct |> query.combined_query_new([qry_a, qry_b, ..mr_qrys])
}

/// Creates an `EXCEPT ALL` query out of two queries as a `Combined` query.
///
/// NOTICE: Not supported by SQLite.
///
pub fn except_all(query_a qry_a: Select, query_b qry_b: Select) -> Combined {
ExceptAll |> query.combined_query_new([qry_a, qry_b])
}

/// Creates an `EXCEPT ALL` query out of two or more queries as a `Combined`
/// query.
///
/// NOTICE: Not supported by SQLite.
///
pub fn except_all_many(
Expand All @@ -79,10 +101,15 @@ pub fn except_all_many(
ExceptAll |> query.combined_query_new([qry_a, qry_b, ..mr_qrys])
}

/// Creates an `INTERSECT` query out of two queries as a `Combined` query.
///
pub fn intersect(query_a qry_a: Select, query_b qry_b: Select) -> Combined {
IntersectDistinct |> query.combined_query_new([qry_a, qry_b])
}

/// Creates an `INTERSECT` query out of two or more queries as a `Combined`
/// query.
///
pub fn intersect_many(
query_a qry_a: Select,
query_b qry_b: Select,
Expand All @@ -91,12 +118,17 @@ pub fn intersect_many(
IntersectDistinct |> query.combined_query_new([qry_a, qry_b, ..mr_qrys])
}

/// Creates an `INTERSECT ALL` query out of two queries as a `Combined` query.
///
/// NOTICE: Not supported by SQLite.
///
pub fn intersect_all(query_a qry_a: Select, query_b qry_b: Select) -> Combined {
IntersectAll |> query.combined_query_new([qry_a, qry_b])
}

/// Creates an `INTERSECT ALL` query out of two or more queries as a `Combined`
/// query.
///
/// NOTICE: Not supported by SQLite.
///
pub fn intersect_all_many(
Expand All @@ -107,40 +139,56 @@ pub fn intersect_all_many(
IntersectAll |> query.combined_query_new([qry_a, qry_b, ..mr_qrys])
}

/// Gets the queries from a `Combined` query.
///
pub fn get_queries(combined_query qry: Combined) -> List(Select) {
qry.queries
}

// ▒▒▒ LIMIT & OFFSET ▒▒▒

/// Sets a `Limit` in the `Combined` query.
///
pub fn limit(query qry: Combined, limit lmt: Int) -> Combined {
let lmt = lmt |> query.limit_new
Combined(..qry, limit: lmt)
}

pub fn get_limit(query qry: Combined) -> Limit {
qry.limit
/// Removes `Limit` from the `Combined` query.
///
pub fn no_limit(query qry: Combined) -> Combined {
Combined(..qry, limit: NoLimit)
}

pub fn no_limit(query qry: Combined) -> Combined {
Combined(..qry, limit: query.NoLimit)
/// Gets `Limit` in the `Combined` query.
///
pub fn get_limit(query qry: Combined) -> Limit {
qry.limit
}

/// Sets an `Offset` in the `Combined` query.
///
pub fn offset(query qry: Combined, offst offst: Int) -> Combined {
let offst = offst |> query.offset_new
Combined(..qry, offset: offst)
}

pub fn get_offset(query qry: Combined) -> Offset {
qry.offset
/// Removes `Offset` from the `Combined` query.
///
pub fn no_offset(query qry: Combined) -> Combined {
Combined(..qry, offset: NoOffset)
}

pub fn no_offset(query qry: Combined) -> Combined {
Combined(..qry, offset: query.NoOffset)
/// Gets `Offset` in the `Combined` query.
///
pub fn get_offset(query qry: Combined) -> Offset {
qry.offset
}

// ▒▒▒ ORDER BY ▒▒▒

/// Defines the direction of an `OrderBy`.
///
pub type Direction {
Asc
Desc
Expand All @@ -153,6 +201,8 @@ fn map_order_by_direction_constructor(in: Direction) -> OrderByDirection {
}
}

/// Creates or appends an ascending `OrderBy`.
///
pub fn order_by_asc(query qry: Combined, by ordb: String) -> Combined {
qry
|> query.combined_order_by(
Expand All @@ -161,6 +211,10 @@ pub fn order_by_asc(query qry: Combined, by ordb: String) -> Combined {
)
}

/// Creates or appends an ascending `OrderBy` with `NULLS FIRST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS FIRST` out of the box.
///
pub fn order_by_asc_nulls_first(
query qry: Combined,
by ordb: String,
Expand All @@ -172,6 +226,10 @@ pub fn order_by_asc_nulls_first(
)
}

/// Creates or appends an ascending `OrderBy` with `NULLS LAST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS LAST` out of the box.
///
pub fn order_by_asc_nulls_last(query qry: Combined, by ordb: String) -> Combined {
qry
|> query.combined_order_by(
Expand All @@ -180,6 +238,8 @@ pub fn order_by_asc_nulls_last(query qry: Combined, by ordb: String) -> Combined
)
}

/// Replaces the `OrderBy` a single ascending `OrderBy`.
///
pub fn replace_order_by_asc(query qry: Combined, by ordb: String) -> Combined {
qry
|> query.combined_order_by(
Expand All @@ -188,6 +248,10 @@ pub fn replace_order_by_asc(query qry: Combined, by ordb: String) -> Combined {
)
}

/// Replaces the `OrderBy` a single ascending `OrderBy` with `NULLS FIRST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS FIRST` out of the box.
///
pub fn replace_order_by_asc_nulls_first(
query qry: Combined,
by ordb: String,
Expand All @@ -199,6 +263,10 @@ pub fn replace_order_by_asc_nulls_first(
)
}

/// Replaces the `OrderBy` a single ascending `OrderBy` with `NULLS LAST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS LAST` out of the box.
///
pub fn replace_order_by_asc_nulls_last(
query qry: Combined,
by ordb: String,
Expand All @@ -210,6 +278,8 @@ pub fn replace_order_by_asc_nulls_last(
)
}

/// Creates or appends a descending `OrderBy`.
///
pub fn order_by_desc(query qry: Combined, by ordb: String) -> Combined {
qry
|> query.combined_order_by(
Expand All @@ -218,6 +288,10 @@ pub fn order_by_desc(query qry: Combined, by ordb: String) -> Combined {
)
}

/// Creates or appends a descending order with `NULLS FIRST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS FIRST` out of the box.
///
pub fn order_by_desc_nulls_first(
query qry: Combined,
by ordb: String,
Expand All @@ -229,6 +303,10 @@ pub fn order_by_desc_nulls_first(
)
}

/// Creates or appends a descending `OrderBy` with `NULLS LAST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS LAST` out of the box.
///
pub fn order_by_desc_nulls_last(
query qry: Combined,
by ordb: String,
Expand All @@ -240,6 +318,8 @@ pub fn order_by_desc_nulls_last(
)
}

/// Replaces the `OrderBy` a single descending order.
///
pub fn replace_order_by_desc(query qry: Combined, by ordb: String) -> Combined {
qry
|> query.combined_order_by(
Expand All @@ -248,6 +328,10 @@ pub fn replace_order_by_desc(query qry: Combined, by ordb: String) -> Combined {
)
}

/// Replaces the `OrderBy` a single descending order with `NULLS FIRST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS FIRST` out of the box.
///
pub fn replace_order_by_desc_nulls_first(
query qry: Combined,
by ordb: String,
Expand All @@ -259,6 +343,10 @@ pub fn replace_order_by_desc_nulls_first(
)
}

/// Replaces the `OrderBy` a single descending `OrderBy` with `NULLS LAST`.
///
/// NOTICE: MariaDB/MySQL do not support `NULLS LAST` out of the box.
///
pub fn replace_order_by_desc_nulls_last(
query qry: Combined,
by ordb: String,
Expand All @@ -270,6 +358,10 @@ pub fn replace_order_by_desc_nulls_last(
)
}

/// Creates or appends an `OrderBy` a column with a direction.
///
/// The direction can either `ASC` or `DESC`.
///
pub fn order_by(
query qry: Combined,
by ordb: String,
Expand All @@ -280,6 +372,8 @@ pub fn order_by(
|> query.combined_order_by(OrderBy(values: [OrderByColumn(ordb, dir)]), True)
}

/// Replaces the `OrderBy` a column with a direction.
///
pub fn replace_order_by(
query qry: Combined,
by ordb: String,
Expand All @@ -290,16 +384,22 @@ pub fn replace_order_by(
|> query.combined_order_by(OrderBy(values: [OrderByColumn(ordb, dir)]), False)
}

pub fn get_order_by(query qry: Combined) -> OrderBy {
qry.order_by
/// Removes the `OrderBy` from the `Combined` query.
///
pub fn no_order_by(query qry: Combined) -> Combined {
Combined(..qry, order_by: NoOrderBy)
}

pub fn no_order_by(query qry: Combined) -> Combined {
Combined(..qry, order_by: query.NoOrderBy)
/// Gets the `OrderBy` from the `Combined` query.
///
pub fn get_order_by(query qry: Combined) -> OrderBy {
qry.order_by
}

// ▒▒▒ EPILOG ▒▒▒

/// Appends an `Epilog` to the `Combined` query.
///
pub fn epilog(query qry: Combined, epilog eplg: String) -> Combined {
let eplg = eplg |> string.trim
case eplg {
Expand All @@ -308,16 +408,22 @@ pub fn epilog(query qry: Combined, epilog eplg: String) -> Combined {
}
}

/// Removes the `Epilog` from the `Combined` query.
///
pub fn no_epilog(query qry: Combined) -> Combined {
Combined(..qry, epilog: NoEpilog)
}

/// Gets the `Epilog` from the `Combined` query.
///
pub fn get_epilog(query qry: Combined) -> Epilog {
qry.epilog
}

// ▒▒▒ COMMENT ▒▒▒

/// Appends a `Comment` to the `Combined` query.
///
pub fn comment(query qry: Combined, comment cmmnt: String) -> Combined {
let cmmnt = cmmnt |> string.trim
case cmmnt {
Expand All @@ -326,10 +432,14 @@ pub fn comment(query qry: Combined, comment cmmnt: String) -> Combined {
}
}

/// Removes the `Comment` from the `Combined` query.
///
pub fn no_comment(query qry: Combined) -> Combined {
Combined(..qry, comment: NoComment)
}

/// Gets the `Comment` from the `Combined` query.
///
pub fn get_comment(query qry: Combined) -> Comment {
qry.comment
}
2 changes: 1 addition & 1 deletion src/cake/query/delete.gleam
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import cake/internal/write_query.{
import gleam/list
import gleam/string

/// Creates a `WriteQuery` from a `Delete`.
/// Creates a `WriteQuery` from a `Delete` query.
///
pub fn to_query(delete dlt: Delete(a)) -> WriteQuery(a) {
dlt |> DeleteQuery
Expand Down
Loading

0 comments on commit 665773a

Please sign in to comment.