# Tempo v2.1.0 - Table of Contents

> Time as an interval, not an instant: ISO 8601 and IXDTF dates, times, intervals, durations, recurrences and sets, with Allen's relations and set algebra over them. Calendar- and time zone-aware.

## Pages

- [Tempo](readme.md)
- [License](license.md)
- [Changelog](changelog.md)

- Tutorial
  - [Tutorial: build a booking-availability service](tutorial-booking-availability.md)

- Upgrading
  - [Migrating from Tempo 1.6 to 2.0](migration.md)

- Livebooks
  - [Everyday holiday questions](everyday-holidays.md)
  - [Getting started with Tempo](getting-started.md)
  - [Scheduling with Tempo](scheduling-workbook.md)
  - [A tour of Tempo](tempo_tour.md)
  - [Uncertain dates with Tempo](uncertain-dates-workbook.md)

- Cookbooks
  - [Tempo Cookbook](cookbook.md)
  - [Holiday cookbook](holiday-cookbook.md)
  - [Holidays — Planning with a Real Holiday Calendar](holidays.md)
  - [Scheduling](scheduling.md)
  - [Working with workdays and weekends](workdays-and-weekends.md)

- Guides
  - [Using Tempo with an AI assistant](ai-assistance.md)
  - [Building expressions](building-expressions.md)
  - [Date rules](date-rules.md)
  - [Enumeration semantics](enumeration-semantics.md)
  - [Falsehoods Programmers Believe About Time](falsehoods.md)
  - [iCalendar integration](ical-integration.md)
  - [Converting to and from Elixir date/time types](interop.md)
  - [Pattern matching with sigils](pattern-matching-with-sigils.md)
  - [Selection](selection.md)
  - [Set operations](set-operations.md)
  - [Dating under uncertainty](uncertain-dates.md)
  - [When to Use Tempo](when-to-use-tempo.md)

- Reference
  - [The date rule grammar](date-rule-grammar.md)
  - [Glossary](glossary.md)
  - [ISO 8601 Conformance Guide](iso8601-conformance.md)
  - [The grammar Tempo reads](iso8601-grammar.md)
  - [RFC 5545 RRULE Conformance](rfc5545_rrule_conformance.md)
  - [One form for ISO 8601 and RFC 5545 RRULE](shared-ast-iso8601-and-rrule.md)

- Foundations
  - [Architecture: the model, the engine and its contracts](architecture.md)
  - [Custom calendars — fiscal years, retail weeks, academic years](custom-calendars.md)
  - [Design Decisions](design-decisions.md)
  - [Temporal formalisms and where Tempo fits](temporal-formalisms.md)

## Modules

- [Tempo.Clock.Test](Tempo.Clock.Test.md): A clock for tests: the current time pinned in the calling process.

- Core
  - [Tempo](Tempo.md): Time as intervals, not instants.
  - [Tempo.Builder](Tempo.Builder.md): Builds an expression a step at a time, so that a pipeline reads as the
sentence it means.
  - [Tempo.Duration](Tempo.Duration.md): A length of time with no place on the time line: `P1Y2M3DT4H5M6S`.
  - [Tempo.Interval](Tempo.Interval.md): Intervals: a span between two ends, `2026-06-01/2026-06-30`.
  - [Tempo.IntervalSet](Tempo.IntervalSet.md): Interval sets: all of several expressions, `{2026-06,2026-08}`.
  - [Tempo.RecurrenceSet](Tempo.RecurrenceSet.md): A collection of rules whose occurrences form one set: a territory's
public holidays, a calendar's events.
  - [Tempo.Sigils](Tempo.Sigils.md): The `~o` sigil: an ISO 8601 text read at compile time.

- Relations and selection
  - [Tempo.Allen](Tempo.Allen.md): Allen's thirteen relations between two spans, their inverses and their
composition, and the everyday predicates as sets of them.
  - [Tempo.Event](Tempo.Event.md): The date of a named computed event in a year: an event fixed by an
algorithm rather than by the calendar.
  - [Tempo.Event.Resolver](Tempo.Event.Resolver.md): A behaviour for a consumer's own computed events, written `(name)e` in a
selection beside the built-ins of `Tempo.Event`.
  - [Tempo.Territory](Tempo.Territory.md): Which territory a caller means: the CLDR territory (`:US`, `:SA`, `:GB`)
whose weekend, workdays and conventions Tempo asks Localize for.
  - [Tempo.Workdays](Tempo.Workdays.md): A territory's workdays less a set of days off: the days a school or a
business is open.

- Recurrence rules and calendar formats
  - [Tempo.Cron](Tempo.Cron.md): Reads cron expressions into Tempo recurrences: the firings a schedule
names, as the recurrence an `RRULE` or an ISO 8601-2 repeat rule reads to.
  - [Tempo.DateRule](Tempo.DateRule.md): Reads date rules: the yearly dates people write, `2nd Monday in June`,
`Friday after 4th Thursday in November`, `easter -2`, `15 Nisan`, `chinese
01-0-01`, `march equinox in Asia/Tokyo`, into the Tempo recurrences they
mean.
  - [Tempo.ICal](Tempo.ICal.md): Reads iCalendar (RFC 5545) data into Tempo: each `VEVENT` an interval
carrying the event's summary, location and the rest as metadata, each
recurring event its occurrences, and RFC 7953 `VAVAILABILITY` components
the time they offer.
  - [Tempo.JSCalendar](Tempo.JSCalendar.md): Reads JSCalendar (RFC 8984) documents into Tempo: each `Event` an
interval or, when it recurs, its occurrences, with the event's title,
status and the rest as metadata; a `Group` its member events; a `Task`
nothing, a task being work to do and not time taken.
  - [Tempo.RRule](Tempo.RRule.md): Reads and writes RFC 5545 `RRULE` text: `parse/2` turns a rule into a
Tempo recurrence, the `%Tempo{}` an ISO 8601-2 repeat rule reads to, and
`to_string/1` writes one back.

- Clock, leap seconds and explanation
  - [Tempo.Clock](Tempo.Clock.md): A behaviour that gives Tempo the current time.
  - [Tempo.Clock.System](Tempo.Clock.System.md): The default `Tempo.Clock`: the system's time, from `DateTime.utc_now/0`.
  - [Tempo.Explain](Tempo.Explain.md): A description of an expression in prose: what it is, the time it covers,
the frame it is in and what walking it gives.
  - [Tempo.LeapSeconds](Tempo.LeapSeconds.md): The leap seconds the International Earth Rotation and Reference Systems
Service (IERS) has announced since UTC began in 1972, and which of them an
expression spans.

- Exceptions
  - [Tempo.ClockError](Tempo.ClockError.md): A clock that cannot tell the time.
  - [Tempo.ConversionError](Tempo.ConversionError.md): An expression that cannot be given the spans asked of it, with the
reason: a duration has no place on the time line, a one-of set has
readings and no spans, a value with no year needs one, a sequence with
no end needs a `:within` window, or more values were asked for at once
than the application's `:max_values_at_once` allows (10,000 unless it is set).
  - [Tempo.FrameError](Tempo.FrameError.md): Two expressions that share no frame to be related or combined on (law 4):
one with a zone or a shift and one with neither, one with a year and one
without and no `:within` window to place it by, or two with no year on
different cycles. Or one expression in the wrong frame for what was asked
of it: a zoned one to be placed in a zone, a floating one to be moved to
another.
  - [Tempo.IntervalEndpointsError](Tempo.IntervalEndpointsError.md): An interval whose ends do not make a span.
  - [Tempo.InvalidCalendarError](Tempo.InvalidCalendarError.md): A module or a name that is no calendar Tempo can ask.
  - [Tempo.InvalidDateError](Tempo.InvalidDateError.md): A value no date or time has: a unit outside the values its calendar gives
it, a day a month lacks, a reading the clock skips.
  - [Tempo.Iso8601EncodeError](Tempo.Iso8601EncodeError.md): A value ISO 8601 has no text for: a struct built by hand with parts in two
calendars or two zones, or a construct the notation does not write.
  - [Tempo.ParseError](Tempo.ParseError.md): Text that is not an ISO 8601 expression Tempo reads.
  - [Tempo.ZoneError](Tempo.ZoneError.md): A time zone Tempo cannot use.