diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d589e6..f7964fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,12 @@ # Changes * 2.2.next in progress + * Address [#404](https://github.com/seancorfield/honeysql/issues/404) by documenting PostgreSQL's `ARRAY` constructor syntax and how to produce it. + * Address parts of [#403](https://github.com/seancorfield/honeysql/issues/403) by improving the documentation for `:array` and also improving the exception that was thrown when it was misused. + * Fix [#402](https://github.com/seancorfield/honeysql/issues/402) by allowing for expressions in `:insert-into` table. * Address [#400](https://github.com/seancorfield/honeysql/issues/400) by adding `:table` clause. * Address [#399](https://github.com/seancorfield/honeysql/issues/399) by correcting multi-column `RETURNING` clauses in docs and tests. - * Address [#398](https://github.com/seancorfield/honeysql/issues/398) by adding `honey.sql.pg-json` namespace that registers PostgreSQL JSON operators and provides symbolic names for "unwritable" operators (that contain `@` or `#`). + * Fix [#398](https://github.com/seancorfield/honeysql/issues/398) by adding `honey.sql.pg-ops` namespace that registers PostgreSQL JSON and regex operators and provides symbolic names for "unwritable" operators (that contain `@`, `#`, or `~`). * Fix [#394](https://github.com/seancorfield/honeysql/issues/394) by restoring HoneySQL 1.x's behavior when quoting. * Fix [#387](https://github.com/seancorfield/honeysql/issues/387) again. * Update CI to reflect Clojure 1.11 release (master -> 1.11; new master is 1.12). diff --git a/doc/postgresql.md b/doc/postgresql.md index 897d8b9..952fd8a 100644 --- a/doc/postgresql.md +++ b/doc/postgresql.md @@ -53,16 +53,19 @@ user=> (sql/format {:select [[[:array [1 2 3]] :a]]}) ["SELECT ARRAY[?, ?, ?] AS a" 1 2 3] ``` -## Operators with @ +## Operators with @, #, and ~ -A number of PostgreSQL operators contain `@` which is not legal in a Clojure keyword or symbol (as literal syntax). The recommendation is to `def` your own name for these -operators, using `at` in place of `@`, with an explicit call to `keyword` (or `symbol`), and then use that `def`'d name when registering new operators and when writing -your DSL expressions: +A number of PostgreSQL operators contain `@`, `#`, or `~` which are not legal in a Clojure keyword or symbol (as literal syntax). The namespace `honey.sql.pg-ops` provides convenient symbolic names for these JSON and regex operators, substituting `at` for `@`, `hash` for `#`, and `tilde` for `~`. + +The regex operators also have more memorable aliases: `regex` for `~`, `iregex` for `~*`, `!regex` for `!~`, and `!iregex` for `!~*`. + +Requiring the namespace automatically registers these operators for use in expressions: ```clojure -(def (require '[honey.sql.pg-ops :refer [regex]]) +nil +user=> (sql/format {:select [[[regex :straw [:inline "needle"]] :match]] :from :haystack}) +["SELECT straw ~ 'needle` AS match FROM haystack"] ``` ## JSON/JSONB diff --git a/src/honey/sql/pg_json.cljc b/src/honey/sql/pg_ops.cljc similarity index 52% rename from src/honey/sql/pg_json.cljc rename to src/honey/sql/pg_ops.cljc index a0af43c..fd3076f 100644 --- a/src/honey/sql/pg_json.cljc +++ b/src/honey/sql/pg_ops.cljc @@ -1,18 +1,27 @@ ;; copyright (c) 2022 sean corfield, all rights reserved -(ns honey.sql.pg-json +(ns honey.sql.pg-ops "Register all the PostgreSQL JSON/JSONB operators and provide convenient Clojure names for those ops. + In addition, provide names for the PostgreSQL + regex operators as well. - For the seven that cannot be written directly as - symbols, use mnemonic names: hash for # and at for @. + For the eleven that cannot be written directly as + symbols, use mnemonic names: hash for #, at for @, + and tilde for ~. - For the four of those that cannot be written as + For the six of those that cannot be written as keywords, invoke the `keyword` function instead. - Those latter four (`at>`, ``, ` ->> -]) (:require [honey.sql :as sql])) @@ -33,6 +42,16 @@ (def at? "The @? operator." (keyword "@?")) (def atat "The @@ operator." (keyword "@@")) +(def tilde "The case-sensitive regex match operator." (keyword "~")) +(def tilde* "The case-insensitive regex match operator." (keyword "~*")) +(def !tilde "The case-sensitive regex unmatch operator." (keyword "!~")) +(def !tilde* "The case-insensitive regex unmatch operator." (keyword "!~*")) +;; aliases: +(def regex tilde) +(def iregex tilde*) +(def !regex !tilde) +(def !iregex !tilde*) + (sql/register-op! :-> :variadic true) (sql/register-op! :->>) (sql/register-op! :#>) @@ -48,3 +67,8 @@ (sql/register-op! :#-) (sql/register-op! at?) (sql/register-op! atat) + +(sql/register-op! tilde) +(sql/register-op! tilde*) +(sql/register-op! !tilde) +(sql/register-op! !tilde*) diff --git a/test/honey/sql/pg_json_test.cljc b/test/honey/sql/pg_ops_test.cljc similarity index 92% rename from test/honey/sql/pg_json_test.cljc rename to test/honey/sql/pg_ops_test.cljc index 58fbbc0..a310b79 100644 --- a/test/honey/sql/pg_json_test.cljc +++ b/test/honey/sql/pg_ops_test.cljc @@ -1,9 +1,9 @@ -;; copyright (c) 2020-2021 sean corfield, all rights reserved +;; copyright (c) 2022 sean corfield, all rights reserved -(ns honey.sql.pg-json-test +(ns honey.sql.pg-ops-test (:require [clojure.test :refer [deftest is testing]] [honey.sql :as sql] - [honey.sql.pg-json :as sut])) + [honey.sql.pg-ops :as sut])) (deftest pg-op-tests (testing "built-in ops"