lesli_date 1.0.0 → 1.1.1

data/docs/api/parsing.md

@@ -0,0 +1,101 @@
+# Parsing rules
+
+LesliDate uses Ruby's date parsers and Rails timezone conversion. It does not
+compile input patterns or maintain its own validation rules for every field.
+
+```ruby
+LesliDate::Formatter.new(value, format = nil, input_zone: "UTC", zone: nil, locale: nil)
+```
+
+## Input values
+
+| Input | Behavior | `.get` result |
+| --- | --- | --- |
+| No argument | Current instant | `ActiveSupport::TimeWithZone` |
+| `Time`, `TimeWithZone`, `DateTime` | Preserve the instant and apply the presentation zone | `ActiveSupport::TimeWithZone` |
+| `Date` | Preserve the calendar date | `Date` |
+| String without a pattern | Use `DateTime.parse` | `Date` or `ActiveSupport::TimeWithZone` |
+| String with a pattern | Use `DateTime.strptime` | `Date` or `ActiveSupport::TimeWithZone` |
+| Other types, including explicit `nil` | Reject with `LesliDate::ParseError` | No value |
+
+The native parser's metadata distinguishes a calendar date from an instant.
+Calendar dates support `.date`, `.date_words`, and `.date_words_day`. Time
+selectors on dates raise `LesliDate::InvalidFormat` instead of inventing an hour.
+Selecting `.date` on an instant preserves its full underlying value in `.get`.
+
+## Native input patterns
+
+The second positional argument is a Ruby `strptime` pattern. It supports native
+directives, including compound directives, month names, offsets and fractions:
+
+```ruby
+LesliDate::Formatter.new("22/10/2026", "%d/%m/%Y").get
+# => Date.new(2026, 10, 22)
+
+LesliDate::Formatter.new("22 October 2026", "%d %B %Y").date.to_s
+LesliDate::Formatter.new("2026-10-22 14:30:45", "%F %T").date_time.to_s
+LesliDate::Formatter.new("2026-10-22T14:30:45.123Z").date_time.to_s
+```
+
+When a pattern is supplied, LesliDate calls `strptime` directly and does not
+retry with `parse`. An unparseable value or a mismatch raises `ParseError` with
+the native exception as its cause.
+
+Accepted syntax, missing-component defaults, precision, calendar conventions,
+and tolerance follow Ruby. For example, native parsing may accept partial dates
+or a valid prefix with trailing text. LesliDate does not add complete-input
+validation, a directive allowlist, year bounds, encoding conversion, or manual
+range checks. Patterns apply to string inputs; temporal objects are used directly.
+
+## UTC input and configured output
+
+Lesli stores database timestamps in UTC. The initializer's
+`Lesli.config.datetime[:time_zone]` controls presentation. Normal Lesli calls
+need no zone options:
+
+```ruby
+# With America/Guatemala and output format %d/%m/%Y %H:%M:
+LesliDate::Formatter.new("2026-10-22 14:30:00").date_time.to_s
+# => "22/10/2026 08:30"
+```
+
+For strings containing a time but no offset, `input_zone` defaults to UTC.
+Strings with an explicit offset already determine an instant. `zone` overrides
+the configured presentation zone for one formatter. Dates do not undergo zone
+conversion.
+
+```ruby
+# An external source supplies local Guatemala time rather than UTC.
+LesliDate::Formatter.new(
+  "22/10/2026 14:30",
+  "%d/%m/%Y %H:%M",
+  input_zone: "America/Guatemala",
+  zone: "UTC"
+).date_time.to_s
+# => "22.10.2026 20:30", with output format %d.%m.%Y %H:%M
+```
+
+Zone names use `ActiveSupport::TimeZone`. Local times, including clock-change
+gaps and overlaps, follow Rails' native `TimeZone#local` behavior. LesliDate does
+not implement a separate daylight-saving validation policy.
+
+## Exceptions
+
+| Error | Meaning |
+| --- | --- |
+| `LesliDate::ParseError` | Unsupported input type or an exception from native parsing |
+| `LesliDate::InvalidTimeZone` | Missing or unknown zone name; an unsupported SQLite output zone when generating SQL |
+| `LesliDate::InvalidFormat` | Invalid output configuration, a time selector applied to a calendar date, or an unsupported PostgreSQL SQL-format directive |
+
+All inherit from `LesliDate::Error < ArgumentError`.
+I18n locale/translation failures keep their native exception behavior. SQL
+execution errors come from ActiveRecord; unsupported SQLite format directives
+return native SQL `NULL` rather than a LesliDate exception.
+
+```ruby
+begin
+  value = LesliDate::Formatter.new(params[:date], "%d/%m/%Y").get
+rescue LesliDate::ParseError
+  # Present the application's validation message.
+end
+```

data/docs/images/date-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="#0c2856" viewBox="0 0 100 100"><desc>A formatted calendar paired with a clock.</desc><rect width="61" height="67" x="8" y="19" rx="7"/><rect width="49" height="43" x="14" y="35" fill="#d8e1ef" rx="3"/><rect width="8" height="18" x="20" y="12" rx="4"/><rect width="8" height="18" x="48" y="12" rx="4"/><rect width="9" height="8" x="20" y="43" rx="2"/><rect width="9" height="8" x="34" y="43" rx="2"/><rect width="9" height="8" x="48" y="43" rx="2"/><rect width="9" height="8" x="20" y="57" rx="2"/><rect width="9" height="8" x="34" y="57" rx="2"/><circle cx="73" cy="68" r="21"/><circle cx="73" cy="68" r="14" fill="#d8e1ef"/><path d="M70 56h6v11l8 5-3 5-11-7Z"/></svg>

data/docs/navigation

@@ -0,0 +1,2 @@
+<%= navigation_for_folder("gems", "date", "about", order:["installation", "configuration", "development"]) %>
+<%= navigation_for_folder("gems", "date", "api", order:["overview", "formatter", "parsing", "database", "examples"]) %>

data/lib/lesli_date/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LesliDate
+    class Error < ArgumentError; end
+    class ParseError < Error; end
+    class InvalidTimeZone < Error; end
+    class InvalidFormat < Error; end
+end

data/lib/lesli_date/formatter.rb

@@ -32,14 +32,34 @@ Building a better future, one line of code at a time.
 
 # maybe move this to a "LDate" gem?
 
+require "lesli_date/parser"
+require "active_record"
+require "i18n"
+
 module LesliDate
     class Formatter
 
-        def initialize(datetime = Time.current, format = "%Y-%m-%d %H:%M:%S")
+        DEFAULT_FORMATS = {
+            :date => "%d.%m.%Y",
+            :time => "%H:%M",
+            :date_time => "%d.%m.%Y %H:%M",
+            :date_words => "%B %d, %Y",             # date in words including day's name
+            :date_words_day => "%A, %B %d, %Y",     # date in words including day's name
+            :date_time_words => "%B %d, %Y, %H:%M", # 24 hours datetime in words format (default)
+            :date_time_words_pm => "%B %d, %Y, %I:%M %p",   # 12 hours datetime in words format
+            :date_time_words_day => "%A, %B %d, %Y, %H:%M", # 24 hours datetime in words format (default)
+        }.freeze
+        private_constant :DEFAULT_FORMATS
+
+        def initialize(datetime = Time.current, format = nil, input_zone: "UTC", zone: nil, locale: nil)
 
             # NOTE: user should be able to change this through settings table
             # get initial datetime configuration
-            config = Lesli.config.datetime
+            config = Lesli.config.datetime || {}
+            configured_zone = config[:time_zone]
+            output_zone = zone.nil? ? configured_zone : zone
+            # Lesli stores timestamps in UTC; the configured zone controls presentation.
+            @parser = Parser.new(input_zone: input_zone, zone: output_zone)
 
 
             # NOTE: Do not modify settings here,
@@ -63,19 +83,11 @@ module LesliDate
             # }
 
             @settings = {
-                :time_zone => config[:time_zone],
-                :start_week_on => config[:start_week_on],
-                :format => {
-                    :date => config[:formats][:date] || "%d.%m.%Y",
-                    :time => "%H:%M",
-                    :date_time => config[:formats][:date_time] || "%d.%m.%Y %H:%M",
-                    :date_words => "%B %d, %Y",             # date in words including day's name
-                    :date_words_day => "%A, %B %d, %Y",     # date in words including day's name
-                    :date_time_words => "%B %d, %Y, %H:%M", # 24 hours datetime in words format (default)
-                    :date_time_words_pm => "%B %d, %Y, %I:%M %p",   # 12 hours datetime in words format
-                    :date_time_words_day => "%A, %B %d, %Y, %H:%M", # 24 hours datetime in words format (default)
-                }
+                :time_zone => @parser.output_zone.name,
+                :start_week_on => config[:start_week_on] || "monday",
+                :format => configured_formats(config[:formats])
             }
+            @locale = locale
 
 
             # default date format
@@ -83,25 +95,16 @@ module LesliDate
 
 
             # get a valid timezone
-            @zone = ActiveSupport::TimeZone.new(@settings[:time_zone])
+            @zone = @parser.output_zone
 
 
             # get datetime object from user params
-            @datetime = parse_initial_datetime(datetime, format).in_time_zone(@zone)
+            @datetime = parse_initial_datetime(datetime, format)
 
         end
 
         # Dynamically define formatting methods like `date`, `time`, etc.
-        [
-            :date, 
-            :time, 
-            :date_time, 
-            :date_words,
-            :date_words_day, 
-            :date_time_words,
-            :date_time_words_pm, 
-            :date_time_words_day
-        ].each do |key|
+        DEFAULT_FORMATS.each_key do |key|
             define_method(key) do
                 set_format(key)
                 self
@@ -110,47 +113,43 @@ module LesliDate
 
         # return query string to get timestamps columns from database
         def db_timestamps table=""
-
-            # avoid ambiguous columns
-            table = table.concat(".") if table != ""
-
-            # get right format for dates
-            format = self.db_format
-
-            # compatibility for SQLite
-            if ActiveRecord::Base.connection.adapter_name == "SQLite"
-                offset = ActiveSupport::TimeZone[@settings[:time_zone]].utc_offset / 3600
-                return "strftime('#{format}', #{table}created_at, '#{offset} hours') as created_at_string"
-            end
-
-            "TO_CHAR(#{table}created_at at time zone 'utc' at time zone '#{@settings[:time_zone]}', '#{format}') as created_at_date, TO_CHAR(#{table}updated_at at time zone 'utc' at time zone '#{@settings[:time_zone]}', '#{format}') as updated_at_date"
-
+            [:created_at, :updated_at].map { |column| db_column(column, table) }.join(", ")
         end
 
         # return query string to get a datetime column from database
         def db_column column, table="", as:nil
-
-            as = "#{column}_string" unless as
+            connection = ActiveRecord::Base.connection
 
             # avoid ambiguous columns
-            table = table.concat(".") if table != ""
+            identifier = connection.quote_column_name(column.to_s)
+            identifier = "#{connection.quote_table_name(table.to_s)}.#{identifier}" unless table.to_s.empty?
 
             # get right format for dates
-            format = self.db_format
+            format = connection.quote(db_format)
 
             # compatibility for SQLite
-            if ActiveRecord::Base.connection.adapter_name == "SQLite"
-                offset = ActiveSupport::TimeZone[@settings[:time_zone]].utc_offset / 3600
-                return "strftime('#{format}', #{table}#{column}, '#{offset} hours') as #{as}"
+            case connection.adapter_name
+            when "SQLite"
+                # SQLite supports fixed offsets, including fractional hours, but not IANA rules.
+                period = @zone.tzinfo.period_for_utc(Time.current.utc)
+                raise InvalidTimeZone, "SQLite requires a fixed output offset; use UTC or format #{@zone.name} in Ruby" if period.ends_at
+
+                offset = connection.quote("#{period.observed_utc_offset} seconds")
+                sql = "strftime(#{format}, #{identifier}, #{offset})"
+            when "PostgreSQL"
+                zone = connection.quote(@zone.tzinfo.identifier)
+                sql = "TO_CHAR(#{identifier} AT TIME ZONE 'UTC' AT TIME ZONE #{zone}, #{format})"
+            else
+                raise NotImplementedError, "LesliDate SQL does not support #{connection.adapter_name}"
             end
 
-            "TO_CHAR(#{table}#{column} at time zone 'utc' at time zone '#{@settings[:time_zone]}', '#{format}') as #{as}"
-
+            return sql if as == false
+            "#{sql} AS #{connection.quote_column_name((as || "#{column}_string").to_s)}"
         end
 
         # convert a datetime object to string representation using defined format
         def to_s
-            @datetime.strftime(@format)
+            I18n.localize(@datetime, format: @format, locale: @locale)
         end
 
         def get
@@ -159,43 +158,68 @@ module LesliDate
 
         private
 
+        def configured_formats(formats)
+            formats = {} if formats.nil?
+            raise InvalidFormat, "datetime[:formats] must be a hash" unless formats.is_a?(Hash)
 
-        # get datetime object or string datetime and return a datetime object
-        def parse_initial_datetime datetime, format
-
-            return datetime if datetime.is_a?(Time)
+            DEFAULT_FORMATS.merge(formats.compact).to_h do |name, pattern|
+                unless pattern.is_a?(String) && pattern.valid_encoding? && !pattern.strip.empty?
+                    raise InvalidFormat, "Format #{name} must be a nonempty string"
+                end
 
-            if datetime.is_a?(::String) and datetime.size == 25 and datetime[10] == "T"
-                return ::DateTime.iso8601(datetime)
+                [name, validated_format(pattern)]
             end
+        end
 
-            return ::DateTime.strptime(datetime, format)
+        def validated_format(pattern)
+            Time.current.strftime(pattern)
+            pattern.dup.freeze
+        rescue ArgumentError => error
+            raise InvalidFormat, error.message
         end
 
 
-        def set_format format
-            @format = @settings[:format][format || :date]
+        # get datetime object or string datetime and return a datetime object
+        def parse_initial_datetime datetime, format
+            # Calendar dates remain Dates; the parser converts only instants.
+            @parser.parse(datetime, format)
         end
 
 
-        def db_format
-            format = @format
-
-            # SQLite format dates are the same of ruby format 
-            return format if ActiveRecord::Base.connection.adapter_name == "SQLite"
+        def set_format format
+            if @datetime.is_a?(::Date) && ![:date, :date_words, :date_words_day].include?(format || :date)
+                raise InvalidFormat, "A calendar date cannot be formatted with a time selector"
+            end
 
-            # Convert Ruby to postgresql date format
-            format = format.gsub("%Y", "YYYY")
-            format = format.gsub("%m", "MM")
-            format = format.gsub("%d", "DD")
+            @format = @settings[:format][format || :date]
+        end
 
-            # Convert Ruby to postgresql time format
-            format = format.gsub("%H", "HH24") # 24 hours format
-            format = format.gsub("%I", "HH12") # 12 hours format
-            format = format.gsub("%p", "AM") # Meridian indicator (AM/PM)
-            format = format.gsub("%M", "MI")
+        def db_format
+            # SQLite format dates are the same of ruby format
+            return @format if ActiveRecord::Base.connection.adapter_name == "SQLite"
+
+            formats = {
+                # Convert Ruby to postgresql date format
+                "%Y" => "YYYY", "%y" => "YY", "%m" => "MM", "%d" => "DD",
+                "%B" => "FMMonth", "%b" => "FMMon", "%A" => "FMDay", "%a" => "FMDy",
+                "%j" => "DDD", "%F" => "YYYY-MM-DD",
+                # Convert Ruby to postgresql time format
+                "%H" => "HH24", # 24 hours format
+                "%I" => "HH12", # 12 hours format
+                "%p" => "AM",   # Meridian indicator (AM/PM)
+                "%P" => "am", "%M" => "MI", "%S" => "SS",
+                "%R" => "HH24:MI", "%T" => "HH24:MI:SS", "%%" => '"%"'
+            }
 
-            format
+            @format.gsub(/%.|[^%]+|%/) do |part|
+                if part.start_with?("%")
+                    formats.fetch(part) { raise InvalidFormat, "PostgreSQL does not support #{part.inspect}" }
+                else
+                    # Quoted text stays literal inside PostgreSQL's format template.
+                    '"' + part.gsub(/["\\]/) { |character| "\\#{character}" } + '"'
+                end
+            end
         end
+
     end
 end

data/lib/lesli_date/parser.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/time"
+require "lesli_date/errors"
+
+module LesliDate
+    # Calendar dates remain Dates; only instants undergo timezone conversion.
+    class Parser
+        attr_reader :output_zone
+
+        def initialize(input_zone:, zone:)
+            @output_zone = resolve_zone(zone)
+            @input_zone = resolve_zone(input_zone)
+        end
+
+        def parse(value, format = nil)
+            case value
+            when String
+                parse_string(value, format)
+            when Time, ActiveSupport::TimeWithZone
+                value.in_time_zone(@output_zone)
+            when DateTime
+                value.new_start(Date::GREGORIAN).in_time_zone(@output_zone)
+            when Date
+                value
+            else
+                raise ParseError, "Expected a date, time or date string"
+            end
+        end
+
+        private
+
+        def resolve_zone(name)
+            zone = ActiveSupport::TimeZone[name] if name.is_a?(String)
+            zone || raise(InvalidTimeZone, "Unknown time zone: #{name.inspect}")
+        end
+
+        def parse_string(value, format)
+            value = value.strip
+            datetime = format ? DateTime.strptime(value, format) : DateTime.parse(value)
+            parts = format ? Date._strptime(value, format) : Date._parse(value)
+
+            # Native parsing metadata distinguishes a date from a time or explicit offset.
+            return datetime.to_date if (parts.keys & [:hour, :min, :sec, :seconds, :offset]).empty?
+
+            if parts[:offset] || parts[:seconds]
+                return datetime.new_start(Date::GREGORIAN).in_time_zone(@output_zone)
+            end
+
+            @input_zone.local(
+                datetime.year, datetime.month, datetime.day,
+                datetime.hour, datetime.minute, datetime.second + datetime.sec_fraction
+            ).in_time_zone(@output_zone)
+        rescue ArgumentError, TypeError => error
+            raise ParseError, error.message
+        end
+    end
+
+    private_constant :Parser
+end

data/lib/lesli_date/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module LesliDate
-    VERSION = "1.0.0"
-    BUILD = "1771715352"
+    VERSION = "1.1.1"
+    BUILD = "1790534691"
 end