Skip to end of metadata
Go to start of metadata

"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
    • Joda
  • 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
    • codename, swear-date
  • 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
    • what other classes?
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

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

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)
  1. Oct 29, 2010

    +1 for this... and not just because I'm waist deep in writing a calendaring product.

    A literal for creating dates would really be a great idea.

    I've found the most common thing I'm having to do is add units of time to an Instant, the terms I've been hankering for:

    • before?
    • after?
    • plus (an interval?)
    • add (ideally able to handle different units - perhaps the unit type given in meta data? - explicit fn's like add-days would satisfy this too)
    • subtract (ditto for 'add').
    • between?

    Let me know how I can help.

  2. Oct 26, 2011

    What does "Aware of offset from UTC" mean? Is that a characteristic that can survive transformations? Is the intention that the instant be composite? (i.e. an instant and an offset is not an instant) What problem is the offset part trying to solve?

  3. Oct 27, 2011

    I think it would be sufficient for the parser to recognize the +/- timezone offsets allowed by ISO8601. Once an instant has been read, it should be in UTC.

  4. Nov 04, 2011

    seems like this is about mandating a serialization format, not the format in memory, so if anything is mandated to be UTC, it should be the intervals as printed, what ends in memory for it is the responsibility of instant-read and whoever set it.

  5. Aug 13, 2012

    For the historical record, the tagged literal feature, including #inst support, was shipped in Clojure 1.4.  Relevant issues: CLJ-871 and CLJ-928.