fixes #364

.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Clojure CLI
         uses: DeLaGuardo/setup-clojure@master
         with:
-          tools-deps: '1.10.3.967'
+          tools-deps: '1.10.3.986'
       - name: Run Tests
         run: clojure -T:build ci
       - name: Check cljdoc.edn

.gitignore

@@ -1,10 +1,16 @@
+.calva/output-window/
 .classpath
 .clj-kondo/.cache
 .cpcache
 .eastwood
 .factorypath
+.hg/
+.hgignore
 .java-version
+.lein-*
+.lsp/.cache
 .lsp/sqlite.db
+.nrepl-history
 .nrepl-port
 .project
 .rebel_readline_history
@@ -16,9 +22,7 @@
 *.jar
 *.swp
 *~
+/checkouts
 /classes
-/classes
-/clojure_test_*
 /cljs-test-runner-out
-/derby.log
 /target

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changes
 
 * 2.0.next in progress
+  * Address #364 by recommending how to handle PostgreSQL operators that contain `@`.
   * Support `AS` aliasing in `DELETE FROM`.
   * Switch from `readme` to `test-doc-blocks` so all documentation is tested!
   * Clean up build/update deps.

deps.edn

@@ -4,7 +4,7 @@
  :aliases
  {;; for help: clojure -A:deps -T:build help/doc
   :build {:deps {io.github.seancorfield/build-clj
-                 {:git/tag "v0.1.2" :git/sha "0719a09"}}
+                 {:git/tag "v0.4.0" :git/sha "54e39ae"}}
           :ns-default build}
 
   ;; versions to test against:
@@ -16,7 +16,7 @@
   :test
   {:extra-paths ["test"]
    :extra-deps  {io.github.cognitect-labs/test-runner
-                 {:git/tag "v0.4.0" :git/sha "334f2e2"}}
+                 {:git/tag "v0.5.0" :git/sha "48c3c67"}}
    :exec-fn     cognitect.test-runner.api/test}
 
   ;; various "runners" for tests/CI:

doc/extending-honeysql.md

@@ -74,6 +74,18 @@ to achieve that:
 ;;=> ["SELECT * FROM table WHERE x <=> ?" 42]
 ```
 
+### PostgreSQL Operators
+
+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:
+
+```clojure
+(def <at (keyword "<@"))
+(sql/register-op! <at)
+;; and use it in expressions: [<at :submitted [:range :begin :end]]
+```
+
 ## Registering a New Function (Special Syntax)
 
 `honey.sql/register-fn!` accepts a keyword (or a symbol)

doc/postgresql.md

@@ -10,6 +10,20 @@ Everything that the nilenso library provided (in 0.4.112) is implemented
 directly in HoneySQL 2.x although a few things have a
 slightly different syntax.
 
+## Operators with @
+
+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:
+
+```clojure
+(def <at (keyword "<@"))
+;; then register it: (sql/register-op! <at)
+;; and use it in expressions: [<at :submitted [:range :begin :end]]
+```
+
+## JSON/JSONB
+
 If you are using JSON with PostgreSQL, you will probably try to pass Clojure
 data structures as values into your HoneySQL DSL -- but HoneySQL will see those
 vectors as function calls and hash maps as SQL statements, so you need to tell
@@ -18,7 +32,9 @@ HoneySQL not to do that. There are two possible approaches:
 1. Use named parameters (e.g., `[:param :myval]`) instead of having the values directly in the DSL structure and then pass `{:params {:myval some-json}}` as part of the options in the call to `format`, or
 2. Use `[:lift ..]` wrapped around any structured values which tells HoneySQL not to interpret the vector or hash map value as a DSL: `[:lift some-json]`.
 
-The code example herein assume:
+## Code Examples
+
+The code examples herein assume:
 ```clojure
 (refer-clojure :exclude '[update set])
 (require '[honey.sql :as sql]