Module: WrapIt::Arguments

Extended by:
ClassMethods, DerivedAttributes
Included in:
Base
Defined in:
lib/wrap_it/arguments.rb

Overview

This module responisble to parse creation arguments in component initialization process.

Respect to ruby language, any method can take variable number of arguments and a hash of options. Also you can pass a block to it. So, when your component subclassed from WrapIt::Base, user can create its instances via helpers. And when such component initialized you should be able to process all arguments, passed to helper or constructor. Finally all unprocessed options setted as component html attributes.

Two API methods provided for this purposes - argument and option. Each of them declares conditions for capturing some arguments and options. Conditions applies to arguments itself or to options keys. CapturedArray Array extension is used to capture arguments, so refer to its documentation for conditions details.

Author:

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

#argument(name, opts = {}) {|name, value| ... } ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Desclares argument for capturing on initialization process.

Inside initialization process, all arguments (except options hash), passed to constructor will be inspected to satisfy conditions, specified in :if and :and options. If this happens, and block given, it evaluated in context of component instance. If no block given, setter with name will be attempted to set value. In any way if conditions satisfied, argument removed from future processing.

If no conditions specified, the name of attribute taked as only condition.

Examples:

without conditions - name is a condition

class Button < WrapIt::Base
  argument(:disabled) { |name, value| puts 'DISABLED' }
end

Button.new(template, :disabled)   # => 'DISABLED'
Button.new(template, 'disabled')  # => nothing

with conditions and setter

class Button < WrapIt::Base
  argument :disabled, if: /^disable(?:d)?$/

  def disabled=(value)
    puts 'DISABLED'
  end
end

Button.new(template, :disabled)   # => 'DISABLED'
Button.new(template, 'disabled')  # => 'DISABLED'
Button.new(template, :disable)    # => 'DISABLED'
Button.new(template, 'some_text') # => nothing

Parameters:

  • name (Symbol) —

    unique name, used to refer to this declaration

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :if (Object) —

    one or array of conditions that should be satisfied to capture argument. See CaptureArray for details. If array given, conditions will be or'ed.

  • :and (Object) —

    additional one or array of conditions, that will be and'ed with :if conditions.

  • :first_only (Boolean) — default: false —

    stop processing on first match

  • :after_options (Boolean) — default: false —

    process this argument after options

Yields:

  • (name, value) —

    yields every time argument captured. Evaluated in instance context

Yield Parameters:

  • name (Symbol) —

    name of argument, specified in name param above

  • value (Object) —

    real argument value

Since:

  • 1.0.0

#capture_arguments!(args, opts = {}, &block) ⇒ Array<Object> Originally defined in module ClassMethods

Capture arguments for class and it's ancestors. All captured arguments and options will be extracted from original args argument.

Actually you rare needs to call this method directly. For example you can call it in instance capture_arguments! override to capture arguments for some child components.

Examples:

capturing arguments for child component

class Button < WrapIt::Base
  option(:color) { |name, value| puts "BUTTON COLOR IS: #{value}" }
end

class Toolbar < WrapIt::Base
  protected
  def capture_arguments!(args, &block)
    @button = Button.new(Button.capture_arguments!(args))
    super(args, &block) # ! don't forget to call parent method
  end
end

Toolbar.new(template, color: :red)  # => 'BUTTON COLOR IS red'

Parameters:

  • args (Array<Object>) —

    arguments to process (include options)

  • opts (Hash) (defaults to: {}) —

    options

  • &block (Proc) —

    block, passed to constructor if present

Options Hash (opts):

  • :inherited (Boolean) — default: true —

    process ancestors

  • :instance (Base) — default: nil —

    if specified valid instance, all #argument and #option blocks will and setters will be called.

Returns:

  • (Array<Object>) —

    captured arguments

#option(name, opts = {}) {|name, value| ... } ⇒ void Originally defined in module ClassMethods

This method returns an undefined value.

Desclares option for capturing on initialization process.

Provides same manner as #argument but for hash of options, passed to constructor. Specified conditions are applied to options keys, not to values.

Hint: you can specify argument and options with same name to call same setter.

Examples:

shared setter

class Button < WrapIt::Base
  REGEXP = /^disable(?:d)?$/

  argument :disabled, if: REGEXP
  option   :disabled, if: i(disable disabled)

  def disabled=(value)
    if value == true || REGEXP =~ value.to_s
      puts 'DISABLED'
    end
  end
end

Button.new(template, :disabled)       # => 'DISABLED'
Button.new(template, 'disabled')      # => 'DISABLED'
Button.new(template, :disable)        # => 'DISABLED'
Button.new(template, disabled: true)  # => 'DISABLED'
Button.new(template, disable: true)   # => 'DISABLED'
Button.new(template, disable: false)  # => nothing
Button.new(template, 'some_text')     # => nothing

Parameters:

  • name (Symbol) —

    unique name, used to refer to this declaration

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

Yields:

  • (name, value) —

    yields every time option captured. Evaluated in instance context

Yield Parameters:

  • name (Symbol) —

    name of option, specified in name param above

  • value (Object) —

    real option value

Since:

  • 1.0.0

Instance Method Details

#capture_arguments!(args, &block) ⇒ Array<Object>

Captures arguments

In rare cases you can override this method to control directly arguments capturing process. Refer to capture_arguments! for examples.

Note that this method is protected, so override should be protected too.

Parameters:

  • args (Array<Object>) —

    arguments, passed to constructor

  • block (Proc) —

    block, passed to constructor

Returns:

  • (Array<Object>) —

    captured arguments



332
333
334
 
# File 'lib/wrap_it/arguments.rb', line 332

def capture_arguments!(args, &block)
  self.class.capture_arguments!(args, true, self, &block)
end