Dates, Clock, and Randomness

Date helpers calculate calendar relationships, such as a due date seven days after an invoice date. They operate on ISO-formatted date strings. Asking for the current time or drawing a random number serves a different purpose: those operations obtain a value from the host rather than calculating only from existing inputs.

This page covers both kinds of operation and explains their inputs. Date snippets are expressions for use after equals, Print, or Respond with; time and random draws are complete statements with their own permission declarations.

Calculate with dates

Use a date string in YYYY-MM-DD form. The first helper produces a new date; the other two count the separation between dates. Business days count Monday through Friday without a holiday calendar.

add 7 days to "2026-06-30"
days between "2026-06-30" and due_date
business days between "2026-06-30" and due_date

Date helpers use ISO YYYY-MM-DD strings. Invalid dates produce nil or an empty string depending on the helper. Business days count Monday through Friday and do not include a holiday calendar.

Request time or randomness

The host supplies these values, so they are effects rather than pure calculations. Declare the corresponding permissions before requesting them. Journaling can capture the supplied values so a recorded run can be replayed.

Permissions:
  Clock
  Randomness

Get the current time as now
Draw a random number between 0 and 1 as unit
Draw a random number between 1 and 6 as roll

These are declared effects so governed runs can journal and replay them.