wrap_it 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7f693b3a5912624587905a8f0ed50eed00090900
+  data.tar.gz: 454f1f68671d59f445b878c52b0cbc690f9e5dfb
+SHA512:
+  metadata.gz: 045a82e459f67f7883c5609789c8bdbb74714eabeae1cf174e9b5979963e62fb24818db29d3d3e8652197705dd2d71110c75a84866907fc78f844604c91b6723
+  data.tar.gz: 650c0ecd43f82eaefe4075d4bb3828fc0dd76774b6fa533b5a7e7965b6b60324dc386eab34417524f806f65edcfba5592c3ca3639a7ce54e5903e24011312042

data/.gitignore

@@ -0,0 +1,11 @@
+.rspec
+Gemfile.lock
+
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*.log
+/tmp
+

data/.rubocop.yml

@@ -0,0 +1,5 @@
+MethodLength:
+  Max: 20
+
+CyclomaticComplexity:
+  Max: 7

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test, :development do
+  gem 'rails', require: false
+end

data/README.md

@@ -0,0 +1,277 @@
+# WrapIt
+
+This library provides set of classes and modules with simple DSL for quick and easy creating html helpers with your own DSL. It's usefull for implementing CSS frameworks, or making your own.
+
+For example, your designer makes perfect button style for some site. This element will appears in many places of site in some variations. The button have `danger`, `success` and `default` look, and can have `active` state. Button can have some icon. So, you make some CSS styles, and now you should place HTML markup of this element in many places of site. With `wrap_it` library you can do it with following code:
+
+```ruby
+class PerfectButton < WrapIt::Container
+  include TextContainer
+  html_class 'button'
+  enum :look, [:default, :success, :danger], html_class_prefix: 'button-'
+  switch :active, html_class: 'button-active'
+  child :icon, [tag: 'img', class: 'button-icon']
+end
+
+WrapIt.register :p_button, 'PerfectButton'
+```
+
+Now, include this helper into you template engine. For Rails:
+
+```ruby
+class MyController < ApplicationController
+  helper WrapIt.helpers
+  ...
+end
+```
+
+And you can use it in you ERB:
+
+```html
+<%= p_button %>button 1<% end %>
+<%= p_button 'button 2', :active, :success %>
+<%= p_button active: true, look: :success, body: 'button 3' %>
+<%= p_button :danger do |b| %>
+  <%= b.icon src: '/path/to/icon.png' %>
+  button 4
+<% end %>
+```
+
+This will produce following code:
+
+```html
+<div class="button">button 1</div>
+<div class="button button-active button-success">button 2</div>
+<div class="button button-active button-success">button 3</div>
+<div class="button button-danger">
+  <img class="button-icon" src="/path/to/icon.png">
+  button 4
+</div>
+```
+
+Note, that lines 2 and 3 produces same html markup.
+
+# Status
+
+Project in pre-release state. First release version `1.0.0` planned to February of 2014.
+
+# Installation
+
+Library have a gem. So, just install it:
+
+```sh
+gem install wrap_it
+```
+
+or include in your `Gemfile`
+
+```ruby
+gem 'wrap_it'
+```
+
+and run
+
+```sh
+bundle install
+```
+
+# Configuration
+
+Library have no specific configuration.
+
+# Usage
+
+All helpers classes derived from `WrapIt::Base` class, that provides allmost all functionality. For helpers, thats includes other helpers, use `WrapIt::Container` class. Where are some library-specific methods, defined directly in `WrapIt` module.
+
+Simple example explained above. More complex usage is to provide some logic to initalization, capturing and rendering process. To do this, use `after` or `before` `initialize`, `capture` and `reder` callbacks respectively. Usually `after` callbacks used. `initialize` callbacks runs around arguments and optioins parsed, `capture` callbacks runs around capturing content of element and `render` callbacks runs around wrapping content into element tag.
+
+Inside callbacks some usefull instance variables available.
+
+`@tag` contains tag name for element.
+
+`@options` contains creation options hash. This hash also contains `:class` key with current set of HTML classes. But its recommended to use class-aware methods to manipulate html classes (see below). **Warning!** You **MUST** remove from this hash all your class-specific user options, because this hash will be used as list of HTML attributes of element.
+
+`@arguments` array available only in `after_initialize` callback and contains creation arguments. Its recommended to extract arguments, related to your class from this array if you plan to subclass your helper in future, so when subclasses `after_initialize` called these arguments will not available there.
+
+`@content` string available in `capture` and `render` callbacks and contains captured content. You can change it to any value. If you want to render some html markup with `@content`, use `html_safe` method (see below) to prevent HTML escaping.
+
+`@template` contains rendering template. Use this variable carefully, so if you call `@template.content_tag` or something else Rails-related, your library will not be portable to other frameworks. So, if you use this gem in user-end application, or Rails-only library, you are free to use all of `@template` methods.
+
+*Examples*
+
+Prevent user from changing element tag:
+
+```ruby
+class Helper < WrapIt::Base
+  after_initialize { @tag = 'table' }
+end
+```
+
+Including some simple HTML into content
+
+```ruby
+class Helper < WrapIt::Base
+  after_initialize do
+    @icon = optioins.delete(:icon)
+  end
+
+  after_capture do
+    unless @icon.nil?
+      @content = html_safe("<i class=\"#{@icon}\"></i>") + @content
+    end
+  end
+```
+
+## WrapIt
+
+#### WrapIt.register(*args)
+
+Registers helper class. In arguments, first specify helper method names as `Symbols` and in last argument fully qualified helper class name as `String`.
+
+#### WrapIt.unregister(*args)
+
+Unregisters helper class. Just pass list of method names as `Symbols`.
+
+#### WrapIt.helpers
+
+Returns a module, that contains all registered helpers. Usefull to provide all helpers to template engine.
+
+## WrapIt::Base
+
+### DSL methods
+
+#### default_tag(name)
+
+Use `default_tag` DSL method inside your class to specify HTML tag name for element. This tag can be changed soon by you or user. `name` can be `Symbol` or `String` and it converted to `String`.
+
+#### html_class(*args)
+
+Use `html_class` DSL method to add default html classes, thats are automatically added when element created.
+
+#### omit_content
+
+Once this method called from class, this class will ommit any text content, captured from template. For example, `<%= element do %><p>Any content</p><% end %>` normally will produce `<div><p>Any content</p></div>`. In some cases you whant to drop `<p>Any content</p>`, for exmaple, inside tables.
+
+#### switch(name, options = {}, &block)
+
+Adds `switch`. Switch is a boolean flag. When element created, creation arguments will be scanned for `Symbol`, that equals to `name`. If it founded, switch turned on. Also creation options inspected. If its contains `name: true` key-value pair, this pair removed from options and switch also turned on. `name` can be `Symbol` or `String` and it converted to `Symbol`.
+
+This method also adds getter and setter for this switch in form `name?` and `name=` respectively.
+
+You can pass `html_class` option. If it presend, this class will be added or removed to element when switch changes its state.
+
+Also `aliases` option available. So if some of aliases founded in arguments it also changes switch state. You should pass only `Symbol` or `Array` if symbols to this optioin.
+
+If block given, it will be called each time switch changes its state in context of element with the switch state as argument.
+
+#### enum(name, options = {}, &block)
+
+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 `name: value` key-value pair with valid value, this pair removed from options and enum takes this value.
+
+This method also adds getter and setter for this enum.
+
+You can pass `html_class_prefix` option. If it present, HTML class will be combined from it and enum value and added or removed from element HTML class.
+
+Also `aliases` option available. So if some of aliases founded in creation options keys it also changes enum value. You should pass only `Symbol` or `Array` if symbols to this optioin.
+
+`default` option sets default value for enum. This value will used if nil or invalid value assigned to enum.
+
+If block given, it will be called each time enum changes its value in context of element with the new value as argument.
+
+### Instance methods
+
+#### html_class
+
+Returns array of html classes
+
+#### html_class=(*args)
+
+Sets html class(es) for element. Arguments can be `String`, `Symbol` or `Array` of it. All converted to plain array of `Symbols`. Duplicated classes removed.
+
+#### add_html_class(*args)
+
+Adds html class. For args see `#html_class=`
+
+#### remove_html_class(*args)
+
+Removes html class. For args see `#html_class=`
+
+#### html_class?(*args, &block)
+
+Determines whether element contains class, satisfied by conditions, specified in method arguments.
+
+There are two forms of method call: with list of conditions as arguments and with block for comparing. Method makes comparison with html class untill first `true` return value or end of list. All conditions should be satisfied for `true` return of this method.
+
+In first form, each argument treated as condition. Condition can be a `Regexp`, so html classes of element tested for matching to that regular expression. If condition is an `Array` then every class will be tested for presence in this array. If condition is `Symbol` or `String` classes will be compared with it via equality operator `==`.
+
+In second form all arguments are ignored and for each comparison given block called with html class as argument. Block return value then used.
+
+*Examples*
+
+```ruby
+# with `Symbol` or `String` conditions
+element.html_class = [:a, :b, :c]
+element.html_class?(:a)       #=> true
+element.html_class?(:d)       #=> false
+element.html_class?(:a, 'b')  #=> true
+element.html_class?(:a, :d)   #=> false
+
+# with `Regexp` conditions
+element.html_class = [:some, :test]
+element.html_class?(/some/)         #=> true
+element.html_class?(/some/, /bad/)  #=> false
+element.html_class?(/some/, :test)  #=> true
+
+# with `Array` conditions
+element.html_class = [:a, :b, :c]
+element.html_class?(%w(a d)) #=> true
+element.html_class?(%w(e d)) #=> false
+
+# with block
+element.html_class = [:a, :b, :c]
+element.html_class? { |x| x == 'a' } #=> true
+```
+
+#### no_html_class?(*args, &block)
+
+Determines whether element doesn't contains class, satisfied by conditions, specified in method arguments. See `html_class?`.
+
+## WrapIt::Container
+
+### DSL methods
+
+#### child(*args, &block)
+
+Creates your own DSL method to create child items. In arguments, you should specify list of method names (aliases if more that one). Then you can specify class name for shild. If ommited, `WrapIt::Base` will be used. and as last argument you can specify array of arguments, that will be passed to child constructor. This array will be mixed with arguments, specified by user, with higher priority. At last, you can define block, that will be called after creating child, but before its rendering. This child passed as argument to block.
+
+# Todo
+
+* Enlarge library functionality
+* Strong testing
+* Finish Sinatra integration
+* Rubydoc documentation
+
+# License
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Alexey Ovchinnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_tasks'
+# require 'yard'
+require 'rspec/core/rake_task'
+# require 'rake/testtask'
+
+# Rake::TestTask.new do |t|
+#   t.name = :spec_rails
+#   t.libs.push "spec_rails"
+#   t.test_files = FileList['spec_rails/**/*_spec.rb']
+#   t.verbose = true
+# end
+
+#YARD::Rake::YardocTask.new
+RSpec::Core::RakeTask.new

data/config.ru

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development

data/lib/wrap_it/arguments_array.rb

@@ -0,0 +1,128 @@
+module WrapIt
+  #
+  # Adds #extract! and #extarct_first! methods to array. Theese methods are
+  # extracts items from array by some condirions and returns its as separate
+  # array for #extract! and as first item for #extract_first!.
+  #
+  # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
+  #
+  module ArgumentsArray
+    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 nad
+    # returns theese elements as new array.
+    #
+    # Condition can be Regexp, class, Array and any other value. 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. 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.
+    #
+    # @overload extract!([condition, ..., options])
+    # @param [Object] condition one of `or`-ed conditions for comparing
+    # @param [Hash] options options for axtracting
+    # @options options [Object, Array] :and one or array of `and`-ed conditions
+    #
+    # @overload extract!(&block)
+    # @yield [element] Gives each element of array to block. You should return
+    #   `true` to extract 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 extracted elements
+    #
+    # @example extract by class
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::ArgumentsArray
+    #   arr.extract(String) #=> ['and', 'string']
+    #   arr                 #=> [1, 2, 3]
+    #
+    # @example extract by value
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::ArgumentsArray
+    #   arr.extract(1, 2) #=> [1, 2]
+    #   arr               #=> [3, 'and', 'string']
+    #
+    # @example extract by Regexp
+    #   arr = [1, 2, 3, 'and', 'string', :str]
+    #   arr.extend WrapIt::ArgumentsArray
+    #   arr.extract(/^str/) #=> ['string', :str]
+    #   arr                 #=> [1, 2, 3, 'and']
+    #
+    # @example extract by Array
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::ArgumentsArray
+    #   arr.extract([1, 10, 'and']) #=> [1, 'and']
+    #   arr                         #=> [2, 3, 'string']
+    #
+    # @example extract by block
+    #   arr = [1, 2, 3, 'and', 'string']
+    #   arr.extend WrapIt::ArgumentsArray
+    #   arr.extract {|x| x < 3} #=> [1, 2]
+    #   arr                     #=> [3, 'and', 'string']
+    #
+    # @example extract with `and` condition
+    #   arr = [1, 2, 3, 'and', 'string', :str]
+    #   arr.extend WrapIt::ArgumentsArray
+    #   arr.extract(String, and: [/^str/]) #=> ['string']
+    #   arr                                #=> [1, 2, 3, 'and', :str]
+    def extract!(*args, &block)
+      extracted = []
+      reject! do |arg|
+        do_compare(arg, *args, &block) && extracted << arg && true
+      end
+      extracted
+    end
+
+    #
+    # Extracts first element from array that is satisfy conditions, passed in
+    # arguments and returns these element.
+    #
+    # @see #extract!
+    def extract_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)
+      if block_given?
+        yield target
+      else
+        options = compare_args.extract_options!
+        result = compare_args.any? do |dest|
+          case
+          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)
+          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/base.rb

@@ -0,0 +1,108 @@
+module WrapIt
+  #
+  # Base class for all HTML helper classes
+  #
+  # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
+  #
+  class Base
+    include DerivedAttributes
+    include Callbacks
+
+    callback :initialize, :capture, :render
+
+    include HTMLClass
+    include Switches
+    include Enums
+    include Renderer
+
+    @omit_content = false
+
+    attr_reader :tag
+    attr_reader :options
+
+    def initialize(template, *args, &block)
+      @template, @arguments, @block = template, args, block
+      self.options = @arguments.extract_options!
+      @arguments.extend ArgumentsArray
+      add_default_classes
+      run_callbacks :initialize do
+        @tag = @options.delete(:tag) ||
+          self.class.get_derived(:@default_tag) || 'div'
+        @helper_name = @options.delete(:helper_name)
+        @helper_name.is_a?(String) && @helper_name = @helper_name.to_sym
+      end
+      @argument = nil
+    end
+
+    def omit_content?
+      self.class.get_derived(:@omit_content)
+    end
+
+    def render(*args, &render_block)
+      # return cached copy if it available
+      return @content unless @content.nil?
+      @content = empty_html
+
+      # capture content from block
+      do_capture
+      # add to content string args and block result if its present
+      args.flatten.each { |a| @content << a if a.is_a? String }
+      block_given? && @content << instance_exec(self, &render_block)
+
+      # cleanup options from empty values
+      @options.select! { |k, v| !v.nil? && !v.empty? }
+      # render element
+      run_callbacks :render do
+        @content = content_tag(@tag, @content, @options)
+      end
+
+#      @content = @wrapper.render(@content.html_safe) if @wrapper.is_a?(Base)
+      if @template.output_buffer.nil?
+        # when render called from code, just return content as a String
+        @content
+      else
+        # in template context, write content to templates buffer
+        concat(@content)
+        empty_html
+      end
+    end
+
+    protected
+
+    #
+    # @dsl
+    # Defines default tag name for element. This tag can be changed soon.
+    # @param  name [<Symbol, String>] Tag name. Converted to `String`.
+    #
+    # @return [void]
+    def self.default_tag(name)
+      name.is_a?(String) || name.is_a?(Symbol) ||
+        fail(ArgumentError, 'Tag name should be a String or Symbol')
+      @default_tag = name.to_s
+    end
+
+    def self.omit_content
+      @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 do_capture
+      run_callbacks :capture do
+        @content ||= empty_html
+        unless @block.nil? || omit_content?
+          @content << (capture(self, &@block) || empty_html)
+        end
+      end
+    end
+  end
+end

data/lib/wrap_it/callbacks.rb

@@ -0,0 +1,63 @@
+module WrapIt
+  #
+  # Callbacks implementation
+  #
+  # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
+  #
+  module Callbacks
+    def self.included(base)
+      extend DerivedAttributes
+      base.extend ClassMethods
+    end
+
+    def run_callbacks(name)
+      self.class.collect_derived("@before_#{name}".to_sym).each do |cb|
+        if cb.is_a?(Symbol)
+          send(cb)# if respond_to?(cb)
+        else
+          instance_eval(&cb)
+        end
+      end
+      yield if block_given?
+      self.class.collect_derived("@after_#{name}".to_sym).reverse.each do |cb|
+        if cb.is_a?(Symbol)
+          send(cb)# if respond_to?(cb)
+        else
+          instance_eval(&cb)
+        end
+      end
+    end
+
+    #
+    # Class methods to include
+    #
+    module ClassMethods
+      def callback(*args)
+        args.each do |name|
+          instance_eval(&Callbacks.define_callback(:before, name))
+          instance_eval(&Callbacks.define_callback(:after, name))
+        end
+      end
+    end
+
+    private
+
+    def self.define_callback(time, name)
+      m_name = "#{time}_#{name}".to_sym
+      var = "@#{m_name}".to_sym
+      proc do
+        define_singleton_method(m_name) do |method = nil, &block|
+          return if block.nil? && !method.is_a?(Symbol)
+          arr =
+            if instance_variable_defined?(var)
+              instance_variable_get(var)
+            else
+              instance_variable_set(var, [])
+            end
+          arr << (block || method)
+          instance_variable_set(var, arr)
+        end
+      end
+    end
+  end
+end