README
Documentation
¶
Overview ¶
Package isnow implements the isnow date/time pattern language: an isnow holds at an instant when every field constraint is satisfied. The defining operation is the membership test, Pattern.Holds(at); Next/Prev derive occurrences from it. See github.com/tsvsheet/isnow (SPECIFICATION.md) for the language and specs/contracts/ for the pinned semantics.
Parse recognizes pattern source (PatternText), resolves symbols and the shorthand ladder, and validates field domains, returning an immutable Pattern that is safe to copy and share across goroutines. Is is the one-shot membership test (Parse then Holds). Errors returned to callers are the four stable errs.Const sentinels shared by every isnow implementation (ErrSyntax, ErrSymbol, ErrRange, ErrContext), matchable with errors.Is; Code maps an error back to its stable cross-implementation string code.
The package is filesystem-, network-, and clock-free by construction: every query takes the instant to evaluate against as an argument, so callers inject their own time source. Pattern recognition reuses the grammar repo's ANTLR-generated parser through the internal/isnowgrammar seam; no ANTLR type escapes into the public surface.
This package is a thin facade: every type, function, and constant it exposes re-exports the implementation in internal/engine unchanged, so the public surface is documented here while the engine stays an internal package.
Index ¶
Examples ¶
Constants ¶
const ( // ErrSyntax is a malformed pattern the grammar rejects. ErrSyntax = constants.ErrSyntax // ErrSymbol is an unknown or ambiguous weekday/time/unit name. ErrSymbol = constants.ErrSymbol // ErrRange is a value outside its field's domain. ErrRange = constants.ErrRange // ErrContext is a grammatical but semantically invalid construct. ErrContext = constants.ErrContext )
The four stable error codes every implementation shares (specs/contracts/ semantics.md in the grammar repo). Callers match with errors.Is.
Variables ¶
This section is empty.
Functions ¶
func Code ¶
Code returns the stable string code of a library error (syntax, symbol, range, context), or "" if err is nil or not a library error.
Example ¶
A rejected pattern carries one of the four stable sentinels, matchable with errors.Is; Code maps it to the cross-implementation string code.
package main
import (
"errors"
"fmt"
isnow "github.com/tsvsheet/go-isnow"
)
func main() {
_, err := isnow.Parse("25:00")
fmt.Println(errors.Is(err, isnow.ErrRange), isnow.Code(err))
}
Output: true range
func Is ¶
func Is(src PatternText, at time.Time) (bool, error)
Is is the one-shot membership test: Parse then Holds.
Example ¶
Is is the one-shot form: Parse then Holds.
package main
import (
"fmt"
"time"
isnow "github.com/tsvsheet/go-isnow"
)
func main() {
at := time.Date(2026, 7, 17, 0, 0, 0, 0, time.UTC)
ok, _ := isnow.Is("F mn", at)
fmt.Println(ok)
}
Output: true
Types ¶
type Pattern ¶
Pattern is a parsed, canonicalized isnow. The zero value is not usable; obtain one from Parse. Patterns are immutable and safe to copy and share.
func Parse ¶
func Parse(src PatternText) (Pattern, error)
Parse recognizes src, resolves symbols and the shorthand ladder, and validates field domains. It returns one of ErrSyntax, ErrSymbol, ErrRange, or ErrContext.
Example ¶
Parse compiles a pattern to an immutable Pattern; Holds is the membership test against any instant the caller supplies.
package main
import (
"fmt"
"time"
isnow "github.com/tsvsheet/go-isnow"
)
func main() {
p, err := isnow.Parse("M,W,F noon")
if err != nil {
fmt.Println(err)
return
}
monday := time.Date(2026, 7, 13, 12, 0, 0, 0, time.UTC)
fmt.Println(p.Holds(monday))
fmt.Println(p.Canonical())
}
Output: true */*/* Monday,Wednesday,Friday 12:00:00
type PatternText ¶
type PatternText = engine.PatternText
PatternText is isnow pattern source text accepted by Parse. It is exported so callers in other packages can convert their string input at the call site.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
constants
Package constants declares the isnow library's sentinel error values — the four stable error codes every isnow implementation shares (specs/contracts/semantics.md in the grammar repo).
|
Package constants declares the isnow library's sentinel error values — the four stable error codes every isnow implementation shares (specs/contracts/semantics.md in the grammar repo). |
|
engine
Package engine implements the isnow pattern engine: recognition of pattern source via the grammar repo's ANTLR-generated parser, the shorthand-ladder role assignment, compilation of every field term to a predicate, membership (Holds) over a broken-down instant, and occurrence derivation (Next/Prev) under the 100-year search horizon.
|
Package engine implements the isnow pattern engine: recognition of pattern source via the grammar repo's ANTLR-generated parser, the shorthand-ladder role assignment, compilation of every field term to a predicate, membership (Holds) over a broken-down instant, and occurrence derivation (Next/Prev) under the 100-year search horizon. |