params-registry 0.1.12 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecda0bf7bd68a9dd7fd9b04cf9d5e3a2695aea9ac1d855f52dabff25f3992af3
-  data.tar.gz: 0acfd9a1a99e2be5f61f85c0b8fad2bdde2e2db9b04060d3ead7d810a508827d
+  metadata.gz: b55a15071c752544d76d3256a835eb927507ff8685a90cc94cc00a9bf6fed373
+  data.tar.gz: c4e5cc3a55c98e39405fa5d61e88ccecdc279e5149d38a04469a6ab5db664e33
 SHA512:
-  metadata.gz: 7f095e9e830b31e7c546cecde3dde1dc9112c4b65d82fa623c403fb5c0672cfeb1ebf0596582139c966b8cd5b23a9dbb23955c2d02100e56fd7e582b68006a36
-  data.tar.gz: fc4a9ce7dea830a031553473d7088951b1f10a16772b561ac10259dea87669ac4ce20caff03490a27a4709ab6bf1ad0ca88a82a8e92d17b13655d55e0ab9fd24
+  metadata.gz: 356602be7b8437695e5439bafcb74c62d85a1e5205a436c2ab90e8ec19d1cdc0692fdd0b25dd16ac18f86861c96d7a501b4114a357469b301e17f6396becd834
+  data.tar.gz: b7f9c511c11070da981d7d85d4354c4f46c7d72a780aee8b2e4eace3ce34c5d52eef6866dce51add8bd32947924614c853f677cf602d7e34d7ec7f6f17df2d19

data/README.md

@@ -18,9 +18,9 @@ _symbols_, which you have to _manage_, and this is a _problem_.
 table: named parameters that are exposed to the wild through
 mechanisms like URLs and APIs.
 
-## So, query parameters, isn't that like, _super_ anal?
+## So, query parameters, isn't that like, _super_ uptight?
 
-So, I vacillated for _years_ before making [the _first_ version of
+I vacillated for _years_ before making [the _first_ version of
 this module](https://metacpan.org/dist/Params-Registry) back in 2013.
 _Query_ parameters? I mean, who cares? Well, it turns out that if you
 want certain outcomes, this is the kind of software you need. _What_

data/lib/params/registry/error.rb

@@ -6,25 +6,33 @@ require_relative 'types'
 # We assume all errors are argument errors
 class Params::Registry::Error < ArgumentError
 
-  def initialize message, context: nil, value: nil
-    @context = context
-    @value   = value
+  def initialize message, context: nil, value: nil, original: nil
+    @context  = context
+    @value    = value
+    @original = original
     super message
   end
 
+  class Internal < self
+  end
+
   # Errors for when nothing can be done with the lexical value of the input
   class Syntax < self
   end
 
-  # Errors for when the syntax checks out but the value doesn't
-  # conform empirically
+  # Errors for when the syntax checks out but one or more values don't
+  # conform empirically.
   class Empirical < self
   end
 
+  # An error for when there are specifically not enough elements (too
+  # many can always be pruned).
   class Cardinality < Empirical
   end
 
-  # A correctable error
+  # This is less an error and more a way to signal to the caller that
+  # the parameter set will serialize differently from how it was
+  # initialized.
   class Correction < Empirical
     def initialize message, context: nil, value: nil, nearest: nil
       @nearest = nearest

data/lib/params/registry/instance.rb

@@ -14,26 +14,50 @@ class Params::Registry::Instance
   # i wish it was smart and would just resolve relative class names
   Types = Params::Registry::Types
 
+  # This method is to process a single parameter _within the context of the
+  # entire parameter set_.
+  #
   # This is the epitome of an internal method. It has weird
   # parameters, modifies state, and returns a value that is useless
   # for anything but subsequent internal processing.
-  def process_one template, values, complement: false, force: false
+  def process_one template, values,
+      defaults: true, complement: false, force: false
+
+    # unconditionally coerce to array unless it already is one
+    values = values.nil? ? [] : values.is_a?(Array) ? values : [values]
+
+    # warn [:process_one, template.slug || template.id, values].inspect
+
+    # set up the set of elements to be deleted
     del = Set[]
 
-    # run the preprocessor
-    if template.preproc? and template.consumes.all? { |k| @content.key? k }
-      others = @content.values_at(*template.consumes)
+    if template.composite? and template.composite.try(values.first).success?
+      # do not run the preprocessor
+      values = values.first
+    elsif template.preproc? and template.consumes.all? { |k| @content.key? k }
+      # we prefer the slugs to make it easier on people
+      others = @content.slice(*template.consumes).transform_keys do |k|
+        t = registry.templates[k]
+        t.slug || k
+      end
 
-      # XXX maybe we should
+      # run the preproc function
       values = template.preproc values, others
+
+      # add these to the instance parameters to be deleted
       del += template.consumes
     end
 
     # if this actually goes here then there's a bug in the perl one
-    return del if values.empty? and not force
+    if values.is_a? Array and values.empty? and not force
+      # warn "lol wtf #{template.default}"
+      @content[template.id] = template.default.dup if
+        defaults and not template.default.nil?
+      return del
+    end
 
     # now we use the template to process it (note this raises)
-    tmp = template.process(*values)
+    tmp = template.process values
     @content[template.id] = tmp if !tmp.nil? or template.empty?
 
     # now we test for conflicts
@@ -52,17 +76,26 @@ class Params::Registry::Instance
     del # the keys slated for deletion
   end
 
+  def encode_value value
+    # URI::encode_www_form_component sucks
+    value = value.to_s.b
+    # the only thing we really need to encode is [&=%#] and non-ascii
+    # because in a query string all other uri chars are legal
+    value.gsub(/[\x0-\x20\x7f-\xff&=%#]/n) { |s| '%%%02X' % s.ord }
+  end
+
   public
 
-  attr_reader :registry
+  attr_reader :registry, :extra
 
-  # Make a new instance.
+  # Initialize a parameter instance. Any `params` will be passed to #process.
   #
-  # @param registry [Params::Registry] the registry
-  # @param struct [Hash{Symbol => Array<String>}] something that
-  #  resembles the output of `URI.decode_www_form`.
+  # @param registry [Params::Registry, Params::Registry::Group] the registry
+  # @param params [String, Hash{Symbol => Array}] something that
+  #  resembles either the input or the output of `URI.decode_www_form`.
   #
-  def initialize registry, struct, defaults: false, force: false
+  def initialize registry, params: nil, defaults: false, force: false
+    # deal with registry/group stuff
     if registry.is_a? Params::Registry::Group
       @group    = registry.id
       @registry = registry = registry.registry
@@ -71,13 +104,32 @@ class Params::Registry::Instance
       @registry = registry
     end
 
+    # set up members
     @content  = {}
     @extra    = {}
 
+    process params, defaults: defaults, force: force if params
+  end
+
+  # Process a set of parameters of varying degrees of parsed-ness, up
+  # to and including a raw query string.
+  #
+  # @param params [String, Hash{Symbol => Array}] something that
+  #  resembles either the input or the output of `URI.decode_www_form`.
+  # @param defaults [true, false] whether to include defaults in the result
+  # @param force [false, true] force strict cardinality checking
+  #
+  # @return [self] for daisy-chaining
+  #
+  def process params, defaults: true, force: false
+
     # warn "wtf lol #{@registry[@group].inspect}"
 
-    # canonicalize the keys of the struct
-    struct = Types::Input[struct].reduce({}) do |hash, pair|
+    # warn [:before, params].inspect
+
+    # make sure we get a struct-like object with canonical keys but
+    # don't touch the values yet
+    params = Types::Input[params].reduce({}) do |hash, pair|
       key, value = pair
       # warn "kv: #{key.inspect} => #{value.inspect}"
       if t = @registry[@group][key]
@@ -92,15 +144,15 @@ class Params::Registry::Instance
     end
 
     errors = {} # collect errors so we only raise once at the end
-    del = Set[] # mark for deletion
+    del = Set[] # mark these keys for deletion
 
     # grab the complements now
     complements = @content[@registry.complement.id] =
-      @registry.complement.process(*struct.fetch(@registry.complement.id, []))
+      @registry.complement.process(params.fetch(@registry.complement.id, []))
 
     # warn registry.templates.ranked.inspect
 
-    # warn complements.class
+    # warn [:process, params].inspect
 
     # now we get the ranked templates and pass them through
     @registry[@group].ranked.each do |templates|
@@ -110,12 +162,13 @@ class Params::Registry::Instance
         # warn t.id
 
         # obtain the raw values or an empty array instead
-        raw = struct.fetch t.id, []
+        raw = params.fetch t.id, []
 
         c = complements.include? t.id
 
         begin
-          del += process_one t, raw, force: force, complement: c
+          del += process_one t, raw,
+            defaults: defaults, force: force, complement: c
         rescue Params::Registry::Error => e
           errors[t.id] = e
         end
@@ -130,6 +183,9 @@ class Params::Registry::Instance
 
     # delete the unwanted parameters
     del.each { |d| @content.delete d }
+
+    # this is a daisy chainer
+    self
   end
 
   # Retrieve the processed value for a parameter.
@@ -159,20 +215,39 @@ class Params::Registry::Instance
   #
   def []= param, value
     unless template = registry.templates[param]
-      value = value.respond_to?(:to_a) ? value.to_a : value
+      # XXX THIS IS POTENTIALLY DUMB
+      value = value.respond_to?(:to_a) ? value : [value]
       return @extras[param] = value
     end
 
-    # XXX do something less dumb about this
-    c = (@content[registry.complement.id] || Set[]).include? template.id
-
-    # this modifies @content and may raise
-    del = process_one template, value, force: true, complement: c
+    # XXX THIS MIGHT FUCK SHIT UP
+    if value.nil?
+      @content.delete template.id
+    else
+      @content[template.id] = template.process value
+    end
+  end
 
-    del.each { |d| @content.delete d }
+  # Bulk-assign instance content.
+  #
+  # @param struct [Hash]
+  #
+  def content= struct
+    # just use the member assign we already have
+    struct.each { |k, v| self[k] = v }
+  end
 
-    # return
-    @content[template.id]
+  # Return a URI with the query set to the string value of this instance.
+  #
+  # @param uri [URI, #query=] the URI you want to assign
+  # @param defaults [false, true] whether to include defaults
+  #
+  # @return [URI, #query=] the URI with the new query string
+  #
+  def make_uri uri, defaults: false, extra: false
+    uri = uri.dup
+    uri.query = to_s defaults: defaults, extra: extra
+    uri
   end
 
   # Taxidermy this object as an ordinary hash.
@@ -199,42 +274,75 @@ class Params::Registry::Instance
     out
   end
 
-  def inspect
-    "<#{self.class} content: #{@content.inspect}, extra: #{@extra.inspect}>"
+  # Create a shallow copy of the parameter instance.
+  #
+  # @return [Params::Registry::Instance] the copy
+  #
+  def dup
+    out = self.class.new @registry[@group]
+    out.content = @content.dup
+    out
   end
 
-  # # Retrieve an {Params::Registry::Instance} that isolates the
-  # # intersection of one or more groups
-  # #
-  # # @param group [Object] the group identifier.
-  # # @param extra [false, true] whether to include any "extra" unparsed
-  # #  parameters.
-  # #
-  # # @return [Params::Registry::Instance] an instance containing just
-  # #  the group(s) identified.
-  # #
-  # def group *group, extra: false
-  # end
-
   # Serialize the instance back to a {::URI} query string.
   #
+  # @params defaults [false, true, Object, Array] whether to serialize
+  #  default values, or specific keys/slugs to include
+  # @params extra [false, true] whether to include parameters that
+  #  were passed in that aren't in the registry
+  #
   # @return [String] the instance serialized as a URI query string.
   #
-  def to_s
+  def to_s defaults: false, extra: false
     ts = registry.templates
+
+    # warn ts.inspect
+
+    # this should give us a list of keys that have defaults that we
+    # want to show up
+    defaults = case defaults
+               when nil, false then []
+               when true then ts.select { |k| ts[k].default? }.values.map(&:id)
+               when -> d { d.respond_to? :to_a } then defaults.to_a
+               else [defaults]
+               end.map { |d| ts[d]&.id }.compact
+
+    # the template keys should have the original order so we want to intersee
     sequence = ts.keys & @content.keys
     complements = Set[]
-    sequence.map do |k|
+    out = sequence.map do |k|
       template = ts[k]
-      deps = @content.values_at(*(template.depends - template.consumes))
-      v, c = template.unprocess @content[k], *deps, with_complement_flag: true
+
+      # we want to skip the parameter if it's the same as
+      next if template.default? and @content[k] == template.default and
+        not defaults.include? k
+
+      # get the dependencies, convert to an array of strings, harvest
+      # complement flag (if present)
+      deps = @content.slice(*(template.depends - template.consumes))
+      v, c = template.unprocess @content[k], deps, try_complement: true
       complements << k if c
 
       # warn @content[k], v.inspect
 
       next if v.empty?
 
-      v.map { |v| "#{template.slug || k}=#{v}" }.join ?&
-    end.compact.join ?&
+      v.map do |v|
+        "#{template.slug || encode_value(k)}=#{encode_value v}"
+      end.join ?&
+    end.compact
+
+    # XXX TODO complement and extras i just don't feel like looking up how
+    # that's supposed to work rn but they would go here
+
+    out.join ?&
+  end
+
+  # Return a string representation of the object suitable for debugging.
+  #
+  # @return [String] said string representation
+  #
+  def inspect
+    "<#{self.class} content: #{@content.inspect}, extra: #{@extra.inspect}>"
   end
 end

data/lib/params/registry/template.rb

@@ -3,13 +3,101 @@
 require_relative 'types'
 require_relative 'error'
 
-# This class manages an individual parameter template.
+# This class manages an individual parameter template. It encapsulates
+# all the information and operations needed to validate and coerce
+# individual parameter values, as well as for serializing them back
+# into a string, and for doing so with bit-for-bit consistency.
+#
+# A parameter template can have a human-readable {::Symbol} as a
+# `slug`, which is distinct from its canonical identifier (`id`),
+# which can be any object, although that must be unique for the entire
+# registry (while a slug only needs to be unique within its enclosing
+# group). It can also have any number of `aliases`.
+#
+# A template can manage a simple type like a string or number, or a
+# composite type like an array, tuple (implemented as a fixed-length
+# array), set, or range containing appropriate simple types. The
+# current (provisional) way to specify the types for the template are
+# the `type` and `composite` initialization parameters, where if the
+# latter is present, the former will be treated as its member type.
+#
+# > If certain forays into open-source diplomacy go well, these can be
+# > consolidated into a single type declaration.
+#
+# A parameter may depend on (`depends`) or conflict (`conflicts`) with
+# other parameters, or even consume (`consumes`) them as input. The
+# cardinality of a parameter is controlled by `min` and `max`, which
+# default to zero and unbounded, respectively. To require a parameter,
+# set `min` to an integer greater than zero, and to enforce a single
+# scalar value, set `max` to 1. (Setting `min` greater than `max` will
+# raise an error.) To control whether a value of `nil` or the empty
+# string is dropped, kept (as the empty string) or kept as `nil`, set
+# the `empty` parameter.
+#
+# When `max` is greater than 1, the template automatically coerces any
+# simple value into an array containing that value. (And when `max` is
+# equal to 1, an array will be replaced with a single value.) Passing
+# an array into #process with fewer than `min` values (or a single
+# value when `min` is greater than 1) will produce an error. Whether
+# the first N values (up to `max`) or the _last_ N values are taken
+# from the input, is controlled by the `shift` parameter.
+#
+# Composite values begin life as arrays of simple values. During
+# processing, the individual values are coerced from what are assumed
+# to be strings, and then the arrays themselves are coerced into the
+# composite types. Serialization is the same thing in reverse, using a
+# function passed into `unwind` (which otherwise defaults to `to_a`)
+# to turn the composite type back into an array, before the individual
+# values being turned into strings by way of the value passed into
+# `format`, which can either be a standard format string or a
+# {::Proc}. The `unwind` function is also expected to sort the
+# array. There is also a `reverse` flag for when it makes sense to
+#
+# The transformation process, from array of strings to composite
+# object and back again, has a few more points of intervention. There
+# is an optional `preproc` function, which is run when the
+# {Params::Registry::Instance} is processed,  after the
+# individual values are coerced and before the composite coercion is
+# applied, and a `contextualize` function, which is run after `unwind`
+# but before `format`. Both of these functions make it possible to use
+# information from the parameter's dependencies to manipulate its
+# values based on its context within a live
+# {Params::Registry::Instance}.
+#
+# Certain composite types, such as sets and ranges, have a coherent
+# concept of a `universe`, which is implemented here as a function
+# that generates a compatible object. This is useful for when the
+# serialized representation of a parameter can be large. For instance,
+# if a set's universe has 100 elements and we want to represent the
+# subset with all the elements except for element 42, rather than
+# serializing a 99-element query string, we complement the set and
+# make a note to that effect (to be picked up by the
+# {Params::Registry::Instance} serialization process and put in its
+# `complement` parameter). The function passed into `complement` will
+# be run as an instance method, which has access to `universe`. Other
+# remarks about these functions:
+#
+# * The `preproc` and `contextualize` functions are expected to take
+#   the form `-> value, hash { expr }` and must return an array. The
+#   `hash` here is expected to contain at least the subset of
+#   parameters marked as dependencies (as is done in
+#   {Params::Registry::Instance}), keyed by `slug` or, failing that,
+#   `id`.
+# * The `unwind` and `complement` functions both take the composite
+#   value as an argument (`-> value { expr }`). `unwind` is expected
+#   to return an array of elements, and `complement` should return a
+#   composite object of the same type.
+# * The `universe` function takes no arguments and is expected to
+#   return a composite object of the same type.
+#
 class Params::Registry::Template
 
   private
 
   # this is dumb
   Types = Params::Registry::Types
+  # when in rome
+  E = Params::Registry::Error
 
   # Post-initialization hook for subclasses, because the constructor
   # is so hairy.
@@ -54,8 +142,11 @@ class Params::Registry::Template
   #  derivatives, a function that returns the universal set or range
   # @param complement [Proc] For {::Set} or {::Range} composite types, a
   #  function that will return the complement of the set or range
-  # @param unwind [Proc] A function that takes the composite type
+  # @param unwind [Proc] A function that takes a composite type
   #  and turns it into an {::Array} of atomic values
+  # @param contextualize [Proc] A function that takes an unwound
+  #  composite value and modifies it based on the other parameters it
+  #  depends on
   # @param reverse [false, true] For {::Range} composite types, a flag
   #  that indicates whether the values should be interpreted and/or
   #  serialized in reverse order. Also governs the serialization of
@@ -65,28 +156,32 @@ class Params::Registry::Template
       composite: nil, format: nil, aliases: nil, depends: nil, conflicts: nil,
       consumes: nil, preproc: nil, min: 0, max: nil, shift: false,
       empty: false, default: nil, universe: nil, complement: nil,
-      unwind: nil, reverse: false
-
-    @registry   = Types::Registry[registry]
-    @id         = Types::NonNil[id]
-    @slug       = Types::Symbol[slug] if slug
-    @type       = Types[type]
-    @composite  = Types[composite] if composite
-    @format     = (Types::Proc | Types::String)[format] if format
-    @aliases    = Types::Array[aliases]
-    @depends    = Types::Array[depends]
-    @conflicts  = Types::Array[conflicts]
-    @consumes   = Types::Array[consumes]
-    @preproc    = Types::Proc[preproc] if preproc
-    @min        = Types::NonNegativeInteger[min || 0]
-    @max        = Types::PositiveInteger.optional[max]
-    @shift      = Types::Bool[shift]
-    @empty      = Types::Bool[empty]
-    @default    = Types::Nominal::Any[default]
-    @unifunc    = Types::Proc[universe]   if universe
-    @complement = Types::Proc[complement] if complement
-    @unwind     = Types::Proc[unwind]     if unwind
-    @reverse    = Types::Bool[reverse]
+      unwind: nil, contextualize: nil, reverse: false
+
+    @registry  = Types::Registry[registry]
+    @id        = Types::NonNil[id]
+    @slug      = Types::Symbol[slug] if slug
+    @type      = Types[type]
+    @composite = Types[composite] if composite
+    @format    = (Types::Proc | Types::String)[format] if format
+    @aliases   = Types::Array[aliases]
+    @depends   = Types::Array[depends]
+    @conflicts = Types::Array[conflicts]
+    @consumes  = Types::Array[consumes]
+    @preproc   = Types::Proc[preproc] if preproc
+    @min       = Types::NonNegativeInteger[min || 0]
+    @max       = Types::PositiveInteger.optional[max]
+    @shift     = Types::Bool[shift]
+    @empty     = Types::Bool[empty]
+    @default   = Types::Nominal::Any[default]
+    @unifunc   = Types::Proc[universe]      if universe
+    @comfunc   = Types::Proc[complement]    if complement
+    @unwfunc   = Types::Proc[unwind]        if unwind
+    @confunc   = Types::Proc[contextualize] if contextualize
+    @reverse   = Types::Bool[reverse]
+
+    raise ArgumentError, "min (#{@min}) cannot be greater than max (#{@max})" if
+      @min and @max and @min > @max
 
     # post-initialization hook
     post_init
@@ -123,13 +218,37 @@ class Params::Registry::Template
   # @!attribute [r] default
   #  @return [Object, nil] a default value for the parameter.
   #
-  # @!attribute [r] unwind
-  # A function that will take a composite object
-  #  and turn it into an array of strings for serialization.
-  # @return [Proc, nil]
-
   attr_reader :registry, :id, :slug, :type, :composite, :aliases,
-    :preproc, :min, :max, :default, :unwind
+    :preproc, :min, :max, :default
+
+  # Unwind a composite value into an array of simple values. This
+  # wraps the matching function passed into the constructor, or
+  # `#to_a` in lieu of one.
+  #
+  # @param value [Object] a composite value
+  #
+  # @raise
+  #
+  # @return [Array] the unwound composite
+  #
+  def unwind value
+    return unless composite?
+
+    func = @unwfunc || -> v { v.to_a }
+
+    begin
+      out = instance_exec value, &func
+    rescue Exception, e
+      raise E::Internal.new "Unwind on #{id} failed: #{e.message}",
+        value: value, original: e
+    end
+
+    raise E::Internal,
+      "Unwind on #{id} returned #{out.class}, not an Array" unless
+      out.is_a? Array
+
+    out
+  end
 
   # @!attribute [r] depends
   # Any parameters this one depends on.
@@ -141,8 +260,8 @@ class Params::Registry::Template
       registry.templates.canonical t
     end
 
-    raise Params::Registry::Error,
-      "Malformed dependency declaration on #{t.id}" if out.any?(&:nil?)
+    raise E::Internal, "Malformed dependency declaration on #{id}" if
+      out.any?(&:nil?)
 
     out
   end
@@ -157,12 +276,26 @@ class Params::Registry::Template
       registry.templates.canonical t
     end
 
-    raise Params::Registry::Error,
-      "Malformed conflict declaration on #{t.id}" if out.any?(&:nil?)
+    raise E::Internal, "Malformed conflict declaration on #{id}" if
+      out.any?(&:nil?)
 
     out
   end
 
+  # @!attribute [r] composite?
+  # Whether this parameter is composite.
+  #
+  # @return [Boolean]
+  #
+  def composite? ; !!@composite; end
+
+  # @!attribute [r] default?
+  # Whether this parameter has a default value.
+  #
+  # @return [Boolean]
+  #
+  def default? ; !@default.nil?; end
+
   # @!attribute [r] preproc?
   # Whether there is a preprocessor function.
   #
@@ -178,8 +311,8 @@ class Params::Registry::Template
   def consumes
     out = @consumes.map { |t| registry.templates.canonical t }
 
-    raise Params::Registry::Error,
-      "Malformed consumes declaration on #{t.id}" if out.any?(&:nil?)
+    raise E::Internal,
+      "Malformed consumes declaration on #{id}" if out.any?(&:nil?)
 
     out
   end
@@ -219,7 +352,14 @@ class Params::Registry::Template
   #
   # @return [Boolean]
   #
-  def complement? ; !!@complement; end
+  def complement? ; !!@comfunc; end
+
+  # @!attribute [r] contextualize?  Whether there is a contextualizing
+  # function present in the unprocessing stack.
+  #
+  # @return [Boolean]
+  #
+  def contextualize? ; !!@confunc; end
 
   # @!attribute [r] blank?
   # Returns true if the template has no configuration data to speak of.
@@ -230,7 +370,8 @@ class Params::Registry::Template
       @format.nil? && @aliases.empty? && @depends.empty? &&
       @conflicts.empty? && @consumes.empty? && @preproc.nil? &&
       @min == 0 && @max.nil? && !@shift && !@empty && @default.nil? &&
-      @unifunc.nil? && @complement.nil? && @unwind.nil? && !@reverse
+      @unifunc.nil? && @comfunc.nil? && @unwfunc.nil? && @confunc.nil? &&
+      !@reverse
   end
 
   # Preprocess a parameter value against itself and/or `consume`d values.
@@ -247,9 +388,9 @@ class Params::Registry::Template
       out = [out] unless out.is_a? Array
     rescue Dry::Types::CoercionError => e
       # rethrow a better error
-      raise Params::Registry::Error.new(
-        "Preprocessor failed on #{template.id} with #{}",
-        context: self, value: e)
+      raise E::Internal.new(
+        "Preprocessor failed on #{id} on value #{myself} with #{e.message}",
+        context: self, original: e)
     end
 
     out
@@ -267,38 +408,57 @@ class Params::Registry::Template
     if @format.is_a? Proc
       instance_exec scalar, &@format
     else
-      @format.to_s % scalar
+      (@format || '%s').to_s % scalar
     end
   end
 
   # Return the complement of the composite value for the parameter.
   #
   # @param value [Object] the composite object to complement.
+  # @param unwind [false, true] whether or not to also apply `unwind`
   #
   # @return [Object, nil] the complementary object, if a complement is defined.
   #
-  def complement value
-    return unless @complement
+  def complement value, unwind: false
+    return unless @comfunc
+
     begin
-      instance_exec value, &@complement
+      out = instance_exec value, &@comfunc
     rescue e
-      raise Params::Registry::Error::Empirical.new(
-        "Complement function failed: #{e.message}",
-        context: self, value: value)
-    end if @complement
+      raise E::Internal.new(
+        "Complement function on #{id} failed: #{e.message}",
+        context: self, value: value, original: e)
+    end
+
+    unwind ? self.unwind(out) : out
   end
 
   # Validate a list of individual parameter values and (if one is present)
   # construct a `composite` value.
   #
-  # @param values [Array] the values given for the parameter.
+  # @param value [Object] the values given for the parameter.
   #
   # @return [Object, Array] the processed value(s).
   #
-  def process *values
+  def process value
+    # XXX what we _really_ want is `Types::Set.of` and
+    # `Types::Range.of` but who the hell knows how to actually make
+    # that happen, so what we're gonna do instead is test if the
+    # template is composite, then test the input against the composite
+    # type, then run `unwind` on it and test the individual members
+
+    # warn [(slug || id), value].inspect
+
+    # coerce and then unwind
+    value = unwind composite[value] if composite?
+
+    # otherwise coerce into an array
+    value = [value] unless value.is_a? Array
+
+    # copy to out
     out = []
 
-    values.each do |v|
+    value.each do |v|
       # skip over nil/empty values unless we can be empty
       if v.nil? or v.to_s.empty?
         next unless empty?
@@ -310,8 +470,7 @@ class Params::Registry::Template
           tmp = type[v] # this either crashes or it doesn't
           v = tmp # in which case v is only assigned if successful
         rescue Dry::Types::CoercionError => e
-          raise Params::Registry::Error::Syntax.new e.message,
-            context: self, value: v
+          raise E::Syntax.new e.message, context: self, value: v, original: e
         end
       end
 
@@ -319,8 +478,8 @@ class Params::Registry::Template
     end
 
     # now we deal with cardinality
-    raise Params::Registry::Error::Cardinality.new(
-      "Need #{min} values and there are only #{out.length} values") if
+    raise E::Cardinality,
+      "Need #{min} values and there are only #{out.length} values" if
       out.length < min
 
     # warn "hurr #{out.inspect}, #{max}"
@@ -335,6 +494,9 @@ class Params::Registry::Template
     composite ? composite[out] : out
   end
 
+  # This method takes a value which is assumed to be valid and
+  # transforms it into an array of strings suitable for serialization.
+  #
   # Applies `unwind` to `value` to get an array, then `format` over
   # each of the elements to get strings. If `scalar` is true, it
   # will also return the flag from `unwind` indicating whether or
@@ -346,47 +508,46 @@ class Params::Registry::Template
   # of the parameters specified in `depends`.
   #
   # @param value [Object, Array<Object>] The parameter value(s).
-  # @param rest  [Array<Object>] The rest of the parameter values.
-  # @param with_complement_flag [false, true] Whether to return the
-  #  `complement` flag in addition to the unwound values.
+  # @param dependencies [Hash] The rest of the parameter values.
+  # @param try_complement [false, true] Whether to attempt to
+  #  complement a composite vlaue and return the `complement` flag in
+  #  addition to the unwound values.
   #
   # @return [Array<String>, Array<(Array<String>, false)>,
   #  Array<(Array<String>, true)>, nil] the unwound value(s), plus
   #  optionally the `complement` flag, or otherwise `nil`.
   #
-  def unprocess value, *rest, with_complement_flag: false
-    # take care of empty properly
-    if value.nil?
-      if empty?
-        return [''] if max == 1
-        return [] if max.nil? or max > 1
-      end
+  def unprocess value, dependencies = {}, try_complement: false
+    # we begin assuming the value has not been complemented
+    comp = false
 
-      # i guess this is nil?
-      return
+    if composite?
+      # coerce just to be sure
+      value = composite[value]
+      # now unwind
+      value = unwind value
+
+      if try_complement and complement?
+        tmp = complement value, unwind: true
+        if tmp.length < value.length
+          value = tmp
+          comp  = true
+        end
+      end
+    else
+      value = [value] unless value.is_a? Array
     end
 
-    # complement flag
-    comp = false
-    begin
-      tmp, comp = instance_exec value, *rest, &@unwind
-      value = tmp
-    rescue Exception, e
-      raise Params::Registry::Error::Empirical.new(
-        "Cannot unprocess value #{value} for parameter #{id}: #{e.message}",
-        context: self, value: value)
-    end if @unwind
+    # now we contextualize
+    value = contextualize value if contextualize?
 
-    # ensure this thing is an array
-    value = [value] unless value.is_a? Array
-
-    # ensure the values are correctly formatted
+    # now we maybe prune out blanks
+    value.compact! unless empty?
+    # any nil at this point is on purpose
     value.map! { |v| v.nil? ? '' : self.format(v) }
 
-    # throw in the complement flag
-    return value, comp if with_complement_flag
-
-    value
+    # now we return the pair if we're trying to complement it
+    try_complement ? [value, comp] : value
   end
 
   # Refreshes stateful information like the universal set, if present.
@@ -398,7 +559,7 @@ class Params::Registry::Template
       # do we want to call or do we want to instance_exec?
       univ = @unifunc.call
 
-      univ = @composite[univ] if @composite
+      univ = composite[univ] if composite?
 
       @universe = univ
     end

data/lib/params/registry/types.rb

@@ -40,6 +40,8 @@ module Params::Registry::Types
     end
   end
 
+  Boolean = Bool
+
   # For some reason there isn't a stock `Proc` type.
   Proc = self.Instance(::Proc)
 
@@ -135,15 +137,66 @@ module Params::Registry::Types
 
   # @!group Composite types not already defined
 
+  # XXX okay so once again dry-types has to be weird as hell. What we
+  # _want_ are `Set.of` and `Range.of` just like the built-in
+  # `Array.of`. What we have to _do_ to achieve this is god-knows-what.
+  #
+  class Container < ::Dry::Types::Nominal
+
+    class Constructor < ::Dry::Types::Array::Constructor
+      def constructor_type = Container::Constructor
+    end
+
+    class Member < ::Dry::Types::Array::Member
+      def constructor_type = Container::Constructor
+    end
+
+    def member_type = Container::Member
+
+    def constructor_type = Container::Constructor
+
+    def of(type)
+      member = case type
+               when ::String then ::Dry::Types[type]
+               else type
+               end
+
+      member_type.new(primitive, **options, member: member)
+    end
+
+  end
+
+  # class List < Array
+  # end
+
+  # XXX UGGGH CAN'T RETURN FROM THESE BECAUSE OF COURSE NOT UGGHGGHHG
+
   List = self.Constructor(::Array) do |x|
-    x.respond_to?(:to_a) ? x.to_a : [x]
+    if x.is_a? ::Array
+      x
+    else
+      x.respond_to?(:to_a) ? x.to_a : [x]
+    end
   end
 
   # {::Set}
-  Set = self.Constructor(::Set) { |x| ::Set[*x] }
+  Set = self.Constructor(::Set) do |x|
+    if x.is_a? ::Set
+      x
+    else
+      ::Set[*x]
+    end
+  end
 
   # {::Range}
-  Range = self.Constructor(::Range) { |x| ::Range.new(*x.take(2)) }
+  Range = self.Constructor(::Range) do |x|
+    # warn x.inspect
+    if x.is_a? ::Range
+      x
+    else
+      ::Range.new(*x.take(2).sort)
+    end
+  end
 
   # The registry itself
   Registry = self.Instance(::Params::Registry)
@@ -157,13 +210,19 @@ module Params::Registry::Types
   # Groups
   GroupMap = Hash|Hash.map(NonNil, Array|TemplateMap)
 
+  Values = self.Constructor(::Object) do |a|
+    # still kind of torn on how to deal with this
+    a.is_a?(::Array) ? a : [a]
+    # a.respond_to?(:to_a) ? a : [a]
+  end
+
   Input = self.Constructor(::Hash) do |input|
     input = input.query.to_s if input.is_a? ::URI
     input = '' if input.nil?
     input = ::URI.decode_www_form input if input.is_a? ::String
 
     case input
-    when ::Hash then Hash.map(Symbolish, Array.of(String))[input]
+    when ::Hash then Hash.map(Symbolish, Values)[input]
     when ::Array
       input.reduce({}) do |out, pair|
         k, *v = Strict::Array.constrained(min_size: 2)[pair]

data/lib/params/registry/version.rb

@@ -3,6 +3,6 @@
 module Params
   class Registry
     # The module version
-    VERSION = '0.1.12'
+    VERSION = '0.2.2'
   end
 end

data/lib/params/registry.rb

@@ -6,6 +6,7 @@ require_relative 'registry/template'
 require_relative 'registry/instance'
 
 require 'uri'
+require 'forwardable'
 
 # {Params::Registry} is intended to contain an organization-wide
 # registry of reusable named parameters. The initial purpose of such a
@@ -19,6 +20,10 @@ class Params::Registry
 
   # A group is an identifiable sequence of parameters.
   class Group
+    extend Forwardable
+
+    def_delegators :@templates, :select
+
     # Create a new group.
     #
     # @param registry [Params::Registry] the registry
@@ -137,7 +142,7 @@ class Params::Registry
 
     # Assign a new sequence of templates to the group.
     #
-    # @param templates [Array, Hash]
+    # @param templates [Array, Hash] the set of templates
     #
     # @return [Array, Hash] whatever was passed
     #  in because Ruby ignores the output
@@ -239,11 +244,16 @@ class Params::Registry
     # @param params
     #  [String, URI, Hash{#to_sym => Array}, Array<Array<(#to_sym, Object)>>]
     #  the parameter set, in a dizzying variety of inputs.
+    # @param defaults [true, false] whether to include default values
+    #  in the instance
+    # @param force [false, true] whether to force something i don't
+    #  remember what though lol
     #
     # @return [Params::Registry::Instance] the instance.
     #
-    def process params
-      registry.instance_class.new self, Types::Input[params]
+    def process params, defaults: true, force: false
+      registry.instance_class.new self,
+        params: params, defaults: defaults, force: force
     end
 
   end
@@ -269,6 +279,7 @@ class Params::Registry
     # for the closures
     ts = templates
 
+
     # we always want these closures so we steamroll over whatever the
     # user might have put in these slots
     spec.merge!({
@@ -282,7 +293,7 @@ class Params::Registry
       unwind: -> set {
         # XXX do we want to sort this lexically or do we want it in
         # the same order as the keys?
-        [set.to_a.map { |t| t = ts[t]; (t.slug || t.id).to_s }.sort, false]
+        set.to_a.map { |t| t = ts[t]; (t.slug || t.id).to_s }.sort
       }
     })
 
@@ -397,11 +408,15 @@ class Params::Registry
   # @param params
   #  [String, URI, Hash{#to_sym => Array}, Array<Array<(#to_sym, Object)>>]
   #  the parameter set, in a dizzying variety of inputs.
+  # @param defaults [true, false] whether to include default values
+  #  in the instance
+  # @param force [false, true] whether to force something i don't
+  #  remember what though lol
   #
   # @return [Params::Registry::Instance] the instance.
   #
-  def process params
-    instance_class.new self, Types::Input[params]
+  def process params, defaults: true, force: false
+    instance_class.new self, params: params, defaults: defaults, force: force
   end
 
   # Refresh any stateful elements of the templates.
@@ -409,7 +424,7 @@ class Params::Registry
   # @return [self]
   #
   def refresh!
-    templates.each { |t| t.refresh! }
+    templates.templates.each { |t| t.refresh! }
 
     self
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: params-registry
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 0.2.2
 platform: ruby
 authors:
 - Dorian Taylor
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-14 00:00:00.000000000 Z
+date: 2025-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types