date-parser · parser technology comparison
Twelve parsers, one date language
The same small language for dates, periods and ranges, implemented with twelve parser generators and parser libraries, from LL(1) to LALR(1), Earley, GLL and PEG. Every implementation passes the same 564 test cases.
- 12implementations, 6 languages
- 564shared test cases
- 0grammar conflicts
- 1specification file
The language
Small enough for every tool, rich enough to show their differences: three date notations, periods, business days, IMM and FX spot dates, lists and ranges. A schedule is a rule: a function of the base date T and the market.
| 2015-06-09 | one date (ISO) |
| 09.06.2015 + 3M | 2015-09-09 (German notation) |
| 06/09/2015 + 1W - 2D | 2015-06-14 (US notation, left to right) |
| 2015-06-09, 1.1.2000 + 1Y | 2015-06-09, 2001-01-01 |
| [2015-01-15 : 1Q : 2015-12-31] | 2015-01-15, -04-15, -07-15, -10-15 |
| [2026-01-01 : 3M : 2026-12-31] > EOQ > 3RD WED IN MONTH | the IMM dates of 2026: shifts apply to each element |
| 2015-06-12 + 1B | 2015-06-15 (business days) |
| 2015-06-09 + 3M > IMM | 2015-09-16 (next IMM date) |
| 2015-06-12 > SPOT USDCAD | 2015-06-15 (FX spot, T+1) |
| T + 2B | two business days after the base date, in the market of the evaluation |
| 24 DEC IF MON TUE WED THU | Christmas Eve from Monday to Thursday, otherwise no date |
| 1 SHAWWAL, 1 ZHENGYUE | Eid al-Fitr and Chinese New Year in the year of T |
| @FOMC + 1B | the business day after each FOMC decision of that year (a named event) |
| [T : T + 7D] \ {1 JAN, 6 JAN} & 25 DEC | exclude and include: sorted, without duplicates |
| [T : 1Y : T + 2Y] > {1 FEB, 1 MAY} | dates in year: 1 February and 1 May of three years |
| 5TH [SPOT : 1Q : ] > EOQ > 3RD WED IN MONTH | pick: the 5th IMM date after T, from an open series |
| T > 2ND LAST BD IN MONTH | the second-to-last business day in the month of T |
schedule = item { "," item } .
item = expr { combine } [ condition ]
| pick ( series | EVENT ) { move } { combine } [ condition ] .
pick = ORDINAL [ "LAST" ] . (* the n-th date after T *)
condition = "IF" ( WEEKDAY { WEEKDAY }
| "{" WEEKDAY { "," WEEKDAY } "}" ) .
combine = ( "&" | "\\" ) operand { move } . (* include, exclude *)
operand = date | "{" expr { "," expr } "}" .
series = ( "[" | "]" ) endpoint ":" ( period ":" [ endpoint ] | endpoint )
( "]" | "[" ) . (* ]a, b[: endpoint left out; no end: open *)
endpoint = single_date { move } .
expr = date { move } .
move = ("+" | "-") period
| ">" ( "IMM" | "SPOT" [ PAIR ] | "FIX" [ PAIR ] | ROLL
| ("NEXT" | "PREV") [ ORDINAL ] anchor
| count select "IN" PERIOD
| "{" annual { "," annual } "}" ) (* dates in year *)
| "{" shift { "," shift } "}" .
shift = WEEKDAY ("+" | "-") period .
anchor = target (* NEXT 3RD FRI *)
| "{" target { "," target } "}" . (* NEXT {MON, FRI} *)
target = chosen | "LAST" WEEKDAY MONTH .
count = ORDINAL [ "LAST" ] | "LAST" . (* 2ND LAST *)
select = chosen (* 3RD WED IN MONTH *)
| "{" target { "," target } "}" .
chosen = WEEKDAY | "BD" | "FD" | "IMM" | fixed | EVENT .
date = single_date | series .
single_date = "T" | "TOM" | "SPOT" [ PAIR ]
| NUM ( "-" NUM "-" NUM (* ISO *)
| "." NUM "." NUM (* German *)
| "/" NUM "/" NUM ) (* US *)
| annual | EVENT .
annual = fixed | "LAST" WEEKDAY MONTH .
fixed = NUM MONTH (* 4 JUL *)
| NUM WEEKDAY MONTH (* 3 MON JAN *)
| "EASTER"
| ("EQUINOX" | "SOLSTICE") MONTH [ ZONE ]
| "SOLARTERM" NUM [ ZONE ] . (* SOLARTERM 5 UTC+8 *)
period = NUM ( "D" | "W" | "M"
| "Q" | "H" | "Y" | "B" | "F" ) . (* F: fixing days *)
ROLL = "FOLLOWING" | "PRECEDING" | "MODFOLLOWING"
| "BOW" | "EOW" | "BOM" | "EOM" | "BOQ" | "EOQ"
| "BOH" | "EOH" | "BOY" | "EOY" .
PERIOD = "WEEK" | "MONTH" | "QUARTER" | "HALFYEAR" | "YEAR" .
MONTH = "JAN" | … | "DEC" (* Gregorian *)
| "MUHARRAM" | … | "DHULHIJJAH" (* Hijri *)
| "NISAN" | … | "ADARII" (* Hebrew *)
| "ZHENGYUE" | … | "LAYUE" . (* Chinese *)
EVENT = "@" UPPER { UPPER | DIGIT | "_" } . (* @FOMC *)
ZONE = "UTC" ("+" | "-") NUM . (* UTC+9, one token *)
ORDINAL = NUM ("ST" | "ND" | "RD" | "TH") . (* 3RD, one token *)
In grammatical terms (after grammatical category):
the upper-case symbols are lexical categories, word classes that the lexer recognises; the lower-case rules are
phrasal categories that the parser builds from words. The numbers carry the content, and the grammar adds a few things
with a small, closed set of forms: number (one date, or several from a list or range), tense
(T is the base date, the anchor date that tense relates to; TOM and SPOT are relative to it, > NEXT and
> PREV look forward and back) and definiteness (4 JUL is the one in the year of T,
> NEXT 4 JUL the next one).
Every decision is LL(1): after the first number, the separator selects the notation; after a complete date,
+ or - starts a period. Periods follow java.time: months first, with the day clamped
to the end of the month (2016-01-31 + 1M is 2016-02-29), then days.
B counts business days, Monday to Friday.
> IMM moves to the next IMM date strictly after the date: the third Wednesday of March, June, September or December.
> SPOT moves to the FX spot date: + 1B for USD against CAD, TRY, PHP or RUB, + 2B for every other pair
(PAIR is six capital letters such as EURUSD).
Parsing a schedule yields a rule, not dates: a function that gets the base date T and a market only when it is evaluated.
The grammar never names a market. A market only answers questions about days (which days are business days, and so which day is spot);
the meaning of a rule doesn't depend on it, so IMM is the third Wednesday everywhere. Without a market, only Saturdays and Sundays are skipped.
Holiday rules: 4 JUL, 3 MON JAN, LAST MON MAY and EASTER are dates in the year of T.
An observance {SAT - 1D, SUN + 1D} shifts a date by the first item for its weekday, so 4 JUL {SAT - 1D, SUN + 1D}
is Independence Day as the NYSE observes it. A market can be declared from such rules; the test markets in the case list below are.
Rolling, seen from T: TOM and SPOT are dates; > NEXT FRI, > PREV IMM or
> NEXT 4 JUL look strictly after or before the date, an ordinal counts (> NEXT 3RD FRI, > NEXT 2ND IMM)
and a set is the nearest of its anchors (> NEXT {MON, FRI}, > NEXT {1 FEB, 1 MAY}); > EOM, > EOQ and friends move to the edge of
month, quarter, half year or year,
and > FOLLOWING, > PRECEDING and > MODFOLLOWING to a business day of the market.
Hijri (Umm al-Qura), Hebrew and Chinese months are month names too: 1 SHAWWAL is the day in the year of T,
an error if it falls there twice or not at all. 24 DEC IF MON TUE WED THU keeps a date only on these weekdays.
EQUINOX MAR, SOLSTICE JUN, EQUINOX SEP and SOLSTICE DEC are the days on which the sun
reaches 0, 90, 180 and 270 degrees, SOLARTERM 5 is Qingming (the Chinese solar terms, counted from Lichun at 315 degrees),
in UTC or in the offset after it: EQUINOX MAR UTC+9 is Japan's Vernal Equinox Day. Every tool computes them after Meeus.
Try it
The Peggy parser of this project, running in your browser: type a schedule, pick the base date T and a market,
and the dates appear as you type, with the syntax tree the parser built: the categories are the rules of the grammar, the words
the input. Its bracket notation below the tree can be pasted into a syntax tree generator. The markets and events are the ones of the
test cases; a click on a test case below loads it here.
Loading the parser …
The same rules in every tool
Rules expr and date, copied from the grammar files. Pick a tool:
// periods are applied from left to right
expr returns [Expr value]
: date { $value = $date.value; }
( move[$value] { $value = $move.value; }
)*
;
// one step, applied to everything on its left
move[Expr before] returns [Expr value]
locals [List<Annual> annuals = new ArrayList<>()]
: '+' period { $value = ScheduleSemantics.plus($before, $period.value); }
| '-' period { $value = ScheduleSemantics.minus($before, $period.value); }
| '>' 'IMM' { $value = ScheduleSemantics.nextImm($before); }
| '>' spot { $value = ScheduleSemantics.spot($before, $spot.pair); }
| '>' 'FIX' (p=PAIR)? { $value = ScheduleSemantics.fix($before, $p == null ? null : $p.text); }
| '>' ROLL { $value = ScheduleSemantics.roll($before, $ROLL.text); }
| '>' 'NEXT' ordinal anchor { $value = ScheduleSemantics.next($before, $ordinal.n, $anchor.value); }
| '>' 'PREV' ordinal anchor { $value = ScheduleSemantics.previous($before, $ordinal.n, $anchor.value); }
| '>' count select 'IN' PERIOD
{ $value = ScheduleSemantics.select($before, $count.n, $count.fromEnd, $select.value, $PERIOD.text); }
// > {1 FEB, 1 MAY}: the dates of the set in the year of the date
| '>' '{' a=annual { $annuals.add($a.value); }
(',' a=annual { $annuals.add($a.value); }
)* '}' { $value = ScheduleSemantics.datesInYear($before, $annuals); }
| observance { $value = ScheduleSemantics.observe($before, $observance.shifts); }
;
Pitfall. $start is reserved (the rule's first token), so the range labels are first/last.
# shifts are applied from left to right
def visitExpr(self, ctx):
start, shifts = self.visit(ctx.date()), [self.visit(shift) for shift in ctx.shift()]
def at(context):
d = start(context)
for shift in shifts:
d = shift(d, context)
return d
return at
def visitPlus(self, ctx):
period = self.visit(ctx.period())
return lambda d, context: semantics.plus(d, period, 1, context.market, context.fixing)
def visitMinus(self, ctx):
period = self.visit(ctx.period())
return lambda d, context: semantics.plus(d, period, -1, context.market, context.fixing)
def visitImm(self, ctx):
return lambda d, context: semantics.next_imm(d)
def visitSpot(self, ctx):
pair = ctx.PAIR() and ctx.PAIR().getText()
return lambda d, context: context.market.spot(d, pair)
def visitRoll(self, ctx):
convention = ctx.ROLL().getText()
return lambda d, context: semantics.roll(d, convention, context.market)
Pitfall. Java actions can't be generated into Python, so the grammar is copied without them. An alternative label may not repeat a rule's name, so > 3RD WED IN MONTH is # selectIn, not # select.
def date: Parser[Context => LocalDate] = series | singleDate
/** a date that is not a series */
def singleDate: Parser[Context => LocalDate] = eventName ^^ event | "TOM" ^^^ ((c: Context) => plusBusinessDays(base(c), 1, c.market)) |
"T" ^^^ base |
"SPOT" ~> opt(pair) ^^ (p => (c: Context) => c.market.spot(base(c), p)) |
annual ^^ {
case l: LunarAnnual => (c: Context) => take(c, c => l.all(base(c).getYear)) // a lunar date can fall twice
case a => (c: Context) => a(base(c).getYear)
} | number ~ (
("-" ~> number) ~ ("-" ~> number) ^^ { case m ~ d => (y: Int) => LocalDate.of(y, m, d) } // ISO
| ("." ~> number) ~ ("." ~> number) ^^ { case m ~ y => (d: Int) => LocalDate.of(y, m, d) } // German
| ("/" ~> number) ~ ("/" ~> number) ^^ { case d ~ y => (m: Int) => LocalDate.of(y, m, d) } // US
) ^^ { case first ~ toDate => val date = toDate(first); (_: Context) => date }
def expr: Parser[Context => LocalDate] = date ~ rep(shift) ^^ {
case start ~ shifts => (c: Context) => shifts.foldLeft(start(c))((d, f) => f(d, c))
}
Pitfall. None: the grammar is ordinary Scala code, there is no generator step.
Expr<out ScheduleSemantics.Expr d>
= Date<out d>
{ Move<out d, d> }.
/* one step, applied to everything on its left */
Move<out ScheduleSemantics.Expr d, ScheduleSemantics.Expr before>
(. TemporalAmount p; String code; ScheduleSemantics.Anchor a; int n;
ScheduleSemantics.Annual an = ScheduleSemantics.EASTER; d = before;
List<ScheduleSemantics.Annual> annuals = new ArrayList<>();
List<ScheduleSemantics.Shift> shifts = new ArrayList<>(); .)
= "+" Period<out p> (. d = ScheduleSemantics.plus(before, p); .)
| "-" Period<out p> (. d = ScheduleSemantics.minus(before, p); .)
| ">"
( "IMM" (. d = ScheduleSemantics.nextImm(before); .)
| Spot<out code> (. d = ScheduleSemantics.spot(before, code); .)
| "FIX" (. code = null; .) /* the fixing date of a value date */
[ pair (. code = t.val; .)
] (. d = ScheduleSemantics.fix(before, code); .)
| Roll<out code> (. d = ScheduleSemantics.roll(before, code); .)
| "NEXT" Counted<out a> (. d = ScheduleSemantics.next(before, a); .)
| "PREV" Counted<out a> (. d = ScheduleSemantics.previous(before, a); .)
| Count<out n> Select<out a>
"IN" PeriodWord<out code> (. d = ScheduleSemantics.select(before, Math.abs(n), n < 0, a, code); .)
| "{" /* > {1 FEB, 1 MAY}: the dates of the set in the year of the date */
( Number<out n> AnnualTail<out an, n> | AnnualWord<out an> ) (. annuals.add(an); .)
{ "," ( Number<out n> AnnualTail<out an, n> | AnnualWord<out an> ) (. annuals.add(an); .)
} "}" (. d = ScheduleSemantics.datesInYear(before, annuals); .)
)
| "{" Shift<shifts> /* {SAT - 1D, SUN + 1D} */
{ "," Shift<shifts> }
"}" (. d = ScheduleSemantics.observe(before, shifts); .)
.
/* a date, a series or a set of dates */
Operand<out List<ScheduleSemantics.Expr> exprs> (. ScheduleSemantics.Expr d; exprs = new ArrayList<>(); .)
= Date<out d> (. exprs.add(d); .)
| "{" Expr<out d> (. exprs.add(d); .)
{ "," Expr<out d> (. exprs.add(d); .)
} "}"
.
Pitfall. Error recovery keeps running semantic actions on incomplete input, so they must not throw.
ScheduleSemantics.Expr Expr() :
{ ScheduleSemantics.Expr d; }
{
d = Date() ( d = Move(d) )*
{ return d; }
}
/** one step, applied to everything on its left */
ScheduleSemantics.Expr Move(ScheduleSemantics.Expr before) :
{ TemporalAmount p; String pair; Token roll, o = null, period, p2 = null; ScheduleSemantics.Anchor a; int n;
ScheduleSemantics.Annual an; List<ScheduleSemantics.Annual> annuals = new ArrayList<ScheduleSemantics.Annual>();
List<ScheduleSemantics.Shift> shifts = new ArrayList<ScheduleSemantics.Shift>(); boolean fromEnd = false; }
{
"+" p = Period() { return ScheduleSemantics.plus(before, p); }
| "-" p = Period() { return ScheduleSemantics.minus(before, p); }
| ">"
( "IMM" { return ScheduleSemantics.nextImm(before); }
| pair = Spot() { return ScheduleSemantics.spot(before, pair); }
| "FIX" ( p2 = <PAIR> )? { return ScheduleSemantics.fix(before, p2 == null ? null : p2.image); } // the fixing date
| roll = <ROLL> { return ScheduleSemantics.roll(before, roll.image); }
| "NEXT" a = Counted() { return ScheduleSemantics.next(before, a); }
| "PREV" a = Counted() { return ScheduleSemantics.previous(before, a); }
// > 3RD WED IN MONTH, > 2ND LAST BD IN MONTH: the n-th match in the period of the date, from its start or its end
| ( o = <ORDINAL> ( "LAST" { fromEnd = true; } )? | "LAST" { fromEnd = true; } )
a = Select() "IN" period = <PERIOD>
{ return ScheduleSemantics.select(before, o == null ? 1 : ScheduleSemantics.ordinal(o.image), fromEnd, a, period.image); }
// > {1 FEB, 1 MAY}: the dates of the set in the year of the date
| "{" ( n = Number() an = AnnualTail(n) | an = AnnualWord() ) { annuals.add(an); }
( "," ( n = Number() an = AnnualTail(n) | an = AnnualWord() ) { annuals.add(an); } )* "}"
{ return ScheduleSemantics.datesInYear(before, annuals); }
)
| "{" Shift(shifts) ( "," Shift(shifts) )* "}" { return ScheduleSemantics.observe(before, shifts); } // {SAT - 1D, SUN + 1D}
}
/** a date, a series or a set of dates */
List<ScheduleSemantics.Expr> Operand() :
{ ScheduleSemantics.Expr d; List<ScheduleSemantics.Expr> exprs = new ArrayList<ScheduleSemantics.Expr>(); }
{
( d = Date() { exprs.add(d); }
| "{" d = Expr() { exprs.add(d); } ( "," d = Expr() { exprs.add(d); } )* "}"
)
{ return exprs; }
}
Pitfall. ParserGeneratorCC (used by the Maven plugin) rejects the classic STATIC option.
expr = date shift*;
shift
= {plus} plus period
| {minus} minus period
| {imm} gt imm
| {spot} gt spot pair?
| {fix} gt fix pair? /* the fixing date of a value date */
| {roll} gt roll
| {next} gt next ordinal? anchor /* NEXT 3RD FRI: the third Friday */
| {prev} gt prev ordinal? anchor
| {select} gt count select in period_word /* > 3RD WED IN MONTH, > 2ND LAST BD IN MONTH */
| {dates_in_year} gt l_brace annual more_annual* r_brace /* > {1 FEB, 1 MAY} */
| {observance} l_brace observe more_observe* r_brace;
observe
= {plus} weekday plus period
| {minus} weekday minus period;
more_observe = comma observe;
/* the n-th match in the period of the date, from its start or its end */
count
= {from_start} ordinal
| {from_end} ordinal last
| {last} last;
/* the targets of NEXT; an annual date starting with LAST only in braces, as LAST also starts the count */
select
= {single} chosen
| {set} l_brace target more_target* r_brace;
/* NEXT {MON, FRI}: the nearest of a set */
anchor
= {single} target
| {set} l_brace target more_target* r_brace;
more_target = comma target;
more_annual = comma annual;
target
= {chosen} chosen
| {last} last weekday month;
chosen
= {weekday} weekday
| {bd} bd
| {fd} fd
| {imm} imm
| {annual} fixed_annual
| {event} event;
date
= {single} single_date
| {series} series;
/* a date that is not a series */
single_date
= {base} base
| {tom} tom
| {spot} spot pair?
| {annual} annual
| {event} event
| {iso} [year]:number [s1]:minus [month]:number [s2]:minus [day]:number
| {german} [day]:number [s1]:dot [month]:number [s2]:dot [year]:number
| {us} [month]:number [s1]:slash [day]:number [s2]:slash [year]:number;
annual
= {fixed} fixed_annual
| {last} last weekday month;
fixed_annual
= {month_day} number month
| {nth_weekday} number weekday month
| {easter} easter
| {season} season month zone?
| {solar_term} solarterm number zone?;
period = number unit;
Pitfall. Elements that occur twice in one alternative need names: [year]:number, [s1]:minus.
/* periods are applied from left to right */
expr ::= date:d {: RESULT = d; :}
| expr:e move:m {: RESULT = m.apply(e); :}
;
/* one step, applied to everything on its left: a function of the expression so far */
move ::= PLUS period:p {: RESULT = e -> ScheduleSemantics.plus(e, p); :}
| MINUS period:p {: RESULT = e -> ScheduleSemantics.minus(e, p); :}
| GT IMM {: RESULT = e -> ScheduleSemantics.nextImm(e); :}
| GT SPOT {: RESULT = e -> ScheduleSemantics.spot(e, null); :}
| GT SPOT PAIR:p {: RESULT = e -> ScheduleSemantics.spot(e, p); :}
| GT FIX {: RESULT = e -> ScheduleSemantics.fix(e, null); :} /* the fixing date */
| GT FIX PAIR:p {: RESULT = e -> ScheduleSemantics.fix(e, p); :}
| GT ROLL:r {: RESULT = e -> ScheduleSemantics.roll(e, r); :}
| GT NEXT counted:a {: RESULT = e -> ScheduleSemantics.next(e, a); :}
| GT PREV counted:a {: RESULT = e -> ScheduleSemantics.previous(e, a); :}
| GT count:n select:a IN PERIOD:p
{: RESULT = e -> ScheduleSemantics.select(e, Math.abs(n), n < 0, a, p); :}
| GT LBRACE annuals:list RBRACE /* > {1 FEB, 1 MAY}: the dates of the set in the year of the date */
{: RESULT = e -> ScheduleSemantics.datesInYear(e, list); :}
| LBRACE shifts:s RBRACE {: RESULT = e -> ScheduleSemantics.observe(e, s); :} /* {SAT - 1D, SUN + 1D} */
;
annuals ::= annual:a {: RESULT = new ArrayList<>(); RESULT.add(a); :}
| annuals:list COMMA annual:a {: list.add(a); RESULT = list; :}
;
/* A & B includes the dates of B, A \\ B excludes them; the moves after it apply to the result */
combined ::= expr:e combines:cs {: ScheduleSemantics.Expr d = e; for (UnaryOperator<ScheduleSemantics.Expr> c : cs) d = c.apply(d); RESULT = d; :}
;
combines ::= {: RESULT = new ArrayList<>(); :}
| combines:list combine:c {: list.add(c); RESULT = list; :}
;
combine ::= AMP operand:o moves:ms {: RESULT = e -> { ScheduleSemantics.Expr d = ScheduleSemantics.combined(e, true, o); for (UnaryOperator<ScheduleSemantics.Expr> m : ms) d = m.apply(d); return d; }; :}
| BACKSLASH operand:o moves:ms {: RESULT = e -> { ScheduleSemantics.Expr d = ScheduleSemantics.combined(e, false, o); for (UnaryOperator<ScheduleSemantics.Expr> m : ms) d = m.apply(d); return d; }; :}
;
moves ::= {: RESULT = new ArrayList<>(); :}
| moves:list move:m {: list.add(m); RESULT = list; :}
;
/* a date, a series or a set of dates */
operand ::= date:d {: RESULT = new ArrayList<>(); RESULT.add(d); :}
| LBRACE operand_exprs:list RBRACE {: RESULT = list; :}
;
operand_exprs ::= expr:e {: RESULT = new ArrayList<>(); RESULT.add(e); :}
| operand_exprs:list COMMA expr:e {: list.add(e); RESULT = list; :}
;
Pitfall. In the JFlex spec, %cupsym must come before %cup, or the EOF action refers to sym.
/* periods are applied from left to right */
expr:
date { $$ = $1; }
| expr move { $$ = $2.apply ($1); }
;
/* one step, applied to everything on its left: a function of the expression so far ($$ is an Object in the Java
skeleton, so each lambda is cast to its type) */
move:
'+' period { TemporalAmount p = $2; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.plus (e, p); }
| '-' period { TemporalAmount p = $2; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.minus (e, p); }
| '>' IMM { $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.nextImm (e); }
| '>' SPOT { $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.spot (e, null); }
| '>' SPOT PAIR { String pair = $3; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.spot (e, pair); }
| '>' FIX { $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.fix (e, null); } /* the fixing date */
| '>' FIX PAIR { String pair = $3; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.fix (e, pair); }
| '>' ROLL { String roll = $2; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.roll (e, roll); }
| '>' NEXT counted { Anchor a = $3; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.next (e, a); }
| '>' PREV counted { Anchor a = $3; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.previous (e, a); }
| '>' count select IN PERIOD { int n = $2; Anchor a = $3; String period = $5;
$$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.select (e, Math.abs (n), n < 0, a, period); }
| '>' '{' annuals '}' { ArrayList<Annual> list = $3; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.datesInYear (e, list); }
| '{' shifts '}' { ArrayList<Shift> s = $2; $$ = (UnaryOperator<Expr>) e -> ScheduleSemantics.observe (e, s); } /* {SAT - 1D, SUN + 1D} */
;
annuals:
annual { ArrayList<Annual> list = new ArrayList<> (); list.add ($1); $$ = list; }
| annuals ',' annual { $1.add ($3); $$ = $1; }
;
/* A & B includes the dates of B, A \\ B excludes them; the moves after it apply to the result */
combined:
expr combines { Expr d = $1; for (UnaryOperator<Expr> c : $2) d = c.apply (d); $$ = d; }
;
combines:
%empty { $$ = new ArrayList<> (); }
| combines combine { $1.add ($2); $$ = $1; }
;
combine:
'&' operand moves { ArrayList<Expr> o = $2; ArrayList<UnaryOperator<Expr>> ms = $3;
$$ = (UnaryOperator<Expr>) e -> { Expr d = ScheduleSemantics.combined (e, true, o); for (UnaryOperator<Expr> m : ms) d = m.apply (d); return d; }; }
| '\\' operand moves { ArrayList<Expr> o = $2; ArrayList<UnaryOperator<Expr>> ms = $3;
$$ = (UnaryOperator<Expr>) e -> { Expr d = ScheduleSemantics.combined (e, false, o); for (UnaryOperator<Expr> m : ms) d = m.apply (d); return d; }; }
;
moves:
%empty { $$ = new ArrayList<> (); }
| moves move { $1.add ($2); $$ = $1; }
;
/* a date, a series or a set of dates */
operand:
date { ArrayList<Expr> list = new ArrayList<> (); list.add ($1); $$ = list; }
| '{' operand_exprs '}' { $$ = $2; }
;
operand_exprs:
expr { ArrayList<Expr> list = new ArrayList<> (); list.add ($1); $$ = list; }
| operand_exprs ',' expr { $1.add ($3); $$ = $1; }
;
Pitfall. In Bison's Java skeleton $$ is a plain Object; only $1…$n are typed.
/* shifts are applied from left to right */
expr: date { $$ = NEW(Expr); $$->date = $1; }
| expr shift { $$ = $1; APPEND(Shift, $$->shifts, $2); }
;
shift: '+' period { $$ = shift(parse, S_PLUS); $$->period = $2; }
| '-' period { $$ = shift(parse, S_MINUS); $$->period = $2; }
| '>' IMM { $$ = shift(parse, S_IMM); }
| '>' SPOT pair { $$ = shift(parse, S_SPOT); $$->pair = $3; }
| '>' FIX pair { $$ = shift(parse, S_FIX); $$->pair = $3; } /* the fixing date of a value date */
| '>' ROLL { $$ = shift(parse, S_ROLL); $$->roll = $2; }
| '>' NEXT anchor { $$ = shift(parse, S_NEXT); $$->count = 1; $$->anchor = $3; }
| '>' NEXT ORDINAL anchor { $$ = shift(parse, S_NEXT); $$->count = $3; $$->anchor = $4; }
| '>' PREV anchor { $$ = shift(parse, S_PREV); $$->count = 1; $$->anchor = $3; }
| '>' PREV ORDINAL anchor { $$ = shift(parse, S_PREV); $$->count = $3; $$->anchor = $4; }
| '>' count select IN PERIOD
{
$$ = shift(parse, S_SELECT);
$$->count = $2 < 0 ? -$2 : $2;
$$->from_end = $2 < 0;
$$->anchor = $3;
$$->within = $5;
}
| '>' '{' annuals '}' { $$ = shift(parse, S_DATES_IN_YEAR); $$->anchor = $3; } /* > {1 FEB, 1 MAY} */
| '{' observes '}' { $$ = shift(parse, S_OBSERVANCE); $$->observes = $2; }
;
annuals: annual { $$ = anchor(parse, AT_ANNUAL); $$->annual = $1; }
| annuals ',' annual { Anchor *a = anchor(parse, AT_ANNUAL); a->annual = $3; $$ = $1; APPEND(Anchor, $$, a); }
;
pair: %empty { $$ = NULL; }
| PAIR
;
Pitfall. Token names become C enumerators in parser.h: a token SEASON and an enumerator SEASON of the tree can't both exist.
// periods are applied from left to right
Expr
= start:Date shifts:(_ @Shift)* { return (c) => shifts.reduce((d, shift) => shift(d, c), start(c)); }
Shift
= "+" _ p:Period { return (d, c) => plus(d, p, 1, c.market, c.fixing); }
/ "-" _ p:Period { return (d, c) => plus(d, p, -1, c.market, c.fixing); }
/ ">" _ "IMM" { return nextImm; }
/ ">" _ "SPOT" pair:(_ @Pair)? { return (d, c) => spot(d, pair, c.market); }
/ ">" _ "FIX" pair:(_ @Pair)? { return (d, c) => fix(d, pair, c.fixing); } // the fixing date of a value date
/ ">" _ convention:$("FOLLOWING" / "PRECEDING" / "MODFOLLOWING" / "BOW" / "EOW" / "BOM" / "EOM" / "BOQ" / "EOQ" / "BOH" / "EOH" / "BOY" / "EOY") {
return (d, c) => roll(d, convention, c.market);
}
/ ">" _ "NEXT" _ anchor:Counted { return (d, c) => anchor(d, 1, c); }
/ ">" _ "PREV" _ anchor:Counted { return (d, c) => anchor(d, -1, c); }
/ ">" _ "{" _ head:Annual tail:(_ "," _ @Annual)* _ "}" { return datesInYear([head, ...tail]); } // > {1 FEB, 1 MAY}
/ ">" _ count:Count _ anchor:Select _ "IN" _ period:$("WEEK" / "MONTH" / "QUARTER" / "HALFYEAR" / "YEAR") {
return (d, c) => select(d, count.n, count.fromEnd, anchor, period, c);
}
/ "{" _ head:Observe tail:(_ "," _ @Observe)* _ "}" {
return (d, c) => observe(d, [head, ...tail], c.market, c.fixing);
}
Pitfall. Peggy provides range() in actions, which silently shadows a helper of the same name.
// shifts are applied from left to right
expr: date shift*
shift: "+" period -> plus
| "-" period -> minus
| ">" "IMM" -> imm
| ">" "SPOT" [PAIR] -> spot
| ">" "FIX" [PAIR] -> fix
| ">" ROLL -> roll
| ">" "NEXT" [ORDINAL] anchor -> next
| ">" "PREV" [ORDINAL] anchor -> prev
| ">" count select "IN" PERIOD -> select
| ">" "{" annual ("," annual)* "}" -> dates_in_year
| "{" observe ("," observe)* "}" -> observance
observe: WEEKDAY "+" period -> observe_plus
| WEEKDAY "-" period -> observe_minus
// > 3RD WED IN MONTH, > 2ND LAST BD IN MONTH: the n-th match in the period of the date, from its start or its end
count: ORDINAL -> from_start
| "LAST" -> last
| ORDINAL "LAST" -> from_end
// the targets of NEXT; an annual date starting with LAST only in braces, as LAST also starts the count
?select: chosen
| "{" target ("," target)* "}" -> any_of
?chosen: WEEKDAY -> weekday
| "BD" -> business_day
| "FD" -> fixing_day
| "IMM" -> imm_anchor
| fixed_annual -> annual_anchor
| EVENT -> event_anchor
// NEXT 3RD FRI: the third Friday; NEXT {MON, FRI}: the first of a set
?anchor: target
| "{" target ("," target)* "}" -> any_of
?target: WEEKDAY -> weekday
| "BD" -> business_day
| "FD" -> fixing_day
| "IMM" -> imm_anchor
| annual -> annual_anchor
| EVENT -> event_anchor
?date: single_date
| series -> element
// a date that is not a series
?single_date: "T" -> base
| "TOM" -> tom
| "SPOT" [PAIR] -> spot_date
| NUM "-" NUM "-" NUM -> iso
| NUM "." NUM "." NUM -> german
| NUM "/" NUM "/" NUM -> us
| annual -> in_year
| EVENT -> event
// dates that recur every year, evaluated in the year of the base date
?annual: fixed_annual
| "LAST" WEEKDAY MONTH -> last_weekday
?fixed_annual: NUM MONTH -> month_day
| NUM WEEKDAY MONTH -> nth_weekday
| "EASTER" -> easter
| SEASON MONTH [ZONE] -> season
| "SOLARTERM" NUM [ZONE] -> solar_term
period: NUM UNIT
Pitfall. In LALR mode the contextual lexer only tries tokens the parser can accept next, so >SPOTUSDCAD parses; ANTLR's lexer reads SPOTUS as a pair and rejects it.
(* shifts are applied from left to right *)
expr = date shift*
<shift> = plus | minus | imm | spot | fix | roll | next | prev | select | dates-in-year | observance
plus = <'+'> period
minus = <'-'> period
imm = <'>'> <'IMM'>
spot = <'>'> <'SPOT'> PAIR?
(* the fixing date of a value date *)
fix = <'>'> <'FIX'> PAIR?
roll = <'>'> ROLL
(* NEXT 3RD FRI: the third Friday *)
next = <'>'> <'NEXT'> ORDINAL? anchor
prev = <'>'> <'PREV'> ORDINAL? anchor
(* > 3RD WED IN MONTH, > 2ND LAST BD IN MONTH: the n-th match in the period of the date, from its start or its end *)
select = <'>'> count (chosen | any-of) <'IN'> PERIOD
<count> = from-start | from-end | last
from-start = ORDINAL
from-end = ORDINAL <'LAST'>
last = <'LAST'>
(* > {1 FEB, 1 MAY}: the dates of the set in the year of the date *)
dates-in-year = <'>'> <'{'> annual (<','> annual)* <'}'>
observance = <'{'> observe (<','> observe)* <'}'>
observe = WEEKDAY SIGN period
(* NEXT {MON, FRI}: the nearest of a set *)
Pitfall. Scannerless with :auto-whitespace: whitespace may come between any two tokens, so a name like @FOMC must be a single regex to keep @ FOMC out.
Side by side
Size counts non-blank, non-comment lines of the grammar files. The JVM modules also share a 385-line helper (market, context, rule builders, periods, business days, IMM and spot dates, ranges, annual dates, lunar months, rolling, named events); the Python modules a 231-line one.
| Tool | Parsing | Lines | Values computed by | Errors surface as |
|---|---|---|---|---|
| ANTLR 4 · Java | ALL(*) · adaptive LL | 99 | Actions with returns […] attributes |
Throwing error listener plus BailErrorStrategy |
| ANTLR 4 · Python | ALL(*) · adaptive LL | 67 + 104grammar + visitor | Visitor over the parse tree; the grammar has no actions | Error listener on lexer and parser that raises |
| Scala combinators | Recursive descent with backtracking | 215 | ^^ functions, foldLeft over the shifts |
NoSuccess result, turned into an exception |
| Coco/R | LL(1) | 132 | (. … .) actions with out parameters |
errors.count, messages written to a stream |
| JavaCC | LL(k), here LL(1) | 143 | Java code inside the productions; each declares its locals | ParseException, TokenMgrException |
| SableCC | LALR(1) with typed AST | 88 + 131grammar + evaluator | Separate evaluator walking the generated typed tree | ParserException, LexerException |
| JFlex + CUP | LALR(1) | 75 + 59parser + lexer | {: … :} actions, left-recursive rules |
parse() throws on the first syntax error |
| GNU Bison | LALR(1) | 198incl. hand-written scanner | { … } actions, left-recursive rules |
parse() returns false |
| Flex + Bison · C | LALR(1) | 160 + 94parser + scanner | { … } actions build a syntax tree, which a C evaluator walks with the context |
yyparse() returns non-zero; the scanner returns YYerror with its own message |
| Peggy | PEG · ordered choice | 275incl. date arithmetic | Action blocks; date arithmetic written by hand | SyntaxError with expected tokens |
| Lark | Earley and LALR(1), one grammar | 47 + 89grammar + transformer | Transformer, one method per rule alias |
UnexpectedInput; VisitError wraps exceptions of the transformer |
| instaparse | GLL · any context-free grammar | 44 + 48grammar + transform | insta/transform, one function per tag, calling the shared Java helper |
insta/failure? on the result, turned into an exception |
What the comparison shows
- Top-down needs right recursion, bottom-up likes left recursion.
The LL tools and Peggy write
date { ("+" | "-") period }as a loop. CUP and both Bison modules writeexpr '+' period, which is natural for LALR(1). - Separating syntax from semantics is a choice.
SableCC's grammar contains no code at all; a separate tree walker computes the dates. Every other tool interleaves actions with the rules. In C, without closures, the Bison actions build a syntax tree as well, and an evaluator walks it like SableCC's.
- Compute while parsing, or build a rule first.
Because the market only arrives at evaluation, no tool can compute the dates while parsing. The action-based tools (ANTLR, Coco/R, JavaCC, CUP, Bison, Peggy) now build functions in their actions; in SableCC the syntax tree already is the rule, and the visitor, transformer and combinator versions only gained a parameter. A side effect: Coco/R's actions no longer compute anything during error recovery.
- Error recovery has consequences.
Coco/R recovers and keeps executing actions on incomplete input, so the actions must tolerate it. ANTLR needs a bail strategy to stop at the first error.
- Ordered choice is not alternation.
PEG tries the alternatives in order and commits to the first match. Here this is harmless because the separators differ, but it's the main semantic difference to the generated LL and LR parsers.
- The library matters as much as the parser.
In JavaScript, about 35 lines (plus 25 for markets, business days, IMM and spot dates) reproduce
java.time's month arithmetic. On the JVM,Periodcan't express business days, soBneeds aTemporalAmountof its own. The end-of-month cases in the test file exist to catch differences. - One grammar, two algorithms.
Lark builds an Earley parser or an LALR(1) parser from the same grammar file; every shared case runs with both. Earley accepts any context-free grammar, including ambiguous ones, but this language doesn't need that. instaparse (GLL) can return every parse of an input: each of the shared cases has exactly one, so the grammar is unambiguous on all of them, which no other tool here could show by running it.
- Actions tie a grammar to one language.
ANTLR's Java grammar computes the dates in Java actions, so it can't be generated into Python. The Python module uses the same rules without actions and a visitor, which would work for every ANTLR target.
- A lexer may or may not know the parser's state.
>SPOTUSDCADwithout a space: ANTLR, Coco/R, JavaCC, JFlex and SableCC readSPOTUSas a currency pair and fail. Peggy, instaparse and the Scala combinators have no lexer, and Lark's contextual lexer only tries the tokens the parser expects; all four accept it. - Six capitals: keyword or currency pair?
EASTERhas six capital letters, likeEURUSD. The tools with a lexer decide by order: ANTLR's implicit keywords come first, JFlex, JavaCC and SableCC take the rule declared first, Coco/R checks its keyword table, and both Bison scanners (hand-written in Java, Flex in C) test the keywords before the length. Without a lexer, or with a contextual one, the pattern itself must exclude the keyword (!"EASTER"in Peggy,!('EASTER' | …)in instaparse,(?!EASTER)in Scala and Lark), otherwiseT > SPOT EASTERwould read a pair. Lunar month names such asTISHRIjoined the list. Event names avoid the race altogether: the sigil in@EASTERmakes it a name in every tool. - Several dates from one expression, without touching the expression rules.
@FOMC + 1Bhas a date per FOMC decision, while every grammar builds an expression as a function returning one date. Instead of changing that in every implementation, the event's date throws until it is bound: the list catches it, looks up the event's dates in the year ofTand evaluates the item once per date. The grammars only gained the token and two alternatives. - A shared test file keeps everyone honest.
Every module reads
examples/schedule.txt. Several tool-specific pitfalls, listed in the tabs above, surfaced only because the same cases had to pass everywhere. - Generated cases test the libraries too.
2186 more cases come from a holiday rule catalog and from finance-date research, with the dates of that project's own engine. They showed that ICU's astronomical Chinese calendar, in ICU4J and in Node's
Intl, puts Chinese New Year 2027 and 2030 a day off: the new moon falls within minutes of midnight in Beijing. The JVM modules and Peggy now take Chinese dates from 6tail's lunar library. In the same way, the Umm al-Qura tables of the JDK and of ICU give Shawwal 1451 (2030) 30 days, the official table 29; all implementations now take Hijri dates from the official table. 3347 further cases translate the rules of date-holidays (data CC BY 3.0) for 207 countries and their regions, with that library's own dates; where its Hijri or Hebrew calendar disagrees with Umm al-Qura or the Hebrew calendar, the year is left out and counted.
The shared test cases
From examples/schedule.txt. Each module has a test that reads this file, so adding a line here tests all twelve implementations. They also read 2186 cases in examples/catalog.txt, generated from a holiday rule catalog, and 3347 in examples/date-holidays.txt, generated from date-holidays (neither listed here).
date notations
2015-06-09 | 2015-06-09 |
09.06.2015 | 2015-06-09 |
06/09/2015 | 2015-06-09 |
1.1.2000 | 2000-01-01 |
date plus / minus periods
09.06.2015 + 3M | 2015-09-09 |
06/09/2015 + 1W - 2D | 2015-06-14 |
2015-06-09 - 3M | 2015-03-09 |
2015-06-09 + 2Q | 2015-12-09 |
2015-06-09+10D | 2015-06-19 |
2015-06-09 - 1Y + 1D | 2014-06-10 |
2015-06-09 + 0D | 2015-06-09 |
end of month
2016-02-29 + 1Y | 2017-02-28 |
2016-01-31 + 1M | 2016-02-29 |
2016-01-31 + 1M - 1M | 2016-01-29 |
lists
2015-06-09, 01.01.2000 + 1Y | 2015-06-09, 2001-01-01 |
2015-06-09,2015-06-09 | 2015-06-09, 2015-06-09 |
ranges
[2015-01-15 : 1Q : 2015-12-31] | 2015-01-15, 2015-04-15, 2015-07-15, 2015-10-15 |
[2016-01-31 : 1M : 2016-04-30] | 2016-01-31, 2016-02-29, 2016-03-31, 2016-04-30 |
[2015-06-09 : 1W : 2015-06-09 + 2W] | 2015-06-09, 2015-06-16, 2015-06-23 |
[2015-06-09 : 1D : 2015-06-09] | 2015-06-09 |
[2015-06-09 : 1D : 2015-06-08] | empty list |
(2015-01-15 : 1Q : 2015-12-31) | error |
business days
2015-06-09 + 2B | 2015-06-11 |
2015-06-12 + 1B | 2015-06-15 |
2015-06-12 + 2B | 2015-06-16 |
2015-06-13 + 1B | 2015-06-15 |
2015-06-09 + 10B | 2015-06-23 |
2015-06-15 - 1B | 2015-06-12 |
2015-06-14 - 1B | 2015-06-12 |
2015-06-13 + 0B | 2015-06-13 |
2015-06-11 + 1M + 1B | 2015-07-13 |
2015-06-09 > SPOT + 3B | 2015-06-16 |
[2015-06-11 : 1B : 2015-06-16] | 2015-06-11, 2015-06-12, 2015-06-15, 2015-06-16 |
[2015-06-13 : 2B : 2015-06-19] | 2015-06-13, 2015-06-16, 2015-06-18 |
IMM dates
2015-06-09 > IMM | 2015-06-17 |
2015-06-17 > IMM | 2015-09-16 |
2015-12-20 > IMM | 2016-03-16 |
2016-12-20 > IMM | 2016-12-21 |
01.01.2015 > IMM | 2015-03-18 |
2015-06-09>IMM | 2015-06-17 |
2015-06-09 > IMM > IMM | 2015-09-16 |
2015-06-09 + 3M > IMM | 2015-09-16 |
2015-06-09 > IMM + 1D | 2015-06-18 |
[2015-01-01 > IMM : 1W : 2015-04-01] | 2015-03-18, 2015-03-25, 2015-04-01 |
FX spot dates
2015-06-09 > SPOT | 2015-06-11 |
2015-06-11 > SPOT | 2015-06-15 |
2015-06-12 > SPOT | 2015-06-16 |
2015-06-13 > SPOT | 2015-06-16 |
2015-12-31 > SPOT | 2016-01-04 |
2015-06-09 > SPOT EURUSD | 2015-06-11 |
2015-06-09 > SPOT EURCAD | 2015-06-11 |
2015-06-09 > SPOT USDCAD | 2015-06-10 |
2015-06-09 > SPOT CADUSD | 2015-06-10 |
2015-06-12 > SPOT USDCAD | 2015-06-15 |
2015-06-09>SPOT USDTRY | 2015-06-10 |
2015-06-12 > SPOT USDCAD > SPOT | 2015-06-17 |
2015-06-09 > SPOT + 1W | 2015-06-18 |
2015-06-09 > SPOT > IMM | 2015-06-17 |
[2015-06-09 > SPOT : 1W : 2015-06-30] | 2015-06-11, 2015-06-18, 2015-06-25 |
base date and market
market XTEST = 2015-06-10, 2015-07-03, 2015-12-25
[2015-06-09] T | 2015-06-09 |
[2015-06-09] T + 1M | 2015-07-09 |
[2015-06-09] T > IMM | 2015-06-17 |
[2015-06-09] T, 2015-01-01 | 2015-06-09, 2015-01-01 |
[2015-06-09] [T : 1W : T + 2W] | 2015-06-09, 2015-06-16, 2015-06-23 |
[2015-06-09] T + 2B | 2015-06-11 |
[2015-06-09 XTEST] T + 2B | 2015-06-12 |
[2015-06-09 XTEST] T + 1B | 2015-06-11 |
[2015-06-11 XTEST] T - 1B | 2015-06-09 |
[2015-07-02 XTEST] T + 1B | 2015-07-06 |
[2015-06-09 XTEST] 2015-06-09 + 2B | 2015-06-12 |
[2015-06-09 XTEST] T > SPOT | 2015-06-12 |
[2015-06-09 XTEST] T > SPOT USDCAD | 2015-06-11 |
[2015-12-24 XTEST] T > SPOT | 2015-12-29 |
[2015-06-09 XTEST] [T : 1B : T + 3B] | 2015-06-09, 2015-06-11, 2015-06-12, 2015-06-15 |
[2015-06-09 XTEST] T + 1M | 2015-07-09 |
T | error |
T + 1D | error |
holiday rules
[2025-06-09] 4 JUL | 2025-07-04 |
[2025-06-09] 3 MON JAN | 2025-01-20 |
[2025-06-09] 1 MON SEP | 2025-09-01 |
[2025-06-09] 4 THU NOV | 2025-11-27 |
[2025-06-09] 4 THU NOV + 1D | 2025-11-28 |
[2025-06-09] LAST MON MAY | 2025-05-26 |
[2025-06-09] 5 FRI JAN | 2025-01-31 |
[2025-06-09] EASTER | 2025-04-20 |
[2025-06-09] EASTER - 2D | 2025-04-18 |
[2024-06-09] EASTER + 1D | 2024-04-01 |
[2025-06-09] 4 JUL {SAT - 1D, SUN + 1D} | 2025-07-04 |
[2026-06-09] 4 JUL {SAT - 1D, SUN + 1D} | 2026-07-03 |
[2027-06-09] 4 JUL {SAT - 1D, SUN + 1D} | 2027-07-05 |
[2022-06-09] 1 JAN {SUN + 1D} | 2022-01-01 |
[2023-06-09] 1 JAN {SUN + 1D} | 2023-01-02 |
[2022-06-09] 25 DEC {SAT - 1D, SUN + 1D} | 2022-12-26 |
[2024-06-09] 1 JUN {SAT + 1D, SUN + 1D} | 2024-06-02 |
[2025-06-09] 4 JUL, 25 DEC | 2025-07-04, 2025-12-25 |
[2025-06-09] [15 JAN : 1Q : 31 DEC] | 2025-01-15, 2025-04-15, 2025-07-15, 2025-10-15 |
[2024-06-09] 29 FEB | 2024-02-29 |
[2025-06-09] 29 FEB | error |
[2025-06-09] 31 APR | error |
[2025-06-09] 5 MON FEB | error |
[2025-06-09] 0 MON JAN | error |
4 JUL | error |
EASTER | error |
[2025-06-09] 4 JUL 2025 | error |
[2025-06-09] LAST JAN | error |
[2025-06-09] 4 JUL {SAT} | error |
[2025-06-09] 4 JUL {} | error |
[2025-06-09] 4 JUL {SAT - 1D SUN + 1D} | error |
[2025-06-09] T > SPOT EASTER | error |
markets declared from holiday rules
market XNYS = 1 JAN {SUN + 1D}, 3 MON JAN, 3 MON FEB, EASTER - 2D, LAST MON MAY, 19 JUN {SAT - 1D, SUN + 1D}, 4 JUL {SAT - 1D, SUN + 1D}, 1 MON SEP, 4 THU NOV, 25 DEC {SAT - 1D, SUN + 1D}
market XEVE = 1 JAN {SAT - 1D, SUN + 1D}
market XTGT = 1 JAN, EASTER - 2D, EASTER + 1D, 1 MAY, 25 DEC, 26 DEC
[2025-07-03 XNYS] T + 1B | 2025-07-07 |
[2026-07-02 XNYS] T + 1B | 2026-07-06 |
[2025-04-17 XNYS] T + 1B | 2025-04-21 |
[2022-12-23 XNYS] T + 1B | 2022-12-27 |
[2021-12-30 XNYS] T + 1B | 2021-12-31 |
[2021-12-30 XEVE] T + 1B | 2022-01-03 |
[2025-11-26 XNYS] T > SPOT | 2025-12-01 |
[2025-01-01 XNYS] 3 FRI APR > PRECEDING | 2025-04-17 |
[2025-01-01 XNYS] 3 FRI MAR > PRECEDING | 2025-03-21 |
[2025-01-01 XNYS] 1 MAR - 1B | 2025-02-28 |
[2025-01-01 XNYS] 20 JAN > FOLLOWING | 2025-01-21 |
[2025-01-01] 20 JAN > FOLLOWING | 2025-01-20 |
rolling
[2025-06-09] TOM | 2025-06-10 |
[2025-06-13] TOM | 2025-06-16 |
[2025-11-26 XNYS] TOM | 2025-11-28 |
[2025-06-09] SPOT | 2025-06-11 |
[2025-06-09] SPOT USDCAD | 2025-06-10 |
[2025-06-09] SPOT + 1M | 2025-07-11 |
[2025-06-09] T > NEXT FRI | 2025-06-13 |
[2025-06-13] T > NEXT FRI | 2025-06-20 |
[2025-06-13] T > PREV FRI | 2025-06-06 |
[2025-06-13] T > NEXT BD | 2025-06-16 |
[2025-06-16] T > PREV BD | 2025-06-13 |
[2025-06-09] T > NEXT IMM | 2025-06-18 |
[2025-06-09] T > PREV IMM | 2025-03-19 |
[2025-06-09] T > NEXT 4 JUL | 2025-07-04 |
[2025-07-04] T > NEXT 4 JUL | 2026-07-04 |
[2025-12-01] T > NEXT 3 MON JAN | 2026-01-19 |
[2025-06-09] T > NEXT LAST MON MAY | 2026-05-25 |
[2025-06-09] T > PREV EASTER | 2025-04-20 |
[2025-04-20] T > PREV EASTER | 2024-03-31 |
[2026-06-09] T > NEXT 4 JUL {SAT - 1D, SUN + 1D} | 2026-07-03 |
[2025-06-09] T > BOM | 2025-06-01 |
[2025-06-09] T > EOM | 2025-06-30 |
[2024-02-10] T > EOM | 2024-02-29 |
[2025-06-09] T > BOY | 2025-01-01 |
[2025-06-09] T > EOY | 2025-12-31 |
2016-01-31 + 1M > EOM | 2016-02-29 |
[2025-05-09] T > EOM > PRECEDING | 2025-05-30 |
[2025-06-09] T > BOM > FOLLOWING | 2025-06-02 |
[2025-05-09] T > EOM > MODFOLLOWING | 2025-05-30 |
[2025-05-30 XNYS] T + 1M > MODFOLLOWING | 2025-06-30 |
[2025-05-30 XNYS] T > MODFOLLOWING | 2025-05-30 |
[2025-06-09] T > NEXT | error |
[2025-06-09] T > NEXT 3M | error |
[2025-06-09] T > NEXT T | error |
[2025-06-09] T > NEXT MONDAY | error |
[2025-06-09] TOM TOM | error |
[2025-06-09] T > EOM EOM | error |
TOM | error |
next IMM date from today, tomorrow or spot
[2025-06-16] T > IMM | 2025-06-18 |
[2025-06-16] TOM > IMM | 2025-06-18 |
[2025-06-16] SPOT > IMM | 2025-09-17 |
[2025-06-16] SPOT - 1D > IMM | 2025-06-18 |
[2025-06-16] SPOT + 1B > IMM | 2025-09-17 |
[2025-06-16] SPOT USDCAD > IMM | 2025-06-18 |
[2025-06-16] SPOT EURSEK > IMM | 2025-09-17 |
[2025-06-17] TOM > IMM | 2025-09-17 |
[2025-06-18] T > IMM | 2025-09-17 |
[2025-06-18] T - 1D > IMM | 2025-06-18 |
lunar months
[2025-01-01] 1 SHAWWAL | 2025-03-30 |
[2025-01-01] [29 RAMADAN : 1D : 3 SHAWWAL] | 2025-03-29, 2025-03-30, 2025-03-31, 2025-04-01 |
[2030-01-01] 1 RAMADAN | 2030-01-05, 2030-12-26 |
[2030-01-01] 1 RAMADAN + 29D | 2030-02-03, 2031-01-24 |
[2030-01-01] [1 RAMADAN + 29D : 1 RAMADAN + 31D] | 2030-02-03, 2030-02-04, 2030-02-05, 2031-01-24, 2031-01-25, 2031-01-26 |
[2030-01-01] [1 RAMADAN : 1D : 3 SHAWWAL] | error |
[2025-01-01] 10 TISHRI | 2025-10-02 |
[2025-01-01] 10 TISHRI - 1D | 2025-10-01 |
[2024-01-01] 14 ADAR | 2024-02-23 |
[2024-01-01] 14 ADARII | 2024-03-24 |
[2025-01-01] 14 ADAR | 2025-03-14 |
[2025-01-01] 14 ADARII | error |
[2025-01-01] 1 ZHENGYUE | 2025-01-29 |
[2025-01-01] 1 ZHENGYUE - 1D | 2025-01-28 |
[2025-06-01] T > NEXT 1 ZHENGYUE | 2026-02-17 |
[2025-01-01] 3 MON SHAWWAL | error |
[2025-01-01] T > SPOT TISHRI | error |
equinoxes, solstices and solar terms
[2025-01-01] EQUINOX MAR | 2025-03-20 |
[2025-01-01] SOLSTICE JUN | 2025-06-21 |
[2025-01-01] EQUINOX SEP | 2025-09-22 |
[2025-01-01] EQUINOX SEP UTC+9 | 2025-09-23 |
[2025-01-01] SOLSTICE DEC | 2025-12-21 |
[2026-01-01] EQUINOX SEP | 2026-09-23 |
[2026-01-01] EQUINOX SEP UTC-4 | 2026-09-22 |
[2027-01-01] SOLSTICE DEC | 2027-12-22 |
[2027-01-01] SOLSTICE DEC UTC-5 | 2027-12-21 |
[2024-01-01] SOLSTICE JUN UTC-4 | 2024-06-20 |
[2024-01-01] EQUINOX SEP UTC+9, EQUINOX SEP UTC+9 + 1D IF MON | 2024-09-22, 2024-09-23 |
[2025-01-01] EQUINOX SEP UTC+9, EQUINOX SEP UTC+9 + 1D IF MON | 2025-09-23 |
[2025-01-01] SOLARTERM 5 UTC+8 | 2025-04-04 |
[2026-01-01] SOLARTERM 5 UTC+8 | 2026-04-05 |
[2025-01-01] SOLARTERM 1 UTC+8 | 2025-02-03 |
[2025-01-01] SOLARTERM 23 UTC+8 | 2025-01-05 |
[2025-06-01] T > NEXT EQUINOX MAR | 2026-03-20 |
[2025-06-01] T > PREV SOLSTICE DEC | 2024-12-21 |
[2025-01-01] [EQUINOX MAR : 1M : SOLSTICE JUN] | 2025-03-20, 2025-04-20, 2025-05-20, 2025-06-20 |
[2025-01-01] EQUINOX JUN | error |
[2025-01-01] SOLSTICE SEP | error |
[2025-01-01] SOLARTERM 25 | error |
[2025-01-01] SOLARTERM 0 UTC+8 | error |
[2025-01-01] EQUINOX | error |
EQUINOX MAR | error |
1 SHAWWAL | error |
conditional dates
[2025-01-01] 24 DEC IF MON TUE WED THU | 2025-12-24 |
[2027-01-01] 24 DEC IF MON TUE WED THU | empty list |
[2025-01-01] 3 JUL IF MON TUE WED THU, 24 DEC IF FRI | 2025-07-03 |
[2025-01-01] 24 DEC IF WED, 25 DEC | 2025-12-24, 2025-12-25 |
[2025-01-01] 24 DEC IF | error |
[2025-01-01] [24 DEC : 1D : 26 DEC] IF WED | 2025-12-24 |
[2025-01-01] [1 JAN : 1M : 1 DEC] > NEXT FRI IF DAY 1..3 | 2025-01-03, 2025-05-02, 2025-10-03 |
[2025-01-01] [1 JAN : 1M : 1 DEC] > NEXT FRI IF DAY 1..3 OCT | 2025-10-03 |
[2019-01-01] 3 MON APR \ {EASTER - 6D, EASTER + 1D}, EASTER - 13D IF DAY 8..14 APR, EASTER + 8D IF DAY 22..28 APR | 2019-04-08 |
[2022-01-01] 3 MON APR \ {EASTER - 6D, EASTER + 1D}, EASTER - 13D IF DAY 8..14 APR, EASTER + 8D IF DAY 22..28 APR | 2022-04-25 |
[2026-01-01] 3 MON APR \ {EASTER - 6D, EASTER + 1D}, EASTER - 13D IF DAY 8..14 APR, EASTER + 8D IF DAY 22..28 APR | 2026-04-20 |
[2025-01-01] 3RD [1 JAN : 1D : ] IF DAY 10..12 | 2025-01-12 |
[2025-01-01] 24 DEC IF DAY 25..31 | empty list |
[2025-01-01] 24 DEC IF DAY 3..1 | error |
[2025-01-01] 24 DEC IF DAY 0..3 | error |
[2025-01-01] 24 DEC IF DAY 1..32 | error |
[2025-01-01] 24 DEC IF DAY 1..31 RAMADAN | error |
[2025-01-01] 24 DEC IF DAY 1 | error |
[2025-01-01] 24 DEC IF DAY | error |
named events
event FOMC = 2025-01-29, 2025-03-19, 2025-05-07, 2025-06-18, 2025-07-30, 2025-09-17, 2025-10-29, 2025-12-10
event THANKSGIVING = 4 THU NOV
event NEWYEAR = 1 JAN {SAT - 1D}
event fed.fomc_decision = 2025-01-29, 2025-03-19, 2025-05-07, 2025-06-18, 2025-07-30, 2025-09-17, 2025-10-29, 2025-12-10
[2025-01-01] @FOMC | 2025-01-29, 2025-03-19, 2025-05-07, 2025-06-18, 2025-07-30, 2025-09-17, 2025-10-29, 2025-12-10 |
[2025-06-30] @FOMC + 3W | 2025-02-19, 2025-04-09, 2025-05-28, 2025-07-09, 2025-08-20, 2025-10-08, 2025-11-19, 2025-12-31 |
[2025-01-01 XNYS] @FOMC + 1B | 2025-01-30, 2025-03-20, 2025-05-08, 2025-06-20, 2025-07-31, 2025-09-18, 2025-10-30, 2025-12-11 |
[2025-01-01] @THANKSGIVING + 1D, @FOMC IF FRI | 2025-11-28 |
[2025-01-01] [@THANKSGIVING : 1D : @THANKSGIVING + 3D] | 2025-11-27, 2025-11-28, 2025-11-29, 2025-11-30 |
[2025-02-01] T > NEXT @FOMC | 2025-03-19 |
[2025-03-19] T > NEXT @FOMC | 2025-05-07 |
[2025-03-19] T > PREV @FOMC | 2025-01-29 |
[2025-01-01] 1 DEC > NEXT @FOMC | 2025-12-10 |
[2024-01-01] @FOMC | empty list |
[2022-01-01] @NEWYEAR | empty list |
[2025-12-15] T > NEXT @FOMC | error |
[2025-01-01] [@FOMC : 1D : 31 DEC] | error |
[2025-01-01] [@FOMC - 1D : 1D : @FOMC] | 2025-01-28, 2025-01-29, 2025-03-18, 2025-03-19, 2025-05-06, 2025-05-07, 2025-06-17, 2025-06-18, 2025-07-29, 2025-07-30, 2025-09-16, 2025-09-17, 2025-10-28, 2025-10-29, 2025-12-09, 2025-12-10 |
[2025-01-01] [@FOMC > PREV 2ND SAT : @FOMC + 1D] IF WED | 2025-01-22, 2025-01-29, 2025-03-12, 2025-03-19, 2025-04-30, 2025-05-07, 2025-06-11, 2025-06-18, 2025-07-23, 2025-07-30, 2025-09-10, 2025-09-17, 2025-10-22, 2025-10-29, 2025-12-03, 2025-12-10 |
[2025-01-01] @NOPE | error |
@FOMC | error |
[2025-01-01] @EASTER | error |
[2025-01-01] FOMC | error |
[2025-01-01] @fomc | error |
[2025-01-01] @ FOMC | error |
[2025-01-01] @fed.fomc_decision | 2025-01-29, 2025-03-19, 2025-05-07, 2025-06-18, 2025-07-30, 2025-09-17, 2025-10-29, 2025-12-10 |
[2025-01-01 XNYS] @fed.fomc_decision + 1B IF THU | 2025-01-30, 2025-03-20, 2025-05-08, 2025-07-31, 2025-09-18, 2025-10-30, 2025-12-11 |
[2025-02-01] T > NEXT @fed.fomc_decision | 2025-03-19 |
[2025-01-01] @FED.FOMC_DECISION | error |
[2025-01-01] @fed. | error |
[2025-01-01] @fed..fomc_decision | error |
[2025-01-01] @fed .fomc_decision | error |
[2025-01-01] @_fed | error |
[2025-01-01] @1fed | error |
US employment report (non-farm payrolls)
market XFED = 1 JAN {SAT - 1D, SUN + 1D}, 3 MON JAN, 3 MON FEB, LAST MON MAY, 19 JUN {SAT - 1D, SUN + 1D}, 4 JUL {SAT - 1D, SUN + 1D}, 1 MON SEP, 2 MON OCT, 11 NOV {SAT - 1D, SUN + 1D}, 4 THU NOV, 25 DEC {SAT - 1D, SUN + 1D}
[2025-01-01 XFED] 3 JAN > NEXT FRI, 12 JAN - 1D > NEXT SAT + 20D > PRECEDING, 12 FEB - 1D > NEXT SAT + 20D > PRECEDING, 12 MAR - 1D > NEXT SAT + 20D > PRECEDING, 12 APR - 1D > NEXT SAT + 20D > PRECEDING, 12 MAY - 1D > NEXT SAT + 20D > PRECEDING, 12 JUN - 1D > NEXT SAT + 20D > PRECEDING, 12 JUL - 1D > NEXT SAT + 20D > PRECEDING, 12 AUG - 1D > NEXT SAT + 20D > PRECEDING, 12 SEP - 1D > NEXT SAT + 20D > PRECEDING, 12 OCT - 1D > NEXT SAT + 20D > PRECEDING, 12 NOV - 1D > NEXT SAT + 20D > PRECEDING | 2025-01-10, 2025-02-07, 2025-03-07, 2025-04-04, 2025-05-02, 2025-06-06, 2025-07-03, 2025-08-01, 2025-09-05, 2025-10-03, 2025-11-07, 2025-12-05 |
[2024-01-01 XFED] 3 JAN > NEXT FRI, 12 JAN - 1D > NEXT SAT + 20D > PRECEDING, 12 FEB - 1D > NEXT SAT + 20D > PRECEDING, 12 MAR - 1D > NEXT SAT + 20D > PRECEDING, 12 APR - 1D > NEXT SAT + 20D > PRECEDING, 12 MAY - 1D > NEXT SAT + 20D > PRECEDING, 12 JUN - 1D > NEXT SAT + 20D > PRECEDING, 12 JUL - 1D > NEXT SAT + 20D > PRECEDING, 12 AUG - 1D > NEXT SAT + 20D > PRECEDING, 12 SEP - 1D > NEXT SAT + 20D > PRECEDING, 12 OCT - 1D > NEXT SAT + 20D > PRECEDING, 12 NOV - 1D > NEXT SAT + 20D > PRECEDING | 2024-01-05, 2024-02-02, 2024-03-08, 2024-04-05, 2024-05-03, 2024-06-07, 2024-07-05, 2024-08-02, 2024-09-06, 2024-10-04, 2024-11-01, 2024-12-06 |
[2026-01-01 XFED] 12 APR - 1D > NEXT SAT + 20D > PRECEDING | 2026-05-08 |
[2026-01-01] 1 FRI MAY | 2026-05-01 |
[2020-01-01 XFED] 12 JUN - 1D > NEXT SAT + 20D > PRECEDING | 2020-07-02 |
[2026-01-01 XFED] 12 JUN - 1D > NEXT SAT + 20D > PRECEDING | 2026-07-02 |
[2026-01-01 XFED] 12 FEB - 1D > NEXT SAT + 20D > PRECEDING | 2026-03-06 |
[2025-01-01] 3 JAN > NEXT FRI | 2025-01-10 |
[2026-01-01] 3 JAN > NEXT FRI | 2026-01-09 |
[2019-01-01] 3 JAN > NEXT FRI | 2019-01-04 |
ordinals, sets, quarters and half years
[2026-11-02] T > NEXT 3RD FRI | 2026-11-20 |
[2026-11-06] T > NEXT 1ST FRI | 2026-11-13 |
[2026-11-02] T > PREV 2ND FRI | 2026-10-23 |
[2026-11-02] T > NEXT 11TH FRI | 2027-01-15 |
[2026-11-02] T > NEXT 2ND BD | 2026-11-04 |
[2026-11-02] SPOT > NEXT 2ND IMM | 2027-03-17 |
[2026-11-02] T > NEXT 2ND 4 JUL | 2028-07-04 |
[2026-11-02] T > PREV 2ND 4 JUL | 2025-07-04 |
[2026-11-02] T > NEXT 3 FRI JAN | 2027-01-15 |
[2026-11-02] T > NEXT 2ND 3 FRI JAN | 2028-01-21 |
[2026-11-02] T > NEXT {MON, FRI} | 2026-11-06 |
[2026-11-02] T > PREV {MON, FRI} | 2026-10-30 |
[2026-11-02] T > NEXT {SAT, SUN, MON} | 2026-11-07 |
[2026-11-02] T > NEXT {FRI} | 2026-11-06 |
[2026-11-02] T > NEXT 7TH {MON, FRI} | 2026-11-27 |
[2026-11-02] T > NEXT {MON, FRI} IF FRI | 2026-11-06 |
[2026-11-02] T > NEXT {1 FEB, 1 MAY} | 2027-02-01 |
[2027-02-10] T > NEXT {1 FEB, 1 MAY} | 2027-05-01 |
[2026-11-02] T > PREV {1 FEB, 1 MAY} | 2026-05-01 |
[2026-11-02] T > NEXT {IMM, 25 DEC} | 2026-12-16 |
[2026-12-17] T > NEXT {IMM, 25 DEC} | 2026-12-25 |
[2026-11-02] T > NEXT {25 DEC, EASTER} + 1D | 2026-12-26 |
[2026-11-02] T > NEXT 0TH FRI | error |
[2026-11-02] T > NEXT 2ST FRI | error |
[2026-11-02] T > NEXT 3 FRI | error |
[2026-11-02] T > NEXT 3RD | error |
[2026-11-02] T > NEXT FRI 3RD | error |
[2026-11-02] T > NEXT MON FRI | error |
[2026-11-02] T > NEXT {MON FRI} | error |
[2026-11-02] T > NEXT {} | error |
[2026-11-02] T > NEXT {3RD FRI} | error |
[2026-11-02] T > BOQ | 2026-10-01 |
[2026-11-02] T > EOQ | 2026-12-31 |
[2026-02-14] T > EOQ | 2026-03-31 |
[2026-05-15] T > BOH | 2026-01-01 |
[2026-05-15] T > EOH | 2026-06-30 |
[2026-08-15] T > BOH | 2026-07-01 |
[2026-08-15] T > EOH | 2026-12-31 |
[2026-11-02] T + 1H | 2027-05-02 |
2026-08-31 + 1H | 2027-02-28 |
2026-08-31 - 2H | 2025-08-31 |
[2026-01-01 : 1H : 2027-12-31] | 2026-01-01, 2026-07-01, 2027-01-01, 2027-07-01 |
[2026-11-02] T > BOM - 1D + 5B | 2026-11-06 |
[2026-11-02] T + 2M > BOM - 1D > NEXT 3RD WED | 2027-01-20 |
selection in a period
[2026-11-02] T > 3RD WED IN MONTH | 2026-11-18 |
[2026-11-02] T > 3RD WED IN MONTH + 1D | 2026-11-19 |
[2026-11-02] T > LAST FRI IN MONTH | 2026-11-27 |
[2026-11-02] T > 5TH BD IN MONTH | 2026-11-06 |
[2027-01-01] T > 1ST BD IN MONTH | 2027-01-01 |
[2027-01-01 XNYS] T > 1ST BD IN MONTH | 2027-01-04 |
[2026-11-02] T > 2ND LAST BD IN MONTH | 2026-11-27 |
[2026-11-02] T > 4TH LAST BD IN MONTH | 2026-11-25 |
[2026-11-02 XNYS] T > 4TH LAST BD IN MONTH | 2026-11-24 |
[2027-05-03] T > LAST BD IN MONTH | 2027-05-31 |
[2027-05-03 XNYS] T > LAST BD IN MONTH | 2027-05-28 |
[2027-05-03 XNYS] T > EOM > PRECEDING | 2027-05-28 |
[2026-11-04] T > 1ST {MON, FRI} IN WEEK | 2026-11-02 |
[2026-11-08] T > LAST {MON, FRI} IN WEEK | 2026-11-06 |
[2026-11-04] T > 2ND IMM IN YEAR | 2026-06-17 |
[2025-04-01] T > 1ST @FOMC IN QUARTER | 2025-05-07 |
[2025-04-01] T > LAST @FOMC IN HALFYEAR | 2025-06-18 |
[2026-11-02] T > LAST BD IN HALFYEAR | 2026-12-31 |
[2026-11-02] T > 1ST 4 JUL IN YEAR | 2026-07-04 |
[2026-12-10] T > 1ST {MON, 25 DEC} IN MONTH | 2026-12-07 |
[2026-11-02] T > 1ST {LAST MON MAY} IN YEAR | 2026-05-25 |
[2026-11-04] T > BOW | 2026-11-02 |
[2026-11-04] T > EOW | 2026-11-08 |
[2026-11-08] T > BOW | 2026-11-02 |
[2026-12-31] T > EOW | 2027-01-03 |
[2027-03-22] SPOT + 1Q > EOQ > 3RD WED IN MONTH | 2027-06-16 |
[2026-11-02] T > 5TH WED IN MONTH | error |
[2026-11-02] T > 2ND 4 JUL IN YEAR | error |
[2026-11-02] T > 0TH WED IN MONTH | error |
[2026-11-02] T > 2ST WED IN MONTH | error |
[2026-11-02] T > LAST MON MAY IN YEAR | error |
[2026-11-02] T > 3RD WED IN | error |
[2026-11-02] T > 3RD WED IN DAY | error |
[2026-11-02] T > 3RD IN MONTH | error |
[2026-11-02] T > LAST LAST FRI IN MONTH | error |
[2026-11-02] T > 3RD WED MONTH | error |
4 JUL > 1ST WED IN MONTH | error |
series and intervals
[2026-01-30 : 2026-02-02] | 2026-01-30, 2026-01-31, 2026-02-01, 2026-02-02 |
]2026-01-30 : 2026-02-02] | 2026-01-31, 2026-02-01, 2026-02-02 |
[2026-01-30 : 2026-02-02[ | 2026-01-30, 2026-01-31, 2026-02-01 |
]2026-01-30 : 2026-02-02[ | 2026-01-31, 2026-02-01 |
[2026-01-01 : 1W : 2026-01-29[ | 2026-01-01, 2026-01-08, 2026-01-15, 2026-01-22 |
]2026-01-01 : 1W : 2026-01-29] | 2026-01-08, 2026-01-15, 2026-01-22, 2026-01-29 |
]2026-01-01 : 2026-01-01] | empty list |
[2026-01-01 : 2026-01-01[ | empty list |
[2026-01-01 : 2026-01-01] | 2026-01-01 |
[2026-01-02 : 2026-01-01] | empty list |
[2026-01-01 : 3M : 2026-12-31] > EOQ > 3RD WED IN MONTH | 2026-03-18, 2026-06-17, 2026-09-16, 2026-12-16 |
[2026-01-01 : 1M : 2026-03-31] > EOQ | 2026-03-31, 2026-03-31, 2026-03-31 |
[2026-01-01 XNYS] [T : 1D : T + 2D] + 1B | 2026-01-02, 2026-01-05, 2026-01-05 |
[2026-01-01 XNYS] [T : 1M : T + 5M] > EOM > PRECEDING | 2026-01-30, 2026-02-27, 2026-03-31, 2026-04-30, 2026-05-29, 2026-06-30 |
[2026-01-01] [T : T + 30D] IF MON, 25 DEC | 2026-01-05, 2026-01-12, 2026-01-19, 2026-01-26, 2026-12-25 |
[2026-01-01] [T : T + 9D] IF {SAT, SUN} | 2026-01-03, 2026-01-04, 2026-01-10 |
[2026-01-01] 24 DEC IF {MON, TUE, WED, THU} | 2026-12-24 |
[2026-01-01] 26 DEC IF {MON, TUE, WED, THU} | empty list |
2026-01-01, [2026-01-05 : 2026-01-06], 2026-01-02 | 2026-01-01, 2026-01-05, 2026-01-06, 2026-01-02 |
[2025-01-01] [@THANKSGIVING : @THANKSGIVING + 3D] IF {FRI} | 2025-11-28 |
[2026-01-01 : 2026-01-05 | error |
[2026-01-01 : : 2026-01-05] | error |
[2026-01-01 : 1D : 2026-01-05] + 4 JUL | error |
[2026-01-01] 24 DEC IF {} | error |
[2026-01-01] 24 DEC IF {MON TUE} | error |
[2026-01-01 : 1M] | error |
[2026-01-01 : 2026-01-05] [2026-01-06 : 2026-01-07] | error |
include, exclude and dates in year
[2026-01-01 : 2026-01-03] & [2026-01-02 : 2026-01-05] | 2026-01-01, 2026-01-02, 2026-01-03, 2026-01-04, 2026-01-05 |
[2026-01-05 : 2026-01-06] & [2026-01-01 : 2026-01-02] | 2026-01-01, 2026-01-02, 2026-01-05, 2026-01-06 |
[2026-01-01] [T : T + 7D] \ {1 JAN, 6 JAN} | 2026-01-02, 2026-01-03, 2026-01-04, 2026-01-05, 2026-01-07, 2026-01-08 |
[2026-01-01] [T : T + 7D] \ {1 JAN, 6 JAN} & 25 DEC | 2026-01-02, 2026-01-03, 2026-01-04, 2026-01-05, 2026-01-07, 2026-01-08, 2026-12-25 |
[2026-01-01] [T : 1W : T + 2W] & [T : 1W : T + 2W] | 2026-01-01, 2026-01-08, 2026-01-15 |
[2026-01-01 : 2026-01-03] & 2026-01-10 + 1D | 2026-01-02, 2026-01-03, 2026-01-04, 2026-01-11 |
[2026-01-01 : 2026-01-03] + 1D & 2026-01-10 | 2026-01-02, 2026-01-03, 2026-01-04, 2026-01-10 |
[2026-01-01] 1 JAN & {1 JAN + 1D, 6 JAN} | 2026-01-01, 2026-01-02, 2026-01-06 |
[2026-01-01] [T : T + 13D] \ [T : 1W : T + 13D] IF {MON, TUE} | 2026-01-05, 2026-01-06, 2026-01-12, 2026-01-13 |
[2026-01-01] [T : T + 2D] & 6 JAN, 31 DEC | 2026-01-01, 2026-01-02, 2026-01-03, 2026-01-06, 2026-12-31 |
[2025-06-01] [T : T + 29D] \ @FOMC IF WED | 2025-06-04, 2025-06-11, 2025-06-25 |
[2026-11-02] T > {1 FEB, 1 MAY} | 2026-02-01, 2026-05-01 |
[2026-11-02] [T : 1Y : T + 2Y] > {1 FEB, 1 MAY} | 2026-02-01, 2026-05-01, 2027-02-01, 2027-05-01, 2028-02-01, 2028-05-01 |
[2026-11-02] [T : 1Y : T + 1Y] > {3 WED MAR, 3 WED JUN, 3 WED SEP, 3 WED DEC} | 2026-03-18, 2026-06-17, 2026-09-16, 2026-12-16, 2027-03-17, 2027-06-16, 2027-09-15, 2027-12-15 |
[2026-11-02] [T : 1Y : T + 1Y] > {LAST MON MAY, 1 MON SEP} | 2026-05-25, 2026-09-07, 2027-05-31, 2027-09-06 |
[2026-11-02 XNYS] [T : 1Y : T + 1Y] > {1 FEB, 1 MAY} > FOLLOWING | 2026-02-02, 2026-05-01, 2027-02-01, 2027-05-03 |
[2026-11-02] T > {1 MAY, 1 FEB, 1 MAY} | 2026-02-01, 2026-05-01 |
[2026-01-01] {1 JAN, 6 JAN} | error |
[2026-01-01] 1 JAN & | error |
[2026-01-01] 1 JAN & {} | error |
[2026-01-01] 1 JAN \ 3M | error |
[2026-01-01] 1 JAN & {1 JAN 6 JAN} | error |
[2026-11-02] T > {} | error |
[2026-11-02] T > {MON} | error |
[2026-11-02] T > {@FOMC} | error |
[2026-11-02] T > {IMM} | error |
picks
[2026-11-02] 5TH [SPOT : 1Q : ] > EOQ > 3RD WED IN MONTH | 2027-12-15 |
[2026-11-02] 7TH [T : 1D : ] IF {MON, FRI} | 2026-11-27 |
[2026-11-02] 1ST [T : 1D : ] IF SAT | 2026-11-07 |
[2026-11-02] 3RD [2026-01-01 : 1M : ] > EOM | 2027-01-31 |
[2026-11-02] 2ND LAST [T : 1D : T + 10D] | 2026-11-11 |
[2026-11-02] 1ST LAST [T : 1W : T + 3W] | 2026-11-23 |
[2026-11-02] 2ND [T : T + 3D], 5 JAN | 2026-11-04, 2026-01-05 |
[2025-04-01] 2ND @FOMC | 2025-06-18 |
[2026-11-02] 1ST [T - 3D : 1D : ] | 2026-11-03 |
[2026-11-02] [T : 1Q : ] | error |
[2026-11-02] ]T : 1W : ] | error |
[2026-11-02] 0TH [T : 1D : ] | error |
[2026-11-02] 2ST [T : 1D : ] | error |
[2026-11-02] 1ST LAST [T : 1D : ] | error |
[2026-11-02] 20000TH [T : 1D : ] | error |
[2026-11-02] 5TH [T : 1D : T + 2D] | error |
[2026-11-02] LAST [T : 1D : T + 2D] | error |
[2026-11-02] 1ST [T : 1D : ] [ | error |
[2026-11-02] [T : 1D : [ | error |
[2026-11-02] 2ND T + 1D | error |
[2026-11-02] 1ST LAST MON MAY | error |
fixing calendar
[2026-04-01] T + 2F | 2026-04-03 |
[2026-04-01 XNYS XTGT] T + 2F | 2026-04-07 |
[2026-04-01 XNYS XTGT] T + 2B | 2026-04-06 |
[2026-04-01 XNYS XTGT] T > SPOT > FIX | 2026-04-01 |
[2026-04-01 XNYS XTGT] T > SPOT USDCAD > FIX USDCAD | 2026-04-01 |
[2026-04-07 XNYS XTGT] T - 1F | 2026-04-02 |
[2026-04-02 XNYS XTGT] T > NEXT FD | 2026-04-07 |
[2026-04-02 XNYS] T > NEXT FD | 2026-04-03 |
[2026-04-01 XNYS XTGT] T > 2ND FD IN MONTH | 2026-04-02 |
[2026-04-01 XNYS XTGT] T > 3RD LAST FD IN MONTH | 2026-04-28 |
[2026-04-01 XNYS XTGT] [T : 1F : T + 7D] | 2026-04-01, 2026-04-02, 2026-04-07, 2026-04-08 |
[2026-04-30 XNYS XTGT] T + 1B | 2026-05-01 |
[2026-04-30 XNYS XTGT] T + 1F | 2026-05-04 |
[2026-04-30 XNYS XTGT] T > NEXT {BD, FD} | 2026-05-01 |
[2026-04-01 XNYS XTGT] T > FIX EUR | error |
[2026-04-01 XNYS XTGT] T + 2FD | error |
[2026-04-01 XNYS XTGT] T > FD | error |
[2026-04-01 XNYS XTGT] T > FIX USDCAD USDCAD | error |
MaturityRule: the examples of another maturity rule language (selectors such as "lastday of month(5) of sp")
[2026-11-02] SPOT + 1W | 2026-11-11 |
[2026-11-02] SPOT + 4M > EOM | 2027-03-31 |
[2026-11-02] SPOT > IMM > IMM | 2027-03-17 |
[2027-03-22] SPOT > IMM > IMM | 2027-09-15 |
[2027-03-22] SPOT > EOQ > IMM | 2027-06-16 |
[2026-11-02] SPOT > EOQ > IMM | 2027-03-17 |
[2026-11-02] SPOT > IMM > IMM > IMM > IMM > IMM | 2027-12-15 |
[2026-11-02] SPOT > NEXT 5TH IMM | 2027-12-15 |
[2026-11-02] T > NEXT 7TH {MON, FRI} | 2026-11-27 |
[2026-11-02] SPOT + 1M > BOM - 1D > NEXT 3RD WED | 2026-12-16 |
[2027-01-01] 1 JAN - 1D + 5B | 2027-01-07 |
[2026-11-02] SPOT > NEXT FRI + 2W | 2026-11-20 |
[2026-11-02] SPOT > NEXT 3RD FRI | 2026-11-20 |
[2026-11-02] SPOT + 1M > BOM | 2026-12-01 |
[2026-11-02] SPOT > EOM | 2026-11-30 |
[2026-11-02] SPOT > NEXT {1 FEB, 1 MAY} | 2027-02-01 |
[2026-11-02] SPOT + 6M | 2027-05-04 |
[2026-11-02] SPOT + 1H | 2027-05-04 |
[2026-11-02] SPOT + 3B | 2026-11-09 |
[2026-11-02] T + 1D | 2026-11-03 |
[2026-11-02] T + 2B | 2026-11-04 |
[2026-11-02] T + 1Q | 2027-02-02 |
[2026-11-02] T + 1Y | 2027-11-02 |
[2026-11-02] T > NEXT 2ND MON | 2026-11-16 |
[2026-11-02] T > PREV 2ND MON | 2026-10-19 |
[2026-11-02] T > BOW | 2026-11-02 |
[2026-11-02] T > EOW | 2026-11-08 |
[2026-11-02] T > BOM + 9D | 2026-11-10 |
[2026-11-02] T > 3RD WED IN MONTH | 2026-11-18 |
[2026-11-02 XNYS] T > 5TH BD IN MONTH | 2026-11-06 |
[2026-11-02 XNYS] T > LAST BD IN MONTH | 2026-11-30 |
[2026-11-02] T > 2ND BD IN QUARTER | 2026-10-02 |
[2026-04-01 XNYS XTGT] T > 3RD FD IN MONTH | 2026-04-07 |
[2026-04-01 XNYS XTGT] T + 2F | 2026-04-07 |
[2026-04-01 XNYS XTGT] SPOT > FIX | 2026-04-01 |
[2026-11-02] T + 2M > BOM | 2027-01-01 |
[2026-11-02] T > BOQ + 1M > BOM | 2026-11-01 |
[2026-11-02] T > BOM > BOW + 1W | 2026-11-02 |
[2026-11-02] T > BOM - 1D > NEXT 2ND 1 JAN | 2028-01-01 |
[2026-11-02] 3RD [T > BOM : 1M : ] | 2027-02-01 |
[2026-11-02] T > NEXT {MON, FRI} | 2026-11-06 |
[2026-11-02] [T > BOW : T > EOW] IF {MON, FRI} | 2026-11-02, 2026-11-06 |
[2026-11-02] T > NEXT 3 WED MAR | 2027-03-17 |
[2026-11-02] T > NEXT 3 WED JUN | 2027-06-16 |
[2026-11-02] T > NEXT 3 WED SEP | 2027-09-15 |
[2026-11-02] T > NEXT 3 WED DEC | 2026-12-16 |
[2026-12-16] T > NEXT 3 WED DEC | 2027-12-15 |
[2026-11-02] 1ST [T > BOY : 1Y : ] + 2M > 3RD WED IN MONTH | 2027-03-17 |
[2026-11-02] T > NEXT 2ND 3 WED MAR | 2028-03-15 |
[2026-11-02] T > NEXT 2ND 3 WED JUN | 2028-06-21 |
[2026-11-02] T > NEXT 2ND 3 WED SEP | 2028-09-20 |
[2026-11-02] T > NEXT 2ND 3 WED DEC | 2027-12-15 |
[2026-11-02] 2ND [T > BOY : 1Y : ] + 11M > 3RD WED IN MONTH | 2027-12-15 |
[2026-11-02] T > NEXT 3RD 3 WED MAR | 2029-03-21 |
[2026-11-02] T > NEXT 3RD 3 WED JUN | 2029-06-20 |
[2026-11-02] T > NEXT 3RD 3 WED SEP | 2029-09-19 |
[2026-11-02] T > NEXT 3RD 3 WED DEC | 2028-12-20 |
[2026-11-02] T > NEXT 1 JAN | 2027-01-01 |
[2026-11-02] T > NEXT 31 MAR | 2027-03-31 |
[2026-11-02] T > NEXT 1 APR | 2027-04-01 |
[2026-11-02] T > NEXT 30 JUN | 2027-06-30 |
[2026-11-02] T > NEXT 1 JUL | 2027-07-01 |
[2026-11-02] T > NEXT 30 SEP | 2027-09-30 |
[2026-11-02] T > NEXT 1 OCT | 2027-10-01 |
[2026-11-02] T > NEXT 31 DEC | 2026-12-31 |
[2026-12-31] T > NEXT 31 DEC | 2027-12-31 |
[2026-11-02] T > NEXT 2ND 1 JAN | 2028-01-01 |
[2026-11-02] T > NEXT 2ND 31 MAR | 2028-03-31 |
[2026-11-02] T > NEXT 2ND 1 APR | 2028-04-01 |
[2026-11-02] T > NEXT 2ND 30 JUN | 2028-06-30 |
[2026-11-02] T > NEXT 2ND 1 JUL | 2028-07-01 |
[2026-11-02] T > NEXT 2ND 30 SEP | 2028-09-30 |
[2026-11-02] T > NEXT 2ND 1 OCT | 2028-10-01 |
[2026-11-02] T > NEXT 2ND 31 DEC | 2027-12-31 |
[2026-11-02] T > NEXT 3RD 1 JAN | 2029-01-01 |
[2026-11-02] T > NEXT 3RD 31 MAR | 2029-03-31 |
[2026-11-02] T > NEXT 3RD 1 APR | 2029-04-01 |
[2026-11-02] T > NEXT 3RD 30 JUN | 2029-06-30 |
[2026-11-02] T > NEXT 3RD 1 JUL | 2029-07-01 |
[2026-11-02] T > NEXT 3RD 30 SEP | 2029-09-30 |
[2026-11-02] T > NEXT 3RD 1 OCT | 2029-10-01 |
[2026-11-02] T > NEXT 3RD 31 DEC | 2028-12-31 |
[2026-11-02 XNYS] [SPOT + 1M : 1M : SPOT + 3M] > EOM + 2B | 2027-01-05, 2027-02-02, 2027-03-02 |
[2026-11-02 XNYS] 2ND [SPOT + 1M : 1M : ] > EOM + 2B | 2027-02-02 |
[2026-11-02] T > IMM | 2026-12-16 |
[2026-11-02] 1ST [T > BOQ : 1Q : ] + 2M > 3RD WED IN MONTH | 2026-12-16 |
[2026-11-02] T + 1M > 2ND WED IN MONTH | 2026-12-09 |
[2026-11-02] SPOT + 1M > 3RD WED IN MONTH | 2026-12-16 |
[2026-06-19] T + 2B > BOM - 1D > NEXT 1 JUN > 3RD WED IN MONTH | 2026-06-17 |
[2026-06-19] T + 2B > NEXT 3 WED JUN | 2027-06-16 |
invalid dates
2015-02-29 | error |
2015-13-01 | error |
31.04.2015 | error |
syntax errors
2015-06 | error |
+ 3M | error |
2015-06-09 + 3 | error |
2015-06-09 + M | error |
2015-06-09 + 3X | error |
2015-06-09 , | error |
2015-06-09 2015-06-10 | error |
2015-06.09 | error |
[2015-01-01 : 1M] | error |
2015-06-09 > | error |
2015-06-09 IMM | error |
2015-06-09 > 3M | error |
2015-06-09 > IM | error |
2015-06-09 SPOT | error |
2015-06-09 > USDCAD | error |
2015-06-09 > SPOT EUR | error |
2015-06-09 > SPOT EURUSDX | error |
2015-06-09 > SPOT usdcad | error |
2015-06-09 > SPOT USDCAD USDCAD | error |
[2015-06-09] 2015-06-09 + T | error |
[2015-06-09] T T | error |
2015-06-09 + 2b | error |
2015-06-09 > 2B | error |
[2015-01-01 : 1M : 2015-02-01], 2015-03-01 | 2015-01-01, 2015-02-01, 2015-03-01 |
(empty input) | error |
step of a range must be positive
[2015-01-01 : 0D : 2015-02-01] | error |
[2015-06-01 : 0B : 2015-06-05] | error |
Rule files and holidays-events
A schedule says which dates; a rule file says whose dates they are. Its grammar wraps the schedule language in declarations. It started in the Lark module as rules.lark; now all 12 implementations read rule files with their own tool and pass the 72 cases of examples/rules.txt.
rule xnys.juneteenth for juneteenth in exchange:XNYS valid from 2022-01-01 = 19 JUN {SAT - 1D, SUN + 1D}
with kind = closed
cites "NYSE holidays & trading hours" url "https://www.nyse.com/markets/hours-calendars" label official;
rule sa.eid_al_fitr for eid_al_fitr in country:SA
= ONE OF { 1 RAMADAN + 29D AS ramadan_29, 1 RAMADAN + 30D AS ramadan_30 }
with kind = closed;
- A declaration
A key, the event it dates, the scope whose calendar it belongs to (
country:GB,exchange:XNYS,central_bank:FED, …), an optional validity, the schedule, and attributes: the kind of day (closed,short_day,working_day,event, …), a session, a precision, a note, and citations.@keyrefers to the dates of another rule; business-day shifts use the calendar of the rule's scope, orONanother one. - Rules only project
Central banks and statistics offices publish their dates a year or two ahead. Those dates are data, given to the evaluator, never part of a rule: they replace a rule's projection for that year, and dates that are only ever announced have no rule.
ONE OFlists alternatives of which exactly one happens, such as a moon-sighted Eid after a 29- or 30-day month. - holidays-events
holidays-events/ holds the projection rules of holidays-events, a collection of market-relevant dates (exchange and payment-system holidays, central-bank decisions, statistics releases), in 11 rule files. Compared day by day with holidays-events' own engine for 2021 to 2031, 187 of 187 rules agree. The README explains how to read and run them.
Run it yourself
You need JDK 17 and Maven 3.9. Bison is optional: without it the Bison module builds empty. The Peggy module downloads its own Node.js. The C module needs a compiler, Flex and Bison, or Docker.
git clone https://github.com/hjuergens/date-parser.git
cd date-parser
mvn clean verify # all modules
mvn -pl date-rule-coco test # one module
docker build -t date-rule-flex-bison date-rule-flex-bison
docker run --rm -v "$PWD:/work" -w /work/date-rule-flex-bison date-rule-flex-bison make test # C