diff --git a/README.md b/README.md index 7453306..6747239 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,35 @@ -![Sonatype Nexus (Releases)](https://img.shields.io/nexus/r/com.eff3ct/criteria4s-core_2.13?server=https%3A%2F%2Fs01.oss.sonatype.org&style=flat-square&label=Sonatype&labelColor=%20&color=%2acf45%20%20) [![License](https://img.shields.io/badge/license-Apache%202-blue.svg?style=flat-square&label=License)](https://github.com/rafafrdz/criteria4s?tab=Apache-2.0-1-ov-file#readme) +![Sonatype Nexus (Releases)](https://img.shields.io/nexus/r/com.eff3ct/criteria4s-core_2.13?server=https%3A%2F%2Fs01.oss.sonatype.org&style=flat-square&label=Sonatype&labelColor=%20&color=%2acf45%20%20) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) # Criteria4s -Criteria4s is a simple domain-specific language (DSL) to define criteria and predicate expressions for any data stores -by using Scala type class mechanisms in a type-safe way. It pretends to be agnostic to any data store, and it is -extensible to support any kind of data stores. - -## Formal Definition of the Expressions - -The formal definition of the Criteria4s' type-classes (expressions) is as follows: - -```text -Criteria := Conjuction Criteria Criteria | Predicate | Value -Predicate := UnaryPred Ref | BinaryPred Ref Ref -Ref := Value | Col -Conjuction := AND | OR -UnaryPred := IS_NULL | IS_NOT_NULL ... -BinaryPred := EQ | NEQ | GT | LT | GEQ | LEQ | IN | LIKE ... -``` - -Where: - -- `Criteria` is the main expression of the DSL -- `Conjuction` is the conjunction operator expression -- `UnaryPredOp` is the unary predicate operator expression -- `BinaryPredOp` is the binary predicate operator expression -- `Ref` is a reference to a value or a column -- `Value` is a value expression of a certain type `T` -- `Col` is a column expression +Criteria4s is a straightforward domain-specific language (DSL) designed to define criteria and predicate expressions for any data store using Scala's type class mechanisms in a type-safe manner. Its core is designed to be agnostic to any specific data store, making it extensible and capable of supporting a variety of data storage systems. ## Getting Started -To use dsl of Criteria4s, you need to add the following dependency to your project: +To utilize the Criteria4s DSL in your project, add the following dependencies to your build configuration: -**SonaType Repository** +### Sonatype Repository -- Core library: [criteria4s-core](https://central.sonatype.com/artifact/com.eff3ct/criteria4s-core_2.13) -- SQL implementation: [criteria4s-sql](https://central.sonatype.com/artifact/com.eff3ct/criteria4s-sql_2.13) -- MongoDB dialect - implementation: [criteria4s-mongodb](https://central.sonatype.com/artifact/com.eff3ct/criteria4s-mongodb_2.13) +- **Core library**: [criteria4s-core](https://central.sonatype.com/artifact/com.eff3ct/criteria4s-core_2.13) +- **SQL implementation**: [criteria4s-sql](https://central.sonatype.com/artifact/com.eff3ct/criteria4s-sql_2.13) +- **MongoDB implementation**: [criteria4s-mongodb](https://central.sonatype.com/artifact/com.eff3ct/criteria4s-mongodb_2.13) -**SBT** +### SBT + +Add these to your `build.sbt`: ```scala libraryDependencies += "com.eff3ct" %% "criteria4s-core" % "" // Core library libraryDependencies += "com.eff3ct" %% "criteria4s-sql" % "" // SQL implementation libraryDependencies += "com.eff3ct" %% "criteria4s-mongodb" % "" // MongoDB implementation - -``` - -**Maven** - -```xml - - - - com.eff3ct - criteria4s-core_2.13 - 0.8.2 - - - - - com.eff3ct - criteria4s-core_2.13 - 0.8.2 - - - - - com.eff3ct - criteria4s-mongodb_2.13 - 0.8.2 - - ``` > [!IMPORTANT] -> Criteria4s is a work in progress and it is not ready for production use. Also, it is just available for Scala 2.13. +> Criteria4s is currently a work in progress and not ready for production use. It is available exclusively for Scala 2.13. -## Dialects +## Dialects Supported -Criteria4s is extensible to support any kind of data stores. Currently, it supports the following **dialects**: +Criteria4s is extensible, supporting various types of data stores. Presently, it supports the following dialects: | Dialect | Package | |-------------|:-------------------------------------------------------------------------------------------| @@ -91,12 +39,11 @@ Criteria4s is extensible to support any kind of data stores. Currently, it suppo ## Examples -Here, we will show some examples of how to use the Criteria DSL. You can find more examples in -the [`criteria4s-examples`](./examples/src/main/scala/io/github/rafafrdz/criteria4s/examples) module. +Here are examples demonstrating how to use the Criteria DSL. More samples are available in the [`criteria4s-examples`](./examples/src/main/scala/io/github/rafafrdz/criteria4s/examples) module. ### Imports -First, we need to import the Criteria4s DSL and the SQL dialect: +Start by importing the Criteria4s DSL and the SQL dialect: ```scala import com.eff3ct.criteria4s.core._ @@ -107,16 +54,16 @@ import com.eff3ct.criteria4s.functions._ ### Defining Criteria Expressions -We can define criteria expressions in a polymorphic way by using the Criteria DSL. You can find more definitions -examples -in the [`Defining Criteria Expressions`](./doc/defining-criteria-expressions.md) document. +Define criteria expressions in a polymorphic way using the Criteria DSL. Additional examples are provided in the [`Defining Criteria Expressions`](./doc/defining-criteria-expressions.md) document. ```scala def expr[T <: CriteriaTag : LEQ : EQ : AND : OR : Show[Column, *]]: Criteria[T] = (col[T]("field1") leq lit(3)) and (col[T]("field2") leq lit(4)) or (col[T]("field3") === lit("c")) ``` -#### Case of use +#### Use Cases + +The following code snippets demonstrate how to use the defined criteria expressions: ```scala def ageCriteria[T <: CriteriaTag : GT : LT : AND : Show[Column, *]]: Criteria[T] = @@ -128,18 +75,16 @@ def refCriteria[T <: CriteriaTag : EQ : Show[Column, *]](fieldName: String, id: ### Evaluating Criteria Expressions -And then we can use those expressions defined belows in order to generate criteria expressions for different -datastores by importing the corresponding dialects. You can find evaluation examples for some different dialects in the -following documents: +Utilize these expressions to generate criteria for different data stores by importing the corresponding dialects. Evaluation examples for various dialects are available in the following documents: -- [PostgreSQL Dialect](./doc/postgresql-dialect-evaluating.md) -- [MongoDB Dialect](./doc/mongodb-dialect-evaluating.md) -- [MySQL Dialect](./doc/mysql-dialect-evaluating.md) -- [Custom Dialect](./doc/custom-dialect-evaluating.md) +- [PostgreSQL Dialect](./doc/postgresql-dialect-evaluating.md): Evaluate criteria expressions for PostgreSQL data stores. +- [MongoDB Dialect](./doc/mongodb-dialect-evaluating.md): Evaluate criteria expressions for MongoDB data stores. +- [MySQL Dialect](./doc/mysql-dialect-evaluating.md): Evaluate criteria expressions for MySQL data stores. +- [Custom Dialect](./doc/custom-dialect-evaluating.md): Evaluate criteria expressions for custom data stores. ### Inline Criteria DSL -Or maybe we can use the Criteria DSL inline: +Leverage the Criteria DSL in an inline manner: ```scala (col[PostgreSQL]("field1") leq lit(3)) and (col[PostgreSQL]("field2") leq lit(4)) or (col[PostgreSQL]("field3") === lit("c")) diff --git a/doc/formal-definition.md b/doc/formal-definition.md new file mode 100644 index 0000000..464b385 --- /dev/null +++ b/doc/formal-definition.md @@ -0,0 +1,22 @@ +## Formal Definition of the Expressions + +The formal definition of the Criteria4s' type-classes (expressions) is as follows: + +```text +Criteria := Conjuction Criteria Criteria | Predicate | Value +Predicate := UnaryPred Ref | BinaryPred Ref Ref +Ref := Value | Col +Conjuction := AND | OR +UnaryPred := IS_NULL | IS_NOT_NULL ... +BinaryPred := EQ | NEQ | GT | LT | GEQ | LEQ | IN | LIKE ... +``` + +Where: + +- `Criteria` is the main expression of the DSL +- `Conjuction` is the conjunction operator expression +- `UnaryPredOp` is the unary predicate operator expression +- `BinaryPredOp` is the binary predicate operator expression +- `Ref` is a reference to a value or a column +- `Value` is a value expression of a certain type `T` +- `Col` is a column expression \ No newline at end of file