Guide for clojure's datatype constructs #202
Conversation
| @@ -0,0 +1,153 @@ | |||
| = Understanding Clojure's Polymorphism | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
multimethods are out of scope of this guide, so not about polymorphism.
There was a problem hiding this comment.
Updated title.
I do mention deftype, but not in depth believing that by default, one should reach for records.
Feedback would be appreciated though.
|
|
||
| == Goals of this guide | ||
|
|
||
| Clojue supports several constructs for speaking to the Java world |
There was a problem hiding this comment.
"Clojue" typo. Why is "speaking to the Java world" relevant here?
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
Strike "Hopefully" - no reason to be apologetic - make it good and improve it if it's missing something.
| 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 |
There was a problem hiding this comment.
I don't see any reason to include this section, it doesn't seem relevant.
| == 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: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| == 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 |
There was a problem hiding this comment.
I think "It is" should be "They are" here to match plural "protocols".
| [source,clojure-repl] | ||
| ---- | ||
| user=> (extend-protocol IBaz | ||
| Date;;Thing from Java |
There was a problem hiding this comment.
I think the lack of spaces before ;; make "Date;;Thing" look like syntax rather than code + comment - add a space.
There was a problem hiding this comment.
fixed and updated to use ArrayList
| (baz [this] | ||
| (str "baz method for a Date: " | ||
| (.toString this))) | ||
| Foo;;Clojure Record |
| "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). + |
There was a problem hiding this comment.
I don't think Interface or Type need to be capitalized.
|
|
||
| * 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 |
There was a problem hiding this comment.
"on-off" has a typo, but I think "anonymous instance" is better
|
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
force-pushed
the
clj-datatype-guide
branch
2 times, most recently
from
abd428a
to
4462095
Compare
iku000888
force-pushed
the
clj-datatype-guide
branch
from
4462095
to
d5f86fe
Compare
|
Overall thanks for making this so much better! |
|
@puredanger ping? |
|
@puredanger Is there anything I can do to carry this forward? |
|
Post 1.9 I'm going to try to work my way through some of the backlog here, I'll let you know. |
| Because these constructs have overlapping capabilities, it may be confusing to know which construct to use at a given situation. + | ||
| This guide clarifies what each construct is good at, while presenting minimal usage examples. | ||
|
|
||
| == Proxy a Java class and/or Interfaces |
There was a problem hiding this comment.
Proxies should probably be the least frequently used so I don't like starting this guide with it. Should move to the end.
|
|
||
| == Proxy a Java class and/or Interfaces | ||
|
|
||
| The proxy macro can be used to create an adhoc object that extends a Java Class. |
There was a problem hiding this comment.
proxy should have code syntax highlighting. Class should not be capitalized here.
| == Proxy a Java class and/or Interfaces | ||
|
|
||
| The proxy macro can be used to create an adhoc object that extends a Java Class. | ||
| The example below extends the good old java.util.ArrayList such that a Clojure vector |
There was a problem hiding this comment.
remove "the good old", code format for java.util.ArrayList
| (.size px) | ||
| ;; => 10 | ||
| ---- | ||
| The ad hoc object can also implement Java Interfaces: |
There was a problem hiding this comment.
Interfaces should not be capitalized here.
|
|
||
| == Leaving Java with defrecord | ||
|
|
||
| So far this is all dealing with Java stuff from Clojure. + |
| nil | ||
| ---- | ||
|
|
||
| == Leaving Java with defrecord |
There was a problem hiding this comment.
Why is this called "Leaving Java"?
| nil | ||
| ---- | ||
|
|
||
| Records are nicer than Java classes for the reasons described in the https://clojure.org/reference/datatypes#_deftype_and_defrecord[reference]. |
There was a problem hiding this comment.
I think this could use some elaboration.
| Records are nicer than Java classes 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. |
There was a problem hiding this comment.
... or don't have map semantics
| 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 |
There was a problem hiding this comment.
Don't need to editorialize in the header
| * They are a cross platform construct | ||
| * They allow third party types to participate in any protocols | ||
|
|
||
| Let's make a protocol that handles Java ArrayList instances as well as Foo records: |
There was a problem hiding this comment.
code font for ArrayList and Foo
| "Foo Baz" | ||
| ---- | ||
|
|
||
| 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). + |
|
|
||
| [source,clojure-repl] | ||
| ---- | ||
| user=> (defprotocol IBaz |
There was a problem hiding this comment.
I think it would be better if this was a real example rather than IBaz / Foo.
|
|
||
| [source,clojure-repl] | ||
| ---- | ||
| user=> (defrecord Foo [a b] |
There was a problem hiding this comment.
Can we make this a real example?
| ---- | ||
| (import 'java.util.ArrayList) | ||
|
|
||
| (def px (let [atm (atom [])] |
There was a problem hiding this comment.
Can we get a more meaningful example?
| we must: | ||
|
|
||
| * Go to the original source code of java.util.Date and say it implements IBaz | ||
| * Also add IBaz to the official jdk release |
| Unlikely to happen, right? | ||
|
|
||
| == Reify-ing Java Interfaces or Protocols | ||
| Sometimes we want to create things that implement a Protocol/Interface but do not want to give it a name for each of them. link:https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/reify[reify] does exactly that: |
There was a problem hiding this comment.
there is some disagreement in pronouns here between "things" and "it". Protocol and Interface don't need to be capitalized here.
| == Take away | ||
| To wrap up, here are some rules of thumb: | ||
|
|
||
| * Prefer protocols and records over Java Types; stay in Clojure |
There was a problem hiding this comment.
Types doesn't need to be capitalized. I'm not sure what's actually meant by "Java types" here though.
| 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 |
There was a problem hiding this comment.
Class doesn't need to be capitalized here and I would move proxy to the end
|
|
||
| * Prefer protocols and records over Java Types; stay in Clojure | ||
| * If you must extend a Java Class, use proxy | ||
| * If you want an anonymous implementation of a Protocol/Interface, use reify |
There was a problem hiding this comment.
Protocol / Interface don't need to be capitalized
|
Thanks for the feedback! Will digest them slowly... 🙏 |
|
Hey @iku000888, can I pick up where you left off? |
|
@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. |
|
@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. |
|
@wildwestrom On my end it says the invite is still pending. Is there anything in your mail? |
|
@iku000888 That was it, my email client was off. |
|
@wildwestrom |
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
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