"This is a toe in the water experiment for support for more data types (like URIs, IPs, UUIDs etc) where the representation will inevitably differ across applications. The idea is that the reader support conveys the semantics (this is a point in time, not a string or number) and printed representation, without dictating the programmatic type. This will allow people to use Clojure data as a richer transport format without locking anyone (or even two ends of the same application) into particular libraries etc." – Rich Hickey on the dev list
- Many programs need to manipulate time-related values and we have no way to incorporate them in the data format used by read.
- Different representations are commonplace and necessary.
- The Java classes in this area are bad
there are no good libraries in this area, we need to invent one
- Provide reader support for time
- Must be pluggable
- Dictate only print/read format
- Don't dictate return data type
- print is already pluggable
- #@ISO8601-STRING reader macro
- calls pluggable parser fn
- extension point is via bindable var
- default parser
- option 1: uses Joda to parse, returns java.util.Date
- throws exception referencing Joda if Joda not on classpath
- option 2: like 1, but uses JDK 6 java.xml.bindDatatypeConverter
- how compatible is XML dateTime with ISO8601? Schema spec says "inspired by" which does not inspire confidence
- print java.util.Date, Joda DateTime in swear-date format
Q & A
- Would Clojure apps now all depend on Joda? No. Joda is only a requirement for building Clojure itself. (Maven's "provided" dependency scope keeps the static tools at bay, and Joda is only loaded dynamically if present.)
- What about localization, time zones, etc? These are not part of the semantics of an instant. You can choose a local representation that complects this, but you should not assume it will be conveyed by print/read.
- What about types that lack resolution to match what ISO8601 can say? Sorry! Bind an instant reader that produces a better type of live with your impoverished local rep.
- RH - instant reader is a bad name, as it is not a reader in the sense the reader is. More like a parsing function. Or let's just call it the read-instant function and not name what it is.
- It would be cool if there were a library for manipulating instants with convenient Clojure syntax. Darn straight. Let's have a contrib for this.
- would be nice to return something meaningful given time part only
- JDK 5 has no ISO8601 parser
- JDK 6 has only in javax.xml.bind.DatatypeConverter
- Using Joda for parse introduces dep into Clojure
- Print/read veracity requires matching parsers
- is this a real issue?
- is flexibility allowing difference not a feature?
- SDH liking this flexibility less, still on fence
- Others I'm sure
Goal for an instant literal:
RH - this presumes an instant literal is a goal, it is not necessarily so
Provide a relatively easy way to create a human readable time instant. Also provide a protocol based library of date functions
What this is:
- A Reader Macro
- Complies with ISO8601
- Joda is the gold standard for parsing. Specifically, the formatter returned by org.joda.time.format.ISODateTimeFormat/dateTime
- Aware of offset from UTC
- Provides a Dateable Protocol
- Provides a CljDate type, which is aware of both the UTC instant and offset from UTC
- Equality/Hashcode based on instant
- Display based on instant+offset
- Plays nice w/ Joda, includes docs to extend to Joda.
- A collection of very common comparators and predicates.
- A collection of converter functions
- Written in Clojure, w/ exception of reader assignment
What this is NOT:
- Time Zone support
- Multiple Chonology support
- Clever duration support
- Directly dependent upon Joda
- A PITA to use
Things to read to facilitate intelligent discussion (TO DO):
Known issues/things to solve
- Support for only a date or time of day?
- Allow partial composition in a literal?
- Parsing dates before 1970 (Epoch start)