Skip to content

Update reader docs for instant and UUID #256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 3 commits into from
Mar 29, 2018
Merged

Update reader docs for instant and UUID #256

merged 3 commits into from
Mar 29, 2018

Conversation

jmckitrick
Copy link
Contributor

@jmckitrick jmckitrick commented Mar 29, 2018 •
edited
Loading

  • Have you read the guidelines for contributing?
  • Have you signed the Clojure Contributor Agreement?
  • Have you verified your asciidoc markup is correct?
@jmckitrick jmckitrick changed the title Jmckitrick patch 1 Mar 29, 2018
puredanger
puredanger requested changes Mar 29, 2018
View reviewed changes
Copy link
Member

@puredanger puredanger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably that can be added, but this is a good start.
content/reference/reader.adoc Outdated
@@ -209,6 +209,35 @@ by invoking the Var `#'my.project.foo/bar` on the vector `[1 2 3]`. The data rea

Reader tags without namespace qualifiers are reserved for Clojure. Default reader tags are defined in https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/default-data-readers[default-data-readers] but may be overridden in `data_readers.clj` or by rebinding https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/%2Adata-readers%2A[pass:[*data-readers*]]. If no data reader is found for a tag, the function bound in https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/%2Adefault-data-reader-fn%2A[pass:[*default-data-reader-fn*]] will be invoked with the tag and value to produce a value. If pass:[*default-data-reader-fn*] is nil (the default), a RuntimeException will be thrown.

Clojure 1.4 introduced some tagged literals useful for Java interop. So far, these include instants and UUIDs.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In first sentence, I wouldn't position this as "for Java interop", they are useful regardless. In the second, no need for "so far" - if it changes, we'll update.
content/reference/reader.adoc Outdated
@@ -209,6 +209,35 @@ by invoking the Var `#'my.project.foo/bar` on the vector `[1 2 3]`. The data rea

Reader tags without namespace qualifiers are reserved for Clojure. Default reader tags are defined in https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/default-data-readers[default-data-readers] but may be overridden in `data_readers.clj` or by rebinding https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/%2Adata-readers%2A[pass:[*data-readers*]]. If no data reader is found for a tag, the function bound in https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/%2Adefault-data-reader-fn%2A[pass:[*default-data-reader-fn*]] will be invoked with the tag and value to produce a value. If pass:[*default-data-reader-fn*] is nil (the default), a RuntimeException will be thrown.

Clojure 1.4 introduced some tagged literals useful for Java interop. So far, these include instants and UUIDs.

Instants have the format `#inst "yyyy-mm-ddThh:mm:ss.fff+hh:mm"`. The default reader will parse the supplied string into a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that while this is the full format, most of the parts are optional. So #inst "2018" is a valid inst literal as is #inst "2018-01-01" etc. Might need to check the code for allowed options.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you asking me to check the code, or that I should add that note to the docs?
content/reference/reader.adoc Outdated
;=> true
----

Since *data-readers* is a dynamic var that can be bound, you can replace the default reader with a different one. For example, `clojure.instant/read-instant-calendar` will parse the literal into a `java.util.Calendar`, while `clojure.instant/read-instant-timestamp` will parse it into a `java.util.Timestamp`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need markup around *data-readers* or it will be treated as asciidoc emphasis. Can use pass:[*data-readers*] to tell asciidoc to pass the string as is.
johnmn3
johnmn3 suggested changes Mar 29, 2018
View reviewed changes
Copy link

@johnmn3 johnmn3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are three quick changes.
content/reference/reader.adoc Outdated
@@ -209,6 +209,35 @@ by invoking the Var `#'my.project.foo/bar` on the vector `[1 2 3]`. The data rea

Reader tags without namespace qualifiers are reserved for Clojure. Default reader tags are defined in https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/default-data-readers[default-data-readers] but may be overridden in `data_readers.clj` or by rebinding https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/%2Adata-readers%2A[pass:[*data-readers*]]. If no data reader is found for a tag, the function bound in https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/%2Adefault-data-reader-fn%2A[pass:[*default-data-reader-fn*]] will be invoked with the tag and value to produce a value. If pass:[*default-data-reader-fn*] is nil (the default), a RuntimeException will be thrown.

Clojure 1.4 introduced some tagged literals useful for Java interop. So far, these include instants and UUIDs.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd simplify this and just say:

Clojure 1.4 introduced the instant and UUID tag literals.

Tagged literals are about more than just Java interop, IME.

And then just make that the first line of the next paragraph.
content/reference/reader.adoc Outdated
;=> true
----

Another tagged literal is `#uuid`, which will be parsed into a `java.util.UUID` as shown below:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've already introduced the UUID tagged literals above, so here we should say:

The #uuid tagged literal will be parsed...
content/reference/reader.adoc Outdated
;=> true
----

Since *data-readers* is a dynamic var that can be bound, you can replace the default reader with a different one. For example, `clojure.instant/read-instant-calendar` will parse the literal into a `java.util.Calendar`, while `clojure.instant/read-instant-timestamp` will parse it into a `java.util.Timestamp`:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*data-reader* is not being properly escaped here.
@jmckitrick
Copy link
Contributor Author

@puredanger @johnmn3 updated
@puredanger puredanger merged commit 2a0dcca into clojure:master Mar 29, 2018
@puredanger puredanger mentioned this pull request Mar 29, 2018
Closed
@jmckitrick jmckitrick deleted the jmckitrick-patch-1 branch March 30, 2018 00:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
3 participants
@jmckitrick @johnmn3 @puredanger