Skip to content

Latest commit

 

History

History
166 lines (102 loc) · 6.1 KB

README.md

File metadata and controls

166 lines (102 loc) · 6.1 KB
Raw

Clojars Project Tests build bb compatible

cljc.java-time

A Clojure(Script) library which mirrors the java.time api through kebab-case-named vars.

The java.time api is augmented with:

  • predicate functions for each entity type: (cljc.java-time.extn.predicates/instant? x)
  • more helpful error messages for unsupported operations on Instants

This library uses a pure-JS implementation of java.time, see here for discussion on whether that affects application performance or build size

See my talk at Clojure/North 2019 for more background.

Temporal, the new JS platform Date-Time lib has been considered for use as an alternative basis of this library instead of js-joda, but although it has some overlap with java.time, Temporal is different enough that implementing cljc.java-time would be very difficult. For a dependency-free Clojure(Script) date-time API, see Tempo

Related Libraries

tick is a higher level date-time library that uses this one. Even if you're using cljc.java-time directly, ie not through tick, it has very relevant docs on extra setup for use with ClojureScript

time-literals is a Clojure(Script) library which provides tagged literals for objects from jsr-310 domain

Rationale

This library sits atop java.time on the jvm and cljs.java-time on Javascript platforms. Writing cross-platform code that uses those libraries directly is harder than interop normally is because:

  • To call the java.time 'static' methods in a cljc file you need to use the dot-special-form which is not idiomatic
  • The underlying js library has changed the name of the getter methods in java.time (in almost all cases) to remove the 'get' part of the name. There are ways to get around that on a case by case basis, but this library handles it for you.

.. but I just develop on the JVM Only

Reasons to use this:

  • All type hinting is done for you
  • comp, apply, juxt and all other clojure.core fns that apply to fns can now be used without anon fns: #(.foo %)
  • In fact, instead of seeing #(.foo %) in someone's code and not knowing what foo is, you'll have a properly namespaced clojure function foo - much better!
  • predicates, for example (local-date? x)

How it works

For every class in java.time, there is a clojure namespace.

For example, corresponding to java.time.LocalDate, there is a namespace

cljc.java-time.local-date

In that and every other namespace, there is one var per public method/field in the corresponding class.

For example, for the method java.time.LocalDate/parse, there is a corresponding function cljc.java-time.local-date/parse

Instance methods take the instance as the extra first arg

Usage

Clojars badge is at the top of this README

Version 0.1.9 and up require minimum Clojurescript version of 1.10.741

If using cljsjs, add js-joda and js-joda-locale-en-us to your dependencies as well

In .cljc file

(ns my.cljc
  (:require  [cljc.java-time.local-date :as ld])
   
;create a date
(def a-date (ld/parse "2019-01-01"))
   
;add some days
(ld/plus-days a-date 99)

Roundtripping with legacy Date

(require '[cljc.java-time.instant :as i])

;cljs
(-> (js/Date.) (.getTime) (i/of-epoch-milli) (i/to-epoch-milli) (js/Date.))

;clj 
(-> (Date.) (.getTime) (i/of-epoch-milli) (i/to-epoch-milli) (Date.))

Here is how to get to a babashka (v 1.2.174+) repl with cljc.java-time:

export BABASHKA_CLASSPATH=$(clojure -Spath -Sdeps '{:deps {com.widdindustries/cljc.java-time {:mvn/version "RELEASE"}}}')

bb

Problems & Irregularities

java.time.Year#isLeap exists as an instance method and a static method. Only the static version has been wrapped.

Inheritance/Polymorphism

The code of this project consists of mechanically generated functions for the java.time methods, even if those methods are inherited via superclasses or interfaces. In this project, functions are generated in every class they can be applied to. For example there is cljc.java-time.temporal.temporal/is-supported and also cljc.java-time.local-date/is-supported, with the latter being essentially unnecessary but included anyway.

Note

Java 9

A couple of new methods were added to java.time in Java 9 - these are not included in this library because according to the Clojure Survey about half of Clojure users are still on Java 8 :(

ClojureScript

Be aware that the underlying js implementation is probably only 99% complete. Anything you find missing can be added via pull request to js-joda

Development

The code of the project is generated by the generate-library-code! function in the dev/gen.clj namespace.

Clojure and Clojurescript

To run all tests:

make test

Start a repl:

 clj -Adev:test:test-cljs

For Clojurescript dev, see the dev/cljs.clj file for functions to start test build in shadow and run tests.

babashka

Start babashka as follows

deps -A:test -Scommand "bb -cp {{classpath}}" --socket-repl 1666'

and run tests from the repl

one cmd to do this would be preferable

License

Copyright © 2021 Widd Industries

Distributed under the MIT License