<commit_before># tick

A Clojure library for dealing with time.

## Install

Add to your lein or boot dependencies:

```clojure
[tick "0.2.0"]
```

## Timelines

Tick adds the concept of immutable *timelines* to java.time. A
timeline is a lazy but orderered sequence of `java.time.ZonedDateTime`
instances.

Timelines are easy to generate. One generator is `periodic-seq`, which
generates a uniform series of times separated by a fixed period.

```clojure
(require '[tick.core :refer [minutes]]
          [tick.timeline :refer [timeline periodic-seq]]
          [tick.clock :refer [now]])

;; A timeline of 15 minute intervals
(take 10
  (timeline (periodic-seq (now) (minutes 15))))
```

Timelines are sequences of instances, and instances are Clojure maps:

```clojure
{:tick/date #object[java.time.ZonedDateTime 0x5a56528d "2012-12-04T05:21Z[Europe/London]"]}
```

Timelines can be finite or infinite.

## Interleaving timelines

Timelines can be interleaved into a consolidated timeline.

`interleave-timelines` takes any number of timelines and returns a
conslidated time-ordered timeline.  amalgamation.

```clojure
(require '[tick.cal :refer [easter-fridays]])

(def holidays
  (interleave-timelines
    (timeline (bank-holiday-mondays))
    (timeline (easter-fridays))))
```

## Schedules

Clojure's `map` takes a function and applies it to every item in a sequence.

Similarly, tick's `schedule` takes a function and applies it to timelines.

Schedules can be run by starting them with a clock.

```clojure
(def schedule (t/schedule println timeline))

(t/start schedule (t/clock-ticking-in-seconds))
```

## Testing

A type of schdule, useful for testing, can be created with `simulate`.

```clojure
(def simulator (t/simulate println timeline))

(t/start simulator (t/fixed-clock ...))
```

If you want to wait for a ticker to complete its journey over a
timeline, `deref` the result of `start`.

At any time after starting a ticker you can find out its future
timeline with `remaining`, while inspecting its clock with `clock`.

## java.time

Most Clojure time libraries use clj-time, but tick uses
[**java.time**](http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html)
which means that it requires Java 8.

Java 8's `java.time` API is both influenced by, and superior to, Joda
Time. It is a modern immutable API that supports functional
programming. Unless you're stuck on Java 7 or ambivalent about library
choice, you should be using `java.time`.

## Discussion

The 'flow of time' complicates our systems and we can simplify them if
we separate the concept of a timeline from the 'flow' of time we
perceive.

For more information, see the author's talk at ClojuTRE-2016 on [The
Universe As A Value](https://www.youtube.com/watch?v=odPAkEO2uPQ)
where he argues that time is a perception.

## Acknowledgements
<commit_msg>README tweaks<commit_after># tick

A Clojure library for dealing with time.

## Install

Add to your lein or boot dependencies:

```clojure
[tick "0.2.0"]
```

## Timelines

Tick adds the concept of immutable *timelines* to java.time. A
timeline is a lazy but orderered sequence of `java.time.ZonedDateTime`
instances.

Timelines are easy to generate. One generator is `periodic-seq`, which
generates a uniform series of times separated by a fixed period.

```clojure
(require '[tick.core :refer [minutes]]
          [tick.timeline :refer [timeline periodic-seq]]
          [tick.clock :refer [now]])

;; A timeline of 15 minute intervals
(take 10
  (timeline (periodic-seq (now) (minutes 15))))
```

Timelines are sequences of ticks, and ticks are Clojure maps. Here's one:

```clojure
{:tick/date #object[java.time.ZonedDateTime 0x5a56528d "2012-12-04T05:21Z[Europe/London]"]}
```

Timelines can be finite or, or of course, infinite so

```clojure
(set! *print-length* 16)
```

to avoid eternal waits.

## Interleaving timelines

Multiple timelines can be interleaved into a consolidated timeline.

`interleave-timelines` takes any number of timelines and returns a
conslidated time-ordered timeline.  amalgamation.

```clojure
(require '[tick.cal :refer [easter-fridays]])

(def holidays
  (interleave-timelines
    (timeline (bank-holiday-mondays))
    (timeline (easter-fridays))))
```

## Schedules

Clojure's `map` takes a function and applies it to every item in a
sequence. Similarly, tick's `schedule` takes a function and applies it
to timelines.

Schedules can be run by starting them with a clock.

```clojure
(def schedule (t/schedule println timeline))

(t/start schedule (t/clock-ticking-in-seconds))
```

You can `stop`, `pause` and `resume` schedules too.

## Testing

A type of schdule, useful for testing, can be created with `simulate`.

```clojure
(def simulator (simulate println timeline))

(start simulator (fixed-clock ...))
```

If you want to wait for a ticker to complete its journey over a
timeline, `deref` the result of `start`.

At any time after starting a ticker you can find out its future
timeline with `remaining`, while inspecting its clock with `clock`.

## java.time

Most Clojure time libraries use clj-time, but tick uses
[**java.time**](http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html)
which means that it requires Java 8.

Java 8's `java.time` API is both influenced by, and superior to, Joda
Time. It is a modern immutable API that supports functional
programming. Unless you're stuck on Java 7 or ambivalent about library
choice, you should be using `java.time`.

## Discussion

The 'flow of time' complicates our systems and we can simplify them if
we separate the concept of a timeline from the 'flow' of time we
perceive.

For more information, see the author's talk at ClojuTRE-2016 on [The
Universe As A Value](https://www.youtube.com/watch?v=odPAkEO2uPQ)
where he argues that time is a perception.

## Acknowledgements

{'fraction_non_alphanumeric': 0.10054626152270399, 'fraction_numerical': 0.015705018777739842, 'mean_word_length': 4.404981549815498, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4239684', 'n_tokens_mistral': 1947, 'n_tokens_neox': 1797, 'n_words': 746}