Date, Time, and Random Numbers
Zoned Date-Time (ZDT) Values
Section titled “Zoned Date-Time (ZDT) Values”Eucalypt has native support for date-time values through the ZDT (Zoned Date-Time) type. ZDT values represent a point in time with timezone information.
ZDT Literals
Section titled “ZDT Literals”Use the t"..." prefix to write date-time literals directly in
eucalypt source:
today: t"2024-03-15"meeting: t"2024-03-15T14:30:00Z"local: t"2024-03-15T14:30:00+01:00"The t"..." syntax accepts ISO 8601 formats:
| Format | Example | Notes |
|---|---|---|
| Date only | t"2024-03-15" |
Midnight UTC |
| UTC | t"2024-03-15T14:30:00Z" |
|
| With offset | t"2024-03-15T14:30:00+05:00" |
|
| Fractional seconds | t"2024-03-15T14:30:00.123Z" |
Parsing and Formatting
Section titled “Parsing and Formatting”The cal namespace provides functions for working with date-time
values:
# Parse from a stringd: cal.parse("2024-03-15T14:30:00Z")
# Format as ISO8601 (cal.format takes no format-string argument)label: t"2024-03-15" cal.format # "2024-03-15T00:00:00+00:00"Date-Time Arithmetic
Section titled “Date-Time Arithmetic”ZDT values support comparison operators:
before: t"2024-01-01" < t"2024-12-31" # truesame: t"2024-03-15" = t"2024-03-15" # trueSorting Date-Times
Section titled “Sorting Date-Times”dates: [t"2024-12-25", t"2024-01-01", t"2024-07-04"]sorted: dates sort-zdts # [Jan 1, Jul 4, Dec 25]YAML Timestamps
Section titled “YAML Timestamps”When importing YAML files, unquoted timestamp values are automatically converted to ZDT values:
created: 2024-03-15updated: 2024-03-15T14:30:00ZQuote the value to keep it as a string: created: "2024-03-15".
See Import Formats for full details.
Current Time
Section titled “Current Time”The io.epoch-time binding provides the current Unix epoch time in
seconds:
now: io.epoch-timeRandom Numbers
Section titled “Random Numbers”Eucalypt provides pseudo-random number generation via the random
namespace, which is a state monad over a PRNG stream.
The random stream
Section titled “The random stream”A random stream is provided at startup as io.random. Each run
produces different values unless you supply a seed:
eu --seed 42 example.euSingle random values
Section titled “Single random values”For a single random value, pass io.random as the stream:
roll: random.int(6, io.random).value + 1colour: random.choice(["red", "green", "blue"], io.random).valueEach operation returns a {value, rest} block — extract .value
to get the result.
Multiple random values
Section titled “Multiple random values”When you need several random values, you must propagate the stream
from each call to the next. Reusing io.random would give the same
value each time:
# WRONG — both use the same stream, so d1 = d2d1: random.int(6, io.random).valued2: random.int(6, io.random).value
# RIGHT — thread the stream manuallyr1: random.int(6, io.random)r2: random.int(6, r1.rest)total: r1.value + r2.value + 2This manual threading is error-prone. The random monad can ease the
overhead somewhat — use a { :random ... } monadic block or
combinators like sequence and map-m:
# Monadic block — stream threads automaticallydice: { :random d6: random.int(6) d20: random.int(20)}.[d6, d20]
result: dice(io.random).value # e.g. [3, 14]
# Or use sequence for a list of actionstwo-dice: random.sequence([random.int(6), random.int(6)], io.random).valueOther operations
Section titled “Other operations”shuffled: random.shuffle(["a", "b", "c", "d"], io.random).valuepicked: random.sample(3, range(1, 50), io.random).valueSee the Random Numbers reference for the full API and the Monads guide for details on the state monad pattern.