Class: Params::Registry

Inherits:
Object
  • Object
show all
Defined in:
lib/params/registry.rb,
lib/params/registry/version.rb

Overview

Registry is intended to contain an organization-wide registry of reusable named parameters. The initial purpose of such a thing is to control the lexical representation of serialization schemes of, e.g., URI query parameters and application/x-www-form-urlencoded Web form input, such that they can be round-tripped from a canonicalized string representation to a processed, in-memory representation and back.

Defined Under Namespace

Modules: Types Classes: Error, Group, Instance, Template

Constant Summary collapse

VERSION =

The module version

"0.1.8"

Instance Attribute Summary collapse

Quasi-static methods to override in subclasses collapse

Instance Method Summary collapse

Constructor Details

#initialize(templates: nil, groups: nil, complement: nil) ⇒ Registry

Note:

The complement parameter is always set (last), and its identifier defaults, unsurprisingly, to :complement. This can be overridden by specifying an identifier you prefer. If you want a slug that is distinct from the canonical identifier, or if you want aliases, pass in a spec like this: { id: URI('https://my.schema/parameters#complement'), slug: :complement, aliases: %i[invert negate] }

Initialize the registry. You will need to supply a set of specs that will become Template objects. You can also supply groups which you can use how you like.

Parameters can be defined within groups or separately from them. This allows subsets of parameters to be easily hived off from the main Instance.

There is a special meta-parameter :complement which takes as its values the names of other parameters. This is intended to be used to signal that the parameters so named, assumed to be some kind of composite, like a Set or Range, are to be complemented or negated. The purpose of this is, for instance, if you want to express a parameter that is a set with many values, and rather than having to enumerate each of the values in something like a query string, you only have to enumerate the values you don't want in the set.

Parameters:

  • templates (Hash) (defaults to: nil) —

    the hash of template specifications.

  • groups (Hash, Array) (defaults to: nil) —

    the hash of groups.

  • complement (Object, Hash) (defaults to: nil) —

    the identifier for the parameter for complementing composites, or otherwise a partial specification.



300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/params/registry.rb', line 300

def initialize templates: nil, groups: nil, complement: nil
  # initialize the object state with an empty default group
  @groups = { nil => Group.new(self, nil) }

  # coerce these guys
  templates = Types::TemplateMap[templates]
  groups    = Types::GroupMap[groups]

  # now load templates
  templates.each { |id, spec| self.templates[id] = spec }

  # now load groups
  groups.each { |id, specs| self[id] = specs }

  # now deal with complement
  cid, cspec = coerce_complement complement
  self.templates[cid] = cspec # XXX note leaky abstraction
  # warn wtf.inspect
  @complement = self.templates[cid]
end

Instance Attribute Details

#complement ⇒ Params::Registry::Template (readonly)

The complement template.

Returns:



324
325
326
 
# File 'lib/params/registry.rb', line 324

def complement
  @complement
end

Instance Method Details

#[](id) ⇒ Params::Registry::Group

Retrieve a group.

Returns:



330
331
332
 
# File 'lib/params/registry.rb', line 330

def [] id
  @groups[id]
end

#[]=(id, spec) ⇒ Params::Registry::Group

Assign a group.

Returns:



338
339
340
341
342
343
 
# File 'lib/params/registry.rb', line 338

def []= id, spec
  # the null id is special; you can't assign to it
  id = Types::NonNil[id]

  @groups[id] = group_class.new self, id, templates: spec
end

#group_class ⇒ Class

The group class to use. Override this in a subclass if you want to use a custom one.

Returns:

  • (Class) —

    the group class, Group.



416
417
418
 
# File 'lib/params/registry.rb', line 416

def group_class
  Group
end

#groups ⇒ Array<Params::Registry::Group>

Retrieve the groups themselves.

Returns:



357
358
359
 
# File 'lib/params/registry.rb', line 357

def groups
  @groups.values_at(*keys)
end

#instance_class ⇒ Class

The instance class to use. Override this in a subclass if you want to use a custom one.

Returns:

  • (Class) —

    the instance class, Instance.



407
408
409
 
# File 'lib/params/registry.rb', line 407

def instance_class
  Instance
end

#keys ⇒ Array

Retrieve the names of the groups.

Returns:

  • (Array) —

    the group names.



349
350
351
 
# File 'lib/params/registry.rb', line 349

def keys
  @groups.keys.reject(&:nil?)
end

#process(params) ⇒ Params::Registry::Instance

Process the parameters and return a Instance.

Parameters:

  • params —

    [String, URI, Hash=> Array, Array>] the parameter set, in a dizzying variety of inputs.

Returns:



378
379
380
 
# File 'lib/params/registry.rb', line 378

def process params
  instance_class.new self, Types::Input[params]
end

#refresh! ⇒ void

This method returns an undefined value.

Refresh any stateful elements of the templates.



386
387
388
389
 
# File 'lib/params/registry.rb', line 386

def refresh!
  templates.each { |t| t.refresh! }
  nil
end

#template_class ⇒ Class

The template class to use. Override this in a subclass if you want to use a custom one.

Returns:

  • (Class) —

    the template class, Template.



398
399
400
 
# File 'lib/params/registry.rb', line 398

def template_class
  Template
end

#templates ⇒ Params::Registry::Group

Retrieve the master template group.

Returns:



365
366
367
368
 
# File 'lib/params/registry.rb', line 365

def templates
  # XXX is this dumb? would it be better off as its own member?
  @groups[nil]
end