yamilmedina / natural-kron

A parser from natural language to a cron expression (port of php's natural-cron-expression)

Natural Kron

A parser that converts natural (English) language to a cron expression written in Kotlin.

Installation

You can add the library to your project using gradle:

implementation("io.github.yamilmedina:natural-kron:1.0.0")

Usage

Using the Unix cron style

This is the default if you don't specify the style of the output:

import io.github.yamilmedina.kron.NaturalKronParser

val expression = "every day at 9am"
val parsed = NaturalKronParser().fromString(expression)

val expectedKronExpressionEveryDayAt9am = "0 9 * * *"
assertEquals(expectedKronExpressionEveryDayAt9am, parsed)  // --> TRUE

Using the Quartz style

Why Quartz like style? If you work with Quartz before, you know that the cron expressions are different from the Unix style. This means they start counting from seconds, adding an initial field to the left. Also, you can not use the day of the week and day of the month fields at the same time¹.

Therefore, in case you want to use Quartz compatible expressions, you can specify the style in the parser, like this:

import io.github.yamilmedina.kron.NaturalKronParser
import io.github.yamilmedina.kron.KronStyle

val expression = "every day at 9am"
val parsed = NaturalKronParser().fromString(expression, KronStyle.QUARTZ)

val expectedKronExpressionEveryDayAt9am = "0 0 9 * * ?"
assertEquals(expectedKronExpressionEveryDayAt9am, parsed)  // --> TRUE

Known limitations

This project is ported "as-is" from the original project, and it has some limitations:

If you provide an invalid expression and a valid time or day part, the parser will return a valid cron expression with default to every day. For example, evaery venus at 5am (note the typo) will return 0 5 * * * because the time part is valid.

The plan is to fix this in the future, and enhance the code.

Credits

This is a port from the project https://github.com/bpolaszek/natural-cron-expression/ written in PHP, to the kotlin language.

License

The MIT license. See LICENSE.

Footnotes

1. Quartz Notes Section ↩