Confusing difference between s/explain and phrase on success

[marco-m]

Hello, thanks for phrase!

I spent hours trying to debug a nil from phrase-first until I realized that there is a behavior difference that I find confusing. Consider the following:

(s/def ::simple int?)

(phrase/defphraser int? [_ _] "Expected an integer")

(deftest simplest-possible-spec-for-phrase
  (is (= "val: 1.0 fails spec: :grape.phrase-test/simple predicate: int?\n"
         (s/explain-str ::simple 1.0)))
  (is (= "Expected an integer"
         (phrase/phrase-first {} ::simple 1.0))))

(deftest difference-between-explain-and-phrase-when-success
  (is (= "Success!\n"
         (s/explain-str ::simple 1)))
  (is (= nil
         (phrase/phrase-first {} ::simple 1))))

First test shows that phrase is for end-user and s/explain is for developers, everything is as expected :-)

Second test shows that, when the spec is actually valid, s/explain returns string "Success!" while phrase returns nil. Although I read the docstring for phrase-first: "Returns nil if x is valid or no phraser was found." I was still confused for hours :-)

In my opinion, there is a big difference between a valid spec and no phraser found. Is there a reason for always returning nil or would it make sense to conform (pun intended) with explain here and return "Success!" ?

[alexanderkiel]

Thanks for asking. I clarified things in aaa3687. The function phrase-first is just a shortcut for phrasing a problem directly with phrase. If there is no problem, you can't phrase anything. So phrase-first returns nil on success. The messages returned by phrase are supposed to be error messages. So "Success!" wouldn't be useful to present to the user. But you can implement your expected behavior using the default phraser.

[marco-m]

Ok, thanks for the explanation.