README
¶
chronic — go-ruby-chronic
A pure-Go (no cgo) reimplementation of Ruby's
chronic gem — a natural-language date
and time parser. It turns English phrases such as "tomorrow", "next tuesday",
"3 days ago", "may 27th" or "2016-05-27" into a concrete instant (or a
Span), faithfully mirroring the deterministic grammar of chronic 0.10.2 —
without any Ruby runtime.
It is the natural-language time backend for go-embedded-ruby, but is a standalone, reusable module with no dependency on the Ruby runtime — a sibling of go-ruby-regexp (the Onigmo engine) and go-ruby-erb (the ERB compiler).
Deterministic by construction
Parse is deterministic: pass a fixed anchor via Options.Now and the result
depends only on the input string, so it needs no interpreter and no wall clock.
Its output is differential-tested byte-for-byte against MRI's own chronic
gem.
Usage
import (
"time"
"github.com/go-ruby-chronic/chronic"
)
now := time.Date(2006, 8, 16, 14, 0, 0, 0, time.Local)
t, _ := chronic.Parse("tomorrow", chronic.Options{Now: now})
// t == 2006-08-17 12:00:00
Tests & coverage
go test ./... runs the unit, golden and differential-oracle suites. The CI
gate enforces 100% statement coverage and builds/tests on all six 64-bit Go
targets — amd64, arm64, riscv64, loong64, ppc64le, s390x.
License
BSD-3-Clause. Copyright (c) the go-ruby-chronic/chronic authors.
WebAssembly
Being pure Go (CGO=0), this library also compiles to WebAssembly — both
GOOS=js GOARCH=wasm (browser / Node.js) and GOOS=wasip1 GOARCH=wasm (WASI).
CI builds both targets on every push, alongside the six 64-bit native/qemu arches.
GOOS=js GOARCH=wasm go build ./... # browser / Node
GOOS=wasip1 GOARCH=wasm go build ./... # WASI (wasmtime, wasmer, wasmedge, …)
Documentation
¶
Overview ¶
Package chronic is a pure-Go (no cgo) reimplementation of Ruby's `chronic` gem — a natural-language date and time parser. It turns English phrases such as "tomorrow", "next tuesday", "3 days ago", "may 27th" or "2016-05-27" into a concrete instant (or a Span), faithfully mirroring the deterministic grammar of chronic 0.10.2.
The entry point is Parse. It is deterministic: pass a fixed anchor via Options.Now and the result depends only on the input string, so it needs no Ruby runtime.
now := time.Date(2006, 8, 16, 14, 0, 0, 0, time.Local)
t, _ := chronic.Parse("tomorrow", chronic.Options{Now: now})
// t == 2006-08-17 12:00:00
Index ¶
Constants ¶
This section is empty.
Variables ¶
var TimeLoc = time.Local
TimeLoc is the location every constructed instant lives in. It mirrors MRI's Time.local, which builds times in the process-local zone. It is a package variable so callers (and the oracle tests) can pin it to a fixed zone for reproducibility.
Functions ¶
Types ¶
type Guess ¶
type Guess int
Guess selects whether Parse returns a single instant or the whole matched Span, and — for an instant — which point of the span to pick.
type Options ¶
type Options struct {
// Now is the anchor instant. Leave zero to use the current time. Pin it for
// deterministic parses.
Now time.Time
// Context resolves ambiguity toward the future (default) or past.
Context Context
// Guess selects the returned instant within the matched span.
Guess Guess
// AmbiguousTimeRange is the hour (1..12) an ambiguous bare time like "5" is
// assumed to fall within (AM..PM). Zero means the default of 6. Set
// AmbiguousTimeRangeNone to disable the assumption entirely.
AmbiguousTimeRange int
AmbiguousTimeRangeNone bool
// EndianLittle parses "03/04/2011" as day/month (d/m) rather than the
// default month/day (m/d).
EndianLittle bool
// WeekStart is the first day of the week ("sunday" default, or "monday").
WeekStart string
// Hours24 forces 24-hour interpretation when true; set Hours24Set together
// with Hours24=false to force 12-hour interpretation. When Hours24Set is
// false the parser auto-detects (the gem's nil).
Hours24 bool
Hours24Set bool
// AmbiguousYearFutureBias biases two-digit year expansion (default 50).
AmbiguousYearFutureBias int
}
Options configures a parse, mirroring Chronic::Parser's options hash. The zero value is valid and matches the gem's defaults (context future, guess middle, sunday week start, ambiguous-time-range 6, endian precedence middle-then- little, ambiguous-year-future-bias 50). Now defaults to time.Now.
Source Files