Var metadata
Rich Hickey
tests and application-specific purposes.
You can establish metadata for a var by attaching it to the symbol
when using def (or defn, defmacro).
(defn
#^ {:doc "This is documentation for foo"
:test (fn [] (assert (= (foo 5) 5)))
:some-app-specific-thing 42}
foo [x]
x)
^(var foo)
-> {:name foo,
:doc "This is documentation for foo",
:file "REPL",
:ns #<Namespace: user>,
:line 2,
:test user.fn__427@71f735,
:some-app-specific-thing 42}
note how the actual metadata is a union of user- and system-supplied
entries (:file, :line, :ns, :name). The metadata is evaluated in a
context in which the var exists, so the tests can refer to the fn
being defined.
Some related changes:
the-var special op is now just var
There is no export function, vars are public by default and can be
made private using :private true in the metadata.
ns-exports is now ns-publics
By convention, put documentation strings under the key :doc, and test
functions as a no-arg fns under the key :test.
There's a simple assert macro and test fn, to be fleshed out later:
(assert (= 42 41))
-> java.lang.Exception: Assert failed: (= 42 41)
(test (var foo))
-> :ok
Rich
Toralf Wittner
> There is no export function, vars are public by default and can be
> made private using :private true in the metadata.
In most code that I've seen the public interface is usually smaller than
the complete implementation. And I don't expect that much metadata to be
attached to private helper functions. But with this change I would have
to. Where I could previously declare my interface in a single expression
I now have to go through my code and inject a #^{:private true} into
many places which is quite inconvenient. I would prefer the export
function instead of this alternative. Any chance to get it back?
-Toralf
Rich Hickey
some motivating concepts behind what I did:
- Some group is going to be (in their opinion negatively) impacted
somewhat by any default.
- The people I least want to impact are those who are brainstorming.
They (ok, I) don't want to be bothered with metadata, declarations,
export lists, documentation, etc when the sparks are flying.
- One of the nice things about Lisp and Clojure is that most of the
code you write matters, vs languages full of declarations. Access
constraints only matter when you are writing a library or decide to
expose some code as a library. At that point, hopefully most of the
brainstorming is over, so access constraints should be something you
can add later.
- Local solutions, like putting access control in metadata, can be
easily finessed with macros. Global solutions, like export lists,
can't.
To your pain point, private fns without metadata otherwise:
(defmacro defn- [name & decls]
(list* `defn (with-meta name (assoc (meta name) :private true))
decls))
I'm not sure about the name, but it leverages the last point above to
reduce, IMO substantially, the effort needed to solve your problem.
Just add a character to your private defns.
Rich
Kearsley Schieder-Wethy
> I've added var metadata to Clojure. It can be used for documentation,
> tests and application-specific purposes.
>
> You can establish metadata for a var by attaching it to the symbol
> when using def (or defn, defmacro).
> Rich
Wonderful. Now I really need to upgrade to the SVN version, rather
than looking (and taking notes) through the lens of the release
version.
Can see lots of uses for this. Thanks for adding it.
--
KSW
Toralf Wittner
> - The people I least want to impact are those who are brainstorming.
> They (ok, I) don't want to be bothered with metadata, declarations,
> export lists, documentation, etc when the sparks are flying.
Agreed. However if by default everything would be exported unless an
export list is explicitly given, no one would be constrained.
> To your pain point, private fns without metadata otherwise:
>
> (defmacro defn- [name & decls]
> (list* `defn (with-meta name (assoc (meta name) :private true))
> decls))
>
> I'm not sure about the name, but it leverages the last point above to
> reduce, IMO substantially, the effort needed to solve your problem.
> Just add a character to your private defns.
Thanks. I expected a macro to come to my rescue ;-) However I would
either need a more complex one or a couple more to take care of the
other def variants like defstruct, defmacro, def etc. I can live with
that and I understand your points about defaults, but I like the
alternative mentioned above because it feels very straightforward. But
yes, if you plan to set visibility to different levels or do something
else more fine-grained your argument about local vs. global solutions
surely applies.
Thanks,
Toralf
Toralf Wittner
> Thanks. I expected a macro to come to my rescue ;-) However I would
> either need a more complex one or a couple more to take care of the
> other def variants like defstruct, defmacro, def etc.
I came up with the following macro to define private scoped vars:
(defmacro private [& defs]
(doseq d# (map (fn* [[def# name# & body#]]
(list* def# (with-meta name# (assoc (meta name#) :private true)) body#))
defs)
(eval d#)))
It takes an arbitrary number of defs and attaches the private tag to its
metadata (based on the example given by Rich). The structural binding
form is very handy I must say. However being relatively new to macros I
would like to know if this can be considered idiomatic or if there is a
better alternative?
Many thanks,
Toralf
Henk Boom
> However being relatively new to macros I
> would like to know if this can be considered idiomatic or if there is a
> better alternative?
I've never before seen a macro with side-effects (of course, in scheme
this is very difficult to do, so perhaps that's why =). Usually macros
are used as code replacement functions, so something like this would
be more idiomatic:
(defmacro private [& defs]
(cons 'do
(map (fn* [[def name & body]]
(list* def
(with-meta name (assoc (meta name) :private true))
body))
defs)))
Useful syntax though, avoids having to define half a dozen more
functions for private versions of things. It doesn't handle the case
where you have a def further inside the code, but that doesn't seem to
happen very often.
Henk
Toralf Wittner
> I've never before seen a macro with side-effects (of course, in scheme
> this is very difficult to do, so perhaps that's why =).
Yeah, I was suspicious of the eval myself :) Thanks for correcting me!
Henk Boom
>
> On Sat, 2008-02-09 at 04:45 -0800, Rich Hickey wrote:
> > - The people I least want to impact are those who are brainstorming.
> > They (ok, I) don't want to be bothered with metadata, declarations,
> > export lists, documentation, etc when the sparks are flying.
>
> Agreed. However if by default everything would be exported unless an
> export list is explicitly given, no one would be constrained.
I think this is a good idea. Some modules end up being almost all
exports, but I've written modules which have only one or two exported
values, with all the rest being private. Also, It's easier to catch
when you forget to export something than when you export something you
didn't mean to. Using export makes it harder to make the latter
mistake, and exporting everything as a fallback permits the sort of
brainstorming advantages you gave (which I agree with). For example,
spread and def-aset are now exported from boot.clj. Maybe this is
intentional, but the timing of them becoming exported is suspicious
=).
I suspect that export can be implemented on top of how it currently
works. An export statement could simply use (ns-interns *ns*) and hide
everything not in the list by re-defing them. Of course, something
extra would have to be done in order to permit multiple export
statements, and I'm not sure how to do that. (btw, it seems that
*exports* is still lying around)
Any change of something like this being supported in boot.clj?
Henk
Rich Hickey
On Feb 10, 4:37 pm, "Henk Boom" <lunarcri...@gmail.com> wrote:
>
>
>
> > On Sat, 2008-02-09 at 04:45 -0800, Rich Hickey wrote:
> > > - The people I least want to impact are those who are brainstorming.
> > > They (ok, I) don't want to be bothered with metadata, declarations,
> > > export lists, documentation, etc when the sparks are flying.
>
> > Agreed. However if by default everything would be exported unless an
> > export list is explicitly given, no one would be constrained.
>
> I think this is a good idea. Some modules end up being almost all
> exports, but I've written modules which have only one or two exported
> values, with all the rest being private. Also, It's easier to catch
> when you forget to export something than when you export something you
> didn't mean to. Using export makes it harder to make the latter
> mistake, and exporting everything as a fallback permits the sort of
> brainstorming advantages you gave (which I agree with). For example,
> spread and def-aset are now exported from boot.clj. Maybe this is
> intentional, but the timing of them becoming exported is suspicious
> =).
>
the metadata, including docs...
> I suspect that export can be implemented on top of how it currently
> works. An export statement could simply use (ns-interns *ns*) and hide
> everything not in the list by re-defing them. Of course, something
> extra would have to be done in order to permit multiple export
> statements, and I'm not sure how to do that. (btw, it seems that
> *exports* is still lying around)
>
> Any change of something like this being supported in boot.clj?
>
interns and explicitly set the :private metadata on all interned vars
in the ns, with only those supplied to the fn remaining public. What's
the rationale for multiple export statements?
Rich
Henk Boom
> Yes. I've been thinking about calling it export-only. It would walk
> interns and explicitly set the :private metadata on all interned vars
> in the ns, with only those supplied to the fn remaining public. What's
> the rationale for multiple export statements?
1) To work like it did before.
2) You can put the exports for each section of the file in that section.
3) When temporarily adding something to the exports for debugging
reasons, it's nice to put it next to other debugging code or the
function itself to make it easier to remember to remove it. (If there
a way to break namespace boundaries for debugging this is a non-issue)
None are really that important, I personally wouldn't mind being
limited to one export if it's a big deal to implement, it's just a
restriction I can imagine people complaining about =).
Henk
Henk Boom
> On 10/02/2008, Rich Hickey <richh...@gmail.com> wrote:
> > What's
> > the rationale for multiple export statements?
Of course, I only remember the good reasons after firing off the email...
- If the namespace is separated between multiple files, it would be
nice to have the exports in the file in which they are defined.
- Sometimes it can be useful to write a macro which defines and
exports a number of functions. Here's a snippet from the opengl
bindings I'm working on. It takes the lispy name of a function along
with information about which of its arguments are opengl constants,
and defines/exports the binding for that function.
----
(defmacro def-gl-function [name-v & arg-types]
(let [name (first name-v)
gl-name (or (frest name-v) (symbol (convert-to-gl-name name)))
argsyms (map (fn [x] (gensym 'arg)) arg-types)]
`(do
(defn ~name [~@argsyms]
(. *gl* (~gl-name ~@(map (fn [type symbol]
(if (= type :c)
`(c ~symbol)
symbol))
arg-types argsyms))))
(export '(~name)))))
(defmacro def-gl-function* [& gl-function-exprs]
`(do ~@(map (fn [expr] `(def-gl-function ~@expr))
gl-function-exprs)))
;---- Normal Cases
(def-gl-function*
[[begin] :c]
[[call-list] :d]
[[clear-color] :d :d :d :d]
[[clear-depth] :d]
[[depth-func] :c]
[[disable] :c]
[[enable] :c]
[[end] ]
[[end-list] ]
[[gen-lists] :d]
[[load-identity] ]
[[matrix-mode] :c]
[[new-list] :d :c]
[[ortho] :d :d :d :d :d :d]
[[rotate glRotated] :d :d :d :d]
[[scale glScaled] :d :d :d]
[[translate glTranslated] :d :d :d])
----
In this case it is inconvenient to put all the exports together,
especially later, once I have more than a very small subset of opengl
bound.
Henk
Rich Hickey
On Feb 10, 6:55 pm, "Henk Boom" <lunarcri...@gmail.com> wrote:
> On 10/02/2008, Henk Boom <lunarcri...@gmail.com> wrote:
> > On 10/02/2008, Rich Hickey <richhic...@gmail.com> wrote:
> > > What's
> > > the rationale for multiple export statements?
>
> Of course, I only remember the good reasons after firing off the email...
>
> - If the namespace is separated between multiple files, it would be
> nice to have the exports in the file in which they are defined.
> - Sometimes it can be useful to write a macro which defines and
> exports a number of functions.
the def, as it is now.
In any case, the namespace system is very accessible now, so people
can define any alternative solutions they want for themselves.
Rich
smith...@googlemail.com
> I've added var metadata to Clojure. It can be used for documentation,
> tests and application-specific purposes.
> #^ {:doc "This is documentation for foo"
> :test (fn [] (assert (= (foo 5) 5)))
> :some-app-specific-thing 42}
> foo [x]
> x)
when I look into boot.clj now I think readability suffered from this
change. This might sound superficial but I think syntax matters.
Just my 2 cents - John
Rich Hickey
On Feb 17, 8:47 am, "smith49...@googlemail.com"
moment. But I'm in the middle of getting the docs in and not doing
anything with the formatting yet.
But it is a concern. I think some of it might have to do with layout,
some with editor support - for instance, in Emacs clojure-mode putting
the metadata map before the fn name causes it to stop showing in a
different color. But the mode does have support for metadata tags
preceding the fn name (nice!), so I think supporting the maps is
possible.
It would be easy enough to emulate the CL docstring after fn sig, but
that is a closed system I don't otherwise want to follow. Metadata
means stuff and that stuff has to go somewhere. I thought about
putting the map that becomes the metadata not as metadata on the
symbol, but as a map sitting between the symbol and the sigs. But is
was, and I imagine will continue to be, very convenient for macros
that generate fn/defn to have it be metadata on the symbol - they
didn't even need to know about it!
There is tremendous value to tools and the Repl experience from having
metadata - it makes rich information about your code programatically
accessible. So there may be a tradeoff in experience between language-
aware tools/editors and the code in an unaware text editor.
So - agreed on the issue, I certainly want to address it. I think a
good first step is creating some code with metadata so I have
something to work with.
As always, suggestions welcome,
Rich
Stuart Sierra
> > when I look into boot.clj now I think readability suffered from this
> > change. This might sound superficial but I think syntax matters.
> I agree. I'm a bit uncomfortable with how boot.clj is looking at the
> moment. But I'm in the middle of getting the docs in and not doing
> anything with the formatting yet.
> As always, suggestions welcome,
Would it be possible to assign metadata separately from the "def"
form? Something like this:
(defmeta list* :doc "Creates a new list containing the item
prepended to more.")
(defn list* [item & more]
(spread (cons item more)))
But that repeats the symbol. Perhaps nest them, with the "def" form
coming first, like this:
(defmeta
(defn list* [item & more]
(spread (cons item more)))
:doc "Creates a new list containing the item prepended to more.")
Just some ideas that popped into my head.
-Stuart
Henk Boom
> (defmeta
> (defn list* [item & more]
> (spread (cons item more)))
> :doc "Creates a new list containing the item prepended to more.")
Or perhaps
(defn [list*
:doc "Creates a new list containing the item prepended to more."
:other "more metadata"]
[item & more]
(spread (cons item more)))
Henk
Rich Hickey
On Feb 17, 1:17 pm, "Henk Boom" <lunarcri...@gmail.com> wrote:
>
> > (defmeta
> > (defn list* [item & more]
> > (spread (cons item more)))
> > :doc "Creates a new list containing the item prepended to more.")
>
> Or perhaps
>
> (defn [list*
> :doc "Creates a new list containing the item prepended to more."
> :other "more metadata"]
> [item & more]
> (spread (cons item more)))
>
(defn =
:tag Boolean
:doc "Equality. Returns true if obj1 equals obj2, false if not. Same
as Java obj1.equals(obj2)
except it also works for nil, and compares numbers in a type-
independent manner. Clojure's immutable data structures define
equals(), and thus =, as a value, not an identity, comparison."
[x y]
(. clojure.lang.RT (equal x y)))
(defn str
:tag String
:doc "With no args, returns the empty string. With one arg x,
returns x.toString(). With more than one arg, returns the
concatenation of the str values of the args. When passed nil, returns
the empty string."
:test (fn []
(assert (= "" (str)))
(assert (= "" (str nil)))
(assert (= "fred" (str 'fred)))
(assert (= "fred123ethel" (str "fred" 123 "ethel"))))
([] "")
([#^Object x]
(if x (. x (toString)) ""))
([x & ys]
(loop [sb (new StringBuilder (str x)) more ys]
(if more
(recur (. sb (append (str (first more)))) (rest more))
(str sb)))))
Still thinking through the implications,
Rich
Josip Gracin
On Sun, 2008-02-17 at 13:31 -0800, Rich Hickey wrote:
Current thoughts:
>
> (defn =
> :tag Boolean
> :doc "Equality. Returns true if obj1 equals obj2, false if not. Same
> as Java obj1.equals(obj2)
> except it also works for nil, and compares numbers in a type-
> independent manner. Clojure's immutable data structures define
> equals(), and thus =, as a value, not an identity, comparison."
>
> [x y]
> (. clojure.lang.RT (equal x y)))
>
wanted to write something like my-defn which delegated everything to
defn except it added something to the definition, perhaps even some
metadata.
(defmacro my-defn [name args & body]
`(defn ~name ~args ~@body...
args becomes very complex in that case.
Rich Hickey
actual metadata on the name makes for a great story for macro writers.
In any case, the key/val pairs after the name would be added to any
metadata from the symbol, so a macro writer could still manipulate
that. But yes, in the general case you would have to look for the key/
val pairs if you needed to process something among or following them.
I haven't decided anything, but remember, the number of defn-
generating macros will be vanishingly smaller than the number of
defns.
Rich
Jeffrey Chu
> support - for instance, in Emacs clojure-mode putting the metadata
> map before the fn name causes it to stop showing in a different
> color. But the mode does have support for metadata tags preceding
> the fn name (nice!), so I think supporting the maps is possible.
tweaking clojure-mode and paredit to better suit me.
So far I've hacked into clojure-mode a fix to the highlighting issue
and forced [...] {...} to indent flush left. I've also fixed some
mixed paren issues in paredit.
If anybody's interested, my git repo is available at:
http://clojure.codestuffs.com/git/?p=clojure-emacs.git;a=summary
git clone http://clojure.codestuffs.com/pub/clojure-emacs.git
I was lazy so my paredit changes and clojure-mode changes are in one
repository. I may change this later if I see a need to.
If there's any suggestions or bugs, I'm open to it :)
- Jeff
Rich Hickey
On Feb 18, 8:13 pm, Jeffrey Chu <joc...@gmail.com> wrote:
> > I think some of it might have to do with layout, some with editor
> > support - for instance, in Emacs clojure-mode putting the metadata
> > map before the fn name causes it to stop showing in a different
> > color. But the mode does have support for metadata tags preceding
> > the fn name (nice!), so I think supporting the maps is possible.
>
> I've been toying with clojure recently and, while at it, I've been
> tweaking clojure-mode and paredit to better suit me.
>
> So far I've hacked into clojure-mode a fix to the highlighting issue
> and forced [...] {...} to indent flush left. I've also fixed some
> mixed paren issues in paredit.
>
> If anybody's interested, my git repo is available at:
>
> http://clojure.codestuffs.com/git/?p=clojure-emacs.git;a=summary
> I was lazy so my paredit changes and clojure-mode changes are in one
> repository. I may change this later if I see a need to.
>
> If there's any suggestions or bugs, I'm open to it :)
>
Clojure, so I really appreciate this support. {} matching and flush-
left are nice.
Rich
Marko Kocić
>
> http://clojure.codestuffs.com/git/?p=clojure-emacs.git;a=summary
> git clone http://clojure.codestuffs.com/pub/clojure-emacs.git
I am able to browse project using first link, but git clone doesn't
work.
Regards,
Marko
Jeffrey Chu
> work.
but even so - you can still git clone it (at least with version
1.5.3.7).
Just blindly type in the command
$ git clone http://clojure.codestuffs.com/pub/clojure-emacs.git
I know, the 404 is still misleading - so I've dropped in a index which
will hopefully keep this from happening again.
If it doesn't work, let me know!
Thanks,
- Jeff
jon
I've just been having a right headache getting this 'tweaked' version
of clojure-mode working... it kinda worked, but faulty, because it was
spitting out the following error a lot:
(void-function destructuring-bind)
After a lot of digging, it turns out that the following line needed to
be added to my '.emacs' (or equivalent) startup file:
(require 'cl)
..which apparently makes various common-lisp compatible stuff
available (including the destructuring-bind macro).
Could this information be added to a Readme or code comments or
something to help others?
Thanks for the work on 'clojure-mode',
Jon
Jeffrey Chu
> I've just been having a right headache getting this 'tweaked' version
> of clojure-mode working...
that I forget that I have to require it. I added (require 'cl) to it
so you don't need it in your .emacs.
Thanks for letting me know!
- Jeff
jon
working..
- but is it the intended/cleanest way of utilizing them?
- also, is it possible to get (comment .........) forms highlighted
the same way as ;;comments are?
Thanks,
Jon
------------------------------------------
(add-to-list 'load-path "~/clojure-emacs/clojure-mode") ; for
clojure-mode.el
(add-to-list 'load-path "~/clojure-emacs/paredit") ; for
paredit.el
(add-to-list 'load-path "~/clojure-emacs/") ; for
clojure-paredit.el
;; Register clojure-mode to autoload when required
(autoload 'clojure-mode "clojure-mode"
"Major mode for editing Clojure code - similar to Lisp mode.."
t)
;; Register paredit to autoload when required
(autoload 'paredit-mode "paredit"
"Minor mode for pseudo-structurally editing Lisp code."
t)
;; ..this tweaks paredit mode and hooks it onto clojure-mode
(load "clojure-paredit")
;; Associate clojure-mode with all .clj files.
(setq auto-mode-alist
(cons '("\\.clj$" . clojure-mode)
auto-mode-alist))
------------------------------------------
jon
this line in clojure-mode.el appears to be invalid for me...
["Eval region and go" lisp-eval-region-go t]
...seems like it ought to be:
["Eval region and go" lisp-eval-region-and-go t]
Jon
Jeffrey Chu
I started a new thread for clojure mode. My replies and future clojure
mode related posts should go there.
http://groups.google.com/group/clojure/t/deba02f96ed17dd8
Thanks,
- Jeff