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 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:

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:

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:

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:

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:

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:

mix test

Check formatting and compile with warnings treated as errors:

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

License

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