Looks well done. I like how the docs describe every syntax feature, and every non-standard feature in detail. Hat tip to implementing Vixie's "*,10" quirk, and to handling DST.
You're welcome! As described in the "Why do you create this crate?" section, I actually started this domain only a few weeks ago. So I experienced how those tribal rules can be confusing and hard to search over the Internet the understand their semantic.
And when I sorted out the parse structure [1] and finished the extensions [2][3], I believe I should write it down for others (and future me) :D
> There are several good candidates like croner and saffron, but they are not suitable for my use case. Both of them do not support defining timezone in the expression which is essential to my use case. Although croner support specific timezone later when matching, the user experience is quite different. Also, the syntax that croner or saffron supports is subtly different from my demand.
>
> Other libraries are unmaintained or immature to use.
>
> Last, most candidates using chrono to processing datetime, while I’d prefer to extend the jiff ecosystem.
This can be optionally supported. To be clear, does it mean almost "RANDOM at construction" and the parser will assign a value by a hash/random function and then the crontab struct has an immutable value of that field?
The way jenkins did it is they took the job name and hashed that. This gives you good staggering while still being consistent from run to run (compared to using a random number). This does mean it is immutable, not just at construction but ideally across separate constructions so long as the seed is the same.
For an API, I could see either taking in something that is hashable or just taking in a number and letting the caller choose their hashing. From the person's perspective writing cron syntax, they shouldn't care so long as they get the intended affect.
Is `timezone` optional? I like it that it has the ability for one to provide it, but not providing it could just use the one the system has been configured to use.
Requiring a timezone seems sensible to me, but I don't understand the choice to make it a required part of the expression, instead of a separate parameter. Most software specifies the timezone separately from the expression (e.g. k8s has separate `schedule` and `timezone` keys).
So many of these restrictions feels arbitrary. Not supporting comments? Why?
Assuming UTC for tz is not weird and cron users expect it,
I guess why even support this specific syntax if the crons need to be edited to fit how this code expects them? There may have been better options if you were going full green field.
> Assuming UTC for tz is not weird and cron users expect it,
That would definitely be weird and unexpected. My crons are interpreted with respect to my system's configured time zone, which seems way more expected than just using UTC.
Taking a datetime and just assuming it's UTC is often a mistake. It's why the TC39 Temporal proposal (overhauling datetimes for Javascript) won't let you silently do it.
Could you elaborate a bit on the issue? I'm not sure you are commenting on cronexpr or other libraries.
In cronexpr, there is no requirement for a timestamp until you'd like to find the next scheduled time, and thus you need to provide a related point.
To decouple with certain datetime lib, I made a `MakeTimestamp` struct which provides multiple constructors. Later, I found it somehow like a function overload :D
Systemd timer units are usually two: one for the service you want to run, one for the timer file.
I think you're confusing systemd timer units with Cronie[0], a crond implementation that I think predates systemd? It's possible there's some systemd thing I don't know about though!
I think most distros at least have an installable crond
With the right harness around it you could trust it. Set it up so that it takes your input, generates the cron expression, then uses a deterministic cron library to spit out a summary of what that expression does plus a list of next upcoming instances.
That should give you all the information you need to determine if it got the right expression.
No, that still leaves a small probability of something weird happening - and since it's a small probability you might not ever spot it in your own testing.
In this case I think it's better to run known, deterministic code that can turn a crontab into a clear explanation.
Looks well done. I like how the docs describe every syntax feature, and every non-standard feature in detail. Hat tip to implementing Vixie's "*,10" quirk, and to handling DST.
You're welcome! As described in the "Why do you create this crate?" section, I actually started this domain only a few weeks ago. So I experienced how those tribal rules can be confusing and hard to search over the Internet the understand their semantic.
And when I sorted out the parse structure [1] and finished the extensions [2][3], I believe I should write it down for others (and future me) :D
[1] https://github.com/tisonkun/cronexpr/pull/4
[2] https://github.com/tisonkun/cronexpr/pull/5
[3] https://github.com/tisonkun/cronexpr/pull/6
Is there a comparison to other cron parsing libraries like Saffron?
https://github.com/cloudflare/saffron
Croner has a table for the syntax supported by it and saffron [1], you can compare it with the one cronexpr supported.
[1] https://github.com/hexagon/croner-rust?tab=readme-ov-file#wh...
As supported in [2],
> There are several good candidates like croner and saffron, but they are not suitable for my use case. Both of them do not support defining timezone in the expression which is essential to my use case. Although croner support specific timezone later when matching, the user experience is quite different. Also, the syntax that croner or saffron supports is subtly different from my demand. > > Other libraries are unmaintained or immature to use. > > Last, most candidates using chrono to processing datetime, while I’d prefer to extend the jiff ecosystem.
[2] https://docs.rs/cronexpr/latest/cronexpr/#why-do-you-create-...
There is also a cron parser library from Cloudflare which is used for their cron jobs: https://github.com/cloudflare/saffron
I knew it. Please see also the comment at https://news.ycombinator.com/item?id=41666886
... and this PR [1][2]
[1] https://github.com/tisonkun/cronexpr/pull/12
[2] https://docs.rs/cronexpr/latest/cronexpr/struct.Crontab.html...
After working with Jenkins which has "hashed value" support for automatic staggering of jobs, I think its essential in any cron syntax evaluater.
This can be optionally supported. To be clear, does it mean almost "RANDOM at construction" and the parser will assign a value by a hash/random function and then the crontab struct has an immutable value of that field?
The way jenkins did it is they took the job name and hashed that. This gives you good staggering while still being consistent from run to run (compared to using a random number). This does mean it is immutable, not just at construction but ideally across separate constructions so long as the seed is the same.
For an API, I could see either taking in something that is hashable or just taking in a number and letting the caller choose their hashing. From the person's perspective writing cron syntax, they shouldn't care so long as they get the intended affect.
Main drawback is the need for timestamps. Most crontab files or expressions I've seen didn't have them.
If you mean timezone, I wrote an FAQ [1]: "Why does the crate require the timezone to be specified in the crontab expression?"
[1] https://docs.rs/cronexpr/latest/cronexpr/#why-does-the-crate...
Is `timezone` optional? I like it that it has the ability for one to provide it, but not providing it could just use the one the system has been configured to use.
Yeah. Actually, this is possible to extend the interface with options to accept
1. Optional Timezone.
2. Second-level precision (perhaps feature flags are more suitable here)
It just falls out my first requirements so I don't support it. Being too generic is a common source of failure in my experience.
As a library developer I have my opinion on how things should be done and provide the default fits that mind :D
Requiring a timezone seems sensible to me, but I don't understand the choice to make it a required part of the expression, instead of a separate parameter. Most software specifies the timezone separately from the expression (e.g. k8s has separate `schedule` and `timezone` keys).
So many of these restrictions feels arbitrary. Not supporting comments? Why?
Assuming UTC for tz is not weird and cron users expect it,
I guess why even support this specific syntax if the crons need to be edited to fit how this code expects them? There may have been better options if you were going full green field.
Good work though!
> Assuming UTC for tz is not weird and cron users expect it,
That would definitely be weird and unexpected. My crons are interpreted with respect to my system's configured time zone, which seems way more expected than just using UTC.
Taking a datetime and just assuming it's UTC is often a mistake. It's why the TC39 Temporal proposal (overhauling datetimes for Javascript) won't let you silently do it.
Sure that’s an alternative too.
Could you elaborate a bit on the issue? I'm not sure you are commenting on cronexpr or other libraries.
In cronexpr, there is no requirement for a timestamp until you'd like to find the next scheduled time, and thus you need to provide a related point.
To decouple with certain datetime lib, I made a `MakeTimestamp` struct which provides multiple constructors. Later, I found it somehow like a function overload :D
Do you mean timezones? if so it shouldn't be that hard to detect if there's no timezone and add it with your own code.
It doesn't need timestamps. It parses crontab to/from timestamps where needed.
isn't cron removed from most distros? now you need 3 or 4 different files for systemd-cronie
Systemd timer units are usually two: one for the service you want to run, one for the timer file.
I think you're confusing systemd timer units with Cronie[0], a crond implementation that I think predates systemd? It's possible there's some systemd thing I don't know about though!
I think most distros at least have an installable crond
[0]: https://github.com/cronie-crond/cronie/
Cron is still part of posix standard
that ship sailed long ago.
If you're into Python, APScheduler is the way to go.
It also has a cron scheduler [0] which includes scheduling down to seconds and perfectly integrates with asyncio [1].
You can also modify the interval on-the-fly.[0] https://apscheduler.readthedocs.io/en/3.x/modules/triggers/c...
[1] https://apscheduler.readthedocs.io/en/3.x/modules/executors/...
+1 for APScheduler, we've been running it in production in multiple apps for going on 4 years now without any issue that I can remember.
[dead]
I've LLM based crontab bot. Where I simply write stuff like "run my backupBitBuckettoDropbox.sh from home directory at 3am everyday".
I never really liked cronjob expressions.
This sounds great, if i could trust it to get it right 100% of the time.
With the right harness around it you could trust it. Set it up so that it takes your input, generates the cron expression, then uses a deterministic cron library to spit out a summary of what that expression does plus a list of next upcoming instances.
That should give you all the information you need to determine if it got the right expression.
You think it would work to just pipe that description and next occurrences and ask an llm if it matches the intended prompt?
No, that still leaves a small probability of something weird happening - and since it's a small probability you might not ever spot it in your own testing.
In this case I think it's better to run known, deterministic code that can turn a crontab into a clear explanation.
Wow. The things people will do to avoid learning cron syntax