Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation for calendar-events to include ranges + repititon value #15030

Closed
eikek opened this issue Mar 5, 2020 · 3 comments · Fixed by #15645
Closed

Documentation for calendar-events to include ranges + repititon value #15030

eikek opened this issue Mar 5, 2020 · 3 comments · Fixed by #15645
Labels
documentation
Milestone
v246

Comments

@eikek
Copy link

eikek commented Mar 5, 2020

Is your feature request related to a problem? Please describe.
I'm trying to understand the syntax and semantics of the repetitive calendar events. The man page systemd.time has good info, but I'm missing a clear description on what it means to put a repetition value to a range. My first guess was that the repetition applies to start and end values just as with a single value, generating multiple ranges. So 1..3/5 → 1..3,6..8,11..13,…. Trying to figure out more using systemd-analyze did not help, unfortunately.

I'm using systemd 243. Many calendar events I tried are not valid, according to systemd-analyze, for example:

> systemd-analyze calendar --iterations=5 "*-*-* *:1..5/5:0"
Failed to parse calendar specification '*-*-* *:1..5/5:0': Invalid argument

A slight variation then works:

> systemd-analyze calendar --iterations=5 "*-*-* *:1..6/5:0"
  Original form: *-*-* *:1..6/5:0
Normalized form: *-*-* *:01..06/5:00
    Next elapse: Fri 2020-03-06 00:01:00 CET
       (in UTC): Thu 2020-03-05 23:01:00 UTC
       From now: 12min left
       Iter. #2: Fri 2020-03-06 00:06:00 CET
       (in UTC): Thu 2020-03-05 23:06:00 UTC
       From now: 17min left
       Iter. #3: Fri 2020-03-06 01:01:00 CET
       (in UTC): Fri 2020-03-06 00:01:00 UTC
       From now: 1h 12min left
       Iter. #4: Fri 2020-03-06 01:06:00 CET
       (in UTC): Fri 2020-03-06 00:06:00 UTC
       From now: 1h 17min left
       Iter. #5: Fri 2020-03-06 02:01:00 CET
       (in UTC): Fri 2020-03-06 01:01:00 UTC
       From now: 2h 12min left

I don't understand why that is. And looking at the iterations, this seems the same as *-*-* *:1,6:0. I couldn't find more information than what the man page shows. I hope I didn't miss anything; if not, maybe a update to the man page would be a good idea?

Describe the solution you'd like
Extend the man page by a few more sentences or just a few examples related to ranges + repetition value.

Describe alternatives you've considered
–
@poettering
Copy link
Member

1..17/5 means "every 5 seconds in the range 1..17. Which means on 1, on 1+5, on 1+10, on 1+15. But not on 1+20 anymore, since that's above 17...

@poettering poettering added this to the v246 milestone Mar 31, 2020
@eikek
Copy link
Author

eikek commented Mar 31, 2020

Thank you! Now that I see it, I'm wondering why this didn't occur to me…

@eikek eikek mentioned this issue Mar 31, 2020
Closed
poettering added a commit to poettering/systemd that referenced this issue Apr 30, 2020
@poettering
calendarspec: be more graceful with two kinds of calendar expressions
e4cac01 
This changes the calendarspec parser to allow expressions such as
"00:05..05", i.e. a range where start and end is the same. It also
allows expressions such as "00:1-2/3", i.e. where the repetition value
does not fit even once in the specified range. With this patch both
cases will now be optimized away, i.e. the range is removed and a fixed
value is used, which is functionally equivalent.

See systemd#15030 for an issue where the inability to parse such expressions
caused confusion.

I think it's probably better to accept these gracefully and optimizing
them away instead of refusing them with a plain EINVAL. With a tool such
as "systemd-analyze" calendar it should be easy to figure out the
normalized form with the redundant bits optimized away.
poettering added a commit to poettering/systemd that referenced this issue Apr 30, 2020
@poettering
man: expand on the star…end/repetition time expressions
afae916 
And attempt to explain what is requested in systemd#15030, but still be
concise.

Fixes: systemd#15030
@poettering poettering mentioned this issue Apr 30, 2020
Merged
@poettering
Copy link
Member

Fix in #15645

(i also made sure your first expression parses now, and is normalized so that the repetition just goes away)

@poettering poettering linked a pull request Apr 30, 2020 that will close this issue
some calendar expression fixes and documentation updates #15645
Merged
poettering added a commit to poettering/systemd that referenced this issue May 5, 2020
@poettering
calendarspec: be more graceful with two kinds of calendar expressions
c9c9f6f 
This changes the calendarspec parser to allow expressions such as
"00:05..05", i.e. a range where start and end is the same. It also
allows expressions such as "00:1-2/3", i.e. where the repetition value
does not fit even once in the specified range. With this patch both
cases will now be optimized away, i.e. the range is removed and a fixed
value is used, which is functionally equivalent.

See systemd#15030 for an issue where the inability to parse such expressions
caused confusion.

I think it's probably better to accept these gracefully and optimizing
them away instead of refusing them with a plain EINVAL. With a tool such
as "systemd-analyze" calendar it should be easy to figure out the
normalized form with the redundant bits optimized away.
poettering added a commit to poettering/systemd that referenced this issue May 5, 2020
@poettering
man: expand on the star…end/repetition time expressions
2edc7ae 
And attempt to explain what is requested in systemd#15030, but still be
concise.

Fixes: systemd#15030
eworm-de pushed a commit to eworm-de/systemd that referenced this issue Jun 23, 2020
@poettering @keszybz
calendarspec: be more graceful with two kinds of calendar expressions
e06b940 
This changes the calendarspec parser to allow expressions such as
"00:05..05", i.e. a range where start and end is the same. It also
allows expressions such as "00:1-2/3", i.e. where the repetition value
does not fit even once in the specified range. With this patch both
cases will now be optimized away, i.e. the range is removed and a fixed
value is used, which is functionally equivalent.

See systemd#15030 for an issue where the inability to parse such expressions
caused confusion.

I think it's probably better to accept these gracefully and optimizing
them away instead of refusing them with a plain EINVAL. With a tool such
as "systemd-analyze" calendar it should be easy to figure out the
normalized form with the redundant bits optimized away.

(cherry picked from commit c9c9f6f)
eworm-de pushed a commit to eworm-de/systemd that referenced this issue Jun 23, 2020
@poettering @keszybz
man: expand on the star…end/repetition time expressions
7c6ea7a 
And attempt to explain what is requested in systemd#15030, but still be
concise.

Fixes: systemd#15030
(cherry picked from commit 2edc7ae)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation
Milestone
v246
Development

Successfully merging a pull request may close this issue.

some calendar expression fixes and documentation updates poettering/systemd
3 participants
@eikek @poettering @anitazha