This is useful information - thanks Alex! Might be worth putting some of this on a Clojure.org page somewhere, perhaps linked to the Java interop section?
As someone who quite regularly interfaces to Clojure from Java, it would be useful to make *some* of the interfaces into an official public Java API. The ones I'm thinking of in particular are: IFn ISeq ILookup IPersistentMap IPersistentVector IPersistentList IPersistentCollection IMeta IObj (for metadata updates) Together these give just enough API surface area to efficiently navigate Clojure data structures, which is pretty crucial for interop...... It might be a good implementation option to put the "public" parts of these interfaces in the clojure.java.api package, and have the internal Clojure interfaces / classes in clojure.lang inherit from these. On Wednesday, 12 February 2014 08:11:18 UTC+8, Alex Miller wrote: > > 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 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 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. > > Re documentation, I personally would like to have more around the Java > interfaces, but I don't know whether that will happen. I think 80% of the > interfaces are pretty obvious but admittedly that last 20% can take a while > to ferret out. I'm happy to answer questions as I see them on the list. > > > On Tuesday, February 11, 2014 5:02:16 PM UTC-6, John Hume wrote: >> >> On Tue, Feb 11, 2014 at 7:32 AM, Phillip Lord >> <philli...@newcastle.ac.uk>wrote: >> >>> "John D. Hume" <duelin....@gmail.com> writes: >>> > Other than the new (and quite minimal) Java API for calling >>> > Clojure code[1], the details of Clojure's underlying Java classes are >>> > considered implementation details and could change from release to >>> release >>> > without being considered a breaking change. >>> >>> >>> And the interfaces? I mean, ISeq is defines the sequence abstraction. >> >> >> When I said "underlying java classes" I meant "underlying Java classes >> and interfaces." >> >> Although there are contrib and third party libraries that depend on these >> implementation details, I think the message to the community at large has >> always been not to depend on them, and as far as I know, the maintainers >> have not committed to keeping anything other than the newly documented Java >> API and the existing Clojure API in Clojure stable. >> >> So if I'm not mistaken, in spite of the fact that you can find many >> examples of people doing it, there is no blessed way to create custom >> Clojure data structures (unless you count defrecord) and no official >> documentation to encourage or assist you. >> >> Hopefully I am mistaken, or this will change someday soon. :) >> >> -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
