Guide for clojure's datatype constructs

[iku000888]

While a lot of people are having fun at EuroClojure, I attempted to write a guide that I think would have helped me a lot when I was starting to learn Clojure :)

I would appreciate any feedback.

Thanks!

Problem statement

1. datatype constructs provided by Clojure have overlapping capabilities and could be confusing to beginners (like my self 1 year ago), albeit provided for different purposes.
2. Official references explain the rationale and capabilities of these constructs really well but are described in separate sections. In order to get a picture of how these constructs fit together, one must read through several sections of the reference.

• protocols https://clojure.org/reference/protocols
• proxy https://clojure.org/reference/java_interop#_implementing_interfaces_and_extending_classes
• reify https://clojure.org/reference/datatypes#_reify

3. More examples for these constructs wanted

Related issue #152

Goal

After reading this guide, one should understand what each of the constructs are good for as well as how to use them.

Scope

• proxy(with some necessary java interop to elaborate the point)
• reify
• defrecord
• protocols
• along with minimal examples that can be tested at the repl

[puredanger]

It's a good start but I think it would help to clarify what the goal is.

[puredanger]

There seems to be confusion between the URL, the title, and other places about whether this is about datatypes, polymorphism, or both. Polymorphism to me includes multimethods. A discussion of datatypes should cover include defrecord and deftype. This page misses both, so it's not clear to me what the goal is here. Seems like clarifying this first would help.

[iku000888]

multimethods are out of scope of this guide, so not about polymorphism.

[iku000888]

Updated title.

I do mention deftype, but not in depth believing that by default, one should reach for records.
Feedback would be appreciated though.

[puredanger]

"Clojue" typo. Why is "speaking to the Java world" relevant here?

[iku000888]

Important because the proxy macro was created first specifically for speaking to the Java world via extending classes and implementing interfaces.

Later came protocols/reify/deftype/defrecord which are not created for Java interop, but instead are Clojure's own constructs for polymorphic dispatch.

As a newbie the overlap of proxy and reify were confusing until I learned the above distinction.

[puredanger]

Strike "Hopefully" - no reason to be apologetic - make it good and improve it if it's missing something.

[iku000888]

Good point :)

[puredanger]

I don't see any reason to include this section, it doesn't seem relevant.

[iku000888]

Dropped

[puredanger]

I think this is a weak example. It would be better to pick a concrete class that you need to extend and provide a method that's abstract in the super class.

[iku000888]

I ended up extending an ArrayList, because it has a SuperClass AbstractList and I wanted the example to be consise as posible.

Feedback on improvement would be appreciated.

[puredanger]

I think "It is" should be "They are" here to match plural "protocols".

[iku000888]

fixed

[puredanger]

I think the lack of spaces before ;; make "Date;;Thing" look like syntax rather than code + comment - add a space.

[iku000888]

fixed and updated to use ArrayList

[puredanger]

same as prior

[iku000888]

fixed

[puredanger]

I don't think Interface or Type need to be capitalized.

[iku000888]

fixed

[puredanger]

"on-off" has a typo, but I think "anonymous instance" is better

[iku000888]

fixed

[iku000888]

thanks for the feedback! will take a close look at them later!

…

On Sat, Aug 5, 2017 at 4:38 AM, Alex Miller ***@***.***> wrote: ***@***.**** commented on this pull request. It's a good start but I think it would help to clarify what the goal is. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > @@ -0,0 +1,153 @@ += Understanding Clojure's Polymorphism There seems to be confusion between the URL, the title, and other places about whether this is about datatypes, polymorphism, or both. Polymorphism to me includes multimethods. A discussion of datatypes should cover include defrecord and deftype. This page misses both, so it's not clear to me what the goal is here. Seems like clarifying this first would help. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > @@ -0,0 +1,153 @@ += Understanding Clojure's Polymorphism +Ikuru Kanuma +2017-07-20 +:type: guides +:toc: macro +:icons: font + +ifdef::env-github,env-browser[:outfilesuffix: .adoc] + +== Goals of this guide + +Clojue supports several constructs for speaking to the Java world "Clojue" typo. Why is "speaking to the Java world" relevant here? ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > @@ -0,0 +1,153 @@ += Understanding Clojure's Polymorphism +Ikuru Kanuma +2017-07-20 +:type: guides +:toc: macro +:icons: font + +ifdef::env-github,env-browser[:outfilesuffix: .adoc] + +== Goals of this guide + +Clojue supports several constructs for speaking to the Java world +and creating types for polymorphic dispatch. + +Because these constructs have overlapping capabilities, it may be confusing to know which construct to use at a given situation. + +Hopefully this guide clarifies what each construct is good at, while presenting minimal usage examples. Strike "Hopefully" - no reason to be apologetic - make it good and improve it if it's missing something. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > +Ikuru Kanuma +2017-07-20 +:type: guides +:toc: macro +:icons: font + +ifdef::env-github,env-browser[:outfilesuffix: .adoc] + +== Goals of this guide + +Clojue supports several constructs for speaking to the Java world +and creating types for polymorphic dispatch. + +Because these constructs have overlapping capabilities, it may be confusing to know which construct to use at a given situation. + +Hopefully this guide clarifies what each construct is good at, while presenting minimal usage examples. + +== Warm up with some Java I don't see any reason to include this section, it doesn't seem relevant. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > +Let's warm up with some Java interop: + +[source,clojure-repl] +---- +user=> (import 'java.util.Date) +java.util.Date +user=> (.toString (Date.)) +"Fri Jul 21 11:40:49 JST 2017" +---- + +Java Interop works. Cool! + +== Proxy a Java class and/or Interfaces + +Say we want the .toString method to add a greeting at the beginning for friendlyness. + +The proxy macro can be used to create an adhoc object that extends a Java Class: I think this is a weak example. It would be better to pick a concrete class that you need to extend and provide a method that's abstract in the super class. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > + (proxy-super toString))) + (call [] + (prn "Someone called me!")) + (close [] + (prn "closing!")))) +user=> (.close px) +"closing!" +nil +user=> (.call px) +"Someone called me!" +nil +---- + +== Leaving Java with defrecord + +Sofar this is all dealing with Java stuff from Clojure. + "Sofar" typo ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > +that implement interfaces (and protocols, coming up next!) from Clojure via the +link:https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/defrecord[defrecord] macro: + +[source,clojure-repl] +---- +user=> (defrecord Foo [a b] + Closeable + (close [this] + (prn (+ a b)))) +user.Foo +user=> (.close (Foo. 2 2)) +4 +nil +---- + +Records are nicer for the reasons described in the https://clojure.org/reference/datatypes#_deftype_and_defrecord[reference]. nicer than what? ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > + Closeable + (close [this] + (prn (+ a b)))) +user.Foo +user=> (.close (Foo. 2 2)) +4 +nil +---- + +Records are nicer for the reasons described in the https://clojure.org/reference/datatypes#_deftype_and_defrecord[reference]. + +https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/deftype[deftype] is +also available for implementing lower level constructs that require mutatable fields. + +== Protocols; like Java Interfaces, but better +https://clojure.org/reference/protocols[protocols] offer similar capabilities as Java interfaces, but is more powerfuld because: Fix capitalization at beginning of sentence ("protocols") and "is" should be "are" to match the plural "protocols". Also, typo "powerfuld". ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > + (prn (+ a b)))) +user.Foo +user=> (.close (Foo. 2 2)) +4 +nil +---- + +Records are nicer for the reasons described in the https://clojure.org/reference/datatypes#_deftype_and_defrecord[reference]. + +https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/deftype[deftype] is +also available for implementing lower level constructs that require mutatable fields. + +== Protocols; like Java Interfaces, but better +https://clojure.org/reference/protocols[protocols] offer similar capabilities as Java interfaces, but is more powerfuld because: + +* It is a cross platform construct I think "It is" should be "They are" here to match plural "protocols". ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > + +https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/deftype[deftype] is +also available for implementing lower level constructs that require mutatable fields. + +== Protocols; like Java Interfaces, but better +https://clojure.org/reference/protocols[protocols] offer similar capabilities as Java interfaces, but is more powerfuld because: + +* It is a cross platform construct +* It allows third party types to participate in any protocols + +Let's make a protocol that handles Java Date instances as well as Foo records: + +[source,clojure-repl] +---- +user=> (extend-protocol IBaz + Date;;Thing from Java I think the lack of spaces before ;; make "Date;;Thing" look like syntax rather than code + comment - add a space. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > +== Protocols; like Java Interfaces, but better +https://clojure.org/reference/protocols[protocols] offer similar capabilities as Java interfaces, but is more powerfuld because: + +* It is a cross platform construct +* It allows third party types to participate in any protocols + +Let's make a protocol that handles Java Date instances as well as Foo records: + +[source,clojure-repl] +---- +user=> (extend-protocol IBaz + Date;;Thing from Java + (baz [this] + (str "baz method for a Date: " + (.toString this))) + Foo;;Clojure Record same as prior ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > +user=> (extend-protocol IBaz + Date;;Thing from Java + (baz [this] + (str "baz method for a Date: " + (.toString this))) + Foo;;Clojure Record + (baz [this] + (str "baz method for a Foo record!"))) +nil +user=> (baz (Date.)) +"baz method for a Date: Fri Jul 21 14:04:46 JST 2017" +user=> (baz (Foo. 1 1)) +"baz method for a Foo record!" +---- + +The main thing to realize here is that protocols are more powerful than Interfaces because we are able to create custom abstraction for Types that we do not control (e.g. java.util.Date). + I don't think Interface or Type need to be capitalized. ------------------------------ In content/guides/clj_datatype_constructs.adoc <#202 (comment)>: > +user=> (baz rf) +"reified baz" +user=> (.close rf) +"reified closing!!" +nil +---- + +One might ask "Doesn't proxy achieves the same if you do not need to extend a concrete Type?" + +The answer is reify has better performance. + +== Take away +To wrap up, here are some rules of thumb: + +* Prefer protocols and records over Java Types; stay in Clojure +* If you must extend a Java Class, use proxy +* If you want a on-off implementation of a Protocol/Interface, use reify "on-off" has a typo, but I think "anonymous instance" is better — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#202 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AK8iURgPp3iXMY1MKCmcht3BJ01_GL2cks5sU3M9gaJpZM4OfCfp> .

[iku000888]

@puredanger

Overall thanks for making this so much better!
I think I addressed your comments, but let me know if I missed something or there is anything else to do :)

[iku000888]

@puredanger ping?

[iku000888]

@puredanger Is there anything I can do to carry this forward?
I understand Clojure 1.9 is just around the corner, so no rush :)

[puredanger]

Post 1.9 I'm going to try to work my way through some of the backlog here, I'll let you know.

[iku000888]

@puredanger ?

[puredanger]

Proxies should probably be the least frequently used so I don't like starting this guide with it. Should move to the end.

[puredanger]

proxy should have code syntax highlighting. Class should not be capitalized here.

[puredanger]

remove "the good old", code format for java.util.ArrayList

[puredanger]

Interfaces should not be capitalized here.

[puredanger]

"Java stuff" is too informal

[puredanger]

Why is this called "Leaving Java"?

[puredanger]

I think this could use some elaboration.

[puredanger]

... or don't have map semantics

[puredanger]

Don't need to editorialize in the header

[puredanger]

code font for ArrayList and Foo

[puredanger]

code font for java.util.Date

[puredanger]

I think it would be better if this was a real example rather than IBaz / Foo.

[puredanger]

Can we make this a real example?

[puredanger]

Can we get a more meaningful example?

[puredanger]

Code font for code stuff

[puredanger]

there is some disagreement in pronouns here between "things" and "it". Protocol and Interface don't need to be capitalized here.

[puredanger]

Types doesn't need to be capitalized. I'm not sure what's actually meant by "Java types" here though.

[puredanger]

Class doesn't need to be capitalized here and I would move proxy to the end

[puredanger]

Protocol / Interface don't need to be capitalized

[puredanger]

This is a good start but it real needs more motivating examples and prose. This has a lot of "how" but not enough "why". What about gen-class?

[iku000888]

Thanks for the feedback! Will digest them slowly... 🙏

[wildwestrom]

Hey @iku000888, can I pick up where you left off?
I'd love to see this added to the site!

[iku000888]

@wildwestrom Of course! Thanks for asking. Happy to let go of any credit to me as well.

[wildwestrom]

@wildwestrom Of course! Thanks for asking. Happy to let go of any credit to me as well.

Ok, I'm thinking I'll fork your repo and then fetch the upstream changes. Is there a cleaner way to do it though? I'd rather not make a new PR and just edit this one directly.

[iku000888]

@wildwestrom
Tried adding you as a collaborator on my fork. Perhaps you can push on this branch?

[wildwestrom]

@iku000888 I'm having a bit of trouble with that.

$ git push
ERROR: Permission to iku000888/clojure-site.git denied to wildwestrom.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

[iku000888]

@wildwestrom On my end it says the invite is still pending. Is there anything in your mail?

[wildwestrom]

@iku000888 That was it, my email client was off.

[iku000888]

@wildwestrom
Awesome! Wishing you a productive time ahead!