net-imap 0.5.6 → 0.6.3

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
@@ -131,8 +132,17 @@ module Net
       def self.global; @global if defined?(@global) end
 
       # A hash of hard-coded configurations, indexed by version number or name.
-      def self.version_defaults; @version_defaults end
-      @version_defaults = {}
+      # Values can be accessed with any object that responds to +to_sym+ or
+      # +to_r+/+to_f+ with a non-zero number.
+      #
+      # Config::[] gets named or numbered versions from this hash.
+      #
+      # For example:
+      #     Net::IMAP::Config.version_defaults[0.5] == Net::IMAP::Config[0.5]
+      #     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; AttrVersionDefaults.version_defaults end
 
       # :call-seq:
       #  Net::IMAP::Config[number] -> versioned config
@@ -155,24 +165,24 @@ module Net
         elsif config.nil? && global.nil?   then nil
         elsif config.respond_to?(:to_hash) then new(global, **config).freeze
         else
-          version_defaults.fetch(config) do
+          version_defaults[config] or
             case config
             when Numeric
               raise RangeError, "unknown config version: %p" % [config]
-            when Symbol
+            when String, Symbol
               raise KeyError, "unknown config name: %p" % [config]
             else
               raise TypeError, "no implicit conversion of %s to %s" % [
                 config.class, Config
               ]
             end
-          end
         end
       end
 
       include AttrAccessors
       include AttrInheritance
       include AttrTypeCoercion
+      extend  AttrVersionDefaults
 
       # The debug mode (boolean).  The default value is +false+.
       #
@@ -184,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
@@ -193,13 +203,16 @@ module Net
 
       # Seconds to wait until a connection is opened.
       #
+      # Applied separately for establishing TCP connection and starting a TLS
+      # connection.
+      #
       # If the IMAP object cannot open a connection within this time,
       # it raises a Net::OpenTimeout exception.
       #
-      # See Net::IMAP.new.
+      # 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.
@@ -207,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
@@ -221,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
@@ -245,9 +274,49 @@ module Net
       #   present.  When capabilities are unknown, Net::IMAP will automatically
       #   send a +CAPABILITY+ command first before sending +LOGIN+.
       #
-      attr_accessor :enforce_logindisabled, type: [
+      attr_accessor :enforce_logindisabled, type: Enum[
         false, :when_capabilities_cached, true
-      ]
+      ], defaults: {
+        0.0r => false,
+        0.5r => true,
+      }
+
+      # The maximum allowed server response size.  When +nil+, there is no limit
+      # on response size.
+      #
+      # The default value (512 MiB, since +v0.5.7+) is <em>very high</em> and
+      # unlikely to be reached.  A _much_ lower value should be used with
+      # untrusted servers (for example, when connecting to a user-provided
+      # hostname).  When using a lower limit, message bodies should be fetched
+      # in chunks rather than all at once.
+      #
+      # <em>Please Note:</em> this only limits the size per response.  It does
+      # not prevent a flood of individual responses and it does not limit how
+      # many unhandled responses may be stored on the responses hash.  See
+      # Net::IMAP@Unbounded+memory+use.
+      #
+      # Socket reads are limited to the maximum remaining bytes for the current
+      # response: max_response_size minus the bytes that have already been read.
+      # When the limit is reached, or reading a +literal+ _would_ go over the
+      # limit, ResponseTooLargeError is raised and the connection is closed.
+      #
+      # Note that changes will not take effect immediately, because the receiver
+      # thread may already be waiting for the next response using the previous
+      # value.  Net::IMAP#noop can force a response and enforce the new setting
+      # immediately.
+      #
+      # ==== Versioned Defaults
+      #
+      # Net::IMAP#max_response_size <em>was added in +v0.2.5+ and +v0.3.9+ as an
+      # attr_accessor, and in +v0.4.20+ and +v0.5.7+ as a delegator to this
+      # config attribute.</em>
+      #
+      # * original: +nil+ <em>(no limit)</em>
+      # * +0.5+: 512 MiB
+      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+).
@@ -275,9 +344,13 @@ module Net
       #   Raise an ArgumentError with the deprecation warning.
       #
       # Note: #responses_without_args is an alias for #responses_without_block.
-      attr_accessor :responses_without_block, type: [
+      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:
@@ -287,66 +360,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.
-      attr_accessor :parser_use_deprecated_uidplus_data, type: [
+      # [+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+.
       #
@@ -415,56 +491,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 named_default?
+        equal?(Config.default) ||
+          AttrVersionDefaults::VERSIONS.any? { equal? Config[_1] }
+      end
+
+      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
+
+      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
+
+      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
+
+      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
 
-      @default = new(
-        debug: false,
-        open_timeout: 30,
-        idle_response_timeout: 5,
-        sasl_ir: true,
-        enforce_logindisabled: true,
-        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[:current] = Config[:default]
-
-      version_defaults[0] = Config[:current].dup.update(
-        sasl_ir: false,
-        responses_without_block: :silence_deprecation_warning,
-        enforce_logindisabled: false,
-        parser_use_deprecated_uidplus_data: true,
-        parser_max_deprecated_uidplus_data_size: 10_000,
-      ).freeze
-      version_defaults[0.0] = Config[0]
-      version_defaults[0.1] = Config[0]
-      version_defaults[0.2] = Config[0]
-      version_defaults[0.3] = Config[0]
-
-      version_defaults[0.4] = Config[0.3].dup.update(
-        sasl_ir: true,
-        parser_max_deprecated_uidplus_data_size: 1000,
-      ).freeze
-
-      version_defaults[0.5] = Config[:current]
-
-      version_defaults[0.6] = Config[0.5].dup.update(
-        responses_without_block: :frozen_dup,
-        parser_use_deprecated_uidplus_data: false,
-        parser_max_deprecated_uidplus_data_size: 0,
-      ).freeze
-      version_defaults[:next] = Config[0.6]
-      version_defaults[:future] = Config[:next]
-
-      version_defaults.freeze
+      Struct   = AttrAccessors.struct
+      @default = AttrVersionDefaults.compile_default!
+      @global  = default.new
+      AttrVersionDefaults.compile_version_defaults!
+
     end
   end
 end

data/lib/net/imap/connection_state.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class ConnectionState < Data # :nodoc:
+      def self.define(symbol, *attrs)
+        symbol => Symbol
+        state = super(*attrs)
+        state.const_set :NAME, symbol
+        state
+      end
+
+      def symbol; self.class::NAME      end
+      def name;   self.class::NAME.name end
+      alias to_sym symbol
+
+      def deconstruct; [symbol, *super] end
+
+      def deconstruct_keys(names)
+        hash = super
+        hash[:symbol] = symbol if names.nil? || names.include?(:symbol)
+        hash[:name]   = name   if names.nil? || names.include?(:name)
+        hash
+      end
+
+      def to_h(&block)
+        hash = deconstruct_keys(nil)
+        block ? hash.to_h(&block) : hash
+      end
+
+      def not_authenticated?; to_sym == :not_authenticated end
+      def authenticated?;     to_sym == :authenticated     end
+      def selected?;          to_sym == :selected          end
+      def logout?;            to_sym == :logout            end
+
+      NotAuthenticated = define(:not_authenticated)
+      Authenticated    = define(:authenticated)
+      Selected         = define(:selected)
+      Logout           = define(:logout)
+
+      class << self
+        undef :define
+      end
+      freeze
+    end
+
+  end
+end

data/lib/net/imap/data_encoding.rb

@@ -155,57 +155,106 @@ 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 '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)
-
-        msg = "nz_number must be non-zero unsigned 32-bit integer: #{num}"
-        raise DataFormatError, msg
+        raise DataFormatError,
+          "nz-number must be non-zero unsigned 32-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
+
+      # 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
 
-        msg = "mod_sequence_value must be unsigned 64-bit integer: #{num}"
-        raise DataFormatError, msg
+      # 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_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