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 https://github.com/clojure/clojure-site/issues/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

[iku000888]

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

On Sat, Aug 5, 2017 at 4:38 AM, Alex Miller [email protected] wrote:

@puredanger 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 https://github.com/clojure/clojure-site/pull/202#discussion_r131450844:

@@ -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 https://github.com/clojure/clojure-site/pull/202#discussion_r131450933:

@@ -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 https://github.com/clojure/clojure-site/pull/202#discussion_r131451106:

@@ -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 https://github.com/clojure/clojure-site/pull/202#discussion_r131451190:

+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 https://github.com/clojure/clojure-site/pull/202#discussion_r131466441:

+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 https://github.com/clojure/clojure-site/pull/202#discussion_r131466688:

•                    (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 https://github.com/clojure/clojure-site/pull/202#discussion_r131466852:

+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 https://github.com/clojure/clojure-site/pull/202#discussion_r131467096:

•     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 https://github.com/clojure/clojure-site/pull/202#discussion_r131467221:

•       (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 https://github.com/clojure/clojure-site/pull/202#discussion_r131467347:

+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 https://github.com/clojure/clojure-site/pull/202#discussion_r131467369:

+== 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 https://github.com/clojure/clojure-site/pull/202#discussion_r131467464:

+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 https://github.com/clojure/clojure-site/pull/202#discussion_r131467838:

+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 https://github.com/clojure/clojure-site/pull/202#pullrequestreview-54436936, 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 ?

[iku000888]

Thanks for the feedback! Will digest them slowly... :pray:

[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!