simple_style_sheet 0.0.1

data/Changelog

@@ -0,0 +1,2 @@
+0.0.1 (February 21, 2012)
+  Initial release.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Jacek Mikrut
+
+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/README.md

@@ -0,0 +1,144 @@
+SimpleStyleSheet
+================
+
+SimpleStyleSheet is a Ruby gem that **parses a CSS-like Hash style sheet** and then **allows searching for property values of given HTML-like tags**. Tag and property names, as well as their meaning, are up to the gem user.
+
+Usage and details
+-----------------
+
+### 1. Style sheet preparation
+
+The style sheet is just a CSS-like Hash object. Its keys are either property names or selectors, and values are either property values or nested Hash objects.
+
+##### Property names
+
+Property names can be objects of any class and their meaning is up to the user. Most often, they would be String or Symbol instances with content that is some formatting-related property name, like "background-color".
+
+##### Property values
+
+The values can also be any objects, except for Hash objects, which are interpreted as nested style sheet definitions.
+
+##### Selectors
+
+A selector is a String object that contains one or more custom **tag names**, **ids** and **class names**. For example: `#content message.success`.
+
+##### A style sheet example
+
+```ruby
+  style_sheet = {
+    "foreground-color" => :white,
+    "background-color" => :blue,
+
+    "#content message.success" => {
+      "background-color" => :green,
+
+      "number" => {
+        "background-color" => :inherit
+      }
+    }
+  }
+```
+
+### 2. Creating a style sheet handler instance
+
+Then the style sheet should be passed to the handler:
+
+```ruby
+  style_sheet_handler = SimpleStyleSheet::Handler.new(style_sheet)
+```
+
+### 3. Tag objects
+
+Tag objects represent tags in a HTML-like structure. As a tag, any object can be used, provided that it responds to :name, :id, :class_names and :parent messages. For example:
+
+```ruby
+  Tag = Struct.new(:name, :id, :class_names, :parent)
+
+  # Tag objects corresponding to the structure:
+  # <section id="content"><message class="success">...</message></section>
+  content_tag = Tag.new("section", "content", [], nil)
+  message_tag = Tag.new("message", nil, ["success"], content_tag)
+```
+
+### 4. Getting property value for a given tag
+
+Now, a property value for a given tag can be obtained:
+
+```ruby
+  style_sheet_handler.value_for(message_tag, "background-color")
+   => :green
+
+  style_sheet_handler.value_for(message_tag, "foreground-color")
+   => :white
+```
+
+The #value_for method looks in the style sheet for selectors that match a given tag. If more than one matching selector is found, the one with highest specificity is used (more details below). Then the value it points to for given property name is returned.
+
+### 5. Getting top-level property value
+
+The #value_for method, when called without the tag argument, returns top-level property value (defined in the style sheet without a selector), which may be interpreted as default one or as a value for text not included in any tags. For example:
+
+```ruby
+  style_sheet_handler.value_for("background-color")
+   => :blue
+```
+
+Selector specificity
+--------------------
+
+In order to return a property value for a given tag, search for the matching selector of highest specificity is performed.
+
+The specificity of each selector is calculated according to rules similar to the standard CSS rules.
+
+The specificity is four numbers: **a,b,c,d**.
+
+**The rules respected by this gem are**:
+
+* **a** is always 0;
+* **b** is the number of ID attributes in the selector;
+* **c** is the number of class names in the selector;
+* **d** is the number of tag names in the selector.
+
+For example, a selector `tag#id1.class1 #id2.class2.class3` has specificity equal to `0,2,3,1`.
+
+Two selector specificities are compared by succesively comparing their corresponding numbers, from left to right.
+
+Property name translator
+------------------------
+
+A property name translator allows using multiple names (or aliases) for a single property name. For example, property named "background-color" can have aliases "background", "bg-color" etc.
+
+The translator, that is supposed to be provided by the gem user, should respond to :translate method and return the translation for a given property name, for example:
+
+```ruby
+  property_name_translator.translate("bg-color")
+   => "background-color"
+```
+
+In order to use the translator, it should be passed as the second argument to SimpleStyleSheet::Handler.new method:
+
+```ruby
+  style_sheet_handler = SimpleStyleSheet::Handler.new(style_sheet, property_name_translator)
+```
+
+Installation
+------------
+
+As a Ruby gem, SimpleStyleSheet can be installed either by running
+
+```bash
+  gem install simple_style_sheet
+```
+
+or adding
+
+```ruby
+  gem "simple_style_sheet"
+```
+
+to the Gemfile and then invoking `bundle install`.
+
+License
+-------
+
+License is included in the LICENSE file.

data/lib/simple_style_sheet/handler.rb

@@ -0,0 +1,52 @@
+module SimpleStyleSheet
+  class Handler
+
+    def initialize(style_sheet_hash, property_name_translator=nil)
+      @map = {}
+      @property_name_translator = property_name_translator
+      populate(style_sheet_hash)
+    end
+
+    def value_for(tag=nil, property_name)
+      found = if tag
+                (@map[final_property_name(property_name)] || [])
+                .select { |data| data[:selector].match?(tag) }
+                .max_by { |data| data[:selector].specificity }
+
+              else
+                (@map[final_property_name(property_name)] || [])
+                .select { |data| data[:selector].empty?      }
+                .last
+
+              end
+
+      found && found[:value]
+    end
+
+    protected
+
+    def populate(style_sheet_hash, selector=new_selector)
+
+      style_sheet_hash.each do |key, value|
+
+        case value
+        when Hash
+          populate(value, selector + key)
+        else
+          property_name = final_property_name(key)
+
+          @map[property_name] ||= []
+          @map[property_name] << { :value => value, :selector => selector }
+        end
+      end
+    end
+
+    def new_selector
+      Selector.new
+    end
+
+    def final_property_name(property_name)
+      @property_name_translator ? @property_name_translator.translate(property_name) : property_name
+    end
+  end
+end

data/lib/simple_style_sheet/selector.rb

@@ -0,0 +1,63 @@
+module SimpleStyleSheet
+  class Selector
+
+    def initialize(string=nil)
+      @segments = []
+      @specificity = SelectorSpecificity.new
+      concat(string) unless string.nil?
+    end
+
+    attr_reader :specificity
+
+    def concat(string)
+      string.scan(/[\w.#]+/).map { |s| SelectorSegment.new(s) }.each do |segment|
+        @segments << segment
+        @specificity += segment.specificity
+      end
+      self
+    end
+
+    def +(string)
+      duplicate.concat(string)
+    end
+
+    def match?(tag)
+      return true  if @segments.none?
+      return false unless @segments.last.match?(tag)
+
+      index = @segments.size - 2
+      current_tag = tag
+
+      while index >= 0 && current_tag = current_tag.parent
+        if @segments[index].match?(current_tag)
+          index -= 1
+          next
+        end
+      end
+      index == -1
+    end
+
+    def empty?
+      @segments.none?
+    end
+
+    def to_s
+      @segments.map { |segment| segment.to_s }.join(" ")
+    end
+
+    def inspect
+      "#<#{self.class} #{to_s.inspect}>"
+    end
+
+    def ==(other)
+      to_s == other.to_s
+    end
+
+    def duplicate
+      d = dup
+      d.instance_variable_set(   "@segments",    @segments.dup)
+      d.instance_variable_set("@specificity", @specificity.dup)
+      d
+    end
+  end
+end

data/lib/simple_style_sheet/selector_segment.rb

@@ -0,0 +1,38 @@
+module SimpleStyleSheet
+  class SelectorSegment
+
+    def initialize(string)
+      @tag_name    = string.lstrip.slice(/^\w+/)
+      @id          = string.slice(/(?<=\#)\w+/)
+      @class_names = string.scan(/(?<=\.)\w+/)
+    end
+
+    attr_reader :tag_name, :id, :class_names
+
+    def specificity
+      @specificity ||= SelectorSpecificity.new(
+        0,
+        id ? 1 : 0,
+        class_names.count,
+        tag_name ? 1 : 0
+      )
+    end
+
+    def match?(tag)
+      return false if tag_name && tag_name != tag.name
+      return false if id       && id       != tag.id
+      return false if (class_names - tag.class_names).any?
+      true
+    end
+
+    def to_s
+      "#{tag_name}" +
+      (id ? "##{id}" : "") +
+      class_names.map { |class_name| ".#{class_name}" }.join
+    end
+
+    def inspect
+      "#<#{self.class} #{to_s.inspect}>"
+    end
+  end
+end

data/lib/simple_style_sheet/selector_specificity.rb

@@ -0,0 +1,32 @@
+module SimpleStyleSheet
+  class SelectorSpecificity
+
+    include Comparable
+
+    def initialize(a=0, b=0, c=0, d=0)
+      @a, @b, @c, @d = a, b, c, d
+    end
+
+    attr_accessor :a, :b, :c, :d
+
+    def <=>(other)
+      [:a, :b, :c, :d].each do |name|
+        result = send(name) <=> other.send(name)
+        return result unless result == 0
+      end
+      0
+    end
+
+    def +(other)
+      self.class.new(a + other.a, b + other.b, c + other.c, d + other.d)
+    end
+
+    def to_s
+      "#{a},#{b},#{c},#{d}"
+    end
+
+    def inspect
+      "#<#{self.class} #{to_s.inspect}>"
+    end
+  end
+end

data/lib/simple_style_sheet/version.rb

@@ -0,0 +1,3 @@
+module SimpleStyleSheet
+  VERSION = "0.0.1"
+end

data/lib/simple_style_sheet.rb

@@ -0,0 +1,9 @@
+require "simple_style_sheet/version"
+
+require "simple_style_sheet/selector_specificity"
+require "simple_style_sheet/selector_segment"
+require "simple_style_sheet/selector"
+require "simple_style_sheet/handler"
+
+module SimpleStyleSheet
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: simple_style_sheet
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jacek Mikrut
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-21 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &74598880 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: *74598880
+description: Parses a CSS-like Hash style sheet and allows searching for property
+  values of HTML-like tags. Tag and property names, as well as their meaning, are
+  up to the gem user.
+email: jacekmikrut.software@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/simple_style_sheet.rb
+- lib/simple_style_sheet/handler.rb
+- lib/simple_style_sheet/version.rb
+- lib/simple_style_sheet/selector.rb
+- lib/simple_style_sheet/selector_segment.rb
+- lib/simple_style_sheet/selector_specificity.rb
+- README.md
+- LICENSE
+- Changelog
+homepage: http://github.com/jacekmikrut/simple_style_sheet
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.12
+signing_key: 
+specification_version: 3
+summary: Parses a CSS-like Hash style sheet and allows searching for property values
+  of HTML-like tags.
+test_files: []