Docs and more
Rich Hickey
documentation for all public functions of Clojure. The documentation
strings appear on the metadata of the var holding the function, under
the :doc key. There are two new Repl-oriented helpers for accessing
docs, (doc varname) and (find-doc "pattern"). doc prints the
documentation for a var, including its name, arglist(s), Macro - if it
is a macro, and the docstring. find-doc does the same for all vars
whose name or documentation matches the supplied string, which is
treated as a regex pattern.
Command-line arguments are now supported for Repl and Script. Anything
following -- on the command line will be treated as a command-line
argument to the application (i.e. not evaluated by Clojure) and will
be available as a sequence of strings - *command-line-args*.
assoc and dissoc now support multiple key/vals and keys respectively.
I've renamed scan to dorun, and touch to doall, the idea being that
when you need side-effects you should think "do__".
I've also added rand and rand-int. Find out about them by trying (find-
doc "rand").
Please try out these new features. I hope to cut a release including
them soon.
Rich
Stephen C. Gilardi
extended to work for the special forms as well (even though they're
not vars).
While browsing the clojure sources recently I saw some ":doc"
metadata and I started to write a doc-ish macro of my own as a
learning tool. Mine failed for arguments that are not vars as well.
Two questions:
What's the best way to test if an argument to a macro is a "var" or
not?
Would it be an enhancement for "(var x)" to return nil if x is not a
var rather than throwing an exception?
--Steve
Henk Boom
> What's the best way to test if an argument to a macro is a "var" or
> not?
>
> Would it be an enhancement for "(var x)" to return nil if x is not a
> var rather than throwing an exception?
I actually ran into a similar problem with seq a while ago. I wanted
to know whether or not an object could be converted to a sequence. I
ended up writing a seq? which caught the exception and returned nil,
but that's probably going to hit problems if the same exception type
is thrown for another reason by the sequence implementation.
Henk
Rich Hickey
On Feb 22, 3:40 pm, Stephen C. Gilardi <scgila...@gmail.com> wrote:
> I like the docs a lot. It would be cool for the "doc" function to be
> extended to work for the special forms as well (even though they're
> not vars).
>
> While browsing the clojure sources recently I saw some ":doc"
> metadata and I started to write a doc-ish macro of my own as a
> learning tool. Mine failed for arguments that are not vars as well.
>
> Two questions:
>
> What's the best way to test if an argument to a macro is a "var" or
> not?
>
that names a var?
There is find-var, but it requires a qualified symbol.
> Would it be an enhancement for "(var x)" to return nil if x is not a
> var rather than throwing an exception?
>
I'm wondering what kind of macro needs to know this (not that it's
wrong, just curious)?
Rich
Rich Hickey
On Feb 22, 7:47 pm, "Henk Boom" <lunarcri...@gmail.com> wrote:
> I actually ran into a similar problem with seq a while ago. I wanted
> to know whether or not an object could be converted to a sequence. I
> ended up writing a seq? which caught the exception and returned nil,
> but that's probably going to hit problems if the same exception type
> is thrown for another reason by the sequence implementation.
>
should always be avoided. If you think the API forces that, it is
something to discuss.
seq? is a bad name since most things that support seq are not seqs
(and now there is a seq? predicate which tests for the ISeq type).
These kinds of things, seq-able? atom? etc come up periodically, and I
wonder if there are generally useful answers. For instance, strings
are seq-able but many programs would rather consider them atoms. Maps
are seq-able but not normally sequential. If you stick to the Clojure
types, there are many useful marker interfaces - IPersistent/
Collection/List/Map/Stack/Vector, ISeq, IRef, IObj, Sequential,
Associative, Reversible, Named etc, with tighter semantics.
I'd hate to close over something like seq-ability. For instance, had I
defined seq-able? prior to supporting seq for strings, it would have
returned false for string. Had you written a program that depended
upon that, it would have broken when I changed seq-able? to return
true for strings as that support was added.
I think most programs are better off specifying what they expect to
see and how they would handle it, but I'm open to suggestions for
general purpose predicates, as they seem to be desired.
Rich
Stephen C. Gilardi
>>
>> What's the best way to test if an argument to a macro is a
>> "var" or
>> not?
>>
>
> Well, it's rarely a var, I presume you want to know if it is a symbol
> that names a var?
That's right.
> There is find-var, but it requires a qualified symbol.
>
>> Would it be an enhancement for "(var x)" to return nil if
>> x is not a
>> var rather than throwing an exception?
>>
>
> Again, find-var returns nil if not found.
Right, but it requires a qualified symbol as you noted.
> I'm wondering what kind of macro needs to know this (not that it's
> wrong, just curious)?
The macro I had in mind was one like doc, but which also worked for
special forms. Here's an example if "var" were changed to return nil
when its argument is not a var:
(defmacro my-doc [x]
(if (var x)
`(doc ~x)
`(doc-special-form ~x)))
I'm sure there's a better way to accomplish the same goal. In this
case, we could turn it around and write a "special-form?" function
which would check if the symbol x names a special form and leave
"var" as the general case.
(defmacro my-doc [x]
(if (special-form? x)
`(doc-special-form ~x)
`(doc ~x)))
--Steve
Rich Hickey
not found. So the logic would become:
test for special-symbol?
else resolve it
if resolved is not nil:
test resolved for var?
test resolved for (instance? Class
anything else is unexpected
Note I have not yet changed doc to do this - still thinking about the
best way to get (doc classname) to show/browse its javadoc.
Rich
Rich
Stuart Sierra
> Note I have not yet changed doc to do this - still thinking about the
> best way to get (doc classname) to show/browse its javadoc.
-Stuart
Stuart Sierra
> best way to get (doc classname) to show/browse its javadoc.
jdoc.com
javadoconline.com
-Stuart