README
¶
zCalendar 
A CalendarSpec (almost) compliant calendar event library.
Why ?
Because cron-spec is notoriously hard to read, not intuitive, and not standardized.
Calendar Event format
Note Shamelessly taken from System's documentation, with some changes to reflect what is or isn't impmemented as of the time of writing.
Calendar events may be used to refer to one or more points in time in a single expression.
Thu,Fri 2012-*-1,5 11:12:13
The above refers to 11:12:13 of the first or fifth day of any month of the year 2012, but only if that day is a Thursday or Friday.
The weekday specification is optional. If specified, it should consist of one or more English language weekday names, either in the abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not matter), separated by commas. Specifying two weekdays separated by ".." refers to a range of continuous weekdays. "," and ".." may be combined freely.
Monday is considered the first day of the week and a range of weekdays must be
contained in the same week. For example, "every weekday except Thursday" cannot
be written Fri..Wed; it may be written Mon..Wed,Fri..Sun instead.
In the date and time specifications, any component may be specified as "*" in which case any value will match. Alternatively, each component can be specified as a list of values separated by commas. Values may be suffixed with "/" and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched. Two values separated by ".." may be used to indicate a range of values; ranges may also be followed with "/" and a repetition value.
Either time or date specification may be omitted, in which case --* and 00:00:00 is implied, respectively. If the year component is not specified, "*-" is assumed. If the second component is not specified, ":00" is assumed.
A timezone specification may be added at the end of the expression. It can be
either UTC or a timezone as defined by the IANA (see
here for a
somewhat complete list).
Examples for valid timestamps and their normalized form:
Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
Wed *-1 → Wed *-*-01 00:00:00
Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
Wed, 17:48 → Wed *-*-* 17:48:00
Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
*-*-7 0:0:0 → *-*-07 00:00:00
10-15 → *-10-15 00:00:00
monday *-12-* 17:00 → Mon *-12-* 17:00:00
Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
12..14:10,20,30 → *-*-* 12..14:10,20,30:00
mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
03-05 08:05:40 → *-03-05 08:05:40
08:05:40 → *-*-* 08:05:40
05:40 → *-*-* 05:40:00
Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
2003-03-05 05:40 → 2003-03-05 05:40:00
2003-02..04-05 → 2003-02..04-05 00:00:00
2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
2003-03-05 → 2003-03-05 00:00:00
03-05 → *-03-05 00:00:00
*:2/3 → *-*-* *:02/3:00
Usage
The main structure is Expression. It implements both encoding.TextMarhaler,
encoding.TextUnmarshaler, and fmt.Stringer, so it can be used in JSON
objects and stored in various ways.
There is also a func Parse(raw string) (exp Expression, err error) method to
parse a textual representation to an expression.
Documentation
¶
Index ¶
- Variables
- type Expression
- func (e Expression) MarshalText() (text []byte, err error)
- func (e Expression) Next(d time.Time) (n time.Time, ok bool)
- func (e *Expression) Scan(src interface{}) (err error)
- func (e Expression) String() string
- func (e *Expression) UnmarshalText(raw []byte) (err error)
- func (e Expression) Value() (val driver.Value, err error)
- type Schedule
Constants ¶
This section is empty.
Variables ¶
var ( MaxYears = 2199 MinYears = 1970 )
Non unit-related boundaries.
Functions ¶
This section is empty.
Types ¶
type Expression ¶
type Expression struct {
// contains filtered or unexported fields
}
An Expression is the Go representation of a Calendar Event as per Systemd's specification (with some exceptions, see the Parse method).
func MustParse ¶
func MustParse(raw string) (e Expression)
MustParse is like Parse but will panic in case of error.
func Parse ¶
func Parse(raw string) (exp Expression, err error)
Parse a raw string into an expression. Follows Systemd's Calendar Events specification with some exceptions: - Any timezone can be specified, not only UTC and local - Sub-second aren't handled - The end-of-month token isn't handled
Original implementation can be found here: https://github.com/systemd/systemd/blob/master/src/basic/calendarspec.c#L879
func (Expression) MarshalText ¶
func (e Expression) MarshalText() (text []byte, err error)
MarshalText implement the encoding.TextMarshaler interface.
func (Expression) Next ¶
Next returns the next point in time that will satisfy the schedule that is strictly after d.
Original implementation can be found here: https://github.com/systemd/systemd/blob/master/src/basic/calendarspec.c#L1199
func (*Expression) Scan ¶
func (e *Expression) Scan(src interface{}) (err error)
Scan implements the sql.Scanner interface, which allow to use an Expression as a database field and scan it.
func (Expression) String ¶
func (e Expression) String() string
String implement the fmt.Stringer interface.
func (*Expression) UnmarshalText ¶
func (e *Expression) UnmarshalText(raw []byte) (err error)
UnmarshalText implements the encoding.TextUnmarshaler interface so an expression can unmarshalled from a JSON object.
type Schedule ¶
type Schedule []Expression
A Schedule represent a list of calendar expressions.
func MustParseSchedule ¶
MustParseSchedule is like ParseSchedule but will panic in case of error.
func ParseSchedule ¶
ParseSchedule parse a list of Expression separated by newlines.
func (Schedule) MarshalText ¶
MarshalText implements the encoding.MarshalText interface.
func (Schedule) Next ¶
Next return the first valid date represented by any expression that is after d.
func (*Schedule) Scan ¶
Scan implements the sql.Scanner interface, which allow to use a Schedule as a database field and scan it.
func (*Schedule) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaller interface, which is used by json.Unmarshal as a fallback when json.Unmarshaler isn't implemented. This is preferred becase the field is a string with a custom parser, which is more semantic to unmarshal with Text rather than JSON.
Source Files