Skip to content

Commit

Permalink
README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@rafafrdz
rafafrdz committed Dec 24, 2024
1 parent ad740a3 commit 4a31bd6
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 80 deletions.
105 changes: 25 additions & 80 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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<Boolean>
Predicate := UnaryPred Ref | BinaryPred Ref Ref
Ref := Value<T> | 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<T>` 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" % "<version>" // Core library
libraryDependencies += "com.eff3ct" %% "criteria4s-sql" % "<version>" // SQL implementation
libraryDependencies += "com.eff3ct" %% "criteria4s-mongodb" % "<version>" // MongoDB implementation

```

**Maven**

```xml
<!-- Core library -->
<dependencies>
<dependency>
<groupId>com.eff3ct</groupId>
<artifactId>criteria4s-core_2.13</artifactId>
<version>0.8.2</version>
</dependency>

<!-- SQL implementation -->
<dependency>
<groupId>com.eff3ct</groupId>
<artifactId>criteria4s-core_2.13</artifactId>
<version>0.8.2</version>
</dependency>

<!-- MongoDB implementation -->
<dependency>
<groupId>com.eff3ct</groupId>
<artifactId>criteria4s-mongodb_2.13</artifactId>
<version>0.8.2</version>
</dependency>
</dependencies>
```

> [!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 |
|-------------|:-------------------------------------------------------------------------------------------|
Expand All @@ -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._
Expand All @@ -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] =
Expand All @@ -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"))
Expand Down
22 changes: 22 additions & 0 deletions doc/formal-definition.md
View file
Original file line number Diff line number Diff line change
@@ -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<Boolean>
Predicate := UnaryPred Ref | BinaryPred Ref Ref
Ref := Value<T> | 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<T>` is a value expression of a certain type `T`
- `Col` is a column expression

0 comments on commit 4a31bd6

Please sign in to comment.