cronstrue_ex

# CronstrueEx

CronstrueEx is an Elixir library that converts cron expressions into clear,
human-readable descriptions.

It follows the behavior and public options of the npm package
[cRonstrue](https://github.com/bradymholt/cRonstrue) as closely as practical,
while providing an idiomatic Elixir API and no runtime dependencies.

> [!IMPORTANT]
> **CronstrueEx is under active development.** The current release implements a
> useful subset of cRonstrue, but compatibility is not complete and the API may
> change before the first stable release. The package is not published on Hex
> yet.

## Current functionality

- Standard five-field cron expressions: minute, hour, day of month, month, and
  day of week.
- Numeric values, wildcards, lists, ranges, and increments.
- Case-insensitive three-letter English month and weekday names such as `JAN`
  and `MON`.
- Human-readable descriptions in English and Spanish.
- Locale-specific clock defaults: English uses 12 hours and Spanish uses 24
  hours.
- Concise and verbose descriptions.
- Configurable hour formatting and parse-error handling.
- Validation of the syntax and ranges currently supported by the parser.

## Usage

English is the default locale:

```elixir
CronstrueEx.to_string("* * * * *")
# => "Every minute"

CronstrueEx.to_string("*/5 * * * *")
# => "Every 5 minutes"

CronstrueEx.to_string("30 11 * * 1-5")
# => "At 11:30 AM, Monday through Friday"

CronstrueEx.to_string("23 12 15 Jan-Mar *")
# => "At 12:23 PM, on day 15 of the month, January through March"
```

Select Spanish with `locale: "es"` or `locale: :es`:

```elixir
CronstrueEx.to_string("*/5 * * * *", locale: "es")
# => "Cada 5 minutos"

CronstrueEx.to_string("30 23 * * MON-FRI", locale: :es)
# => "A las 23:30, de lunes a viernes"
```

## Supported syntax

| Syntax | Example | Meaning |
| --- | --- | --- |
| Wildcard | `* * * * *` | Every minute |
| Value | `30 11 * * *` | At 11:30 AM |
| List | `0 9,17 * * *` | At 9:00 AM and 5:00 PM |
| Range | `0 9-17 * * *` | Every hour from 9:00 AM to 5:00 PM |
| Increment | `*/10 * * * *` | Every 10 minutes |
| Named range | `30 11 * * MON-FRI` | At 11:30 AM, Monday through Friday |

Names are accepted only in English in the cron expression, regardless of the
output locale. For example, use `MON-FRI` when requesting either English or
Spanish output.

## Options

Options are passed as a keyword list to `CronstrueEx.to_string/2`:

| Option | Default | Description |
| --- | --- | --- |
| `:locale` | `"en"` | Output language: `"en"`, `:en`, `"es"`, or `:es` |
| `:verbose` | `false` | Includes wording normally omitted for brevity |
| `:use_24_hour_time_format` | Locale default | Overrides the locale's clock format |
| `:trim_hours_leading_zero` | `false` | Removes a leading zero from formatted hours |
| `:throw_exception_on_parse_error` | `true` | Raises on invalid input when enabled |

For example:

```elixir
CronstrueEx.to_string("30 22 * * *", use_24_hour_time_format: true)
# => "At 22:30"

CronstrueEx.to_string("* * * * *", verbose: true)
# => "Every minute, every hour, every day"
```

Invalid expressions raise `CronstrueEx.ParseError` by default. A localized
generic message can be returned instead:

```elixir
CronstrueEx.to_string("invalid", locale: "es", throw_exception_on_parse_error: false)
# => "Ocurrió un error mientras se generaba la descripción de la expresión. Revise la sintaxis de la expresión de cron."
```

## Current limitations

- Only five-field expressions are supported.
- Seconds and year fields are not supported.
- Quartz syntax such as `?`, `L`, `W`, and `#` is not supported.
- Cron nicknames such as `@daily`, `@weekly`, and `@reboot` are not supported.
- Some complex combinations may not yet produce exactly the same description
  as cRonstrue.
- CronstrueEx describes schedules; it does not calculate future executions or
  run scheduled jobs.

## Roadmap

Planned work includes broader parity for five-field expressions, six- and
seven-field expressions, cron nicknames, Quartz syntax, additional formatting
options, and more locales. Features will be added incrementally with compatibility
tests derived from cRonstrue v3.24.0.

## Requirements

- Elixir 1.14 or later

## Installation

CronstrueEx is not available on Hex yet. Once published, it is expected to be
installed by adding it to the dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:cronstrue_ex, "~> 0.1.0"}
  ]
end
```

Until then, clone the repository to try or contribute to the project.

## Development

Run the test suite:

```console
mix test
```

Check formatting and compile with warnings treated as errors:

```console
mix format --check-formatted
mix compile --warnings-as-errors
```

## License

CronstrueEx is released under the MIT License. See [LICENSE](LICENSE) for
details. Its behavior and parts of its locale wording are based on the
MIT-licensed cRonstrue project.