net-imap 0.5.9 → 0.6.4

data/lib/net/imap/config.rb

@@ -3,6 +3,7 @@
 require_relative "config/attr_accessors"
 require_relative "config/attr_inheritance"
 require_relative "config/attr_type_coercion"
+require_relative "config/attr_version_defaults"
 
 module Net
   class IMAP
@@ -141,15 +142,7 @@ module Net
       #     Net::IMAP::Config[0.5]       == Net::IMAP::Config[0.5r]     # => true
       #     Net::IMAP::Config["current"] == Net::IMAP::Config[:current] # => true
       #     Net::IMAP::Config["0.5.6"]   == Net::IMAP::Config[0.5r]     # => true
-      def self.version_defaults; @version_defaults end
-      @version_defaults = Hash.new {|h, k|
-        # NOTE: String responds to both so the order is significant.
-        # And ignore non-numeric conversion to zero, because: "wat!?".to_r == 0
-        (h.fetch(k.to_r, nil) || h.fetch(k.to_f, nil) if k.is_a?(Numeric)) ||
-          (h.fetch(k.to_sym, nil) if k.respond_to?(:to_sym)) ||
-          (h.fetch(k.to_r,   nil) if k.respond_to?(:to_r) && k.to_r != 0r) ||
-          (h.fetch(k.to_f,   nil) if k.respond_to?(:to_f) && k.to_f != 0.0)
-      }
+      def self.version_defaults; AttrVersionDefaults.version_defaults end
 
       # :call-seq:
       #  Net::IMAP::Config[number] -> versioned config
@@ -189,6 +182,7 @@ module Net
       include AttrAccessors
       include AttrInheritance
       include AttrTypeCoercion
+      extend  AttrVersionDefaults
 
       # The debug mode (boolean).  The default value is +false+.
       #
@@ -200,7 +194,7 @@ module Net
       #
       # *NOTE:* Versioned default configs inherit #debug from Config.global, and
       # #load_defaults will not override #debug.
-      attr_accessor :debug, type: :boolean
+      attr_accessor :debug, type: :boolean, default: false
 
       # method: debug?
       # :call-seq: debug? -> boolean
@@ -218,7 +212,7 @@ module Net
       # See Net::IMAP.new and Net::IMAP#starttls.
       #
       # The default value is +30+ seconds.
-      attr_accessor :open_timeout, type: Integer
+      attr_accessor :open_timeout, type: Integer, default: 30
 
       # Seconds to wait until an IDLE response is received, after
       # the client asks to leave the IDLE state.
@@ -226,7 +220,7 @@ module Net
       # See Net::IMAP#idle and Net::IMAP#idle_done.
       #
       # The default value is +5+ seconds.
-      attr_accessor :idle_response_timeout, type: Integer
+      attr_accessor :idle_response_timeout, type: Integer, default: 5
 
       # Whether to use the +SASL-IR+ extension when the server and \SASL
       # mechanism both support it.  Can be overridden by the +sasl_ir+ keyword
@@ -240,9 +234,25 @@ module Net
       #   Do not use +SASL-IR+, even when it is supported by the server and the
       #   mechanism.
       #
+      # [+:when_capabilities_cached+]
+      #   Use +SASL-IR+ when Net::IMAP#capabilities_cached? is +true+ and it is
+      #   supported by the server and the mechanism, but do not send a
+      #   +CAPABILITY+ command to discover the server capabilities.
+      #
+      #   <em>(+:when_capabilities_cached+ option was added by +v0.6.0+)</em>
+      #
       # [+true+ <em>(default since +v0.4+)</em>]
       #   Use +SASL-IR+ when it is supported by the server and the mechanism.
-      attr_accessor :sasl_ir, type: :boolean
+      attr_accessor :sasl_ir, type: Enum[
+        false, :when_capabilities_cached, true
+      ], defaults: {
+        0.0r => false,
+        0.4r => true,
+      }
+
+      # :stopdoc:
+      alias sasl_ir? sasl_ir
+      # :startdoc:
 
       # Controls the behavior of Net::IMAP#login when the +LOGINDISABLED+
       # capability is present.  When enforced, Net::IMAP will raise a
@@ -266,7 +276,44 @@ module Net
       #
       attr_accessor :enforce_logindisabled, type: Enum[
         false, :when_capabilities_cached, true
-      ]
+      ], defaults: {
+        0.0r => false,
+        0.5r => true,
+      }
+
+      # The maximum bytesize for sending non-synchronizing literals, when the
+      # server supports them.  To disable non-synchronizing literals, set the
+      # value to +-1+.
+      #
+      # Non-synchronizing literals are only sent when the server's
+      # capabilities[rdoc-ref:IMAP#capabilities] have been
+      # cached[rdoc-ref:IMAP#capabilities_cached?] and include either
+      # <tt>LITERAL+</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]],
+      # <tt>LITERAL-</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]], or
+      # +IMAP4rev2+ [RFC9051[https://www.rfc-editor.org/rfc/rfc9051]].
+      #
+      # For <tt>LITERAL+</tt>, this value is the only limit on whether a literal
+      # value is sent as non-synchronizing literals.  For <tt>LITERAL-</tt> and
+      # <tt>IMAP4rev2</tt>, non-synchronizing literals must also be smaller than
+      # +4096+ bytes.
+      #
+      # Non-synchronizing literals avoid the latency of waiting for the server
+      # to allow continuation.  However, if a client sends a non-synchronizing
+      # literal that is too large for the server, the server may need to close
+      # the connection.  Because <tt>LITERAL+</tt> does not directly indicate
+      # the server's limits, it's best to avoid sending very large
+      # non-synchronized literals.
+      #
+      # ==== Versioned Defaults
+      #
+      # max_non_synchronizing_literal <em>was added in +v0.6.4+.</em>
+      #
+      # * original: +-1+ (_never_ send non-synchronizing literals)
+      # * +0.6+: 16 KiB
+      attr_accessor :max_non_synchronizing_literal, type: Integer?, defaults: {
+        0.0r => -1,
+        0.6r => 16 << 16, # 16 KiB
+      }
 
       # The maximum allowed server response size.  When +nil+, there is no limit
       # on response size.
@@ -300,7 +347,10 @@ module Net
       #
       # * original: +nil+ <em>(no limit)</em>
       # * +0.5+: 512 MiB
-      attr_accessor :max_response_size, type: Integer?
+      attr_accessor :max_response_size, type: Integer?, defaults: {
+        0.0r => nil,
+        0.5r => 512 << 20, # 512 MiB
+      }
 
       # Controls the behavior of Net::IMAP#responses when called without any
       # arguments (+type+ or +block+).
@@ -330,7 +380,11 @@ module Net
       # Note: #responses_without_args is an alias for #responses_without_block.
       attr_accessor :responses_without_block, type: Enum[
         :silence_deprecation_warning, :warn, :frozen_dup, :raise,
-      ]
+      ], defaults: {
+        0.0r => :silence_deprecation_warning,
+        0.5r => :warn,
+        0.6r => :frozen_dup,
+      }
 
       alias responses_without_args  responses_without_block  # :nodoc:
       alias responses_without_args= responses_without_block= # :nodoc:
@@ -340,66 +394,69 @@ module Net
       #
       # Alias for responses_without_block
 
-      # Whether ResponseParser should use the deprecated UIDPlusData or
-      # CopyUIDData for +COPYUID+ response codes, and UIDPlusData or
-      # AppendUIDData for +APPENDUID+ response codes.
+      # **NOTE:** <em>+UIDPlusData+ has been removed since +v0.6.0+, and this
+      # config option only affects deprecation warnings.
+      # This config option will be **removed** in +v0.7.0+.</em>
       #
-      # UIDPlusData stores its data in arrays of numbers, which is vulnerable to
-      # a memory exhaustion denial of service attack from an untrusted or
-      # compromised server.  Set this option to +false+ to completely block this
-      # vulnerability.  Otherwise, parser_max_deprecated_uidplus_data_size
-      # mitigates this vulnerability.
+      # ResponseParser always returns CopyUIDData for +COPYUID+ response codes,
+      # and AppendUIDData for +APPENDUID+ response codes.  Previously, this
+      # option determined when UIDPlusData would be returned instead.
       #
-      # AppendUIDData and CopyUIDData are _mostly_ backward-compatible with
-      # UIDPlusData.  Most applications should be able to upgrade with little
-      # or no changes.
+      # Parser support for +UIDPLUS+ added in +v0.3.2+.
       #
-      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      # Config option added in +v0.4.19+ and +v0.5.6+.
       #
-      # <em>(Config option added in +v0.4.19+ and +v0.5.6+.)</em>
+      # <em>UIDPlusData removed in +v0.6.0+.</em>
       #
-      # <em>UIDPlusData will be removed in +v0.6+ and this config setting will
-      # be ignored.</em>
-      #
-      # ==== Valid options
+      # ==== Options
       #
       # [+true+ <em>(original default)</em>]
-      #    ResponseParser only uses UIDPlusData.
+      #    <em>Since v0.6.0:</em>
+      #    Prints a deprecation warning when parsing +COPYUID+ or +APPENDUID+.
       #
       # [+:up_to_max_size+ <em>(default since +v0.5.6+)</em>]
-      #    ResponseParser uses UIDPlusData when the +uid-set+ size is below
-      #    parser_max_deprecated_uidplus_data_size.  Above that size,
-      #    ResponseParser uses AppendUIDData or CopyUIDData.
+      #    <em>Since v0.6.0:</em>
+      #    Prints a deprecation warning when parsing +COPYUID+ or +APPENDUID+.
       #
-      # [+false+ <em>(planned default for +v0.6+)</em>]
-      #    ResponseParser _only_ uses AppendUIDData and CopyUIDData.
+      # [+false+ <em>(default since +v0.6.0+)</em>]
+      #    This is the only supported option <em>(since v0.6.0)</em>.
       attr_accessor :parser_use_deprecated_uidplus_data, type: Enum[
         true, :up_to_max_size, false
-      ]
+      ], defaults: {
+        0.0r => true,
+        0.5r => :up_to_max_size,
+        0.6r => false,
+      }
 
-      # The maximum +uid-set+ size that ResponseParser will parse into
-      # deprecated UIDPlusData.  This limit only applies when
-      # parser_use_deprecated_uidplus_data is not +false+.
+      # **NOTE:** <em>+UIDPlusData+ has been removed since +v0.6.0+, and this
+      # config option is ignored.
+      # This config option will be **removed** in +v0.7.0+.</em>
       #
-      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      # ResponseParser always returns CopyUIDData for +COPYUID+ response codes,
+      # and AppendUIDData for +APPENDUID+ response codes.  Previously, this
+      # option determined when UIDPlusData would be returned instead.
       #
-      # <em>Support for limiting UIDPlusData to a maximum size was added in
-      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.</em>
+      # Parser support for +UIDPLUS+ added in +v0.3.2+.
       #
-      # <em>UIDPlusData will be removed in +v0.6+.</em>
+      # Support for limiting UIDPlusData to a maximum size was added in
+      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.
       #
-      # ==== Versioned Defaults
+      # <em>UIDPlusData was removed in +v0.6.0+.</em>
       #
-      # Because this limit guards against a remote server causing catastrophic
-      # memory exhaustion, the versioned default (used by #load_defaults) also
-      # applies to versions without the feature.
+      # ==== Versioned Defaults
       #
       # * +0.3+ and prior: <tt>10,000</tt>
       # * +0.4+: <tt>1,000</tt>
       # * +0.5+: <tt>100</tt>
       # * +0.6+: <tt>0</tt>
       #
-      attr_accessor :parser_max_deprecated_uidplus_data_size, type: Integer
+      attr_accessor :parser_max_deprecated_uidplus_data_size, type: Integer,
+        defaults: {
+          0.0r => 10_000,
+          0.4r =>  1_000,
+          0.5r =>    100,
+          0.6r =>      0,
+        }
 
       # Creates a new config object and initialize its attribute with +attrs+.
       #
@@ -468,85 +525,150 @@ module Net
       # Returns all config attributes in a hash.
       def to_h; data.members.to_h { [_1, send(_1)] } end
 
+      # Returns a string representation of overriden config attributes and the
+      # inheritance chain.
+      #
+      # Attributes overridden by ancestors are also inspected, recursively.
+      # Attributes that are inherited from default configs are not shown (see
+      # Config@Versioned+defaults and Config@Named+defaults).
+      #
+      #     # (Line breaks have been added to the example output for legibility.)
+      #
+      #     Net::IMAP::Config.new(0.4)
+      #       .new(open_timeout: 10, enforce_logindisabled: true)
+      #       .inspect
+      #     #=> "#<Net::IMAP::Config:0x0000745871125410 open_timeout=10 enforce_logindisabled=true
+      #     #      inherits from Net::IMAP::Config[0.4]
+      #     #      inherits from Net::IMAP::Config.global
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      # Non-default attributes are listed after the ancestor config from which
+      # they are inherited.
+      #
+      #     # (Line breaks have been added to the example output for legibility.)
+      #
+      #     config = Net::IMAP::Config.global
+      #       .new(open_timeout: 10, idle_response_timeout: 2)
+      #       .new(enforce_logindisabled: :when_capabilities_cached, sasl_ir: false)
+      #     config.inspect
+      #     #=> "#<Net::IMAP::Config:0x00007ce2a1e20e40 sasl_ir=false enforce_logindisabled=:when_capabilities_cached
+      #     #      inherits from Net::IMAP::Config:0x00007ce2a1e20f80 open_timeout=10 idle_response_timeout=2
+      #     #      inherits from Net::IMAP::Config.global
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      #     Net::IMAP.debug = true
+      #     config.inspect
+      #     #=> "#<Net::IMAP::Config:0x00007ce2a1e20e40 sasl_ir=false enforce_logindisabled=:when_capabilities_cached
+      #     #      inherits from Net::IMAP::Config:0x00007ce2a1e20f80 open_timeout=10 idle_response_timeout=2
+      #     #      inherits from Net::IMAP::Config.global debug=true
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      # Use +pp+ (see #pretty_print) to inspect _all_ config attributes,
+      # including default values.
+      #
+      # Use #to_h to inspect all config attributes ignoring inheritance.
+      def inspect;
+        "#<#{inspect_recursive}>"
+      end
+      alias to_s inspect
+
+      # Used by PP[https://docs.ruby-lang.org/en/master/PP.html] to create a
+      # string representation of all config attributes and the inheritance
+      # chain.  Inherited attributes are listed with the ancestor config from
+      # which they are inherited.
+      #
+      #     pp Config.new[0.4].new(open_timeout: 10, idle_response_timeout: 10)
+      #     # #<Net::IMAP::Config:0x0000745871125410
+      #     #   open_timeout=10
+      #     #   idle_response_timeout=10
+      #     #   inherits from Net::IMAP::Config[0.4]
+      #     #     responses_without_block=:silence_deprecation_warning
+      #     #     max_response_size=nil
+      #     #     sasl_ir=true
+      #     #     enforce_logindisabled=false
+      #     #     parser_use_deprecated_uidplus_data=true
+      #     #     parser_max_deprecated_uidplus_data_size=1000
+      #     #     inherits from Net::IMAP::Config.global
+      #     #       inherits from Net::IMAP::Config.default
+      #     #         debug=false>
+      #
+      # Related: #inspect, #to_h.
+      def pretty_print(pp)
+        pp.group(2, "#<", ">") do
+          pretty_print_recursive(pp)
+        end
+      end
+
+      # :stopdoc:
+
       protected
 
-      def defaults_hash
-        to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
+      def named_default?
+        equal?(Config.default) ||
+          AttrVersionDefaults::VERSIONS.any? { equal? Config[_1] }
       end
 
-      @default = new(
-        debug: false,
-        open_timeout: 30,
-        idle_response_timeout: 5,
-        sasl_ir: true,
-        enforce_logindisabled: true,
-        max_response_size: 512 << 20, # 512 MiB
-        responses_without_block: :warn,
-        parser_use_deprecated_uidplus_data: :up_to_max_size,
-        parser_max_deprecated_uidplus_data_size: 100,
-      ).freeze
-
-      @global = default.new
-
-      version_defaults[:default] = Config[default.send(:defaults_hash)]
-
-      version_defaults[0r] = Config[:default].dup.update(
-        sasl_ir: false,
-        responses_without_block: :silence_deprecation_warning,
-        enforce_logindisabled: false,
-        max_response_size: nil,
-        parser_use_deprecated_uidplus_data: true,
-        parser_max_deprecated_uidplus_data_size: 10_000,
-      ).freeze
-      version_defaults[0.0r] = Config[0r]
-      version_defaults[0.1r] = Config[0r]
-      version_defaults[0.2r] = Config[0r]
-      version_defaults[0.3r] = Config[0r]
-
-      version_defaults[0.4r] = Config[0.3r].dup.update(
-        sasl_ir: true,
-        parser_max_deprecated_uidplus_data_size: 1000,
-      ).freeze
-
-      version_defaults[0.5r] = Config[0.4r].dup.update(
-        enforce_logindisabled: true,
-        max_response_size: 512 << 20, # 512 MiB
-        responses_without_block: :warn,
-        parser_use_deprecated_uidplus_data: :up_to_max_size,
-        parser_max_deprecated_uidplus_data_size: 100,
-      ).freeze
-
-      version_defaults[0.6r] = Config[0.5r].dup.update(
-        responses_without_block: :frozen_dup,
-        parser_use_deprecated_uidplus_data: false,
-        parser_max_deprecated_uidplus_data_size: 0,
-      ).freeze
-
-      version_defaults[0.7r] = Config[0.6r].dup.update(
-      ).freeze
-
-      # Safe conversions one way only:
-      #   0.6r.to_f == 0.6  # => true
-      #   0.6 .to_r == 0.6r # => false
-      version_defaults.to_a.each do |k, v|
-        next unless k in Rational
-        version_defaults[k.to_f] = v
+      def name
+        if    equal? Config.default   then "#{Config}.default"
+        elsif equal? Config.global    then "#{Config}.global"
+        elsif equal? Config[0.0r]     then "#{Config}[:original]"
+        elsif (v = AttrVersionDefaults::VERSIONS.find { equal? Config[_1] })
+          "%s[%0.1f]" % [Config, v]
+        else
+          Kernel.instance_method(:to_s).bind_call(self).delete("<#>")
+        end
       end
 
-      current = VERSION.to_r
-      version_defaults[:original] = Config[0]
-      version_defaults[:current]  = Config[current]
-      version_defaults[:next]     = Config[current + 0.1r]
-      version_defaults[:future]   = Config[current + 0.2r]
+      def inspect_recursive(attrs = AttrAccessors.struct.members)
+        strings  = [name]
+        assigned = assigned_attrs_hash(attrs)
+        strings.concat assigned.map { "%s=%p" % _1 }
+        if parent
+          if parent.equal?(Config.default)
+            inherited_overrides = []
+          elsif parent
+            inherited_overrides = attrs - assigned.keys
+            inherited_overrides &= DEFAULT_TO_INHERIT if parent.named_default?
+          end
+          strings << "inherits from #{parent.inspect_recursive(inherited_overrides)}"
+        end
+        strings.join " "
+      end
 
-      version_defaults.freeze
+      def pretty_print_recursive(pp, attrs = AttrAccessors.struct.members)
+        pp.text name
+        assigned = assigned_attrs_hash(attrs)
+        pp.breakable
+        pp.seplist(assigned, ->{pp.breakable}) do |key, val|
+          pp.text key.to_s
+          pp.text "="
+          pp.pp val
+        end
+        if parent
+          pp.breakable if assigned.any?
+          pp.nest(2) do
+            pp.text "inherits from "
+            parent.pretty_print_recursive(pp, attrs - assigned.keys)
+          end
+        elsif assigned.empty?
+          pp.text "(overridden)"
+        end
+      end
 
-      if ($VERBOSE || $DEBUG) && self[:current].to_h != self[:default].to_h
-        warn "Misconfigured Net::IMAP::Config[:current] => %p,\n" \
-             " not equal to Net::IMAP::Config[:default] => %p" % [
-                self[:current].to_h, self[:default].to_h
-              ]
+      def assigned_attrs_hash(attrs)
+        own_attrs = attrs.reject { inherited?(_1) }
+        own_attrs.to_h { [_1, data[_1]] }
+      end
+
+      def defaults_hash
+        to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
       end
+
+      Struct   = AttrAccessors.struct
+      @default = AttrVersionDefaults.compile_default!
+      @global  = default.new
+      AttrVersionDefaults.compile_version_defaults!
+
     end
   end
 end

data/lib/net/imap/connection_state.rb

@@ -2,7 +2,7 @@
 
 module Net
   class IMAP
-    class ConnectionState < Net::IMAP::Data # :nodoc:
+    class ConnectionState < Data # :nodoc:
       def self.define(symbol, *attrs)
         symbol => Symbol
         state = super(*attrs)

data/lib/net/imap/data_encoding.rb

@@ -155,57 +155,156 @@ module Net
 
     # Common validators of number and nz_number types
     module NumValidator # :nodoc
+      NUMBER_RE = /\A(?:0|[1-9]\d*)\z/
       module_function
 
-      # Check is passed argument valid 'number' in RFC 3501 terminology
+      # Check if argument is a valid 'number' according to RFC 3501
+      #     number          = 1*DIGIT
+      #                        ; Unsigned 32-bit integer
+      #                        ; (0 <= n < 4,294,967,296)
       def valid_number?(num)
-        # [RFC 3501]
-        # number          = 1*DIGIT
-        #                    ; Unsigned 32-bit integer
-        #                    ; (0 <= n < 4,294,967,296)
-        num >= 0 && num < 4294967296
+        0 <= num && num <= 0xffff_ffff
       end
 
-      # Check is passed argument valid 'nz_number' in RFC 3501 terminology
+      # Check if argument is a valid 'nz-number' according to RFC 3501
+      #     nz-number       = digit-nz *DIGIT
+      #                        ; Non-zero unsigned 32-bit integer
+      #                        ; (0 < n < 4,294,967,296)
       def valid_nz_number?(num)
-        # [RFC 3501]
-        # nz-number       = digit-nz *DIGIT
-        #                    ; Non-zero unsigned 32-bit integer
-        #                    ; (0 < n < 4,294,967,296)
-        num != 0 && valid_number?(num)
+        0 < num && num <= 0xffff_ffff
       end
 
-      # Check is passed argument valid 'mod_sequence_value' in RFC 4551 terminology
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     number64        = 1*DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 <= n <= 9,223,372,036,854,775,807)
+      def valid_number64?(num)
+        0 <= num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     nz-number64     = digit-nz *DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 < n <= 9,223,372,036,854,775,807)
+      def valid_nz_number64?(num)
+        0 < num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
+      # Check if argument is a valid 'mod-sequence-value' according to RFC 4551
+      #     mod-sequence-value  = 1*DIGIT
+      #                            ; Positive unsigned 64-bit integer
+      #                            ; (mod-sequence)
+      #                            ; (1 <= n < 18,446,744,073,709,551,615)
       def valid_mod_sequence_value?(num)
-        # mod-sequence-value  = 1*DIGIT
-        #                        ; Positive unsigned 64-bit integer
-        #                        ; (mod-sequence)
-        #                        ; (1 <= n < 18,446,744,073,709,551,615)
-        num >= 1 && num < 18446744073709551615
+        1 <= num && num < 0xffff_ffff_ffff_ffff
+      end
+
+      # Check if argument is a valid 'mod-sequence-valzer' according to RFC 4551
+      #     mod-sequence-valzer = "0" / mod-sequence-value
+      def valid_mod_sequence_valzer?(num)
+        0 <= num && num < 0xffff_ffff_ffff_ffff
       end
 
       # Ensure argument is 'number' or raise DataFormatError
       def ensure_number(num)
         return num if valid_number?(num)
-
-        msg = "number must be unsigned 32-bit integer: #{num}"
-        raise DataFormatError, msg
+        raise DataFormatError,
+          "number must be unsigned 32-bit integer: #{num}"
       end
 
-      # Ensure argument is 'nz_number' or raise DataFormatError
+      # Ensure argument is 'nz-number' or raise DataFormatError
       def ensure_nz_number(num)
         return num if valid_nz_number?(num)
+        raise DataFormatError,
+          "nz-number must be non-zero unsigned 32-bit integer: #{num}"
+      end
+
+      # Ensure argument is 'number64' or raise DataFormatError
+      def ensure_number64(num)
+        return num if valid_number64?(num)
+        raise DataFormatError,
+          "number64 must be unsigned 63-bit integer: #{num}"
+      end
 
-        msg = "nz_number must be non-zero unsigned 32-bit integer: #{num}"
-        raise DataFormatError, msg
+      # Ensure argument is 'nz-number64' or raise DataFormatError
+      def ensure_nz_number64(num)
+        return num if valid_nz_number64?(num)
+        raise DataFormatError,
+          "nz-number64 must be non-zero unsigned 63-bit integer: #{num}"
       end
 
-      # Ensure argument is 'mod_sequence_value' or raise DataFormatError
+      # Ensure argument is 'mod-sequence-value' or raise DataFormatError
       def ensure_mod_sequence_value(num)
         return num if valid_mod_sequence_value?(num)
+        raise DataFormatError,
+          "mod-sequence-value must be non-zero unsigned 64-bit integer: #{num}"
+      end
 
-        msg = "mod_sequence_value must be unsigned 64-bit integer: #{num}"
-        raise DataFormatError, msg
+      # Ensure argument is 'mod-sequence-valzer' or raise DataFormatError
+      def ensure_mod_sequence_valzer(num)
+        return num if valid_mod_sequence_valzer?(num)
+        raise DataFormatError,
+          "mod-sequence-valzer must be unsigned 64-bit integer: #{num}"
+      end
+
+      # Like #ensure_number, but usable with numeric String input.
+      def coerce_number(num)
+        case num
+        when Integer   then ensure_number num
+        when NUMBER_RE then ensure_number Integer num
+        else
+          raise DataFormatError, "%p is not a valid number" % [num]
+        end
+      end
+
+      # Like #ensure_nz_number, but usable with numeric String input.
+      def coerce_nz_number(num)
+        case num
+        when Integer   then ensure_nz_number num
+        when NUMBER_RE then ensure_nz_number Integer num
+        else
+          raise DataFormatError, "%p is not a valid nz-number" % [num]
+        end
+      end
+
+      # Like #ensure_number64, but usable with numeric String input.
+      def coerce_number64(num)
+        case num
+        when Integer   then ensure_number64 num
+        when NUMBER_RE then ensure_number64 Integer num
+        else
+          raise DataFormatError, "%p is not a valid number64" % [num]
+        end
+      end
+
+      # Like #ensure_nz_number64, but usable with numeric String input.
+      def coerce_nz_number64(num)
+        case num
+        when Integer   then ensure_nz_number64 num
+        when NUMBER_RE then ensure_nz_number64 Integer num
+        else
+          raise DataFormatError, "%p is not a valid nz-number64" % [num]
+        end
+      end
+
+      # Like #ensure_mod_sequence_value, but usable with numeric String input.
+      def coerce_mod_sequence_value(num)
+        case num
+        when Integer   then ensure_mod_sequence_value num
+        when NUMBER_RE then ensure_mod_sequence_value Integer num
+        else
+          raise DataFormatError, "%p is not a valid mod-sequence-value" % [num]
+        end
+      end
+
+      # Like #ensure_mod_sequence_valzer, but usable with numeric String input.
+      def coerce_mod_sequence_valzer(num)
+        case num
+        when Integer   then ensure_mod_sequence_valzer num
+        when NUMBER_RE then ensure_mod_sequence_valzer Integer num
+        else
+          raise DataFormatError, "%p is not a valid mod-sequence-valzer" % [num]
+        end
       end
 
     end