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.2.2'

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.



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/params/registry.rb', line 336

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:



360
361
362
 
# File 'lib/params/registry.rb', line 360

def complement
  @complement
end

Instance Method Details

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

Retrieve a group.

Returns:



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

def [] id
  @groups[id]
end

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

Assign a group.

Returns:



374
375
376
377
378
379
 
# File 'lib/params/registry.rb', line 374

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.



457
458
459
 
# File 'lib/params/registry.rb', line 457

def group_class
  Group
end

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

Retrieve the groups themselves.

Returns:



393
394
395
 
# File 'lib/params/registry.rb', line 393

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.



448
449
450
 
# File 'lib/params/registry.rb', line 448

def instance_class
  Instance
end

#keys ⇒ Array

Retrieve the names of the groups.

Returns:

  • (Array) —

    the group names.



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

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

#process(params, defaults: true, force: false) ⇒ 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.

  • defaults (true, false) (defaults to: true) —

    whether to include default values in the instance

  • force (false, true) (defaults to: false) —

    whether to force something i don't remember what though lol

Returns:



418
419
420
 
# File 'lib/params/registry.rb', line 418

def process params, defaults: true, force: false
  instance_class.new self, params: params, defaults: defaults, force: force
end

#refresh! ⇒ self

Refresh any stateful elements of the templates.

Returns:

  • (self) 


426
427
428
429
430
 
# File 'lib/params/registry.rb', line 426

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

  self
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.



439
440
441
 
# File 'lib/params/registry.rb', line 439

def template_class
  Template
end

#templates ⇒ Params::Registry::Group

Retrieve the master template group.

Returns:



401
402
403
404
 
# File 'lib/params/registry.rb', line 401

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