4

In Clojure, some tasks (such as instantiating a PersistentQueue or using deftype to implement a custom data type that is compatible with the clojure.core functions) require knowledge of the classes and/or interfaces in clojure.lang.

However, according to clojure.lang/package.html:

The only class considered part of the public API is clojure.lang.IFn. All other classes should be considered implementation details.

Are these statements incorrect or outdated? If so, are there plans to correct them in the future? If not, is there a more preferred way to perform the tasks mentioned above, or should they simply not be done at all in idiomatic Clojure code?

Sam Estep
  • 12,974
  • 2
  • 37
  • 75
  • Just because members of `clojure.lang` are considered implementation details doesn't mean you're not allowed to reference them. Rather, it simply means that you shouldn't expect such code to be portable (e.g., you might need separate code for Clojure vs ClojureScript). – DaoWen Nov 22 '15 at 00:51
  • 1
    @DaoWen `clojure.lang` being considered an implementation detail means more than just code not being portable. In the strictest sense of the term, an implementation detail may be changed at any time as long as the public interfaces stay the same. `clojure.lang` isn't quite that militant however. – Daniel Compton Nov 22 '15 at 03:39

1 Answers1

2

Alex Miller has commented on this in the past (the whole thread is worth reading though):

I'd say there is a range of "public"-ness to the internals of Clojure.

  • The new Clojure API (clojure.java.api.Clojure) is an official public API for external callers of Clojure. This API basically consists of ways to resolve vars and invoke functions.
  • For Clojure users in Clojure, pretty much any var that's public and has a docstring, and shows up in the api docs can be considered public API.
  • Clojure vars that are private or have no docstring (such that the var is omitted from public api docs) are likely places to tread very carefully.
  • The Clojure internal Java interfaces [clojure.lang] are certainly intended to allow library builders to create useful stuff that plays in the Clojure world. I do not know that anyone has ever said that they are "public", but I certainly think that any change to a core interface likely to break external users would be considered very carefully.
  • The Clojure internal Java classes [clojure.lang] should in most cases be considered private and subject to change without notice. There are grey areas even there.

In general, we do not place a high value on encapsulation or hiding internals. In most cases, the internals are left available if they might be useful to an advanced user doing interesting things, with the caveat that the weirder things you do, the more likely you are to be accidentally broken in a future release.

Daniel Compton
  • 13,878
  • 4
  • 40
  • 60