cronli5/README.md

Cron Like I'm Five: A Cron to English Utility

> ## DISCLAIMER: IN PROGRESS
> 
> This is a work in progress and does not yet work in all intended cases. DO
> NOT USE until this discalimer has been removed. If you need something like
> this now, use [prettycron][prettycron].

# Cron Like I'm Five: A Cron to English Utility

Generate English language descriptions of schedules from cron patterns.
Accepts classic (five-part) cron patterns, or extended (six-part) cron
patterns, where the first field is assumed to refer to seconds. Accepts the
standard allowed values and the following operators: asterisks (`*`), commas
(`,`), hyphens (`-`), and slashes (`/`).

`cronli5` is a good library to use if you need to display an English language
interpretation of a cron pattern in a Node or in a browser environment. If you
need to do other things with cron patterns, consider a library like [Later.js]
[later]. If you want an alternative to `cronli5`, [prettycron][prettycron] may
also meet your needs as an interpreter.

## Installation

Install using npm:
```
# If you plan to use the cli:
npm install -g cronli5

# For a Node project:
npm install --save cronli5
```

Browser (script tag):
```
<script src="cronli5.min.js" type="text/javascript"></script>
```

When included in a script tag, the `cronli5` function will be available as a
global in the scripts that follow.  
_Unsolicited advice: rather than including
`cronli5` in its own script tag, consider using a bundler like [Browserify]
[browserify], [Rollup][rollup], or [Webpack][webpack] and `include` or
`require` instead. See below._

## Usage

As a command line tool:
```
$ cronli5 "* * * * *"
Runs every minute.
```

Including `cronli5.min.js` in a script tag will expose `cronli5` as a global
object.

Import with require:
```
var cronli5 = require('cronli5');
```

Import as an ESNext module:
```
import cronli5 from 'cronli5';
```

Programmatic usage (ES5):
```
// Cron patterns can be represented as strings
var cronString = '*/5 * * * *';

// Cron patterns can be represented as arrays of cron fields
var cronArray = ['*/5', '*', '*', '*', '*'];

// Cron patterns can be represented as objects
var cronObject = {
  minute: '*/5',
  hour: '*',
  date: '*',
  month: '*',
  weekday: '*',
};

var expectedOutput = 'every five minutes';

expect(cronli5(cronString)).to.equal(expectedOutput);
expect(cronli5(cronArray)).to.equal(expectedOutput);
expect(cronli5(cronObject)).to.equal(expectedOutput);
```

## Options

The `cronli5` function takes an `options` object as its second parameter with
several boolean flag properties supported:
* `ampm` &mdash; Default `true`: Use 12-hour time if `true`, 24-hour time if
`false`.
* `short` &mdash; Default `false`. Use abbreviatted forms if `true`.
* `seconds` &mdash; Default `false`. Always treat the first field of strings
and of arrays as the second field if `true`.
* `years` &mdash; Default `false`. Treat six field string or array patterns as
if the last field is the year field if `true`.

## On Timezones

`cronli5` always describes the pattern in whatever timezone the cron pattern
is being run. This utility does not, nor does it ever intend to, deal with
timezone conversions because, firstly, that functionality would require some
non-trivial dependencies (like [moment][moment] with [moment-timezone]
[moment-timezone]) to even approximate correctness and, secondly, the output
_would still be wrong anyways_ because [timezones are problematic][timezones].
To be accurate, associate the description with a timezone (e.g.
America/Phoenix).

## About

The project name is a reference to the phrase [Explain Like I'm Five (ELI5)]
[eli5], which is used to ask for a friendly, simplified, and layman-accessible
summary of material that may be hard to understand without some background.

`cronli5` was partially inspired by [`prettycron`][prettycron], which itself
is based on code from [a gist by dunse][dunse]. Although `prettycron` was
close to meeting my needs, I wasn't fully satisfied with the output and was
limited by the lack of support for extended cron patterns. `cronli5` tries to
render as many cron patterns in as direct and idiomatic English as possible.

`cronli5` was written from scratch and has no production dependencies. Its
source does not borrow code, in whole or in part, from [prettycron]
[prettycron], [Stack Overflow answers][stackoverflow], or any other project.
Any resemblance to other code, living or dead, is purely coincidental.

## License

*[MIT License][license]*  
_Copyright &copy; 2016 [Andrew Broz][abroz]_

[abroz]: https://github.com/abroz
[browserify]: http://browserify.org/
[dunse]: https://gist.github.com/dunse/3714957
[eli5]: https://www.reddit.com/r/explainlikeimfive/
[later]: https://bunkat.github.io/later/
[license]: ./LICENSE.md
[moment]: http://momentjs.com/
[moment-timezone]: http://momentjs.com/timezone/
[prettycron]: https://github.com/azza-bazoo/prettycron
[rollup]: http://rollupjs.org/
[stackoverflow]: https://stackoverflow.com/
[timezones]: https://www.w3.org/TR/timezone/
[webpack]: https://webpack.github.io/