NAME
Langertha::Holmgang::Sim::Linux::Calendar - systemd calendar expressions (OnCalendar) for the Linux simulator — check, normalise, next elapse
VERSION
version 0.001
SYNOPSIS
use Langertha::Holmgang::Sim::Linux::Calendar ();
my $c = Langertha::Holmgang::Sim::Linux::Calendar::parse('Mon-Fri 06:00');
# { normalized => 'Mon..Fri *-*-* 06:00:00', tz => undef, … } or undef
my $t = Langertha::Holmgang::Sim::Linux::Calendar::next_elapse( $c, $now ); # epoch
my $s = Langertha::Holmgang::Sim::Linux::Calendar::format_local($t); # "Wed 2026-10-21 06:00:00 CEST"
DESCRIPTION
Models systemd's calendar expressions (systemd.time(7)) for OnCalendar= and systemd-analyze calendar, checked against the real systemd-analyze calendar (systemd 257; the table is in t/sim/linux_timer.t):
Shorthands
minutely,hourly,daily,weekly,monthly,quarterly,semiannually,yearly/annually(case-insensitive, also followed by a time zone).Weekdays at the start:
MonorMonday(case-insensitive), lists with,, ranges with..or-; a reversed range (Fri..Mon) is invalid. Normal form as systemd: runs of three or more days asa..b, two days asa,b, all seven days are dropped.Date
Y-M-DorM-D, last day with~(*-02~01); two-digit years are 20xx. TimeH:M[:S], seconds also with a fraction. Every field:*, number, list, rangea..b, stepa/nora..b/n(/1after a range is dropped in the normal form).Time zone at the end:
UTC(case-insensitive),GMT,Etc/UTC,Etc/GMT, the abbreviations of local time (CET,CEST) and the names in%ZONE(Europe, USA, some in Asia). Unknown names are invalid.
Everything else is invalid, e.g. daily 02:00, 02:00 daily, Mo..Fr, Mon..Fri 06:00,Sat 08:00, 24:00, 30 2 * * *, now.
The local time of the simulated servers is Europe/Berlin (CET/CEST by the EU rule). Time zones with daylight saving time follow the EU or the US rule.
parse
my $c = parse($expression);
Checks a calendar expression. Returns undef (systemd does not accept it) or a hash with normalized (normal form as systemd-analyze calendar), tz (name of the time zone or undef for local time), utc (1 for a UTC zone) and the value sets of the fields.
offset
my $sec = offset( $epoch [, $zone] ); # Europe/Berlin: 7200 (CEST) or 3600 (CET)
Offset of a time zone (default Europe/Berlin) at a UTC epoch.
next_elapse
my $t = next_elapse( $c, $after );
The first point in time (epoch) after $after that the expression matches; undef when there is none in the next five years.
format_local
format_local( $t ); # "Wed 2026-10-21 06:00:00 CEST" (local time)
format_local( $t, 1 ); # "Wed 2026-10-21 04:00:00 UTC"
format_local( $t, 'Asia/Tokyo' ); # in another zone
left
left( $seconds ); # "13h", "1 day 2h", "45min" — as systemd ("… left")
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.