Clojure

doc macro does not expand special cases properly

Details

  • Type: Defect Defect
  • Status: Open Open
  • Priority: Minor Minor
  • Resolution: Unresolved
  • Affects Version/s: Release 1.6
  • Fix Version/s: None
  • Component/s: None
  • Labels:
  • Patch:
    Code and Test

Description

The doc macro supports three special cases, mapping & to fn, catch to try, and finally to try. However, the macro does not currently expand these cases - it executes them like a function instead. This is evident if you use the following at a REPL:

user> (macroexpand '(doc try))   ;; ok
((var clojure.repl/print-doc) ((var clojure.repl/special-doc) (quote try)))

user> (macroexpand '(doc catch)) ;; broken
;; -- unexpectedly prints try doc -- ;;
nil

user> (= (with-out-str (doc catch)) (with-out-str (doc try))) ;; broken, expect true
;; -- unexpectedly prints try doc -- ;;
false

Workaround: Call doc with the symbol to which the special case is mapped, fn or try.

Cause: Incorrect quoting when handling special cases in doc macro

Solution: Update special case quoting approach to match the other cases.

Patch: CLJ-1358.patch

Activity

Hide
Chad Taylor added a comment -

Adding a patch with code and test.

Show
Chad Taylor added a comment - Adding a patch with code and test.
Chad Taylor made changes -
Field Original Value New Value
Attachment CLJ-1358.patch [ 12820 ]
Chad Taylor made changes -
Patch Code and Test [ 10002 ]
Description The {{doc}} macro supports three special cases, mapping {{&}} to {{fn}}, {{catch}} to {{try}}, and {{finally}} to {{try}}. However, the macro does not currently expand these cases - it executes them like a function instead. This is evident if you use the following at a REPL:

{code}
user> (macroexpand '(doc try)) ;; ok
((var clojure.repl/print-doc) ((var clojure.repl/special-doc) (quote try)))

user> (macroexpand '(doc catch)) ;; broken
;; -- unexpectedly prints try doc -- ;;
nil

user> (= (with-out-str (doc catch)) (with-out-str (doc try))) ;; broken, expect true
;; -- unexpectedly prints try doc -- ;;
false
{code}

*Workaround:* Call {{doc}} with the symbol to which the special case is mapped, {{fn}} or {{try}}.

*Cause:* Incorrect quoting when handling special cases in {{doc}} macro

*Solution:* Update special case quoting approach to match the other cases.
The {{doc}} macro supports three special cases, mapping {{&}} to {{fn}}, {{catch}} to {{try}}, and {{finally}} to {{try}}. However, the macro does not currently expand these cases - it executes them like a function instead. This is evident if you use the following at a REPL:

{code}
user> (macroexpand '(doc try)) ;; ok
((var clojure.repl/print-doc) ((var clojure.repl/special-doc) (quote try)))

user> (macroexpand '(doc catch)) ;; broken
;; -- unexpectedly prints try doc -- ;;
nil

user> (= (with-out-str (doc catch)) (with-out-str (doc try))) ;; broken, expect true
;; -- unexpectedly prints try doc -- ;;
false
{code}

*Workaround:* Call {{doc}} with the symbol to which the special case is mapped, {{fn}} or {{try}}.

*Cause:* Incorrect quoting when handling special cases in {{doc}} macro

*Solution:* Update special case quoting approach to match the other cases.

*Patch:* CLJ-1358.patch

People

Vote (0)
Watch (0)

Dates

  • Created:
    Updated: