From e44a30a7fd805bb1872965a7778b79757a14b93d Mon Sep 17 00:00:00 2001
From: Sean Corfield <sean@corfield.org>
Date: Sat, 25 Sep 2021 16:32:00 -0700
Subject: [PATCH] fixes #364

---
 .github/workflows/test.yml |  2 +-
 .gitignore                 | 10 +++++++---
 CHANGELOG.md               |  1 +
 deps.edn                   |  4 ++--
 doc/extending-honeysql.md  | 12 ++++++++++++
 doc/postgresql.md          | 18 +++++++++++++++++-
 6 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index d89ed56..9d3b291 100644
--- a/.github/workflows/test.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 8357fa3..db6dee7 100644
--- a/.gitignore
+++ b/.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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a94a924..adeebd4 100644
--- a/CHANGELOG.md
+++ b/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.
diff --git a/deps.edn b/deps.edn
index e1fcf33..dd1348d 100644
--- a/deps.edn
+++ b/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:
diff --git a/doc/extending-honeysql.md b/doc/extending-honeysql.md
index b7c7192..e28a1d7 100644
--- a/doc/extending-honeysql.md
+++ b/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)
diff --git a/doc/postgresql.md b/doc/postgresql.md
index a19b4ea..9f60600 100644
--- a/doc/postgresql.md
+++ b/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]