Documentation for the new where clause DSL

Author: jeffgbutler

CHANGELOG.md

@@ -18,6 +18,14 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
    `where (a < 5 and B = 3) and (not (C = 4 or D = 5) and E = 6)`. With this enhancement (and the enhancement for
    arbitrary grouping) it should now be possible to write virtually any where clause imaginable.
    ([#438](https://github.com/mybatis/mybatis-dynamic-sql/pull/438))
+4. Major update to the Kotlin where clause DSL. Where clauses now support the "group" and "not" features from above. In
+   addition, the where clause DSL has been fully updated to make it feel more like natural SQL. The previous version
+   of the where clause DSL yielded almost unreadable code when the "group" and "not" functions were added. This update
+   is better all around and yields a DSL that is very similar to native SQL. The new DSL includes many Kotlin DSL
+   construction features including infix functions, operator overloads, and functions with receivers. We believe it
+   will be well worth the effort to migrate to the new DSL. The prior where clause DSL remains in the library for now,
+   but is deprecated. It will be removed in version 1.5.0 of the library. Documentation for the new DSL is here:
+   https://github.com/mybatis/mybatis-dynamic-sql/blob/master/src/site/markdown/docs/kotlinWhereClauses.md
 
 ## Release 1.3.1 - December 18, 2021
 

src/site/markdown/docs/kotlinMyBatis3.md

@@ -156,9 +156,10 @@ where clause and an order by clause as follows:
 
 ```kotlin
 val rows = mapper.select {
-    where(id, isLessThan(100))
-    or (employed, isTrue()) {
-        and (occupation, isEqualTo("Developer"))
+    where { id isLessThan 100 }
+    or {
+        employed.isTrue())
+        and { occupation isEqualTo "Developer" }
     }
     orderBy(id)
 }
@@ -227,9 +228,8 @@ supplied where clause. Clients can use the methods as follows:
 
 ```kotlin
 val rows = mapper.count {
-    where(occupation, isNull()) {
-        and(employed, isFalse())
-    }
+    where { occupation.isNull() }
+    and { employed.isFalse() }
 }
 ```
 
@@ -294,7 +294,7 @@ method as follows:
 
 ```kotlin
 val rows = mapper.delete {
-    where(occupation, isNull())
+    where { occupation.isNull() }
 }
 ```
 
@@ -870,17 +870,17 @@ the methods as follows:
 ```kotlin
 val mapper = getMapper() // not shown
 val distinctRecords = mapper.selectDistinct {
-    where(id, isGreaterThan(5))
+    where { id isGreaterThan 5 }
 }
 
 val rows = mapper.select {
-    where(firstName, isIn("Fred", "Barney"))
+    where { firstName.isIn("Fred", "Barney") }
     orderBy(id)
     limit(3)
 }
 
 val record = mapper.selectOne {
-    where(id, isEqualTo(1))
+    where { id isEqualTo 1 }
 }
 
 ```
@@ -890,7 +890,7 @@ The general `selectOne` method can also be used to implement a `selectByPrimaryK
 ```kotlin
 fun PersonMapper.selectByPrimaryKey(id_: Int) =
     selectOne {
-        where(id, isEqualTo(id_))
+        where { id isEqualTo id_ }
     }
 ```
 
@@ -934,7 +934,7 @@ select list. Like other select methods, this method can be used as follows:
 
 ```kotlin
 val records = mapper.select {
-    where(id, isLessThan(100))
+    where { id isLessThan 100 }
     limit(5)
 }
 ```
@@ -995,7 +995,7 @@ where clause. Clients can use the method as follows:
 ```kotlin
 val rows = mapper.update {
     set(occupation).equalTo("Programmer")
-    where(id, isEqualTo(100))
+    where { id isEqualTo 100 }
     and(firstName, isEqualTo("Joe"))
 }
 ```
@@ -1030,7 +1030,7 @@ follows:
 ```kotlin
 val rows = mapper.update {
     updateSelectiveColumns(updateRecord)
-    where(id, isEqualTo(100))
+    where { id isEqualTo 100 }
 }
 ```
 
@@ -1045,7 +1045,7 @@ fun PersonMapper.updateByPrimaryKey(record: PersonRecord) =
         set(employed).equalToOrNull(record::employed)
         set(occupation).equalToOrNull(record::occupation)
         set(addressId).equalToOrNull(record::addressId)
-        where(id, isEqualTo(record.id!!))
+        where { id isEqualTo record.id!! }
     }
 
 fun PersonMapper.updateByPrimaryKeySelective(record: PersonRecord) =
@@ -1056,7 +1056,7 @@ fun PersonMapper.updateByPrimaryKeySelective(record: PersonRecord) =
         set(employed).equalToWhenPresent(record::employed)
         set(occupation).equalToWhenPresent(record::occupation)
         set(addressId).equalToWhenPresent(record::addressId)
-        where(id, isEqualTo(record.id!!))
+        where { id isEqualTo record.id!! }
     }
 ```
 

src/site/markdown/docs/kotlinOverview.md

@@ -25,7 +25,7 @@ of the DSL will yield correct results. However, it would be best to use the DSL
 diagnose problems.
 
 If you plan to use the Kotlin DSL, we recommend that you do not use any function from
-`org.mybatis.dynamic.sql.SqlBuilder` (the Java DSL entry points). Many functions from that class has been duplicated
+`org.mybatis.dynamic.sql.SqlBuilder` (the Java DSL entry points). Many functions from that class have been duplicated
 for the Kotlin DSL, but in a more Kotlin native manner.
 
 ## Package Structure
@@ -158,7 +158,7 @@ The DSL for count statements looks like this:
 ```kotlin
 // count(*)
 val countRowsStatement = countFrom(person) {
-    where(id, isLessThan(4))
+    where { id isLessThan 4 }
 }
 
 // count(column)
@@ -188,7 +188,7 @@ The DSL for delete statements looks like this:
 
 ```kotlin
 val deleteStatement = deleteFrom(person) {
-   where(id, isLessThan(4))
+   where { id isLessThan 4 }
 }
 ```
 
@@ -374,7 +374,7 @@ val insertSelectStatement = insertSelect(person) {
         add(id, constant<Int>("100")), firstName, lastName, birthDate, employed, occupation, addressId
     ) {
         from(person)
-        where(employed, isTrue())
+        where { employed.isTrue() }
     }
 }
 ```
@@ -401,10 +401,12 @@ The DSL for select statements looks like this:
 ```kotlin
 val selectStatement = select(id, firstName, lastName, birthDate, employed, occupation, addressId) {
    from(person)
-   where(id, isLessThan(5))
-   and(id, isLessThan(4)) {
-      and(id, isLessThan(3)) {
-         and(id, isLessThan(2))
+   where { id isLessThan 5 }
+   and {
+      id isLessThan 4
+      and {
+         id isLessThan 3
+         or { id isLessThan 2 }
       }
    }
    orderBy(id)
@@ -419,10 +421,12 @@ There is also a method that will create a "distinct" query (`select distinct ...
 ```kotlin
 val selectStatement = selectDistinct(id, firstName, lastName, birthDate, employed, occupation, addressId) {
    from(person)
-   where(id, isLessThan(5))
-   and(id, isLessThan(4)) {
-      and(id, isLessThan(3)) {
-         and(id, isLessThan(2))
+   where { id isLessThan 5 }
+   and {
+      id isLessThan 4
+      and {
+         id isLessThan 3
+         or { id isLessThan 2 }
       }
    }
    orderBy(id)
@@ -448,7 +452,7 @@ The DSL for update statements looks like this:
 ```kotlin
 val updateStatement = update(person) {
    set(firstName).equalTo("Sam")
-   where(firstName, isEqualTo("Fred"))
+   where { firstName isEqualTo "Fred" }
 }
 ```
 

src/site/markdown/docs/kotlinSpring.md

@@ -114,17 +114,17 @@ import org.mybatis.dynamic.sql.util.kotlin.spring.countFrom
 val template: NamedParameterJdbcTemplate = getTemplate() // not shown
 
 val rowcount = template.countFrom(person) {
-    where(id, isLessThan(4))
+    where { id isLessThan 4 }
 }
 
 val columnCount = template.count(lastName) {
     from(person)
-    where(id, isLessThan(4))
+    where { id isLessThan 4 }
 }
 
 val distinctColumnCount = template.countDistinct(lastName) {
     from(person)
-    where(id, isLessThan(4))
+    where { id isLessThan 4 }
 }
 ```
 
@@ -159,7 +159,7 @@ import org.mybatis.dynamic.sql.util.kotlin.spring.deleteFrom
 val template: NamedParameterJdbcTemplate = getTemplate() // not shown
 
 val rows = template.deleteFrom(person) {
-    where(id, isLessThan(4))
+    where { id isLessThan 4 }
 }
 ```
 
@@ -405,7 +405,7 @@ val insertSelectRows: Int = template.insertSelect(person) {
         add(id, constant<Int>("100")), firstName, lastName, birthDate, employed, occupation, addressId
     ) {
         from(person)
-        where(employed, isTrue())
+        where { employed.isTrue() }
     }
 }
 ```
@@ -422,7 +422,7 @@ val rows = template.withKeyHolder(keyHolder) {
           add(id, constant<Int>("100")), firstName, lastName, birthDate, employed, occupation, addressId
        ) {
           from(person)
-          where(employed, isTrue())
+          where { employed.isTrue() }
        }
     }
 }
@@ -513,11 +513,13 @@ Select statements can be constructed and executed in a single step with code lik
 ```kotlin
 val personRecords: List<PersonRecord> = template.select(id, firstName, lastName, birthDate, employed, occupation, addressId) {
     from(person)
-    where(id, isLessThan(5))
-    and(id, isLessThan(4)) {
-        and(id, isLessThan(3)) {
-            and(id, isLessThan(2))
-        }
+    where { id isLessThan 5 }
+    and {
+       id isLessThan 4
+       and {
+          id isLessThan 3
+          or { id isLessThan 2 }
+       }
     }
     orderBy(id)
     limit(3)
@@ -540,7 +542,7 @@ like this:
 ```kotlin
 val personRecord: PersonRecord? = template.selectOne(id, firstName, lastName, birthDate, employed, occupation, addressId) {
     from(Person)
-    where(id, isEqualTo(key))
+    where { id isEqualTo key }
 }.withRowMapper { rs, _ ->
    PersonRecord(
       id = rs.getInt(id.name()),
@@ -559,7 +561,7 @@ A distinct query looks like this:
 ```kotlin
 val personRecord: List<PersonRecord> = template.selectDistinct(id, firstName, lastName, birthDate, employed, occupation, addressId) {
     from(Person)
-    where(id, isLessThan(key))
+    where { id isLessThan key }
 }.withRowMapper { rs, _ ->
    PersonRecord(
       id = rs.getInt(id.name()),
@@ -591,7 +593,7 @@ Update statements can be constructed and executed in a single step with code lik
 ```kotlin
 val rows = template.update(Person) {
     set(firstName).equalTo("Sam")
-    where(firstName, isEqualTo("Fred"))
+    where { firstName isEqualTo "Fred" }
 }
 ```