wrap_it 0.2.0 → 1.0.0

data/lib/wrap_it/base.rb

@@ -19,59 +19,79 @@ module WrapIt
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   class Base
+    # Documentation includes
+    #
+    # @!parse extend  Arguments::ClassMethods
+    # @!parse extend  Enums::ClassMethods
+    # @!parse extend  HTML::ClassMethods
+    # @!parse extend  Sections::ClassMethods
+    # @!parse extend  Switches::ClassMethods
+
+    #
+    # include appropriate functionality from modules
     include DerivedAttributes
     include Callbacks
 
     callback :initialize, :capture, :render
 
+    include Arguments
     include Sections
-    include HTMLClass
-    include HTMLData
+    include HTML
     include Switches
     include Enums
     include Renderer
 
     @omit_content = false
 
-    attr_reader :tag
-    attr_reader :options
-
+    attr_reader :helper_name
+    option :helper_name
+    option :tag
     section :content, :render_arguments, :render_block
     place :content, :after, :begin
     place :render_block, :after, :begin
     place :render_arguments, :after, :begin
 
     def initialize(template, *args, &block)
-      @template, @arguments, @block = template, args, block
-      self.options = @arguments.extract_options!
-
-      @helper_name = @options.delete(:helper_name)
-      @helper_name.is_a?(String) && @helper_name = @helper_name.to_sym
-
-      @arguments.extend ArgumentsArray
+      @template, @block = template, block
       add_default_classes
-
       run_callbacks :initialize do
-        @tag = @options.delete(:tag) ||
-          self.class.get_derived(:@default_tag) || 'div'
-        @tag = @tag.to_s
+        capture_arguments!(args, &block)
+        # TODO: uncomment following after html_attr implementation finished
+        #html_attr.merge!(args.extract_options!)
+        self.html_attr = args.extract_options!
+        # TODO: find convenient way to save unprocessed arguments
+        @arguments = args
       end
     end
 
+    def tag
+      @tag ||= (self.class.get_derived(:@default_tag) || 'div').to_s
+    end
+
+    def tag=(value)
+      value.is_a?(Symbol) && value = value.to_s
+      value.is_a?(String) && @tag = value
+    end
+
+    def helper_name=(value)
+      value.is_a?(String) && value = value.to_sym
+      value.is_a?(Symbol) && @helper_name = value
+    end
+
     def omit_content?
-      self.class.get_derived(:@omit_content)
+      self.class.get_derived(:@omit_content) == true
     end
 
     #
     # Renders element to template
     #
-    # @override render([content, ...])
-    # @param  content [String] additional content that will be appended
-    #                          to element content
-    # @yield [element] Runs block after capturing element content and before
-    #                  rendering it. Returned value appended to content.
-    # @yieldparam element [Base] rendering element.
-    # @yieldreturn [String, nil] content to append to HTML
+    # @overload render([content, ...])
+    #   @param content [String] additional content that will be appended
+    #                           to element content
+    #   @yield [element] Runs block after capturing element content and before
+    #                    rendering it. Returned value appended to content.
+    #   @yieldparam element [Base] rendering element.
+    #   @yieldreturn [String, nil] content to append to HTML
     #
     # @return [String] rendered HTML for element
     def render(*args, &render_block)
@@ -110,17 +130,17 @@ module WrapIt
     #
     # If block present, it will be called when wrapper will rendered.
     #
-    # @override wrap(wrapper)
-    # @param  wrapper [Base] wrapper instance.
+    # @overload wrap(wrapper)
+    #   @param  wrapper [Base] wrapper instance.
     #
-    # @override wrap(wrapper_class, [arg, ...], options = {})
-    # @param  wrapper_class [Class] WrapIt::Base subclass for wrapper.
-    # @param  arg [String, Symbol] wrapper creation arguments.
-    # @param  options [Hash] wrapper creation options.
+    # @overload wrap(wrapper_class, [arg, ...], options = {})
+    #   @param  wrapper_class [Class] WrapIt::Base subclass for wrapper.
+    #   @param  arg [String, Symbol] wrapper creation arguments.
+    #   @param  options [Hash] wrapper creation options.
     #
-    # @override wrap([arg, ...], options = {})
-    # @param  arg [String, Symbol] wrapper creation arguments.
-    # @param  options [Hash] wrapper creation options.
+    # @overload wrap([arg, ...], options = {})
+    #   @param  arg [String, Symbol] wrapper creation arguments.
+    #   @param  options [Hash] wrapper creation options.
     #
     # @return [void]
     def wrap(*args, &block)
@@ -139,7 +159,6 @@ module WrapIt
     protected
 
     #
-    # @dsl
     # Defines or gets default tag name for element. This tag can be changed
     # soon. Without parameters returns current default_tag value.
     # @param  name [<Symbol, String>] Tag name. Converted to `String`.
@@ -158,17 +177,6 @@ module WrapIt
       @omit_content = true
     end
 
-    def options=(hash)
-      hash.is_a?(Hash) || return
-      hash.symbolize_keys!
-
-      # sanitize class
-      hash[:class] ||= []
-      hash[:class] = [hash[:class]] unless hash[:class].is_a?(Array)
-      hash[:class] = hash[:class].map { |c| c.to_s }.uniq
-      @options = hash
-    end
-
     def capture_sections
       run_callbacks :capture do
         unless @block.nil?
@@ -199,12 +207,13 @@ module WrapIt
 
     def do_render
       # cleanup options from empty values
-      @options.select! do |k, v|
+      html_attr.select! do |k, v|
         !v.nil? && (!v.respond_to?(:empty?) || !v.empty?)
       end
       @rendered = render_sections
       run_callbacks :render do
-        @rendered = content_tag(@tag, @rendered, @options)
+        options = html_attr.merge(class: html_class.to_html, data: html_data)
+        @rendered = content_tag(tag, @rendered, options)
       end
     end
 

data/lib/wrap_it/callbacks.rb

@@ -5,38 +5,57 @@ module WrapIt
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   module Callbacks
+    # Documentation includes
+    # @!parse extend  Callbacks::ClassMethods
+
+    # module implementation
+
     extend DerivedAttributes
 
+    #
     def self.included(base)
       base.extend ClassMethods
     end
 
+    #
+    # Runs specified callbacks with block
+    #
+    # Runs first `before` callbacks in inheritance order, then yields block if
+    # it given and then `after` callbacks in reverse order.
+    #
+    # @param  name [Symbol] callback name, that should be defined by
+    #   {ClassMethods#callback callback} method.
+    #
+    # @return [void]
     def run_callbacks(name)
       self.class.collect_derived("@before_#{name}").each do |cb|
         if cb.is_a?(Symbol)
-#          break if send(cb) == false # if respond_to?(cb)
           send(cb) # if respond_to?(cb)
         else
-#          break if instance_eval(&cb) == false
           instance_eval(&cb)
         end
       end
       yield if block_given?
       self.class.collect_derived("@after_#{name}").reverse.each do |cb|
         if cb.is_a?(Symbol)
-#          break if send(cb) == false # if respond_to?(cb)
           send(cb) # if respond_to?(cb)
         else
-#          break if instance_eval(&cb) == false
           instance_eval(&cb)
         end
       end
     end
 
     #
-    # Class methods to include
+    # {Callbacks} class methods
     #
     module ClassMethods
+      #
+      # Defines callback
+      #
+      # @overload callback([name, ...])
+      #   @param  name [Symbol, String] callback name
+      #
+      # @return [void]
       def callback(*args)
         args.each do |name|
           instance_eval(&Callbacks.define_callback(:before, name))

data/lib/wrap_it/capture_array.rb

@@ -0,0 +1,140 @@
+module WrapIt
+  #
+  # Adds #capture! and #capture_first! methods to array. Theese methods are
+  # extracts items from array by some conditions and returns its as separate
+  # array for #capture! and as first item for #capture_first!.
+  #
+  # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
+  #
+  module CaptureArray
+    REQUIRED_METHODS = %i(reject! find_index delete_at)
+
+    #
+    def self.included(base)
+      methods = base.methods
+      # avoid including in classes thats doen't have methods, used in
+      # inplementation
+      REQUIRED_METHODS.all? { |m| methods.include?(m) } || fail(
+        TypeError,
+        "#{self.class.name} can't be included into #{base.class.name}"
+      )
+    end
+
+    #
+    # Extracts elements from array by conditions, passed in arguments and
+    # returns theese elements as new array.
+    #
+    # Condition can be Regexp, Class, Array, lambdas and any other value.
+    # if condition contains labdas, all off them will be called before
+    # tests and results of theese calls will be used as conditions.
+    #
+    # If condition is `Regexp`, all elements of array are tested for matching
+    # to this regexp, previously converted to String by their `to_s` method. If
+    # condition is an `Array`, all elements tested if it included in these
+    # array. If the condition is a class, then elements are tested via `is_a?`
+    # method for this class. `true` and `false` conditions do exactly what it
+    # mean - `true` will satisfy condition, `false` will not. For any other
+    # value, elements are tested with equality operator `==`.
+    #
+    # You can provide a block. In this case, all arguments are ignored, and
+    # block yielded for each element of array. If block returns `true`,
+    # element extracted from array.
+    #
+    # All conditions, passed as arguments are `or`-ed so `String, Symbol` means
+    # select Symbol or String elements.
+    #
+    # You can also specify `and` option, so all tests will be and'ed with its
+    # conditions.
+    #
+    # @overload capture!([condition, ...], opts = {})
+    #   @param condition [Object] one of `or`-ed conditions for comparing
+    #   @param opts [Hash] options for extracting
+    #   @option opts [Object, Array] :and one or array of `and`-ed conditions
+    #
+    # @overload capture!(&block)
+    #   @yield [element] Gives each element of array to block. You should return
+    #     `true` to capture this element or `false` to keep it in array.
+    #   @yieldparam [Object] element element of array to inspect
+    #   @yieldreturn [Boolean] whether exclude this element or not
+    #
+    # @return [Array] array of captured elements
+    #
+    # @example capture by class
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::CaptureArray
+    #   arr.capture(String) #=> ['and', 'string']
+    #   arr                 #=> [1, 2, 3]
+    #
+    # @example capture by value
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::CaptureArray
+    #   arr.capture(1, 2) #=> [1, 2]
+    #   arr               #=> [3, 'and', 'string']
+    #
+    # @example capture by Regexp
+    #   arr = [1, 2, 3, 'and', 'string', :str]
+    #   arr.extend WrapIt::CaptureArray
+    #   arr.capture(/^str/) #=> ['string', :str]
+    #   arr                 #=> [1, 2, 3, 'and']
+    #
+    # @example capture by Array
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::CaptureArray
+    #   arr.capture([1, 10, 'and']) #=> [1, 'and']
+    #   arr                         #=> [2, 3, 'string']
+    #
+    # @example capture by block
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::CaptureArray
+    #   arr.capture {|x| x < 3} #=> [1, 2]
+    #   arr                     #=> [3, 'and', 'string']
+    #
+    # @example capture with `and` condition
+    #   arr = [1, 2, 3, 'and', 'string', :str]
+    #   arr.extend WrapIt::CaptureArray
+    #   arr.capture(String, and: [/^str/]) #=> ['string']
+    #   arr                                #=> [1, 2, 3, 'and', :str]
+    def capture!(*args, &block)
+      captureed = []
+      reject! do |arg|
+        do_compare(arg, *args, &block) && (captureed << arg) && true
+      end
+      captureed
+    end
+
+    #
+    # Extracts first element from array that is satisfy conditions, passed in
+    # arguments and returns these element.
+    #
+    # @see #capture!
+    def capture_first!(*args, &block)
+      index = find_index { |arg| do_compare(arg, *args, &block) }
+      index.nil? ? nil : delete_at(index)
+    end
+
+    private
+
+    def do_compare(target, *compare_args, &block)
+      if block_given?
+        yield target
+      else
+        options = compare_args.extract_options!
+        compare_args.map! { |x| x.is_a?(Proc) && x.lambda? ? x.call : x }
+        result = compare_args.any? do |dest|
+          case
+          when dest == true || dest == false then dest
+          when dest.is_a?(Array) then dest.include?(target)
+          when dest.is_a?(Regexp) then dest.match(target.to_s)
+          when dest.is_a?(Class) then target.is_a?(dest)
+          when dest.is_a?(Proc) then dest.call(dest) == true
+          else dest == target
+          end
+        end
+        if options[:and].is_a?(Array)
+          result &&= do_compare(target, *options[:and])
+        end
+        result
+      end
+    end
+  end
+end

data/lib/wrap_it/container.rb

@@ -4,7 +4,8 @@ module WrapIt
   #
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
-  # TODO: single_child
+  # @todo  single_child realization
+  # @todo  refactor code for more clearness
   class Container < Base
     switch :deffered_render do |_|
       # avoid changing deffered_render after any child added
@@ -15,27 +16,64 @@ module WrapIt
       end
     end
 
+    # list of children elements
     attr_reader :children
+
+    # children can be extracted from normal template flow and rendered in
+    # separate section.
     attr_writer :extract_children
+
     section :children
 
     def extract_children?
       @extract_children == true
     end
 
-    after_initialize do
+    before_initialize do
       @children = []
-      self.class.extract_from_options.each do |option, name|
-        args = options.delete(option)
-        next if args.nil?
-        args = [args] unless args.is_a?(Array)
-        self.deffered_render = true
-        send(name, *args)
-      end
     end
 
     #
-    # Defines child elements helper for creation of child items.
+    # Defines helper for child elements creation.
+    #
+    # @example  simple usage
+    #   class Item < WrapIt::Base
+    #     include TextContainer
+    #   end
+    #
+    #   class List < WrapIt::Container
+    #     default_tag 'ul'
+    #     child :item, tag: 'li'
+    #   end
+    #
+    #   list = List.new(template)
+    #   list.item 'list item 1'
+    #   list.item 'list item 2'
+    #   list.render # => '<ul><li>list item 1'</li><li>list item 2</li></ul>'
+    #
+    # @example  with option
+    #   class Button < WrapIt::Container
+    #     include TextContainer
+    #     html_class 'btn'
+    #     child :icon, tag: 'i', option: true
+    #   end
+    #
+    #   btn = Button.new(template, 'Home', icon: { class: 'i-home' })
+    #   btn.render # => '<div class="btn">Home<i class="i-home"></i></div>'
+    #
+    # @overload child(name, class_name = nil, [args, ...], opts = {}, &block)
+    #   @param name [Symbol, String] helper method name
+    #   @param class_name [String, Base] class for child elements. If ommited
+    #     WrapIt::Base will be used
+    #   @param args [Object] any arguments that will be passed to child
+    #     element constructor
+    #   @param opts [Hash] options
+    #   @option opts [true, Symbol] :option if specified, child can be created
+    #     via option with same name (if :option is true) or with specified
+    #     name
+    #   @option opts [Symbol] :section section to that this children will be
+    #     rendered. By default children rendered to `children`. Refer to
+    #     {Sections} module for details.
     #
     # @return [String]
     def self.child(name, *args, &block)
@@ -48,8 +86,11 @@ module WrapIt
           'WrapIt::Base'
         end
       child_class = child_class.name if child_class.is_a?(Class)
-      @helpers ||= []
-      @helpers << name
+
+      opts = args.extract_options!
+      extract = opts.delete(:option)
+      args << opts
+
       define_method name do |*helper_args, &helper_block|
         # We should clone arguments becouse if we have loop in template,
         # `extract_options!` below works only for first iterration
@@ -60,20 +101,21 @@ module WrapIt
         helper_args += default_args + [options]
         add_children(name, child_class, block, *helper_args, &helper_block)
       end
-    end
 
-    def self.extract_from_options(*args)
-      return @extract_from_options || [] if args.size == 0
-      hash = args.extract_options!
-      args.size.odd? && fail(ArgumentError, 'odd arguments number')
-      args.each_with_index { |arg, i| i.even? && hash[arg] = args[i + 1] }
-      @helpers ||= []
-      hash.symbolize_keys!
-      @extract_from_options = Hash[
-        hash.select do |k, v|
-          (v.is_a?(String) || v.is_a?(Symbol)) && @helpers.include?(k)
-        end.map { |k, v| [k, v.to_sym] }
-      ]
+      unless extract.nil?
+        extract.is_a?(Array) || extract = [extract]
+        extract.each do |opt_name|
+          opt_name = name if opt_name == true
+          option(opt_name) do |_, arguments|
+            self.deffered_render = true
+            arguments.is_a?(Array) || arguments = [arguments]
+            o = arguments.extract_options!
+            o.merge!(extracted: true)
+            arguments << o
+            send name, *arguments
+          end
+        end
+      end
     end
 
     after_capture do
@@ -106,6 +148,7 @@ module WrapIt
     def add_children(name, helper_class, class_block, *args, &helper_block)
       options = args.extract_options!
       section = options.delete(:section) || :children
+      extracted = options.delete(:extracted) == true
       args << options
       item = Object
         .const_get(helper_class)
@@ -120,6 +163,7 @@ module WrapIt
       class_block.nil? || instance_exec(item, &class_block)
 
       deffered_render? && @children << item
+      return if extracted
       if !deffered_render? && (omit_content? || extract_children?)
         self[section] << capture { item.render }
       end