addresses #403: improve error message; improve docs

doc/special-syntax.md

@@ -19,6 +19,27 @@ of that sequence (as SQL parameters):
 ;;=> ["ARRAY[?, ?, ?, ?, ?]" 0 1 2 3 4]
 ```
 
+> Note: you cannot provide a named parameter as the argument for `:array` because the generated SQL depends on the number of elements in the sequence, so the following throws an exception:
+
+``` clj
+(sql/format {:select [[[:array :?tags] :arr]]} {:params {:tags [1 2 3]}})
+```
+
+You can do the following instead:
+
+```clojure
+(let [tags [1 2 3]]
+  (sql/format {:select [[[:array tags] :arr]]} {:inline true}))
+;;=> ["SELECT ARRAY[1, 2, 3] AS arr"]
+```
+
+In addition, the argument to `:array` is treated as a literal sequence of Clojure values and is **not** interpreted as a HoneySQL expression, so you must use the `{:inline true}` formatting option as shown above rather than try to inline the values like this:
+
+```clojure
+(sql/format {:select [[[:array [:inline [1 2 3]]] :arr]]})
+;;=> ["SELECT ARRAY[inline, (?, ?, ?)] AS arr" 1 2 3]
+```
+
 ## between
 
 Accepts three arguments: an expression, a lower bound, and

src/honey/sql.cljc

@@ -402,11 +402,19 @@
   This is intended to be used when writing your own formatters to
   extend the DSL supported by HoneySQL."
   [exprs & [opts]]
+  (when-not (sequential? exprs)
+    (throw (ex-info (str "format-expr-list expects a sequence of expressions, found: "
+                         (type exprs))
+                    {:exprs exprs})))
   (reduce (fn [[sql params] [sql' & params']]
             [(conj sql sql') (if params' (into params params') params)])
           [[] []]
           (map #(format-expr % opts) exprs)))
 
+(comment
+  (format-expr-list :?tags)
+  )
+
 (defn- format-columns [k xs]
   (let [[sqls params] (format-expr-list xs {:drop-ns (= :columns k)})]
     (into [(str "(" (str/join ", " sqls) ")")] params)))