From 665773ace6938a0cc19605522c0bd5e2a6590f19 Mon Sep 17 00:00:00 2001 From: inoas Date: Sat, 22 Jun 2024 00:01:28 +0200 Subject: [PATCH] docs --- src/cake/query/combined.gleam | 138 ++++++++++++++++++++++++++++++---- src/cake/query/delete.gleam | 2 +- src/cake/query/insert.gleam | 2 +- src/cake/query/select.gleam | 2 +- src/cake/query/update.gleam | 2 +- 5 files changed, 128 insertions(+), 18 deletions(-) diff --git a/src/cake/query/combined.gleam b/src/cake/query/combined.gleam index 1050120..f1a9afe 100644 --- a/src/cake/query/combined.gleam +++ b/src/cake/query/combined.gleam @@ -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, @@ -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, @@ -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, @@ -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( @@ -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, @@ -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( @@ -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 @@ -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( @@ -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, @@ -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( @@ -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( @@ -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, @@ -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, @@ -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( @@ -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, @@ -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, @@ -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( @@ -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, @@ -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, @@ -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, @@ -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, @@ -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 { @@ -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 { @@ -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 } diff --git a/src/cake/query/delete.gleam b/src/cake/query/delete.gleam index 90b8586..5b53585 100644 --- a/src/cake/query/delete.gleam +++ b/src/cake/query/delete.gleam @@ -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 diff --git a/src/cake/query/insert.gleam b/src/cake/query/insert.gleam index fa30880..f0a3c7b 100644 --- a/src/cake/query/insert.gleam +++ b/src/cake/query/insert.gleam @@ -15,7 +15,7 @@ import cake/internal/write_query.{ import cake/param.{type Param} import gleam/string -/// Creates a `WriteQuery` from an `Insert`. +/// Creates a `WriteQuery` from an `Insert` query. /// pub fn to_query(insert isrt: Insert(a)) -> WriteQuery(a) { isrt |> InsertQuery diff --git a/src/cake/query/select.gleam b/src/cake/query/select.gleam index cd7dbb8..73c3c46 100644 --- a/src/cake/query/select.gleam +++ b/src/cake/query/select.gleam @@ -15,7 +15,7 @@ import cake/param import gleam/list import gleam/string -/// Creates a `Query` from a `Select`. +/// Creates a `Query` from a `Select` query. /// pub fn to_query(query qry: Select) -> Query { qry |> SelectQuery diff --git a/src/cake/query/update.gleam b/src/cake/query/update.gleam index 192e020..67feafe 100644 --- a/src/cake/query/update.gleam +++ b/src/cake/query/update.gleam @@ -15,7 +15,7 @@ import cake/param.{type Param} import gleam/list import gleam/string -/// Creates a `WriteQuery` from an `Update`. +/// Creates a `WriteQuery` from an `Update` query. /// pub fn to_query(update updt: Update(a)) -> WriteQuery(a) { updt |> UpdateQuery