Module: WrapIt::Arguments::ClassMethods

Included in:
WrapIt::Arguments, Base
Defined in:
lib/wrap_it/arguments.rb

Overview

WrapIt::Arguments Class methods to include

Instance Method Summary collapse

Instance Method Details

#argument(name, opts = {}) {|name, value| ... } ⇒ void

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



94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/wrap_it/arguments.rb', line 94

def argument(name, first_only: false, after_options: false,
             **opts, &block)
  name.is_a?(String) && name = name.to_sym
  fail ArgumentError, 'Wrong name' unless name.is_a?(Symbol)
  arguments[name] = {
    name: name,
    conditions: Arguments.make_conditions(name, **opts),
    block: block,
    first_only: first_only == true,
    after_options: after_options == true
  }
end

#capture_arguments!(args, opts = {}, &block) ⇒ Array<Object>

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



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/wrap_it/arguments.rb', line 200

def capture_arguments!(args, inherited = true, instance = nil, &block)
  opts = args.extract_options!
  if inherited
    arg_parents.select { |a| a.protected_methods.include?(:extract_for_class) }
               .each { |a| a.extract_for_class(args, opts, instance, &block) }
    result_args = collect_derived(:@provided_arguments, {}, :merge)
                  .values
                  .flatten
    result_opts = collect_derived(:@provided_options, {}, :merge)
                  .values
                  .reduce({}) { |a, e| a.merge!(e) }
  else
    extract_for_class(args, opts, instance, &block)
    result_args = @provided_arguments.values.flatten
    result_opts = @provided_options
                  .values
                  .reduce({}) { |a, e| a.merge!(e) }
  end
  opts.empty? || args << opts
  result_opts.empty? || result_args << result_opts
  result_args
end

#option(name, opts = {}) {|name, value| ... } ⇒ void

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



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/wrap_it/arguments.rb', line 154

def option(name, after: nil, **opts, &block)
  name.is_a?(String) && name = name.to_sym
  fail ArgumentError, 'Wrong name' unless name.is_a?(Symbol)
  @dependencies = !after.nil?
  options[name] = {
    name: name,
    conditions: Arguments.make_conditions(name, **opts),
    block: block
  }
end