Newbie: What is the function of refer-clojure?

[samppi]

I'm trying to get into more of how namespaces work. The refer function
refers to all the public variables of a library. What is the point of
refer-clojure, though? When would you use it? What variables of
clojure.core are not normally present in a new namespace?

[Stuart Halloway]

All of them, if you use in-ns:

(in-ns 'foo)
#<Namespace foo>

> str
java.lang.Exception: Unable to resolve symbol: str in this context

(clojure.core/refer-clojure)
-> nil

str
-> #<core$str__2981 clojure.core$str__2981@bf8aa92>

[Chouser]

On Tue, Jan 20, 2009 at 2:59 PM, Stuart Halloway
<stuart....@gmail.com> wrote:
>>
>> I'm trying to get into more of how namespaces work. The refer function
>> refers to all the public variables of a library. What is the point of
>> refer-clojure, though? When would you use it? What variables of
>> clojure.core are not normally present in a new namespace?
>
> All of them, if you use in-ns:
>
> (in-ns 'foo)
> #<Namespace foo>
>
> > str
> java.lang.Exception: Unable to resolve symbol: str in this context
>
> (clojure.core/refer-clojure)
> -> nil
>
> str
> -> #<core$str__2981 clojure.core$str__2981@bf8aa92>

While this is true, it's not the primary purpose of 'refer-clojure',
since you could instead simply do: (clojure.core/refer 'clojure.core)

The reason 'refer-clojure' exists is for use with the 'ns' macro.
By default, 'ns' refers all of clojure.core, which is usually what you
want. However, if you want to restrict or change any of the
clojure.core symbols on their way into your new namespace, you can use
:refer-clojure and 'ns' will let you do what you want.

Let's say I want a new "normal" namespace, except without the builtin
'slurp' function:

(ns bar
(:refer-clojure :exclude (slurp)))

bar=> slurp
java.lang.Exception: Unable to resolve symbol: slurp in this context
(NO_SOURCE_FILE:0)

Why would I want to do something like this? Perhaps because I want to
use a different version of 'slurp':

(ns bar
(:refer-clojure :exclude (slurp))
(:use [clojure.contrib.mmap :only (slurp)]))

bar=> str
#<core$str__2987 clojure.core$str__2987@1ee148b>

bar=> slurp
#<mmap$slurp__205 clojure.contrib.mmap$slurp__205@7ecd78>

Note that 'ns' is meant to be used in .clj files, not at the REPL.

--Chouser

[Stephen C. Gilardi]

(Adding perhaps a few interesting tidbits to the fine answers already
given...)

----------------------------

If you use "in-ns" to create a namespace, the only symbols that are
resolvable without explicit namespace qualification are:

- special forms,
- in-ns,
- ns,
- java.lang.*,
- Compiler (referring to clojure.lang.Compiler, I'm not sure if this
is intentional or not.)

Special forms, in-ns, and ns are handled as special cases. You can see
the rest by using "ns-map" on a freshly created namespace:

Clojure
user=> (in-ns 'fresh)
#<Namespace fresh>
fresh=> (clojure.core/doseq [e (clojure.core/ns-map 'fresh)]
(clojure.core/prn e))
[ProcessBuilder java.lang.ProcessBuilder]
[Enum java.lang.Enum]
[SuppressWarnings java.lang.SuppressWarnings]
[Throwable java.lang.Throwable]
[InterruptedException java.lang.InterruptedException]
[...]

You can use "refer" to bring in some or all of clojure.core (or any
other namespace) into the new namespace by reference.

----------------------------

If you use "ns" to create a namespace (as you should in nearly all
cases--one exception being ad-hoc creation of a namespace
interactively at the repl), all of the above plus all symbols in the
clojure.core namespace are resolvable without explicit namespace
qualification by default.

The purpose of a ":refer-clojure" clause within an ns form is to
enable fine tuning of how much of clojure.core is brought into the new
namespace. You can use ":only" or ":exclude" to pull in just what you
want, or to leave some (or all) things out. The (only) purpose of
refer-clojure is to support the :refer-clojure clause.

----------------------------

Note: the doc string for "refer-clojure" is outdated--it needs an
update (clojure -> clojure.core).

--Steve