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: Mon or Monday (case-insensitive), lists with ,, ranges with .. or -; a reversed range (Fri..Mon) is invalid. Normal form as systemd: runs of three or more days as a..b, two days as a,b, all seven days are dropped.

  • Date Y-M-D or M-D, last day with ~ (*-02~01); two-digit years are 20xx. Time H:M[:S], seconds also with a fraction. Every field: *, number, list, range a..b, step a/n or a..b/n (/1 after 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.