Dates & Time

CalcMark has built-in support for dates, durations, relative date expressions, calendar quarters, and fiscal periods. This page covers how dates work, what creates a date, and what does not.

Creating Dates #

There are three ways to create a date in CalcMark:

1. Date literals require a month name (full or abbreviated), optionally with a day and year:

christmas = Dec 25 2025
project_start = January 15 2026
independence_day = Jul 4

When the year is omitted, CalcMark uses the current year. Month names are case-insensitive and accept standard abbreviations (Jan, Feb, Mar, Apr, Jun, Jul, Aug, Sep, Sept, Oct, Nov, Dec).

2. Date keywords produce dates relative to today:

right_now = today
the_day_after = tomorrow
the_day_before = yesterday

3. Relative date expressions resolve dates from context:

meeting = next Friday
retro = last Tuesday
start = this Monday
month_start = this month
q_start = this quarter
eom = end of this month

See Relative Dates below for the full list.

What is NOT a Date #

These common patterns do not create dates in CalcMark:

To express a year as a date, use a month name: Jan 1 2019, or the calendar-year shorthand: CY2019 (resolves to January 1 — see Quarter and Year Shorthand).

To express a date with a time offset, use arithmetic: Apr 1 2019 + 12 hours + 30 minutes. The result carries time precision internally.

Date Arithmetic #

Dates compose naturally with durations:

launch = Jan 15 2026 + 90 days
deadline = Jun 1 2026 - 2 weeks
next_review = today + 3 months

CalcMark uses calendar-correct month and year arithmetic. Adding 1 month to January 31 gives February 28 (or 29 in a leap year) – not March 3.

end_of_jan = Jan 31 2026
plus_one_month = Jan 31 2026 + 1 month

Date subtraction produces a duration in days:

project_start = Jan 1 2026
project_end = Jun 30 2026
project_length = Jun 30 2026 - Jan 1 2026

Duration Units #

Supported duration units: years (year, yr, yrs), months (month), weeks (week), days (day), hours (hour, hr), minutes (minute, min), seconds (second, sec), milliseconds (millisecond, ms).

Sub-day durations (hours, minutes, seconds) add time precision to dates:

meeting = Apr 1 2026 + 14 hours + 30 minutes

The from and ago Keywords #

Two alternative syntaxes for duration-relative dates:

review = 7 days from Jan 1 2026
launch = 2 weeks from today
next_step = 3 days from next Friday
budget = 90 days from now

lookback = 2 weeks ago
prior_quarter = 3 months ago

from computes a future date from a base. ago computes a past date from the current time.

Relative Dates #

Weekday Expressions #

d = next Friday
d = last Tuesday
d = this Wednesday
d = Friday

next <weekday> resolves to the soonest future occurrence of that weekday. If today is that weekday, it means next week’s. last <weekday> resolves to the most recent past occurrence. this <weekday> resolves to that weekday in the current calendar week (Monday through Sunday). A bare weekday name (Friday) is shorthand for this Friday.

Period Expressions #

d = this week
d = next month
d = last year

Period expressions resolve to the first day of the period. this week = Monday of the current week. this month = the 1st of the current month. this year = January 1.

Named Month Expressions #

d = next April
d = last December
d = this September

next <month> resolves to the 1st of that month in its next occurrence. If the current month is April, next April means April of next year.

Calendar Quarters #

q_start = this quarter
planning = next quarter
report = last quarter

Calendar quarters: Q1 = January, Q2 = April, Q3 = July, Q4 = October. Resolves to the first day of the quarter.

Start and End of Periods #

Use start of and end of to get the first or last day of any period:

eom = end of this month
eoq = end of this quarter
eoy = end of this year

board_deck = end of this quarter - 2 weeks

end of resolves to the last day of the period. start of is the explicit form of the default (first day). These compose with all period types: weeks, months, years, quarters, named months, and fiscal periods.

start of and end of are first-class language operators (not string-prefix sugar). The inner expression must be a period — a span of time the calendar can take the start or end of. Things that are NOT periods produce a clear diagnostic at type-check time:

• end of today — today is a single Date, not a period. The intent is usually end of this month or end of this week.
• end of 5 — Numbers aren’t periods.
• end of "Jan 15 2026" — Date literals are points, not periods.

The same rule applies to start of. Variable-bound forms (q = Q1; e = end of q) are deferred to a future release; until then, use the period literal directly: e = end of Q1.

Period values type-check at editing time, so the LSP completion dropdown and the cmw editor’s diagnostic markers surface these errors as you type.

Fiscal Periods #

CalcMark supports fiscal year and quarter calculations when configured via frontmatter:

---
fiscal_year_starts: july
---

You can also specify a start day for fiscal years that don’t begin on the 1st:

---
fiscal_year_starts: July 15
---

Only Month or Month Day are accepted — not full dates, not relative expressions, not years.

With fiscal configuration:

fq_start = this fiscal quarter
next_fq = next fiscal quarter
fy_start = this fiscal year
fy_end = end of this fiscal year

Note: Without the fiscal_year_starts frontmatter key, fiscal expressions produce an error: “fiscal expressions require a ‘fiscal_year_starts’ frontmatter key”.

Fiscal quarter numbering: FQ1 begins at the configured start month. With fiscal_year_starts: july: FQ1 = Jul-Sep, FQ2 = Oct-Dec, FQ3 = Jan-Mar, FQ4 = Apr-Jun.

Choosing how an FY label maps to a calendar year #

When the fiscal year does not start in January it straddles two calendar years, and different organisations label that span differently. CalcMark exposes the choice as a single frontmatter key:

---
fiscal_year_starts: february 2
calendar_year_offset: before   # default — can be omitted
---

The two values:

• calendar_year_offset: before (the default). The FY label is the calendar year the FY ends in. Used by the Australian government year (FY2026 = Jul 1, 2025 → Jun 30, 2026), the US tax year for non-calendar fiscal periods, and most publicly traded companies. With fiscal_year_starts: february 2, FY2026 resolves to Feb 2, 2025 → Feb 1, 2026.
• calendar_year_offset: after. The FY label is the calendar year the FY starts in. Some organisations label by the starting year — FY2026 = Feb 2, 2026 → Feb 1, 2027 under this convention.

The setting only affects labeling — the duration and quarter shape of the fiscal year are unchanged. It also has no effect when fiscal_year_starts: january (start year and end year are the same).

If your team’s CFO or finance system uses a different label than CalcMark gives you by default, set calendar_year_offset: after once in frontmatter and FY2026, FQ1, this fiscal year, etc. will all line up with what they expect.

Quarter and Year Shorthand #

CalcMark supports compact notation for quarters and years:

q1_start = Q1
q4_start = Q4
eoq2 = end of Q2

Q1 through Q4 are always calendar quarters: Q1 = Jan, Q2 = Apr, Q3 = Jul, Q4 = Oct of the current year.

With fiscal configuration, fiscal notation is available:

fq1_start = FQ1
fq3_start = FQ3
fy_start = FY2027
cy_start = CY2026

• FQ1-FQ4 — fiscal quarters (requires fiscal_year_starts)
• FY27 or FY2027 — first day of fiscal year 2027. By default the FY label is the year it ends in (matches the Australian government year, the US tax year, and most publicly traded companies). With fiscal_year_starts: july, FY2027 = July 1, 2026 through June 30, 2027. Set calendar_year_offset: after to label by the starting year instead.
• CY26 or CY2026 — January 1 of calendar year 2026. Disambiguates a year from a bare number (2026 is the number 2,026; CY2026 is January 1, 2026)

All notation is case-insensitive: q1, fq3, fy27, cy2026 all work.

In editors that integrate the CalcMark LSP, typing Q, FQ, FY, CY, end, end of, start, or start of surfaces the corresponding completions in the dropdown — including snippet-form FY${1:NNNN} and CY${1:NNNN} for the year-bearing forms, and synthesized end of <period> / start of <period> items for every parseable period kind. New period kinds added to the registry automatically light up in the completion dropdown without further wiring.

FQ1 always refers to the current fiscal year you are in. If you need a future fiscal quarter, use next fiscal quarter. The distinction:

• FQ1 — first quarter of the current fiscal year (may be in the past)
• this fiscal quarter — whichever fiscal quarter you are currently in
• next fiscal quarter — the fiscal quarter after the current one

Leap Year Handling #

CalcMark delegates all calendar math to Go’s time package for correct leap year handling:

leap = Feb 29 2024
after = Feb 29 2024 + 1 year

Feb 29 2024 + 1 year = February 28, 2025 (clipped to the last day of February in a non-leap year).

Timezone Behavior #

today and now use your machine’s local timezone, the same as Excel and most spreadsheet tools. If your machine says it’s Wednesday, CalcMark’s today returns Wednesday.

On servers or CI pipelines running in UTC, today may differ from your local date during timezone overlap windows. A future timezone configuration option is planned but not yet available.

Year Range #

CalcMark validates years to the range 1900-2100. Dates outside this range produce an error. BCE dates are not supported. CalcMark is designed for technical, business, and personal planning – not historical research.