Allow AssertionError messages for function :pre and :post conditions to be specified.

Question

A failing in a predicate in a list of {{:pre}} or {{:post}} conditions currently causes messages similar to one below to be displayed:


(defn must-be-a-map [m] {:pre [(map? m)]} m)
(must-be-a-map [])
;;=> AssertionError Assert failed: (map? m)  user/must-be-a-map (form-init.....clj:1)


These exception messages could be made significantly more descriptive by allowing specific messages strings to be associated with each predicate in {{:pre}} and {{:post}} conditions.

Predicate functions and there associated messages strings could be specified as a pair of values in a map:


(defn must-be-a-map
  [m]
  {:pre [{(map? m) "m must be a map due to some domain specific reason."}]}
  m)


The following would then produce an error message as follows:

(must-be-a-map 10)
AssertionError Assert failed: m must be a map due to some domain specific reason.
(map? m) user/must-be-a-map (form-init.....clj:1)


This would allow predicates without messages to specified alongside pairs of associated predicate message pairs as follows:


(defn n-and-m [n m] {:pre [(number? n) {(map? m) "You must provide a map!"}]})


This change would not break any existing functionality and still allow for predicates to be predefined elsewhere in code.

As a result pre and post conditions could provide a natural means of further documenting the ins and outs of a function, simplify the process of providing meaningful output when developing libraries and perhaps make the language better suited to teaching environments[1]

[1] http://wiki.science.ru.nl/tfpie/images/2/22/TFPIE2013_Steps_Towards_Teaching_Clojure.pdf

Answer 1

_Comment made by: coltnz_

Attached approach differs from that advocated for in the description by not requiring a map. The existing spec of :

{:pre [pre-expr*]
 :post [post-expr*]}

in effect becoming :

{:pre [(pre-expr assert-msg?)*]
 :post [(pre-expr assert-msg?)*]}


where assert-msg is a String. Note this means a (presumably erroneous) second String after an expression would be treated as a truthy pre-expr.

Contrived example :

(defn print-if-alphas-and-nums [arg] {:pre [(hasAlpha arg) "No alphas"
                                            (hasNum arg) "No numbers"
                                            (canPrint arg)]}
  (println arg))

user=> (print-if-alphas-and-nums "a5%")
a5%
nil
user=> (print-if-alphas-and-nums "$$%")
AssertionError Assert failed: No alphas
(hasAlpha arg)  user/print-if-alphas-and-nums (NO_SOURCE_FILE:19)


I have considered extending the spec further to (pre-expr assert-msg? data-map)* perhaps supported by ex-info, ex-data analogues in assert-info, assert-data to convey diagnostic info (locals?). A map could contain a :msg key or perhaps the map is additional to the message string. I thought I'd wait for input though at this point.

I also considered allowing % substitution for the fn return value in the message as in :post conds, but how to escape?

 

Answer 2

Comment made by: coltnz

I should point out that the tests include the currently uncovered existing functionality too.

Answer 3

Reference: https://clojure.atlassian.net/browse/CLJ-1817 (reported by alex+import)