Skip to content

Latest commit

 

History

History
177 lines (114 loc) · 8.25 KB

README.adoc

File metadata and controls

177 lines (114 loc) · 8.25 KB
Raw

clojars tests build bb compatible

tick

A Clojure(Script) & babashka library for dealing with time. Intended as a replacement for clj-time.

Based on Java 8 time (on the JVM) and js-joda (on JavaScript runtimes). Javascript’s modern date-time API Temporal is a consideration as an alternative foundation for tick in future. See the Tempo library if interested.

Status

  • tick.core - stable

  • tick.alpha.interval - Alpha: Ready to use with the caveat that the API might still undergo minor changes. Note also that this part of tick is not being actively maintained at the moment (other than to keep existing tests passing). There are currently around 4 open tickets relating to intervals which no one is looking at. It may be maintained again in the future of course.

Should you use Tick for date-time work?

  • If you are just working on the JVM and are comfortable with the java.time API then raw interop will work just fine.

  • If you are working in a Javascript environment then seriously consider using cljc.java-time: Its build size will not adversely affect your users (unless in a highly constrained context such as a microcontroller). The reason is the native Date API is flawed

  • If you meet any of the following criteria, use cljc.java-time:

    • are creating cross-platform date-time logic

    • are not proficient in java.time and would like improved error messages

    • would rather not maintain type hints in your code

  • If you meet the criteria to use cljc.java-time but would like a more terse API and the benefits of e.g. (t/with-clock …​) but will not miss having every date-time recipe one google search away, then tick might be a good choice. Tick uses cljc.java-time so you can always drop to that if Tick is missing something you need.

  • Similar in aiming for a terse API, but jvm-only is clojure.java-time.

Usage

(require '[tick.core :as t])

;; Get the current time
(t/instant)

Top tips

java.time

In both Clojure and Clojurescript versions, tick is just calling through to java.time methods. Understanding the main entities of java.time is necessary to use tick. For example, one should know that there are 2 separate ways to measure amounts of time (Period and Duration), 3 ways to represent a point on the timeline (Instant, ZonedDateTime & OffsetDateTime) and so on.

Instants

Instants are not 'calendar-aware' - they just contain millis+nanos fields representing an offset from the Unix epoch. This means Instants have no method to get their year or month for example, because to do so would require a calendar (e.g. the Gregorian calendar).

However, the following does work in Tick: (t/year (t/instant)). To make that possible, tick first converts the Instant into a ZonedDateTime (which does have a calendar). Take note however that the zone of the ZonedDateTime will be the browser’s or jvm’s timezone. To be explicit about the zone required do this:

(-> (t/instant)
    (t/in "UTC")
    (t/year))

The other cases where calendar-awareness might come up is when formatting Instants to string or when shifting them by e.g. years/months, so Tick shows explanatory error messages in that case.

Singular vs Plural ?

As with java.time, any functions working with amounts of time (ie Durations or Periods), will have names which are in the plural. Functions that work with dates and times are singular. Knowing that, e.g. t/second vs t/seconds makes sense.

Install

Get the latest from Clojars and add to your project.clj, build.boot or deps.edn.

To use this from Clojurescript, you must have at least version 1.11.51. If using shadow-cljs, it must be at least version 2.19.3

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

For Clojurescript users of Tick, see docs/cljs.adoc, for some discussion around Clojurescript build size.

Here is a one-liner to drop into a node repl with tick:

clj -Sdeps '{:deps {org.clojure/clojurescript {:mvn/version "RELEASE" } tick/tick {:mvn/version "RELEASE"} henryw374/js-joda {:mvn/version "RELEASE"} }}' -m cljs.main  -re node  --repl

Here is how to get to a babashka (v 1.2.174+) repl with tick:

export BABASHKA_CLASSPATH=$(clojure -Spath -Sdeps '{:deps {tick/tick {:mvn/version "0.6.0"}}}')

bb

Development

Develop The Documentation Site

Build the html

make

make dev-docs-cljs to build the js for the site needs fixing.

Build a production version of the Documentation Site

The following is not working currently:

make release-docs-cljs

Develop Tick

clj -Atest-clj:test-cljs

  • To start testing clojurescript, follow instructions in the cljs ns.

  • To start testing clojure, follow instructions in the the repl ns.

See the .github dir to see instructions for CLI testing

Release

create a git tag.

make install (this installs in ~/.m2 - check that things look ok)

make deploy - you need to have set up clojars credentials as per https://github.com/applied-science/deps-library

git push origin new-tag-name

Acknowledgements

In particular, special credit to Eric Evans for discovering Allen’s interval algebra and pointing out its potential usefulness, demonstrating a working implementation of Allen’s ideas in his Clojure library.

Thanks also to my esteemed colleagues Patrik Kårlin for his redesign of the interval constructor function, and Henry Widd for porting to cljc.

Copyright & License

The MIT License (MIT)

Copyright © 2016-2021 JUXT LTD.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.