wrap_it 0.2.0 → 1.0.0

data/lib/wrap_it/derived_attributes.rb

@@ -5,33 +5,49 @@ module WrapIt
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   module DerivedAttributes
+    # Documentation includes
+    # @!parse extend  DerivedAttributes::ClassMethods
+
+    # module implementation
+
+    #
     def self.included(base)
       base.extend ClassMethods
     end
 
     #
-    # Class methods to include
+    # {DerivedAttributes} class methods
     #
     module ClassMethods
+      #
+      # retrieves first founded derived variable or nil
+      # @param  name [Symbol] variable name (should contain `@` sign)
+      #
+      # @return [Object, nil] founded variable or nil
       def get_derived(name)
         return instance_variable_get(name) if instance_variable_defined?(name)
         ancestors.each do |ancestor|
-          break if ancestor == Object
           next unless ancestor.instance_variable_defined?(name)
+          break if ancestor == Base
           return ancestor.instance_variable_get(name)
         end
         nil
       end
 
+      #
+      # Collects all derived variables with specified name
+      # @param  name [Symbol] variable name (should contain `@` sign)
+      # @param  initial [Object] initial collection object
+      # @param  method [Symbol] collection's method name to concatinate
+      #   founded variable with collection
+      #
+      # @return [Object] collection of variables
       def collect_derived(name, initial = [], method = :concat)
         result = initial
-        # if instance_variable_defined?(name)
-        #  result = result.send(method, instance_variable_get(name))
-        # end
         ancestors.each do |ancestor|
-          break if ancestor == Object
           next unless ancestor.instance_variable_defined?(name)
           result = result.send(method, ancestor.instance_variable_get(name))
+          break if ancestor == Base
         end
         result
       end

data/lib/wrap_it/enums.rb

@@ -5,47 +5,38 @@ module WrapIt
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   module Enums
+    # Documentation includes
+    # @!parse extend  Enums::ClassMethods
+
+    # module implementation
+
     extend DerivedAttributes
 
+    #
     def self.included(base)
       base == Base || fail(
         TypeError,
         "#{self.class.name} can be included only into WrapIt::Base"
       )
-      base.extend ClassMethods
-      base.after_initialize :enums_init
-    end
+      base.class_eval do
+        extend ClassMethods
 
-    private
+        before_initialize { @enums = {} }
 
-    def enums_init
-      @enums = {}
-      opt_keys = @options.keys
-      enums.each do |name, opts|
-        value = nil
-        names = [name] + [opts[:aliases] || []].flatten
-        opt_keys.select { |o| names.include? o }.each do |key|
-          tmp = @options.delete(key)
-          value ||= tmp
-          !value.nil? && !opts[:values].include?(value) && value = nil
-        end
-        @arguments.extract!(Symbol, and: [opts[:values]]).each do |key|
-          value ||= key
+        before_capture do
+          self.class.collect_derived(:@enums, {}, :merge).each do |name, e|
+            next unless e.key?(:default) && !@enums.key?(name)
+            send("#{name}=", e[:default])
+          end
         end
-        send("#{name}=", value)
       end
     end
 
-    def enums
-      @enums_hash ||= self.class.collect_derived(:@enums, {}, :merge)
-    end
-
     #
-    # Class methods to include
+    # {Enums} class methods
     #
     module ClassMethods
       #
-      # @dsl
       # Adds `enum`. When element created, creation arguments will be scanned
       # for `Symbol`, that included contains in `values`. If it founded, enum
       # takes this value. Also creation options inspected. If its  contains
@@ -60,16 +51,26 @@ module WrapIt
       #
       # This method also adds getter and setter for this enum.
       #
+      # @example
+      #   class Button < WrapIt::Base
+      #     enum :style, %i(red green black), html_class_prefix: 'btn-'
+      #   end
+      #
+      #   btn = Button.new(template, :green)
+      #   btn.render # => '<div class="btn-green">'
+      #   btn = Button.new(template, style: :red)
+      #   btn.render # => '<div class="btn-red">'
+      #
       # @param  name [String, Symbol] Enum name. Converted to `Symbol`.
-      # @param  options [Hash] Enum options
-      # @options options [String, Symbol] :html_class_prefix prefix of HTML
+      # @param  opts [Hash] Enum options
+      # @option opts [String, Symbol] :html_class_prefix prefix of HTML
       #   class that will automatically added to element if enum changes its
       #   value.
-      # @options options [Boolean] :html_class whether this enum changes
+      # @option opts [Boolean] :html_class whether this enum changes
       #   should affect to html class.
-      # @options options [Symbol, Array<Symbol>] :aliases list of enum aliases.
+      # @option opts [Symbol, Array<Symbol>] :aliases list of enum aliases.
       #   Warning! Values are not converted - pass only `Symbols` here.
-      # @options options [String, Symbol] :default default value for enum,
+      # @option opts [String, Symbol] :default default value for enum,
       #   if nil or wrong value given. Converted to `Symbol`.
       # @yield [value] Runs block when enum value changed, gives it to block.
       # @yieldparam value [Symbol] New enum value.
@@ -90,25 +91,34 @@ module WrapIt
           opts[:regexp] = /\A#{prefix}(?:#{values.join('|')})\z/
           opts[:html_class_prefix] = prefix
         end
-        define_method("#{name}") { @enums[name] }
+        define_method("#{name}") { @enums[name] ||= opts[:default] }
         define_method("#{name}=", &Enums.setter(name, &block))
         @enums ||= {}
+
+        o_params = {}
+        if opts.key?(:aliases)
+          aliases = [opts[:aliases]].flatten.compact
+          o_params[:if] = [name] + aliases
+        end
+
         @enums[name] = opts
+        option(name, **o_params) { |_, v| send("#{name}=", v) }
+        argument(name, if: Symbol, and: values) { |_, v| send("#{name}=", v) }
       end
     end
 
     private
 
     def self.setter(name, &block)
-      proc do |value|
-        opts = enums[name]
+      ->(value) do
+        opts = self.class.collect_derived(:@enums, {}, :merge)[name]
         v = value if opts[:values].include?(value)
         v ||= opts[:default] if opts.key?(:default)
         @enums[name] = v
         block.nil? || instance_exec(v, &block)
         if opts.key?(:regexp)
-          remove_html_class(opts[:regexp])
-          v.nil? || add_html_class("#{opts[:html_class_prefix]}#{v}")
+          html_class.delete(opts[:regexp])
+          v.nil? || html_class << "#{opts[:html_class_prefix]}#{v}"
         end
       end
     end

data/lib/wrap_it/frameworks.rb

@@ -1,7 +1,9 @@
-#
-# Framework detection methods
-#
 module WrapIt
+  #
+  # Framework detection methods
+  #
+
+  # @private
   def self.framework
     return @framework unless @framework.nil?
     gems = Gem.loaded_specs.keys
@@ -14,10 +16,12 @@ module WrapIt
     end
   end
 
+  # @private
   def self.rails?
     framework == :rails
   end
 
+  # @private
   def self.sinatra?
     framework == :sinatra
   end

data/lib/wrap_it/helpers.rb

@@ -1,9 +1,64 @@
 #
-# Helper registering
+# Registering helpers
+#
+# To use your classes and helpers in templates you should register your
+# library. First, in your framework initialization, you should register
+# your library in WrapIt. You can have separate module for it or WrapIt
+# will make anonymous one. After this, your module will have `register`
+# and `unregister` methods to register your classes.
+#
+# @example usual case - library in separate module
+#   # initialization time
+#   module Library
+#     module Helpers; end
+#   end
+#   WrapIt.register_module Library::Helpers, prefix: 'lib_'
+#
+#   # controller
+#   class MyController < ApplicationController
+#     helper Library::Helpers
+#   end
+#
+#   # implementation
+#   module Library
+#     module Helpers
+#       class Button < WrapIt::Base
+#         ...
+#       end
+#
+#       register :super_button, Button
+#     end
+#   end
+#
+#   # in template:
+#   <%= lib_super_button 'text' %>
+#
+# @example anonymous module
+#   helpers = WrapIt.register_module prefix: 'lib_'
+#
+#   class Button < WrapIt::Base
+#     ...
+#   end
+#
+#   helpers.register :super_button, Button
+#
+#   class MyController
+#     helper helpers
+#   end
 #
 # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
 #
 module WrapIt
+  #
+  # Registers helpers module
+  #
+  # @overload register_module(mod = nil, opts = {})
+  #   @param  mod [Module] module for register. Anonymous module will be
+  #     created if ommited.
+  #   @param  opts [Hash] options
+  #   @option opts [String] :prefix prefix for helper methods
+  #
+  # @return [void]
   def self.register_module(*args)
     options = args.extract_options!
     options.symbolize_keys!
@@ -17,6 +72,16 @@ module WrapIt
     mod
   end
 
+  # @!method register([name, ...], class_name)
+  # adds to template list of helpers for creating elements of specified class
+  # @param name [Symbol, String] name of helper. Will be prefixed with prefix
+  #   option, specified in {WrapIt#register_module} call.
+  # @param class_name [String, Class] element class
+
+  # @!method unregister([name, ...])
+  # removes list of helpers from template
+  # @param name [Symbol, String] name of helper to remove from tampate
+
   private
 
   def self.register_block(options)

data/lib/wrap_it/html.rb

@@ -0,0 +1,149 @@
+require File.join %w(wrap_it html_class)
+require File.join %w(wrap_it html_data)
+
+module WrapIt
+  #
+  # Methods for manipulationg with HTML class. For internal usage.
+  # You should not include this class directly - subclass from
+  # `WrapIt::Base` instead.
+  #
+  # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
+  #
+  module HTML
+    # Documentation includes
+    # @!parse extend  HTML::ClassMethods
+
+    # module implementation
+
+    extend DerivedAttributes
+
+    #
+    def self.included(base)
+      base == Base || fail(
+        TypeError,
+        "#{self.class.name} can be included only into WrapIt::Base"
+      )
+      base.class_eval do
+        extend ClassMethods
+
+        option(:class) { |_, v| self.html_class << v }
+
+        # TODO: extend hashes for html_attr and html_data
+        before_initialize do
+          html_class
+          @html_attr ||= {}
+          @html_data ||= {}
+        end
+      end
+    end
+
+    # TODO: actually we should have separate setter and merge (see Base)
+    #
+    # Sets HTML attributes hash.
+    #
+    # Actually it merges its with current
+    # attributes. To remove some attributes use `html_attr.delete(:attr)`.
+    # extracts HTML class and data from provided hash and places its to
+    # appropriate holder
+    #
+    # @param  hash [Hash] attributes
+    #
+    # @return [Hash] resulting attributes
+    def html_attr=(hash)
+      return unless hash.is_a?(Hash)
+      hash.symbolize_keys!
+      html_class << hash.delete(:class)
+      html_data.merge(hash.delete(:data) || {})
+      (@html_attr ||= {}).merge!(hash)
+    end
+
+    #
+    # Retrieves HTML attributes hash (without HTML class and HTML data)
+    #
+    # @return [Hash] attributes
+    def html_attr
+      @html_attr ||= {}
+    end
+
+    #
+    # Retrieves HTML data hash
+    #
+    # @return [Hash] data
+    def html_data
+      @html_data ||= {}
+    end
+
+    #
+    # HTML class prefix getter
+    #
+    # This prefix used in enums to combine HTML classes.
+    #
+    # @return [String] HTML class prefix.
+    def html_class_prefix
+      @html_class_prefix ||= self.class.html_class_prefix
+    end
+
+    #
+    # Sets HTML class(es) for element
+    #
+    # @example
+    #   element.html_class = [:a, 'b', ['c', :d, 'a']]
+    #   element.html_class #=> ['a', 'b', 'c', 'd']
+    #
+    # @param  value [Symbol, String, Array<Symbol, String>] HTML class or list
+    #   of classes. All classes will be converted to Strings, duplicates are
+    #   removed. Refer to {HTMLClass} description for details.
+    # @return [HTMLClass] resulting html class
+    def html_class=(value)
+      @html_class = HTMLClass.new(value)
+    end
+
+    #
+    # Retrieves HTML class of element
+    #
+    # See {HTMLClass} for details
+    #
+    # @return [HTMLClass] HTML class of element
+    def html_class
+      @html_class ||= HTMLClass.new
+    end
+
+    protected
+
+    def add_default_classes
+      html_class << self.class.collect_derived(
+        :@html_class, HTMLClass.new, :<<
+      )
+    end
+
+    #
+    # {HTML} class methods
+    #
+    module ClassMethods
+      #
+      # Adds default html classes, thats are automatically added when element
+      # created.
+      # @overload html_class([html_class, ...])
+      #   @param  html_class [String, Symbol, Array<String, Symbol>] HTML class.
+      #     Converted to `String`
+      #
+      # @return [void]
+      def html_class(*args)
+        (@html_class ||= HTMLClass.new) << args
+      end
+
+      #
+      # Sets HTML class prefix. It used in switchers and enums
+      # @param  prefix [String] HTML class prefix
+      #
+      # @return [void]
+      def html_class_prefix(prefix = nil)
+        return(get_derived(:@html_class_prefix) || '') if prefix.nil?
+        prefix.is_a?(Symbol) && prefix = prefix.to_s
+        prefix.is_a?(String) || fail(ArgumentError,
+                                     'prefix should be a String or Symbol')
+        @html_class_prefix = prefix
+      end
+    end
+  end
+end