apropos 0.1.0

data/lib/apropos/sass_functions.rb

@@ -0,0 +1,69 @@
+module Apropos
+  # A collection of methods mixed into Sass::Script::Functions to allow
+  # Apropos to be used from Sass files. The primary method is
+  # `image-variants`, which generates the actual CSS rules.  Configuration
+  # directly from the Sass file is possible with the `add-dpi-image-variant`
+  # and `add-breakpoint-image-variant` methods, although the limitations of
+  # Sass syntax require that the output of these functions be assigned to a
+  # dummy variable.
+  module SassFunctions
+    def self.sass_function_exist?(meth)
+      Sass::Script::Functions.instance_methods.include? meth
+    end
+
+    def self.included(mod)
+      ::Sass::Script::Functions.declare :image_variants, []
+      ::Sass::Script::Functions.declare :add_dpi_image_variant, []
+      ::Sass::Script::Functions.declare :add_breakpoint_image_variant, []
+      ::Sass::Script::Functions.declare :nth_polyfill, [:list, :index]
+      unless sass_function_exist? :str_index
+        ::Sass::Script::Functions.declare :str_index, [:string, :substring]
+      end
+    end
+
+    def self.value(val)
+      val.respond_to?(:value) ? val.value : val
+    end
+
+    def image_variants(path)
+      assert_type path, :String
+      out = ::Apropos.image_variant_rules(path.value)
+      ::Apropos.convert_to_sass_value(out)
+    end
+
+    def add_dpi_image_variant(id, query, sort=0)
+      sort = ::Apropos::SassFunctions.value(sort)
+      ::Apropos.add_dpi_image_variant(id.value, query.value, sort)
+      ::Sass::Script::Bool.new(false)
+    end
+
+    def add_breakpoint_image_variant(id, query, sort=0)
+      sort = ::Apropos::SassFunctions.value(sort)
+      ::Apropos.add_breakpoint_image_variant(id.value, query.value, sort)
+      ::Sass::Script::Bool.new(false)
+    end
+
+    # Can be replaced with stock `nth` once dca1498 makes it into a Sass release
+    # http://git.io/eGNOKA
+    def nth_polyfill(list, index)
+      index = index.value
+      list = list.value
+      index = list.length + index + 1 if index < 0
+      list[index - 1]
+    end
+
+    # Polyfill for `str-index` function from master branch of Sass.
+    # Implementation taken from:
+    # https://github.com/nex3/sass/blob/master/lib/sass/script/functions.rb
+    # Using Sass::Script::Number rather than Sass::Script::Value::Number for
+    # backwards compatibility, however.
+    unless sass_function_exist? :str_index
+      def str_index(string, substring)
+        assert_type string, :String, :string
+        assert_type substring, :String, :substring
+        index = string.value.index(substring.value) || -1
+        ::Sass::Script::Number.new(index + 1)
+      end
+    end
+  end
+end

data/lib/apropos/set.rb

@@ -0,0 +1,58 @@
+module Apropos
+  # A Set generates a list of Variants from a base image path. Any file in the
+  # same directory as the base image with the pattern "basename.*.extension" is
+  # considered to be a potential Variant, though not all generated Variants are
+  # guaranteed to be valid.
+  class Set
+    attr_reader :path
+
+    def initialize(path, basedir)
+      @path = path
+      @basedir = Pathname.new(basedir)
+    end
+
+    def variants
+      variant_paths.map do |code_fragment, path|
+        Variant.new(code_fragment, path)
+      end.sort
+    end
+
+    def variant_paths
+      paths = {}
+      Dir.glob(@basedir.join(variant_path_glob)).each do |path|
+        key = code_fragment(path)
+        paths[key] = remove_basedir(path)
+      end
+      paths
+    end
+
+    def remove_basedir(path)
+      path.sub(basedir_re, '')
+    end
+
+    def basedir_re
+      @basedir_re ||= Regexp.new("^.*#{Regexp.escape(@basedir.to_s)}/")
+    end
+
+    def code_fragment(path)
+      start = File.join(File.dirname(path), basename)
+      path[(start.length + 1)...(path.length - extname.length)]
+    end
+
+    def variant_path_glob
+      Pathname.new(dirname).join("#{basename}#{SEPARATOR}*#{extname}")
+    end
+
+    def dirname
+      @dirname ||= File.dirname(@path)
+    end
+
+    def basename
+      @basename ||= File.basename(@path, extname)
+    end
+
+    def extname
+      @extname ||= File.extname(@path)
+    end
+  end
+end

data/lib/apropos/variant.rb

@@ -0,0 +1,67 @@
+module Apropos
+  # A Variant represents a single image file that should be displayed instead
+  # of the base image in one or more conditions. These conditions are parsed
+  # from the codes in the provided code fragment. If none of the available
+  # parsers can understand the Variant's codes, then the Variant is not
+  # considered valid.
+  #
+  # A valid Variant can generate a CSS rule from its matching conditions, and
+  # can be compared to other Variants based on the aggregate sort values of its
+  # matching conditions.
+  class Variant
+    attr_reader :path
+
+    def initialize(code_fragment, path)
+      @code_fragment = code_fragment
+      @path = path
+    end
+
+    def codes
+      @_codes ||= @code_fragment.split(SEPARATOR)
+    end
+
+    def conditions
+      @_conditions ||= codes.map do |code|
+        ExtensionParser.each_parser.inject(nil) do |_, parser|
+          query_or_selector = parser.match(code)
+          break query_or_selector if query_or_selector
+        end
+      end.compact
+    end
+
+    def conditions_by_type
+      @_conditions_by_type ||= {}.tap do |combination|
+        conditions.each do |condition|
+          combination[condition.type] = if combination[condition.type]
+            combination[condition.type].combine(condition)
+          else
+            condition
+          end
+        end
+      end
+    end
+
+    def valid?
+      !conditions.empty?
+    end
+
+    def rule
+      sorted_selector_types = conditions_by_type.keys.sort
+      condition_css = sorted_selector_types.map do |rule_type|
+        conditions_by_type[rule_type].to_css
+      end
+      key = sorted_selector_types.join('+')
+      [key] + condition_css + [path]
+    end
+
+    def aggregate_sort_value
+      conditions.inject(0) do |total, query_or_selector|
+        total + query_or_selector.sort_value
+      end
+    end
+
+    def <=>(other)
+      aggregate_sort_value <=> other.aggregate_sort_value
+    end
+  end
+end

data/lib/apropos/version.rb

@@ -0,0 +1,3 @@
+module Apropos
+  VERSION = "0.1.0"
+end

data/spec/apropos/class_list_spec.rb

@@ -0,0 +1,8 @@
+require_relative "../spec_helper.rb"
+
+describe Apropos::ClassList do
+  it "combines class lists" do
+    combo = described_class.new([".foo"]).combine(described_class.new([".bar"]))
+    combo.to_css.should == ".foo, .bar"
+  end
+end

data/spec/apropos/extension_parser_spec.rb

@@ -0,0 +1,71 @@
+require_relative "../spec_helper.rb"
+
+describe Apropos::ExtensionParser do
+  before :each do
+    described_class.parsers.clear
+  end
+
+  describe ".parsers" do
+    it "keeps track of variant parsers" do
+      parser = described_class.add_parser('2x') do
+      end
+      described_class.parsers['2x'].should == parser
+      described_class.parsers.count.should == 1
+    end
+  end
+
+  describe ".add_parser" do
+    it "overrides previously defined parsers with the same extension" do
+      old_parser = described_class.add_parser('2x')
+      new_parser = described_class.add_parser('2x')
+      described_class.parsers['2x'].should == new_parser
+    end
+  end
+
+  describe ".each_parser" do
+    it "yields each parser to the block" do
+      described_class.add_parser('2x')
+      described_class.add_parser('medium')
+      described_class.add_parser('fr')
+      vals = []
+      described_class.each_parser do |parser|
+        vals << parser.pattern
+      end
+      vals.should == %w[2x medium fr]
+    end
+  end
+
+  describe "#match" do
+    let(:locale_pattern) { /^([a-z]{2})$/ }
+
+    it "calls the block when the extension matches" do
+      lastmatch = nil
+      parser = described_class.new(locale_pattern) do |match|
+        lastmatch = match
+      end
+      parser.match('fr')
+      lastmatch[1].should == 'fr'
+    end
+
+    it "doesn't call the block when there is no match" do
+      expect {
+        parser = described_class.new(/^fr$/) do |match|
+          raise
+        end
+        parser.match('en').should be_nil
+      }.to_not raise_error
+    end
+
+    it "allows the block to return a nil value" do
+      parser = described_class.new(locale_pattern) do |match|
+        if match[1] == 'fr'
+          true
+        else
+          nil
+        end
+      end
+      parser.match('fr').should == true
+      parser.match('en').should be_nil
+    end
+  end
+end

data/spec/apropos/functions_spec.rb

@@ -0,0 +1,185 @@
+require_relative "../spec_helper.rb"
+
+describe Apropos do
+  def stub_files(*files)
+    Dir.stub(:glob).with(Pathname.new("/project/images/foo.*.jpg")).and_return(files)
+  end
+
+  let(:rules) { Apropos.image_variant_rules("foo.jpg") }
+
+  before :each do
+    Compass.configuration.stub(:project_path).and_return('/project')
+    Compass.configuration.stub(:images_dir).and_return('images')
+  end
+
+  describe ".add_class_image_variant" do
+    after :each do
+      Apropos.clear_image_variants
+    end
+
+    it "adds a simple class variant" do
+      Apropos.add_class_image_variant('alt', 'alternate')
+      stub_files("/foo.alt.jpg")
+      rules.should == [
+        ["class", ".alternate", "/foo.alt.jpg"]
+      ]
+    end
+
+    it "adds multiple classes" do
+      Apropos.add_class_image_variant('alt', ['alternate', 'alt'])
+      stub_files("/foo.alt.jpg")
+      rules.should == [
+        ["class", ".alternate, .alt", "/foo.alt.jpg"]
+      ]
+    end
+
+    it "respects sort order" do
+      Apropos.add_class_image_variant('alt', 'alternate', 1)
+      Apropos.add_class_image_variant('b', 'blue', 0)
+      stub_files("/foo.alt.jpg", "/foo.b.jpg")
+      rules.should == [
+        ["class", ".blue", "/foo.b.jpg"],
+        ["class", ".alternate", "/foo.alt.jpg"]
+      ]
+    end
+
+    it "uses a custom block to generate class names" do
+      Apropos.add_class_image_variant(/^[a-z]{2}$/) do |match|
+        if match[0] == 'en'
+          "lang-en"
+        elsif match[0] == 'fr'
+          ["lang-fr", "country-FR"]
+        end
+      end
+      stub_files('/foo.en.jpg', '/foo.fr.jpg', '/foo.de.jpg')
+      rules.should == [
+        ["class", ".lang-en", "/foo.en.jpg"],
+        [ "class", ".lang-fr, .country-FR", "/foo.fr.jpg"]
+      ]
+    end
+  end
+
+  describe ".image_variant_rules" do
+    before :all do
+      Apropos.add_dpi_image_variant('2x', "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)", 0.5)
+      Apropos.add_breakpoint_image_variant('medium', 'min-width: 768px', 1)
+      Apropos.add_breakpoint_image_variant('large', 'min-width: 1024px', 2)
+      Apropos::ExtensionParser.add_parser(/^([a-z]{2}(?:-(ca))?)$/) do |match|
+        if match[2]
+          Apropos::ClassList.new([".locale-fr-CA"], 3)
+        elsif match[1]
+          if match[1] == 'fr'
+            Apropos::ClassList.new([".lang-fr"], 2)
+          elsif match[1] == 'ca'
+            Apropos::ClassList.new([".country-CA"], 1)
+          end
+        else
+          nil
+        end
+      end
+    end
+
+    after :all do
+      Apropos.clear_image_variants
+    end
+
+    it "ignores invalid variants" do
+      stub_files("/foo.1x.jpg", "/foo.de.jpg", "/foo.ca.jpg")
+      rules.should == [
+        ["class", ".country-CA", "/foo.ca.jpg"]
+      ]
+    end
+
+    it "generates a locale class rule for localized variant" do
+      stub_files("/foo.ca.jpg")
+      rules.should == [
+        ["class", ".country-CA", "/foo.ca.jpg"]
+      ]
+    end
+
+    it "generates a media query rule for breakpoint variant" do
+      stub_files("/foo.medium.jpg")
+      rules.should == [
+        ["media", "(min-width: 768px)", "/foo.medium.jpg"]
+      ]
+    end
+
+    it "generates a media query rule for retina variant" do
+      stub_files("/foo.2x.jpg")
+      rules.should == [
+        ["media", "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)", "/foo.2x.jpg"]
+      ]
+    end
+
+    it "generates a combined rule for retina + localized variant" do
+      stub_files("/foo.2x.ca.jpg")
+      rules.should == [
+        ["class+media", ".country-CA", "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)", "/foo.2x.ca.jpg"]
+      ]
+    end
+
+    it "generates multiple rules for multiple variants" do
+      stub_files("/foo.2x.ca.jpg", "/foo.medium.2x.fr.jpg")
+      rules.should == [
+        ["class+media", ".country-CA", "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)", "/foo.2x.ca.jpg"],
+        ["class+media", ".lang-fr", "(min-width: 768px) and (-webkit-min-device-pixel-ratio: 2), (min-width: 768px) and (min-resolution: 192dpi)", "/foo.medium.2x.fr.jpg"]
+      ]
+    end
+
+    it "sorts breakpoint rules" do
+      stub_files("/foo.large.jpg", "/foo.medium.jpg")
+      rules.should == [
+        ["media", "(min-width: 768px)", "/foo.medium.jpg"],
+        ["media", "(min-width: 1024px)", "/foo.large.jpg"]
+      ]
+    end
+
+    it "sorts retina rules after non-retina rules" do
+      stub_files("/foo.2x.large.jpg", "/foo.large.jpg")
+      rules.should == [
+        ["media", "(min-width: 1024px)", "/foo.large.jpg"],
+        ["media", "(-webkit-min-device-pixel-ratio: 2) and (min-width: 1024px), (min-resolution: 192dpi) and (min-width: 1024px)", "/foo.2x.large.jpg"]
+      ]
+    end
+
+    it "sorts breakpoints within retina rules" do
+      stub_files("/foo.2x.large.jpg", "/foo.2x.medium.jpg", "/foo.2x.jpg")
+      rules.should == [
+        ["media", "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)", "/foo.2x.jpg"],
+        ["media", "(-webkit-min-device-pixel-ratio: 2) and (min-width: 768px), (min-resolution: 192dpi) and (min-width: 768px)", "/foo.2x.medium.jpg"],
+        ["media", "(-webkit-min-device-pixel-ratio: 2) and (min-width: 1024px), (min-resolution: 192dpi) and (min-width: 1024px)", "/foo.2x.large.jpg"]
+      ]
+    end
+
+    it "sorts locale rules: country < lang < locale" do
+      stub_files("/foo.fr.jpg", "/foo.fr-ca.jpg", "/foo.ca.jpg")
+      rules.should == [
+        ["class", ".country-CA", "/foo.ca.jpg"],
+        ["class", ".lang-fr", "/foo.fr.jpg"],
+        ["class", ".locale-fr-CA", "/foo.fr-ca.jpg"]
+      ]
+    end
+  end
+
+  describe ".convert_to_sass_value" do
+    it "converts strings to sass strings" do
+      val = Apropos.convert_to_sass_value("foo")
+      val.value.should == "foo"
+      val.class.should == Sass::Script::String
+    end
+
+    it "converts arrays to sass lists" do
+      original_value = ["foo", "bar"]
+      val = Apropos.convert_to_sass_value(original_value)
+      val.class.should == Sass::Script::List
+      val.value.map(&:value).should == original_value
+      val.separator.should == :space
+    end
+
+    it "raises an exception on other input types" do
+      expect {
+        Apropos.convert_to_sass_value(3)
+      }.to raise_exception
+    end
+  end
+end