Formatter
LesliDate::Formatter interprets calendar dates and instants and exposes a set of display formats. Calendar dates retain their day; instants are converted to the presentation time zone.
Create a formatter
formatter = LesliDate::Formatter.new(Time.current)
The constructor accepts a value, an optional positional input format, zone options, and an optional output locale:
LesliDate::Formatter.new("2026/10/05 14:30", "%Y/%m/%d %H:%M")
| Argument | Default | Purpose |
|---|---|---|
datetime | Time.current | Date or instant to interpret; explicit nil is invalid |
format | nil | Native Ruby strptime pattern; otherwise use DateTime.parse |
input_zone: | "UTC" | Interpret date-time strings that have no offset |
zone: | nil | Presentation zone; nil uses Time.zone, then Lesli.config.datetime[:time_zone] |
locale: | nil | Output language; nil uses I18n.locale when rendering |
Lesli's database timestamps are UTC. The active Rails zone controls output; normal Lesli calls need no zone keywords. input_zone: is available for external sources that provide local times instead of UTC.
Accepted objects are Date, DateTime, Time, and ActiveSupport::TimeWithZone. Strings are interpreted with Ruby's DateTime.parse or, when a pattern is provided, DateTime.strptime. Accepted syntax and directives follow Ruby rather than a separate LesliDate format language. See Parsing rules for timezone behavior and errors.
LesliDate::Formatter.new(
"2026-10-22 14:30",
input_zone: "America/Guatemala",
zone: "UTC"
).date_time.to_s
# => "22.10.2026 20:30", with output format %d.%m.%Y %H:%M
LesliDate::Formatter.new("2026-10-22").get
# => Date.new(2026, 10, 22)
Select an output format
Every selector uses its matching key in Lesli.config.datetime[:formats]. Missing or nil values use these fallback patterns:
| Method | Fallback pattern |
|---|---|
date | %d.%m.%Y |
time | %H:%M |
date_time | %d.%m.%Y %H:%M |
date_words | %B %d, %Y |
date_words_day | %A, %B %d, %Y |
date_time_words | %B %d, %Y, %H:%M |
date_time_words_pm | %B %d, %Y, %I:%M %p |
date_time_words_day | %A, %B %d, %Y, %H:%M |
Each selector returns the formatter:
formatter.date_time_words.to_s
Selectors change the output format of the same instance. They do not parse the input again or replace .get. Input strings, temporal values and the host's configuration are not modified. Patterns are copied at construction, so later configuration edits do not change an existing formatter. .get exposes the underlying parsed value without cloning it. Use a separate formatter for independent selector state.
to_s uses I18n.localize with the selected pattern. Days, months and AM/PM use the translations already loaded by Rails. LesliDate does not install or replace translation data. The initializer determines the pattern and the current Rails locale determines its translated words:
I18n.with_locale(:es) do
LesliDate::Formatter.new("2026-10-22").date_words.to_s
end
LesliDate::Formatter.new("2026-10-22", locale: :es).date_words.to_s
get returns a Date for calendar inputs and an ActiveSupport::TimeWithZone for instants. Selecting .date on an instant does not discard its underlying time or fractional seconds.
Calendar dates support date, date_words, and date_words_day. Selecting time or any date_time* format raises LesliDate::InvalidFormat without changing the previous output format.
Invalid values and native parsing failures raise LesliDate::ParseError; invalid zone options raise LesliDate::InvalidTimeZone. InvalidFormat is used for invalid output configuration and time selectors applied to calendar dates. All inherit from LesliDate::Error < ArgumentError.
See Configuration for defaults, validation, locales and optional translation overrides in Lesli. See Application examples for forms, APIs and imports.
Last Update: 2026/11/15