Clojure Instant Literal & Library

Problems

• 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

Non-problems

• there are no good libraries in this area, we need to invent one
  • Joda

• Provide reader support for time
• Must be pluggable
  • Dictate only print/read format
• Don't dictate return data type
• print is already pluggable

Proposal

• #@ISO8601-STRING reader macro
  • codename, swear-date
• calls pluggable parser fn
  • extension point is via bindable var
• default parser returns j.u.Date
  • provide optional parser for Joda and auto-install if detected?
• print j.u.Dates (and Joda stuff) in this format

Issues

• 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?
• Others I'm sure

Old Notes

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):

• ISO 8601 - Wikipedia
• Joda Design docs - Joda Time
• JSR 310 - http://jcp.org/en/jsr/detail?id=310
• Other languages time libs
• How Hotspot Clocks Work

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)