field_struct 0.15.0

data/lib/field_struct/types/big_decimal.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # BigDecimal type. Accepts a {::BigDecimal}, +Integer+, +Float+, or a
+    # numeric string. Float input is converted with +Float::DIG+ precision
+    # to avoid the bare +BigDecimal(Float)+ "can't omit precision" error.
+    class BigDecimal < Base
+      # Native options: a +round:+ Integer precision and an +in:+ Array or
+      # Range of allowed values.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          round: option(type: [::Integer]),
+          in: option(type: [::Array, ::Range])
+        }
+      end
+
+      # @return [::Integer, nil] the field-level rounding precision, or +nil+
+      #   for no rounding. Subclasses override.
+      def self.default_round
+        nil
+      end
+
+      # @param value [::BigDecimal, Numeric, ::String, nil] +nil+ → +nil+;
+      #   a +BigDecimal+ passes through; +Float+ uses +Float::DIG+
+      #   precision; everything else goes through
+      #   +Kernel.BigDecimal(value.to_s)+ — non-numeric strings raise
+      #   ArgumentError.
+      # @param round [::Integer, nil] decimal places, rounding half up (ties
+      #   away from zero) whatever the global +BigDecimal.mode+; +nil+ leaves
+      #   the value unrounded. The result is a BigDecimal even at +round: 0+.
+      # @return [::BigDecimal, nil]
+      # @raise [ArgumentError] when a value's string form cannot be parsed
+      #   (e.g. a non-numeric String, or a Rational's "1/3"), or the value
+      #   is NaN or ±Infinity (as a Float, a BigDecimal, or a String like "NaN")
+      def coerce(value, round: self.class.default_round, **)
+        return nil if value.nil?
+
+        result = if value.is_a?(::BigDecimal)
+                   value
+                 elsif value.is_a?(::Float)
+                   ::Kernel.BigDecimal(value, ::Float::DIG)
+                 else
+                   parse(value)
+                 end
+        # The class, never the value — see Types::Time#coerce.
+        raise ArgumentError, "BigDecimal fields expect a finite number, got a non-finite #{value.class}" unless result.finite?
+
+        # An explicit mode keeps the result a BigDecimal (bare round(0)
+        # returns an Integer) and ignores the process-global
+        # BigDecimal.mode, which a host may have set to banker's rounding.
+        round ? result.round(round, ::BigDecimal::ROUND_HALF_UP) : result
+      end
+
+      # @return [Class] the top-level +::BigDecimal+ class
+      def ruby_type
+        ::BigDecimal
+      end
+
+      private
+
+      # @param value [Object] a value that is neither a BigDecimal nor a Float
+      # @return [::BigDecimal]
+      # @raise [ArgumentError] when its string form is not a number; the
+      #   message names the class, never the value (Kernel's echoes it)
+      def parse(value)
+        ::Kernel.BigDecimal(value.to_s)
+      rescue ::ArgumentError
+        raise ArgumentError, "BigDecimal fields could not read a #{value.class} as a number", cause: nil
+      end
+    end
+  end
+end

data/lib/field_struct/types/binary.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module FieldStruct
+  module Types
+    # Binary type — coerces input to a String and forces +ASCII-8BIT+
+    # encoding. Intended for raw bytes (file contents, BLOBs, etc.)
+    # where whitespace bytes (+\x20+, +\n+, etc.) are meaningful data,
+    # not "missing" content.
+    #
+    # +missing?+ is therefore +nil+-or-empty only — unlike
+    # {Types::String} which treats whitespace-only as missing.
+    class Binary < FieldStruct::Types::String
+      # @param value [#to_s, nil] anything stringable; +nil+ stays +nil+
+      # @return [::String, nil] +nil+ when input is +nil+, otherwise a
+      #   fresh ASCII-8BIT-encoded copy of +value.to_s+
+      def coerce(value, **)
+        result = super
+        return nil if result.nil?
+
+        result.dup.force_encoding(::Encoding::ASCII_8BIT)
+      end
+
+      # Missing if nil or empty. Whitespace bytes are meaningful in
+      # binary data, so they don't count as missing.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def missing?(value)
+        return true if value.nil?
+        return true if value.respond_to?(:empty?) && value.empty?
+
+        false
+      end
+    end
+  end
+end

data/lib/field_struct/types/boolean.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Boolean type. Accepts the literal +true+/+false+, the strings
+    # "true"/"false" (case-insensitive), and the integers/strings 1/0.
+    # Anything else raises +ArgumentError+.
+    #
+    # Per-field +values:+ option customizes the truthy/falsy vocabulary:
+    #
+    #   required :active, :boolean, values: {truthy: %w[on yes y],
+    #                                        falsy:  %w[off no n]}
+    #   required :flag,   :boolean, values: :english_yes_no
+    #
+    # Hash form takes +:truthy+ and +:falsy+ Arrays of strings (matched
+    # case-insensitively). Symbol form names a built-in preset; see
+    # {.presets} for the available names.
+    #
+    # Ruby has no Boolean class, so {#ruby_type} returns the pair
+    # +[TrueClass, FalseClass]+.
+    class Boolean < Base
+      # Native options: a +values:+ Hash with +:truthy+ / +:falsy+ keys, or a
+      # Symbol naming one of {.presets}.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {values: option(type: [::Hash, ::Symbol], presets: presets.keys)}
+      end
+
+      # @return [Array<::String>] case-insensitive strings that coerce to true
+      def self.default_truthy
+        %w[true 1]
+      end
+
+      # @return [Array<::String>] case-insensitive strings that coerce to false
+      def self.default_falsy
+        %w[false 0]
+      end
+
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => ::Array<::String>}}] named presets for the +values:+ option
+      def self.presets
+        {
+          english_yes_no: {truthy: %w[true yes y on 1], falsy: %w[false no n off 0]},
+          english: {truthy: %w[true yes y on 1], falsy: %w[false no n off 0]},
+          numeric: {truthy: %w[1], falsy: %w[0]}
+        }
+      end
+
+      # Resolve a Symbol +values:+ to its preset Hash at field-declaration
+      # time. Pass-through for Hash form; raises for unknown preset names.
+      def self.resolve_options(options)
+        return options unless options.key?(:values)
+
+        resolved = options.dup
+        if resolved[:values].is_a?(::Symbol)
+          preset = presets.fetch(resolved[:values]) do
+            raise ArgumentError,
+              "unknown :boolean values preset #{resolved[:values].inspect}. " \
+              "Available: #{presets.keys.inspect}"
+          end
+          resolved[:values] = preset
+        end
+        unless resolved[:values].is_a?(::Hash)
+          raise ArgumentError, 'boolean values: must be a Hash {truthy:, falsy:} or a preset Symbol'
+        end
+
+        resolved
+      end
+
+      # @param value [Boolean, ::Integer, ::String, nil] accepts literal
+      #   +true+/+false+; the integers +1+/+0+; or a String matched
+      #   case-insensitively against the truthy/falsy vocabularies.
+      #   Anything else raises ArgumentError.
+      # @param values [Hash{::Symbol=>Array<::String>}, nil] +{truthy: [...], falsy: [...]}+
+      #   custom vocabulary; +nil+ uses {.default_truthy} / {.default_falsy}
+      # @return [Boolean, nil]
+      # @raise [ArgumentError] when the value can't be mapped to true/false
+      def coerce(value, values: nil, **)
+        return nil if value.nil?
+        return value if value == true || value == false # rubocop:disable Style/MultipleComparison
+        return true if value == 1
+        return false if value == 0
+
+        truthy, falsy = truthy_and_falsy_for(values)
+        if value.is_a?(::String)
+          downcased = value.downcase
+          return true if truthy.include?(downcased)
+          return false if falsy.include?(downcased)
+        end
+
+        raise ArgumentError, refusal_message(value, truthy + falsy)
+      end
+
+      # @return [Array(Class, Class)] +[TrueClass, FalseClass]+
+      def ruby_type
+        [TrueClass, FalseClass]
+      end
+
+      private
+
+      # The accepted vocabulary is declared schema, so it is listed; the
+      # refused value is named by class only — it may be payments data.
+      #
+      # @param value [Object] the refused input
+      # @param accepted [Array<::String>] the truthy then falsy strings
+      # @return [::String]
+      def refusal_message(value, accepted)
+        got = value.is_a?(::String) ? 'a String that is not one' : value.class.to_s
+        "Boolean fields expect true, false, 1, 0 or one of the strings #{accepted.map(&:inspect).join(", ")}, got #{got}"
+      end
+
+      # @param values [::Hash{::Symbol=>::Array<::String>}, nil] the field's +values:+
+      # @return [Array(::Array<::String>, ::Array<::String>)] +[truthy, falsy]+, downcased
+      def truthy_and_falsy_for(values)
+        return [self.class.default_truthy, self.class.default_falsy] unless values
+
+        [
+          Array(values[:truthy]).map { |s| s.to_s.downcase },
+          Array(values[:falsy]).map { |s| s.to_s.downcase }
+        ]
+      end
+    end
+  end
+end

data/lib/field_struct/types/date.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Date type. Returns a +Date+ as-is, narrows a +DateTime+ or +Time+ down
+    # to a plain Date, reads a String via +Date.parse+ (or +strptime+ when the
+    # field declares a +format:+), and refuses everything else.
+    #
+    # Per-field +format:+ option (String or Symbol-preset) controls both
+    # parsing (strptime when input is a String) and serialization
+    # (strftime when emitting via +as_json+ / +to_json+). When no format
+    # is set, the type uses +Date.parse+ for input and ISO-8601 for output.
+    class Date < Base
+      # Native options: a +format:+ strftime/strptime String (or Symbol
+      # preset; see {.presets}) and an +in:+ Array or Range of allowed values.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          format: option(type: [::String, ::Symbol], presets: presets.keys),
+          in: option(type: [::Array, ::Range])
+        }
+      end
+
+      # @return [::String, nil] field-level strftime/strptime format; +nil+
+      #   leaves the type using ISO-8601 in/out
+      def self.default_format
+        nil
+      end
+
+      # Named presets for the +format:+ option.
+      #
+      # +:iso8601+ is an {Rfc3339Format} rather than a strftime String: the
+      # contract cannot be written as one (see that class). The display presets
+      # stay strftime-based — they are for humans, not wire formats.
+      #
+      # @return [Hash{::Symbol=>Object}]
+      def self.presets
+        {
+          iso8601: Rfc3339Format.date,
+          us: '%m/%d/%Y',
+          eu: '%d/%m/%Y'
+        }
+      end
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its strftime
+      # string at field-declaration time; other forms pass through.
+      def self.resolve_options(options)
+        TimeFormatResolver.call(options, presets)
+      end
+
+      # Resolve a declared +format:+ (a Symbol preset name or a strftime
+      # String) into the String that {#coerce} and JSON rendering actually
+      # use. Declarations are stored exactly as written, so this is where a
+      # preset name becomes usable. See {TimeFormatResolver}.
+      #
+      # @param format [::String, ::Symbol, nil] the format as declared
+      # @return [::String, nil] +nil+ when the field declares no format
+      # @raise [ArgumentError] when a Symbol names no preset in {.presets}
+      def self.resolve_format(format)
+        # Skip building the presets Hash for the common, undeclared case.
+        return format if format.nil? || format.is_a?(::String)
+
+        TimeFormatResolver.resolve(format, presets)
+      end
+
+      # Dispatch is on explicit stdlib classes, never on a +respond_to?+ probe
+      # against the value. ActiveSupport defines +String#to_date+, so a probe
+      # that is false on plain Ruby is TRUE under Rails, and the type would take
+      # a different branch there than it does in its own suite — which is
+      # exactly how a declared +format:+ came to be ignored under Rails while
+      # every spec here passed. +Date.parse+ and +Date.strptime+ are not
+      # redefined by ActiveSupport, so dispatching on them gives one behaviour
+      # in both worlds.
+      #
+      # @param value [::String, ::Date, ::DateTime, ::Time, nil] +nil+ → +nil+;
+      #   a String is read through +strptime+ when a +format:+ is set and
+      #   +Date.parse+ otherwise; a +Date+ passes through; a +DateTime+ or
+      #   +Time+ (including ActiveSupport's TimeWithZone) is narrowed to a
+      #   plain +Date+. Anything else is refused.
+      # @param format [::String, nil] strptime/strftime format; +nil+ uses
+      #   {.default_format} (which itself defaults to +nil+ = ISO-8601 path)
+      # @return [::Date, nil]
+      # @raise [ArgumentError] when a String cannot be parsed, or the value is
+      #   not a String or a temporal object
+      def coerce(value, format: self.class.default_format, **)
+        return nil if value.nil?
+
+        fmt = self.class.resolve_format(format)
+
+        case value
+        when ::String then parse_string(value, fmt)
+        # ::DateTime is a ::Date, so this arm narrows both. A plain Date is
+        # returned untouched; a DateTime is rebuilt as one.
+        when ::Date then value.instance_of?(::Date) ? value : ::Date.new(value.year, value.mon, value.mday)
+        # ActiveSupport::TimeWithZone lands here: AS overrides Time.=== so it
+        # matches, even though it is not an instance of ::Time.
+        when ::Time then ::Date.new(value.year, value.mon, value.mday)
+        else
+          # The class, never the value. FieldStruct wraps this as "could not be
+          # coerced: <message>" and that string reaches API responses and audit
+          # rows, so a value echoed here is a value published.
+          raise ArgumentError, "expected a String, Date, DateTime or Time, got #{value.class}"
+        end
+      end
+
+      # @return [Class] the top-level +::Date+ class
+      def ruby_type
+        ::Date
+      end
+
+      private
+
+      # @param value [::String] the raw string
+      # @param format [::String, nil] strptime format, when the field declares one
+      # @return [::Date]
+      # @raise [ArgumentError] when the string cannot be read
+      def parse_string(value, format)
+        # Validated first, then handed to the stdlib parser: the checks decide
+        # what is ACCEPTABLE, the stdlib still decides what the value IS, so
+        # the two can't drift apart. See {TemporalParser} for the three rules.
+        if format.is_a?(Rfc3339Format)
+          parts = format.parse(value)
+          return ::Date.new(parts[:year], parts[:mon], parts[:mday])
+        end
+
+        # The validation step has already parsed the string once; build the
+        # Date from those parts rather than having the stdlib parse it again.
+        if format
+          parts = TemporalParser.strptime_parts(value, format)
+          return date_from_parts(parts) || ::Date.strptime(value, format)
+        end
+
+        date_from_parts(TemporalParser.parse_parts(value)) || ::Date.parse(value)
+      end
+
+      # +Date.parse+ and +Date.strptime+ build the Date straight from year,
+      # month and day whenever the parts carry all three and neither a Julian
+      # day (+:jd+) nor a day of the year (+:yday+) — date_core.c's fast path
+      # in +d_new_by_frags+ — so this returns the same Date. Any other shape is
+      # left to the stdlib (+nil+).
+      #
+      # @param parts [::Hash{::Symbol=>Object}] already checked by {TemporalParser}
+      # @return [::Date, nil]
+      def date_from_parts(parts)
+        return nil if parts.key?(:jd) || parts.key?(:yday)
+
+        year, month, day = parts.values_at(:year, :mon, :mday)
+        return nil if year.nil? || month.nil? || day.nil?
+
+        ::Date.new(year, month, day)
+      end
+    end
+  end
+end

data/lib/field_struct/types/datetime.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # DateTime type. Returns a +DateTime+ as-is, builds one from a +Date+ or
+    # +Time+'s components, reads a String via +DateTime.parse+ (or +strptime+
+    # when the field declares a +format:+), and refuses everything else.
+    #
+    # Per-field +format:+ option (String or Symbol-preset) controls both
+    # parsing (strptime when input is a String) and serialization
+    # (strftime via +as_json+).
+    class DateTime < Base
+      # Native options: a +format:+ strftime/strptime String (or Symbol
+      # preset; see {.presets}), an +in:+ Array or Range of allowed values,
+      # and a +zone:+ String (+"UTC"+, +"±HH:MM"+ or an IANA name; see {ZoneOption}).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          format: option(type: [::String, ::Symbol], presets: presets.keys),
+          in: option(type: [::Array, ::Range]),
+          zone: option(type: [::String])
+        }
+      end
+
+      # @return [::String, nil] field-level strftime/strptime format; +nil+
+      #   leaves the type using ISO-8601 in/out
+      def self.default_format
+        nil
+      end
+
+      # Named presets for the +format:+ option.
+      #
+      # +:iso8601+ is an {Rfc3339Format} rather than a strftime String: +%z+
+      # renders +\+0000+, which RFC 3339 rejects, and no strftime string can
+      # express optional fractional seconds. The interchange and display
+      # presets stay strftime-based.
+      #
+      # @return [Hash{::Symbol=>Object}]
+      def self.presets
+        {
+          iso8601: Rfc3339Format.timestamp,
+          rfc2822: '%a, %d %b %Y %H:%M:%S %z',
+          db: '%Y-%m-%d %H:%M:%S'
+        }
+      end
+
+      # Validate a Symbol +format:+ preset (see {.presets}) and a +zone:+
+      # (see {ZoneOption}) at field-declaration time.
+      #
+      # @param options [::Hash{::Symbol => Object, nil}] the per-field options
+      # @return [::Hash{::Symbol => Object, nil}] the options, unchanged
+      # @raise [ArgumentError] on an unknown preset or an unreadable +zone:+
+      def self.resolve_options(options)
+        ZoneOption.validate!('DateTime', TimeFormatResolver.call(options, presets))
+      end
+
+      # Resolve a declared +format:+ (a Symbol preset name or a strftime
+      # String) into the String that {#coerce} and JSON rendering actually
+      # use. Declarations are stored exactly as written, so this is where a
+      # preset name becomes usable. See {TimeFormatResolver}.
+      #
+      # @param format [::String, ::Symbol, nil] the format as declared
+      # @return [::String, nil] +nil+ when the field declares no format
+      # @raise [ArgumentError] when a Symbol names no preset in {.presets}
+      def self.resolve_format(format)
+        # Skip building the presets Hash for the common, undeclared case.
+        return format if format.nil? || format.is_a?(::String)
+
+        TimeFormatResolver.resolve(format, presets)
+      end
+
+      # Dispatch is on explicit stdlib classes, never on a +respond_to?+ probe
+      # against the value: ActiveSupport defines +String#to_datetime+, so a
+      # probe that is false on plain Ruby is TRUE under Rails.
+      # +DateTime.parse+ and +DateTime.strptime+ are not redefined by
+      # ActiveSupport. See {Types::Time#coerce} for why cross-class conversion
+      # is built from components rather than +to_datetime+.
+      #
+      # @param value [::String, ::DateTime, ::Date, ::Time, nil] +nil+ → +nil+;
+      #   a String is read through +strptime+ when a +format:+ is set and
+      #   +DateTime.parse+ otherwise; a +DateTime+ passes through; a +Date+
+      #   becomes midnight and a +Time+ (including ActiveSupport's
+      #   TimeWithZone) keeps its instant and offset. Anything else is refused.
+      # @param format [::String, nil] strptime/strftime format; +nil+ uses
+      #   {.default_format} (which itself defaults to +nil+ = ISO-8601 path)
+      # @param zone [::String, nil] +"UTC"+, +"±HH:MM"+ or an IANA name: the offset for a
+      #   String that names none, and for a +Date+'s midnight. Input carrying
+      #   its own offset keeps it. +nil+ means UTC. See {ZoneOption}.
+      # @return [::DateTime, nil]
+      # @raise [ArgumentError] when a String cannot be parsed, or the value is
+      #   not a String or a temporal object
+      def coerce(value, format: self.class.default_format, zone: nil, **)
+        return nil if value.nil?
+
+        fmt = self.class.resolve_format(format)
+
+        case value
+        when ::String then parse_string(value, fmt, zone)
+        # ::DateTime before ::Date — DateTime is a subclass of Date.
+        when ::DateTime then value
+        when ::Date
+          return datetime_from_time(ZoneOption.midnight(value, zone)) if zone
+
+          ::DateTime.new(value.year, value.mon, value.mday)
+        # ActiveSupport::TimeWithZone matches here too (AS overrides Time.===)
+        # and answers every reader this uses.
+        when ::Time then datetime_from_time(value)
+        else
+          # The class, never the value — see Types::Date#coerce.
+          raise ArgumentError, "expected a String, Date, DateTime or Time, got #{value.class}"
+        end
+      end
+
+      # @return [Class] the top-level +::DateTime+ class
+      def ruby_type
+        ::DateTime
+      end
+
+      private
+
+      # @param value [::String] the raw string
+      # @param format [::String, nil] strptime format, when the field declares one
+      # @param zone [::String, nil] the field's +zone:+, if declared
+      # @return [::DateTime]
+      # @raise [ArgumentError] when the string cannot be read
+      def parse_string(value, format, zone)
+        # Validated first, then handed to the stdlib parser: the checks decide
+        # what is ACCEPTABLE, the stdlib still decides what the value IS, so
+        # the two can't drift apart. See {TemporalParser} for the three rules.
+        if format.is_a?(Rfc3339Format)
+          parts = format.parse(value)
+          return ::DateTime.new(parts[:year], parts[:mon], parts[:mday], parts[:hour], parts[:min],
+            parts[:sec] + parts[:sec_fraction], ::Kernel.Rational(parts[:offset], 86_400))
+        end
+
+        if format
+          parts = TemporalParser.strptime_parts(value, format)
+          return datetime_from_time(ZoneOption.time_at(value, format, zone, parts)) if zone && ZoneOption.zoneless?(parts)
+
+          return ::DateTime.strptime(value, format)
+        end
+
+        parts = TemporalParser.parse_parts(value)
+        return datetime_from_time(ZoneOption.time_at(value, nil, zone, parts)) if zone && ZoneOption.zoneless?(parts)
+
+        ::DateTime.parse(value)
+      end
+
+      # @param value [::Time] the value to convert
+      # @return [::DateTime] the same instant, at the same offset, sub-second
+      #   precision preserved
+      def datetime_from_time(value)
+        ::DateTime.new(value.year, value.mon, value.mday, value.hour, value.min,
+          value.sec + ::Kernel.Rational(value.nsec, 1_000_000_000),
+          ::Kernel.Rational(value.utc_offset, 86_400))
+      end
+    end
+  end
+end

data/lib/field_struct/types/email.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module FieldStruct
+  module Types
+    # Email type — a {Types::String} that pre-fills the field's +format:+
+    # option with a pragmatic email pattern. Same shape as
+    # {Types::UUID} / {Types::URL}: bad-format input is a validation
+    # error, not a coercion failure.
+    #
+    # The default pattern is deliberately not RFC 5322 strict — those
+    # regexes are unwieldy and reject real-world addresses. It checks
+    # +local@domain.tld+ shape with no internal whitespace or extra +@+
+    # characters; users can override via +format: /.../+ for stricter
+    # rules.
+    class Email < FieldStruct::Types::String
+      # Inherits +format:+ / +enum:+ from {Types::String}, advertising the
+      # +:format+ presets this subtype resolves (see {.presets}).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {format: option(type: [::Regexp, ::Symbol], presets: presets.keys)}
+      end
+
+      # @return [Regexp] pragmatic +local@domain.tld+ shape, no internal
+      #   whitespace or extra +@+; deliberately not RFC 5322 strict.
+      #   Override per-field via +format:+ (Regexp or Symbol preset).
+      def self.default_format
+        /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
+      end
+
+      # @return [Hash{::Symbol=>Regexp}] named presets for +format:+
+      def self.presets
+        {
+          permissive: /\A[^@\s]+@[^@\s]+\z/,
+          default: default_format,
+          strict: /\A[\w.+-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+\z/
+        }
+      end
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its Regexp at
+      # field-declaration time; a user-supplied Regexp passes through.
+      def self.resolve_options(options)
+        PresetResolver.call(options, :format, presets, label: ':email format')
+      end
+    end
+  end
+end