I am generating Codox documentation for a Clojurescript webapp. Here's an example function that I'll use to demonstrate my issue:
(defn breadcrumbs
"Render Breadcrumbs"
[app owner]
(om/component
(let [crumbs (:breadcrumbs app)]
(dom/div #js {:id "breadcrumbs"}
(when (> (count crumbs) 0)
(apply dom/ol #js {:className "breadcrumb os-border-default"}
(om/build-all breadcrumb crumbs)))))))
The problem is that using om/component causes Codox to generate documentation for four additional "hidden" functions (presumably these are the IRender, IDidUpdate, etc functions that can be defined for a component...but I'm not sure). In the documentation these functions look like this:
->t6127
(->t6127 crumb breadcrumb meta6128)
->t6130
(->t6130 crumb breadcrumb meta6131)
->t6133
(->t6133 owner app breadcrumbs meta6134)
->t6136
(->t6136 owner app breadcrumbs meta6137)
This unneeded documentation is greatly cluttering up the final product. I know individual functions can be skipped via "^:no-doc" but there doesn't seem to be a way to use that here.
Has anyone else experienced this and know how to get rid of the clutter?
Codox currently has problems with reify in ClojureScript, which is used internally by om/component.
David Nolen suggested that the information to distinguish these temporary values should be available in current versions of ClojureScript via the analyzer, but I haven't been able to find it, and no-one's been able to point me to it. See issue #72 on the Codox project page for more information.
om/component is a very simple macro that generates only render for IRender. It looks like Codox is giving you two functions for breadcumb (first two) and two for breadcumbs. One is probably the one you want and the other one is from render. You could either write your components like this:
(defn breadcrumbs
"Render Breadcrumbs"
[app owner]
(reify
om/IRender
(render ^:no-doc [_]
(let [crumbs (:breadcrumbs app)]
(dom/div #js {:id "breadcrumbs"}
(when (> (count crumbs) 0)
(apply dom/ol #js {:className "breadcrumb os-border- default"}
(om/build-all breadcrumb crumbs)))))))
or write your own no-doc-component macro:
(defmacro no-doc-component
[& body]
`(reify
om.core/IRender
(~(vary-meta 'render assoc :no-doc true) [this#]
~#body)))
Disclaimer: although I've tried the macro, I haven't tried it with Codox.
weevejester fixed this issue in version 0.8.11.
He also configured the ClojureScript analyzer to not analyze dependencies which allows me to generate docs for my Om projects. It should also reduce the number of namespaces in the :exclude configuration. Mine has been reduced to 0.
Related
I just finished my first six weeks working with Clojure and so far I'm pretty happy with the language. I'm developing my personal blog with leiningen and PostgreSQL. I already can publish new content, upload files and I have sessions, cookies and roles, anyway I think at this point I have enough code to start to worry about the testing section, but I'm kind of stuck since looks like a lot of things are happening in the clojure's testing and spec side.
So I have this function:
(defn download
"GET /admin/uploads/download/:id"
[params]
(let [id (-> params :id)
upload (model-upload/get-upload id)
filename (:filename upload)
body (clojure.java.io/file (str "public/uploads/" filename))]
{:status 200
:body body
:headers {"Content-Type" "application/pdf"
"Content-Length" (str (.length body))
"Cache-Control" "no-cache"
"Content-Disposition" (str "attachment; filename=" filename)}}))
The function takes a map as argument and delivers a final map to be sent and processed by compojure. I come from a Rails world so the way to test this function in Rails would be to create a FactoryGirl class, create a Rspec model file with the classic:
expect(first_map).to eq(map_returned_by_function)
in it comparing what is expected, and then to run the rspec from the command line to get the green or red line.
Since yesterday I'm trying to replicate that process with Clojure using this doc:
https://www.codesai.com/2018/03/kata-generating-bingo-cards
but I think there is not yet a "standard" way to do a test including the DB (CRUD) part in Clojure. I don't even know where to put the spec files. I see Clojure libraries similar to FactoryGirl but I don't know if I should create my own data structures with spec so I'm not sure where to start, there are clojure.test.check.generators and spec generators but I don't know if they are different or if I should use only spec but not clojure.test.check. Can I run a test from the command line and not inside the REPL?
I mean: is there a document or tutorial about how to test a set of CRUD functions? I think I just need the initial HOWTO and then I could take it from there and I'll write a tutorial to newbies like me.
UPDATED:
It looks like Midje is what I'm looking for:
https://github.com/marick/Midje/wiki/A-tutorial-introduction
It's idiomatic in Clojure to push IO to the edges of your application. Instead of reading from the DB inside your download function, you pass in the data read from the DB into your download function in the param map. Then you write your tests against the pure part.
Your function would end up looking like this:
(defn download-without-db
"GET /admin/uploads/download/:id"
[params]
(let [upload (-> params :upload)
filename (:filename upload)
body (clojure.java.io/file (str "public/uploads/" filename))]
{:status 200
:body body
:headers {"Content-Type" "application/pdf"
"Content-Length" (str (.length body))
"Cache-Control" "no-cache"
"Content-Disposition" (str "attachment; filename=" filename)}}))
(defn get-upload-from-db [params]
(assoc params :upload (-> params :id model-upload/get-upload)))
(defn download [params]
(-> params
get-upload-from-db
download-without-db))
You're just looking for clojure.test. It even mentions relationships with RSpec in its doc.
This is included as part of Clojure itself, no dependencies are needed, and I'd recommend you get familiar with it first before using a non standard test framework like Midje, since it is the defacto test framework for Clojure, and the most popular one.
You would write a test as such:
(deftest download
(testing "With valid input"
(testing "it should return a header map with filename included"
(is (= first_map (unit/download {:id 1}))))))
Now, Clojure is not object oriented, so there are no objects to mock. That said, you often use Java form within Clojure, and Java provides classes and objects. If you want to mock them easily, you can use the Java mocking framework called Mockito.
In your case though, the download function does not use any Java objects. So you don't need too.
Now, if you want this to be an integration test, the test I wrote is good enough for you. If you want this to be a unit test, and I assume (model-upload/get-upload id) does some IO, you'll want to mock the model-upload/get-upload function. You can easily do this using with-redefs-fn:
(deftest download
(testing "With valid input"
(testing "it should return a header map with filename included"
(with-redefs-fn {#'model-upload/get-upload (constantly {:filename "cool.pdf"})}
(is (= first_map (unit/download {:id 1})))))))
Or you can use with-redefs:
(deftest download
(with-redefs [model-upload/get-upload (constantly {:filename "cool.pdf"})]
(testing "With valid input"
(testing "it should return a header map with filename included"
(is (= first_map (unit/download {:id 1})))))))
Here are some online resources for you:
http://jafingerhut.github.io/cheatsheet/clojuredocs/cheatsheet-tiptip-cdocs-summary.html
http://clojuredocs.org/
http://clojure-doc.org/
https://www.braveclojure.com/
https://pragprog.com/book/dswdcloj2/web-development-with-clojure-second-edition
and the following is an example of how I like to structure general tests (not CRUD, though):
https://github.com/cloojure/tupelo/blob/master/test/tst/tupelo/misc.cljc
In the clojurescript re-frame todomvc application we find the following snippet in the todomvc.views namespace.
(defn todo-list
[visible-todos]
[:ul.todo-list
(for [todo #visible-todos]
^{:key (:id todo)} [todo-item todo])])
Although I have read the Clojure chapter on metadata I don't quite understand the purpose of:
^{:key
in the snippet above. Please explain.
The :key is what React needs when you have many items, so that they can be unique within the group. But the latest version of React does not need these keys. So if you use the latest versions of reframe / Reagent, just try without the :key metadata.
This metadata is equivalent to placing :key within the component. So for example what you have is equivalent to:
[todo-item {:key (:id todo)} todo]
Using the metadata approach is a convenience, which must in some cases be easier than the 'first key in props passed to the component' approach.
Here's more explanation.
^{:key (:id todo)} [todo-item todo] would be equivalent to (with-meta [todo-item todo] {:key (:id todo)}), see https://clojuredocs.org/clojure.core/with-meta
Reagent uses this to generate the corresponding react component with a key. Keys help React identify which items have changed, are added, or are removed. here is the explanation: https://reactjs.org/docs/lists-and-keys.html
I am new to Clojure and Reagent. Kindly tell how to print the variable first inside the atom variable contacts?
(def app-state
(r/atom
{:contacts [{:first "Ben" :last "Lem" :middle "Ab"}]}))
First of all: the reagent tutorial is a really good place to start. It even gives you examples to solve exactly this problem.
Since reagents atom can be treated just as a regular Clojurescript atom, you can use all your normal sequence operations. Keep in mind that in order to access the current value, you have to dereference the atom via #.If you really just want to access the first :first in your atom:
(:first (first (:contacts #app-state))) or (get (first (get #app-state :contacts)) :first)
Or, if you think it's more readable
(-> #app-state
:contacts
first
:first)
I guess what you might want to do is define a few functions to make the access more easy such as:
(defn get-contacts!
"Returns the current vector of contacts stored in the app-state."
[]
(:contacts #app-state))
(defn get-first-names!
"Return a vector of all first names in the current list of contacts in the
app-state."
[]
(mapv :first (get-contacts!)))
Please keep in mind that in reagent (and in general really) you might want to dereference that atom as fiew times as possible, so look for a good place to dereference it and just use regular functions that operate on a simple sequence instead of an atom.
Still, I would really suggest you go read the aforementioned reagent tutorial.
Here is a concise way to access the value that you are looking for using Clojure's (get-in m ks) function:
(get-in #app-state [:contacts 0 :first])
Just as an extra, you may see this often written as
(->> #app-state
:contacts
(mapv :first)
first
and it's useful to understand what's going on here.
->> is a macro called thread-last which will re-write the code above to be
(first (mapv :first (:contacts #app-state)))
Thread last is a bit weird at first but it makes the code more readable when lots of things are going on. I suggest that on top of the reagent tutorial mentioned in the other comments, you read this.
#app-state will give you whatever is inside the r/atom and (:first (first (:contacts #app-state))) will return the first element and (println (:first (first (:contacts #app-state)))) will print output to the browser console (so you need to have the developer tools console open to see it).
Note that for println to output to the browser developer tools console you need to have this line in your code:
(enable-console-print!)
I tried to follow the documentation for clojure.instant/read-instant-timestamp, which reads:
clojure.instant/read-instant-timestamp
To read an instant as a java.sql.Timestamp, bind *data-readers* to a
map with this var as the value for the 'inst key. Timestamp preserves
fractional seconds with nanosecond precision. The timezone offset will
be used to convert into UTC.`
The following result was unexpected:
(do
(require '[clojure.edn :as edn])
(require '[clojure.instant :refer [read-instant-timestamp]])
(let [instant "#inst \"1970-01-01T00:00:09.999-00:00\""
reader-map {'inst #'read-instant-timestamp}]
;; This binding is not appearing to do anything.
(binding [*data-readers* reader-map]
;; prints java.util.Date -- unexpected
(->> instant edn/read-string class println)
;; prints java.sql.Timestamp -- as desired
(->> instant (edn/read-string {:readers reader-map}) class println))))
How can I use the *data-readers* binding? Clojure version 1.5.1.
clojure.edn functions by default only use data readers stored in clojure.core/default-data-readers which, as of Clojure 1.5.1, provides readers for instant and UUID literals. If you want to use custom readers, you can do that by passing in a :readers option; in particular, you can pass in *data-readers*. This is documented in the docstring for clojure.edn/read (the docstring for clojure.edn/read-string refers to that for read).
Here are some examples:
(require '[clojure.edn :as edn])
;; instant literals work out of the box:
(edn/read-string "#inst \"2013-06-08T01:00:00Z\"")
;= #inst "2013-06-08T01:00:00.000-00:00"
;; custom literals can be passed in in the opts map:
(edn/read-string {:readers {'foo identity}} "#foo :asdf")
;= :asdf
;; use current binding of *data-readers*
(edn/read-string {:readers *data-readers*} "...")
(The following section added in response to comments made by Richard Möhn in this GitHub issue's comment thread. The immediate question there is whether it is appropriate for a reader function to call eval on the data passed in. I am not affiliated with the project in question; please see the ticket for details, as well as Richard's comments on the present answer.)
It is worth adding that *data-readers* is implicitly populated from any data_readers.{clj,cljc} files that Clojure finds at the root of the classpath at startup time. This can be convenient (it allows one to use custom tagged literals in Clojure source code and at the REPL), but it does mean that new data readers may appear in there with a change to a single dependency. Using an explicitly constructed reader map with clojure.edn is a simple way to avoid surprises (which could be particularly nasty when dealing with untrusted input).
(Note that the implicit loading process does not result in any code being loaded immediately, or even when a tag mentioned in *data-readers* is first encountered; the process which populates *data-readers* creates empty namespaces with unbound Vars as placeholders, and to actually use those readers one still has to require the relevant namespaces in user code.)
The *data-readers* dynamic var seems to apply to the read-string and read functions from clojure.core only.
(require '[clojure.instant :refer [read-instant-timestamp]])
(let [instant "#inst \"1970-01-01T00:00:09.999-00:00\""
reader-map {'inst #'read-instant-timestamp}]
;; This will read a java.util.Date
(->> instant read-string class println)
;; This will read a java.sql.Timestamp
(binding [*data-readers* reader-map]
(->> instant read-string class println)))
Browsing through the source code for clojure.edn reader here, I couldn't find anything that would indicate that the same *data-readers* var is used at all there.
clojure.core's functions read and read-string use LispReader (which uses the value from *data-readers*), while the functions from clojure.edn use the EdnReader.
This edn library is relatively new in Clojure so that might be the reason why the documentation string is not specific enough regarding edn vs. core reader, which can cause this kind of confusion.
Hope it helps.
I'm developing a web application with Clojure, currently with Ring, Moustache, Sandbar and Hiccup. I have a resource named job, and a route to show a particular step in a multi-step form for a particular job defined like this (other routes omitted for simplicity):
(def web-app
(moustache/app
;; matches things like "/job/32/foo/bar"
:get [["job" id & step]
(fn [req] (web.controllers.job/show-job id step))]))
In the view my controller renders, there are links to other steps within the same job. At the moment, these urls are constructed by hand, e.g. (str "/job/" id step). I don't like that hard-coded "/job/" part of the url, because it repeats what I defined in the moustache route; if I change the route I need to change my controller, which is a tighter coupling than I care for.
I know that Rails' routing system has methods to generate urls from parameters, and I wish I had similar functionality, i.e. I wish I had a function url-for that I could call like this:
(url-for :job 32 "foo" "bar")
; => "/job/32/foo/bar"
Is there a Clojure web framework that makes this easy? If not, what are your thoughts on how this could be implemented?
Noir provides something similar. It's even called url-for.
The example function you have mentioned could be implemented as below. But I am not sure if this is exactly what you are looking for.
(defn url-for [& rest]
(reduce
#(str %1 "/" %2) "" (map #(if (keyword? %1) (name %1) (str %1)) rest)))