xass 0.1.0

data/lib/sass/cache_stores/base.rb

@@ -0,0 +1,88 @@
+module Sass
+  module CacheStores
+    # An abstract base class for backends for the Sass cache.
+    # Any key-value store can act as such a backend;
+    # it just needs to implement the
+    # \{#_store} and \{#_retrieve} methods.
+    #
+    # To use a cache store with Sass,
+    # use the {file:SASS_REFERENCE.md#cache_store-option `:cache_store` option}.
+    #
+    # @abstract
+    class Base
+      # Store cached contents for later retrieval
+      # Must be implemented by all CacheStore subclasses
+      #
+      # Note: cache contents contain binary data.
+      #
+      # @param key [String] The key to store the contents under
+      # @param version [String] The current sass version.
+      #                Cached contents must not be retrieved across different versions of sass.
+      # @param sha [String] The sha of the sass source.
+      #                Cached contents must not be retrieved if the sha has changed.
+      # @param contents [String] The contents to store.
+      def _store(key, version, sha, contents)
+        raise "#{self.class} must implement #_store."
+      end
+
+      # Retrieved cached contents.
+      # Must be implemented by all subclasses.
+      # 
+      # Note: if the key exists but the sha or version have changed,
+      # then the key may be deleted by the cache store, if it wants to do so.
+      #
+      # @param key [String] The key to retrieve
+      # @param version [String] The current sass version.
+      #                Cached contents must not be retrieved across different versions of sass.
+      # @param sha [String] The sha of the sass source.
+      #                Cached contents must not be retrieved if the sha has changed.
+      # @return [String] The contents that were previously stored.
+      # @return [NilClass] when the cache key is not found or the version or sha have changed.
+      def _retrieve(key, version, sha)
+        raise "#{self.class} must implement #_retrieve."
+      end
+
+      # Store a {Sass::Tree::RootNode}.
+      #
+      # @param key [String] The key to store it under.
+      # @param sha [String] The checksum for the contents that are being stored.
+      # @param obj [Object] The object to cache.
+      def store(key, sha, root)
+        _store(key, Sass::VERSION, sha, Marshal.dump(root))
+      rescue TypeError, LoadError => e
+        Sass::Util.sass_warn "Warning. Error encountered while saving cache #{path_to(key)}: #{e}"
+        nil
+      end
+
+      # Retrieve a {Sass::Tree::RootNode}.
+      #
+      # @param key [String] The key the root element was stored under.
+      # @param sha [String] The checksum of the root element's content.
+      # @return [Object] The cached object.
+      def retrieve(key, sha)
+        contents = _retrieve(key, Sass::VERSION, sha)
+        Marshal.load(contents) if contents
+      rescue EOFError, TypeError, ArgumentError, LoadError => e
+        Sass::Util.sass_warn "Warning. Error encountered while reading cache #{path_to(key)}: #{e}"
+        nil
+      end
+
+      # Return the key for the sass file.
+      #
+      # The `(sass_dirname, sass_basename)` pair
+      # should uniquely identify the Sass document,
+      # but otherwise there are no restrictions on their content.
+      #
+      # @param sass_dirname [String]
+      #   The fully-expanded location of the Sass file.
+      #   This corresponds to the directory name on a filesystem.
+      # @param sass_basename [String] The name of the Sass file that is being referenced.
+      #   This corresponds to the basename on a filesystem.
+      def key(sass_dirname, sass_basename)
+        dir = Digest::SHA1.hexdigest(sass_dirname)
+        filename = "#{sass_basename}c"
+        "#{dir}/#{filename}"
+      end
+    end
+  end
+end

data/lib/sass/cache_stores/chain.rb

@@ -0,0 +1,33 @@
+module Sass
+  module CacheStores
+    # A meta-cache that chains multiple caches together.
+    # Specifically:
+    #
+    # * All `#store`s are passed to all caches.
+    # * `#retrieve`s are passed to each cache until one has a hit.
+    # * When one cache has a hit, the value is `#store`d in all earlier caches.
+    class Chain < Base
+      # Create a new cache chaining the given caches.
+      #
+      # @param caches [Array<Sass::CacheStores::Base>] The caches to chain.
+      def initialize(*caches)
+        @caches = caches
+      end
+
+      # @see Base#store
+      def store(key, sha, obj)
+        @caches.each {|c| c.store(key, sha, obj)}
+      end
+
+      # @see Base#retrieve
+      def retrieve(key, sha)
+        @caches.each_with_index do |c, i|
+          next unless obj = c.retrieve(key, sha)
+          @caches[0...i].each {|prev| prev.store(key, sha, obj)}
+          return obj
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/sass/cache_stores/filesystem.rb

@@ -0,0 +1,64 @@
+require 'fileutils'
+
+module Sass
+  module CacheStores
+    # A backend for the Sass cache using the filesystem.
+    class Filesystem < Base
+      # The directory where the cached files will be stored.
+      #
+      # @return [String]
+      attr_accessor :cache_location
+
+      # @param cache_location [String] see \{#cache\_location}
+      def initialize(cache_location)
+        @cache_location = cache_location
+      end
+
+      # @see Base#\_retrieve
+      def _retrieve(key, version, sha)
+        return unless File.readable?(path_to(key))
+        File.open(path_to(key), "rb") do |f|
+          if f.readline("\n").strip == version && f.readline("\n").strip == sha
+            return f.read
+          end
+        end
+        begin
+          File.unlink path_to(key)
+        rescue Errno::ENOENT
+          # Already deleted. Race condition?
+        end
+        nil
+      rescue EOFError, TypeError, ArgumentError => e
+        Sass::Util.sass_warn "Warning. Error encountered while reading cache #{path_to(key)}: #{e}"
+      end
+
+      # @see Base#\_store
+      def _store(key, version, sha, contents)
+        # return unless File.writable?(File.dirname(@cache_location))
+        # return if File.exists?(@cache_location) && !File.writable?(@cache_location)
+        compiled_filename = path_to(key)
+        # return if File.exists?(File.dirname(compiled_filename)) && !File.writable?(File.dirname(compiled_filename))
+        # return if File.exists?(compiled_filename) && !File.writable?(compiled_filename)
+        FileUtils.mkdir_p(File.dirname(compiled_filename))
+        Sass::Util.atomic_create_and_write_file(compiled_filename, 0600) do |f|
+          f.puts(version)
+          f.puts(sha)
+          f.write(contents)
+        end
+      rescue Errno::EACCES
+        #pass
+      end
+
+      private
+
+      # Returns the path to a file for the given key.
+      #
+      # @param key [String]
+      # @return [String] The path to the cache file.
+      def path_to(key)
+        key = key.gsub(/[<>:\\|?*%]/) {|c| "%%%03d" % Sass::Util.ord(c)}
+        File.join(cache_location, key)
+      end
+    end
+  end
+end

data/lib/sass/cache_stores/memory.rb

@@ -0,0 +1,47 @@
+module Sass
+  module CacheStores
+    # A backend for the Sass cache using in-process memory.
+    class Memory < Base
+      # Since the {Memory} store is stored in the Sass tree's options hash,
+      # when the options get serialized as part of serializing the tree,
+      # you get crazy exponential growth in the size of the cached objects
+      # unless you don't dump the cache.
+      #
+      # @private
+      def _dump(depth)
+        ""
+      end
+
+      # If we deserialize this class, just make a new empty one.
+      #
+      # @private
+      def self._load(repr)
+        Memory.new
+      end
+
+      # Create a new, empty cache store.
+      def initialize
+        @contents = {}
+      end
+
+      # @see Base#retrieve
+      def retrieve(key, sha)
+        if @contents.has_key?(key)
+          return unless @contents[key][:sha] == sha
+          obj = @contents[key][:obj]
+          obj.respond_to?(:deep_copy) ? obj.deep_copy : obj.dup
+        end
+      end
+
+      # @see Base#store
+      def store(key, sha, obj)
+        @contents[key] = {:sha => sha, :obj => obj}
+      end
+      
+      # Destructively clear the cache.
+      def reset!
+        @contents = {}
+      end
+    end
+  end
+end

data/lib/sass/cache_stores/null.rb

@@ -0,0 +1,25 @@
+module Sass
+  module CacheStores
+    # Doesn't store anything, but records what things it should have stored.
+    # This doesn't currently have any use except for testing and debugging.
+    #
+    # @private
+    class Null < Base
+      def initialize
+        @keys = {}
+      end
+
+      def _retrieve(key, version, sha)
+        nil
+      end
+      
+      def _store(key, version, sha, contents)
+        @keys[key] = true
+      end
+      
+      def was_set?(key)
+        @keys[key]
+      end
+    end
+  end
+end

data/lib/sass/cache_stores.rb

@@ -0,0 +1,15 @@
+require 'stringio'
+
+module Sass
+  # Sass cache stores are in charge of storing cached information,
+  # especially parse trees for Sass documents.
+  #
+  # User-created importers must inherit from {CacheStores::Base}.
+  module CacheStores
+  end
+end
+
+require 'sass/cache_stores/base'
+require 'sass/cache_stores/filesystem'
+require 'sass/cache_stores/memory'
+require 'sass/cache_stores/chain'

data/lib/sass/callbacks.rb

@@ -0,0 +1,66 @@
+module Sass
+  # A lightweight infrastructure for defining and running callbacks.
+  # Callbacks are defined using \{#define\_callback\} at the class level,
+  # and called using `run_#{name}` at the instance level.
+  #
+  # Clients can add callbacks by calling the generated `on_#{name}` method,
+  # and passing in a block that's run when the callback is activated.
+  #
+  # @example Define a callback
+  #   class Munger
+  #     extend Sass::Callbacks
+  #     define_callback :string_munged
+  #
+  #     def munge(str)
+  #       res = str.gsub(/[a-z]/, '\1\1')
+  #       run_string_munged str, res
+  #       res
+  #     end
+  #   end
+  #
+  # @example Use a callback
+  #   m = Munger.new
+  #   m.on_string_munged {|str, res| puts "#{str} was munged into #{res}!"}
+  #   m.munge "bar" #=> bar was munged into bbaarr!
+  module Callbacks
+    # Automatically includes {InstanceMethods}
+    # when something extends this module.
+    #
+    # @param base [Module]
+    def self.extended(base)
+      base.send(:include, InstanceMethods)
+    end
+    protected
+
+    module InstanceMethods
+      # Removes all callbacks registered against this object.
+      def clear_callbacks!
+        @_sass_callbacks = {}
+      end
+    end
+
+    # Define a callback with the given name.
+    # This will define an `on_#{name}` method
+    # that registers a block,
+    # and a `run_#{name}` method that runs that block
+    # (optionall with some arguments).
+    #
+    # @param name [Symbol] The name of the callback
+    # @return [void]
+    def define_callback(name)
+      class_eval <<RUBY, __FILE__, __LINE__ + 1
+def on_#{name}(&block)
+  @_sass_callbacks ||= {}
+  (@_sass_callbacks[#{name.inspect}] ||= []) << block
+end
+
+def run_#{name}(*args)
+  return unless @_sass_callbacks
+  return unless @_sass_callbacks[#{name.inspect}]
+  @_sass_callbacks[#{name.inspect}].each {|c| c[*args]}
+end
+private :run_#{name}
+RUBY
+    end
+  end
+end