Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.
Sign upGitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
Guide for clojure's datatype constructs #202
Open
Conversation
|
It's a good start but I think it would help to clarify what the goal is. |
| @@ -0,0 +1,153 @@ | |||
| = Understanding Clojure's Polymorphism | |||
puredanger
Aug 4, 2017
Member
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 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
Aug 11, 2017
Author
Contributor
multimethods are out of scope of this guide, so not about polymorphism.
multimethods are out of scope of this guide, so not about polymorphism.
iku000888
Aug 11, 2017
Author
Contributor
Updated title.
I do mention deftype, but not in depth believing that by default, one should reach for records.
Feedback would be appreciated though.
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 |
puredanger
Aug 4, 2017
Member
"Clojue" typo. Why is "speaking to the Java world" relevant here?
"Clojue" typo. Why is "speaking to the Java world" relevant here?
iku000888
Aug 11, 2017
Author
Contributor
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.
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. |
puredanger
Aug 4, 2017
Member
Strike "Hopefully" - no reason to be apologetic - make it good and improve it if it's missing something.
Strike "Hopefully" - no reason to be apologetic - make it good and improve it if it's missing something.
iku000888
Aug 11, 2017
Author
Contributor
Good point :)
Good point :)
| 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 |
puredanger
Aug 4, 2017
Member
I don't see any reason to include this section, it doesn't seem relevant.
I don't see any reason to include this section, it doesn't seem relevant.
iku000888
Aug 11, 2017
Author
Contributor
Dropped
Dropped
| == 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: |
puredanger
Aug 4, 2017
Member
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.
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
Aug 11, 2017
Author
Contributor
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.
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 |
puredanger
Aug 4, 2017
Member
I think "It is" should be "They are" here to match plural "protocols".
I think "It is" should be "They are" here to match plural "protocols".
iku000888
Aug 11, 2017
Author
Contributor
fixed
fixed
| [source,clojure-repl] | ||
| ---- | ||
| user=> (extend-protocol IBaz | ||
| Date;;Thing from Java |
puredanger
Aug 4, 2017
Member
I think the lack of spaces before ;; make "Date;;Thing" look like syntax rather than code + comment - add a space.
I think the lack of spaces before ;; make "Date;;Thing" look like syntax rather than code + comment - add a space.
iku000888
Aug 11, 2017
Author
Contributor
fixed and updated to use ArrayList
fixed and updated to use ArrayList
| (baz [this] | ||
| (str "baz method for a Date: " | ||
| (.toString this))) | ||
| Foo;;Clojure Record |
puredanger
Aug 4, 2017
Member
same as prior
same as prior
iku000888
Aug 11, 2017
Author
Contributor
fixed
fixed
| "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). + |
puredanger
Aug 4, 2017
Member
I don't think Interface or Type need to be capitalized.
I don't think Interface or Type need to be capitalized.
iku000888
Aug 11, 2017
Author
Contributor
fixed
fixed
|
|
||
| * 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 |
puredanger
Aug 4, 2017
Member
"on-off" has a typo, but I think "anonymous instance" is better
"on-off" has a typo, but I think "anonymous instance" is better
iku000888
Aug 11, 2017
Author
Contributor
fixed
fixed
|
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
iku000888:clj-datatype-guide
branch
2 times, most recently
from
abd428a
to
4462095
|
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 |
puredanger
Apr 6, 2018
Member
Proxies should probably be the least frequently used so I don't like starting this guide with it. Should move to the end.
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. |
puredanger
Apr 6, 2018
Member
proxy should have code syntax highlighting. Class should not be capitalized here.
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 |
puredanger
Apr 6, 2018
Member
remove "the good old", code format for java.util.ArrayList
remove "the good old", code format for java.util.ArrayList
| (.size px) | ||
| ;; => 10 | ||
| ---- | ||
| The ad hoc object can also implement Java Interfaces: |
puredanger
Apr 6, 2018
Member
Interfaces should not be capitalized here.
Interfaces should not be capitalized here.
|
|
||
| == Leaving Java with defrecord | ||
|
|
||
| So far this is all dealing with Java stuff from Clojure. + |
puredanger
Apr 6, 2018
Member
"Java stuff" is too informal
"Java stuff" is too informal
| nil | ||
| ---- | ||
|
|
||
| == Leaving Java with defrecord |
puredanger
Apr 6, 2018
Member
Why is this called "Leaving Java"?
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]. |
puredanger
Apr 6, 2018
Member
I think this could use some elaboration.
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. |
puredanger
Apr 6, 2018
Member
... or don't have map semantics
... 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 |
puredanger
Apr 6, 2018
Member
Don't need to editorialize in the header
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: |
puredanger
Apr 6, 2018
Member
code font for ArrayList and Foo
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). + |
puredanger
Apr 6, 2018
Member
code font for java.util.Date
code font for java.util.Date
|
|
||
| [source,clojure-repl] | ||
| ---- | ||
| user=> (defprotocol IBaz |
puredanger
Apr 6, 2018
Member
I think it would be better if this was a real example rather than IBaz / Foo.
I think it would be better if this was a real example rather than IBaz / Foo.
|
|
||
| [source,clojure-repl] | ||
| ---- | ||
| user=> (defrecord Foo [a b] |
puredanger
Apr 6, 2018
Member
Can we make this a real example?
Can we make this a real example?
| ---- | ||
| (import 'java.util.ArrayList) | ||
| (def px (let [atm (atom [])] |
puredanger
Apr 6, 2018
Member
Can we get a more meaningful example?
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 |
puredanger
Apr 6, 2018
Member
Code font for code stuff
Code font for code stuff
| 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: |
puredanger
Apr 6, 2018
Member
there is some disagreement in pronouns here between "things" and "it". Protocol and Interface don't need to be capitalized here.
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 |
puredanger
Apr 6, 2018
Member
Types doesn't need to be capitalized. I'm not sure what's actually meant by "Java types" here though.
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 |
puredanger
Apr 6, 2018
Member
Class doesn't need to be capitalized here and I would move proxy to the end
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 |
puredanger
Apr 6, 2018
Member
Protocol / Interface don't need to be capitalized
Protocol / Interface don't need to be capitalized
|
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? |
|
Thanks for the feedback! Will digest them slowly... |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
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