buildpack-support 1.0.0

data/lib/buildpack_support/component/with_timing.rb

@@ -0,0 +1,40 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/component'
+
+module BuildpackSupport
+  module Component
+
+    # A mixin for printing out a caption and timing when executing a block
+    module WithTiming
+
+      # Wrap the execution of a block with timing information
+      #
+      # @param [String] caption the caption to print when timing starts
+      # @return [Void]
+      def with_timing(caption)
+        start_time = Time.now
+        print "       #{caption} "
+
+        yield
+
+        puts "(#{(Time.now - start_time).duration})"
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/configuration_utils.rb

@@ -0,0 +1,58 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support'
+require 'buildpack_support/directory_finder'
+require 'buildpack_support/logging/logger_factory'
+require 'pathname'
+require 'yaml'
+
+module BuildpackSupport
+
+  # Utilities for dealing with Configuration files
+  class ConfigurationUtils
+    include DirectoryFinder
+
+    # Creates a new instance
+    #
+    # @param [Boolean] should_log whether the contents of the configuration file should be logged.  This value should be
+    #                             left to its default and exists to allow the logger to use the utility.
+    def initialize(should_log = true)
+      @config_directory = load_path_peer 'config'
+      @logger           = BuildpackSupport::Logging::LoggerFactory.instance.get_logger ConfigurationUtils if should_log
+    end
+
+    # Loads a configuration file from the buildpack configuration directory.  If the configuration file does not exist,
+    # returns an empty hash.
+    #
+    # @param [String] identifier the identifier of the configuration
+    # @return [Hash] the configuration or an empty hash if the configuration file does not exist
+    def load(identifier)
+      file = @config_directory + "#{identifier}.yml"
+
+      configuration = {}
+      if file.exist?
+        configuration = YAML.load_file(file)
+        @logger.debug { "Configuration from #{file}: #{configuration}" } if @logger
+      else
+        @logger.debug { "No configuration file #{file} found" } if @logger
+      end
+
+      configuration
+    end
+
+  end
+
+end

data/lib/buildpack_support/constantize.rb

@@ -0,0 +1,46 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# A mixin that adds the ability to turn a +String+ into a constant.
+class String
+
+  # Tries to find a constant with the name specified by this +String+:
+  #
+  #   "Module".constantize     # => Module
+  #   "Test::Unit".constantize # => Test::Unit
+  #
+  # The name is assumed to be the one of a top-level constant, no matter whether
+  # it starts with "::" or not. No lexical context is taken into account:
+  #
+  #   C = 'outside'
+  #   module M
+  #     C = 'inside'
+  #     C               # => 'inside'
+  #     "C".constantize # => 'outside', same as ::C
+  #   end
+  #
+  # @return [String] The constantized rendering of this +String+.
+  # @raise NameError if the name is not in CamelCase or the constant is unknown.
+  def constantize
+    names = split('::')
+    names.shift if names.empty? || names.first.empty?
+
+    constant = Object
+    names.each do |name|
+      constant = constant.const_defined?(name, false) ? constant.const_get(name) : constant.const_missing(name)
+    end
+    constant
+  end
+end

data/lib/buildpack_support/dash_case.rb

@@ -0,0 +1,29 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# A mixin that adds the ability to turn a +String+ into dash case
+class String
+
+  # Converts a string to dash case.  For example, the String +Foo::DashCase+ would become +dash-case+.
+  #
+  # @return [String] The dash case rendering of this +String+
+  def dash_case
+    split('::').last
+    .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2')
+    .gsub(/([a-z\d])([A-Z])/, '\1-\2')
+    .downcase
+  end
+
+end

data/lib/buildpack_support/directory_finder.rb

@@ -0,0 +1,45 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support'
+require 'pathname'
+
+module BuildpackSupport
+
+  # A module encapsulating all of the code for the directory finding utilities
+  module DirectoryFinder
+
+    # Finds a directory that is a peer of the +$LOAD_PATH+
+    #
+    # @param [String] name the name of the peer directory
+    # @return [Pathname] the path to the found directory if it exists, otherwise a path to the current working directory
+    def load_path_peer(name)
+      directory = Pathname.new('.nil')
+
+      $LOAD_PATH.each do |path|
+        candidate = Pathname.new(path) + '..' + name
+
+        next unless candidate.exist?
+
+        directory = candidate
+        break
+      end
+
+      directory
+    end
+
+  end
+
+end

data/lib/buildpack_support/filtering_pathname.rb

@@ -0,0 +1,227 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support'
+require 'pathname'
+require 'set'
+
+module BuildpackSupport
+
+  # This class conforms to the interface of +Pathname+, but filters the set of files that can be accessed and does not
+  # support +Pathname+'s class methods. This class also provides a +glob+ instance method which filters its output.
+  #
+  # If a +Pathname+ method which mutates the file system is called, it will throw an exception unless the instance is
+  # created as mutable.
+  #
+  # If the underlying filesystem is modified once an instance of this path has been created, the view provided
+  # by the instance will not change unless a file or directory allowed by the instance's filter is created, modified, or
+  # deleted.
+  class FilteringPathname
+
+    # Create a +FilteringPathname+ which behaves like the given pathname, but which applies the given filter to all files.
+    #
+    # The filesystem underpinning the given pathname must not contain a file or directory whose name is the name of the
+    # given pathname with '.nil' appended to it. This must be true for the lifetime of the +FilteringPathname+.
+    #
+    # The filter is applied to files which are accessed via the given pathname.
+    # If the filter returns +true+ for a particular pathname, the pathname behaves normally for this instance.
+    # If the filter returns +false+ for a particular pathname, the pathname behaves as if it does not exist.
+    #
+    # Note that the filter must obey the following rule: if the filter accepts Pathnames p and r, where p is a parent
+    # directory of r, then the filter must accept every Pathname q where p is a parent directory of q and q is a parent
+    # directory of r. FilteringPathname does not check that the filter obeys this rule.
+    #
+    # The +FilteringPathname+ may be immutable in which case calling a mutator method causes an exception to be thrown.
+    # Alternatively, the +FilteringPathname+ may be mutable in which case calling a mutator method may mutate the
+    # file system. The results of mutating the file system will be subject to filtering by the given filter.
+    #
+    # @param [Pathname] pathname the +Pathname+ which is to be filtered
+    # @param [Proc] filter a lambda which takes a +Pathname+ and returns either +true+ (to 'keep' the pathname) or
+    #         +false+ (to filter out the pathname).  Defaults to keeping everything
+    # @param [Boolean] mutable +true+ if and only if the +FilteringPathname+ may be used to mutate the file system
+    def initialize(pathname, filter, mutable)
+      fail 'Non-absolute pathname' unless pathname.absolute?
+
+      @pathname = pathname
+      @filter   = filter
+      @mutable  = mutable
+
+      @non_existent = Pathname.new "#{pathname}.nil"
+      check_file_does_not_exist @non_existent
+
+      @delegated_pathname = filter(@pathname) ? @pathname : @non_existent
+    end
+
+    # @see Pathname.
+    def <=>(other)
+      @pathname <=> comparison_target(other)
+    end
+
+    # @see Pathname.
+    def ==(other)
+      @pathname == comparison_target(other)
+    end
+
+    # @see Pathname.
+    def ===(other)
+      @pathname === comparison_target(other) # rubocop:disable CaseEquality
+    end
+
+    # Dispatch superclass methods via method_missing.
+    undef_method :taint
+    undef_method :untaint
+
+    # @see Pathname.
+    def +(other)
+      filtered_pathname(@pathname + other)
+    end
+
+    # @see Pathname.
+    def each_entry(&block)
+      delegate_and_yield_visible(:each_entry, &block)
+    end
+
+    # @see Pathname.
+    def entries
+      visible delegate.entries
+    end
+
+    # @see Pathname.
+    def open(mode = nil, *args, &block)
+      check_mutable if mode =~ /[wa]/
+      delegate.open(mode, *args, &block)
+    end
+
+    # @see Pathname.
+    def to_s
+      @pathname.to_s
+    end
+
+    # @see Pathname.
+    def children(with_directory = true)
+      if with_directory
+        super # delegate to method_missing
+      else
+        visible delegate.children(false)
+      end
+    end
+
+    # @see Pathname.
+    def each_child(with_directory = true, &block)
+      if with_directory
+        super # delegate to method_missing
+      else
+        delegate_and_yield_visible(:each_child, false, &block)
+      end
+    end
+
+    # Execute this +FilteringPathname+ as a glob.
+    def glob(flags = 0)
+      if block_given?
+        Pathname.glob(@pathname, flags) do |file|
+          yield filtered_pathname(file) if visible file
+        end
+      else
+        result = Pathname.glob(@pathname, flags)
+        convert_result_if_necessary(result)
+      end
+    end
+
+    attr_reader :pathname
+
+    protected :pathname
+
+    private
+
+    MUTATORS = [:chmod, :chown, :delete, :lchmod, :lchown, :make_link, :make_symlink, :mkdir, :mkpath, :rename, :rmdir, :rmtree, :taint, :unlink, :untaint].to_set.freeze
+
+    private_constant :MUTATORS
+
+    def check_file_does_not_exist(file)
+      fail "#{file} should not exist" if file.exist?
+    end
+
+    def check_mutable
+      fail 'FilteringPathname is immutable' unless @mutable
+    end
+
+    def comparison_target(other)
+      other.instance_of?(FilteringPathname) ? other.pathname : other
+    end
+
+    def convert_if_necessary(r)
+      if r.instance_of?(Pathname) && r.absolute?
+        filter(r) ? filtered_pathname(r) : nil
+      else
+        r
+      end
+    end
+
+    def convert_result_if_necessary(result)
+      if result.instance_of? Array
+        result.map { |r| convert_if_necessary(r) }.compact
+      else
+        result ? convert_if_necessary(result) || filtered_pathname(@non_existent) : nil
+      end
+    end
+
+    def delegate
+      check_file_does_not_exist @non_existent
+      @delegated_pathname
+    end
+
+    def delegate_and_yield_visible(method, *args)
+      delegate.send(method, *args) do |y|
+        yield y if visible y
+      end
+    end
+
+    def filtered_pathname(pathname)
+      FilteringPathname.new(pathname, @filter, @mutable)
+    end
+
+    def method_missing(method, *args)
+      check_mutable if MUTATORS.member? method
+      if block_given?
+        result = delegate.send(method, *args) do |*values|
+          converted_values = values.map { |value| convert_if_necessary(value) }.compact
+          yield(*converted_values) unless converted_values.empty?
+        end
+      else
+        result = delegate.send(method, *args)
+      end
+      convert_result_if_necessary(result)
+    end
+
+    def respond_to_missing?(symbol, include_private = false)
+      delegate.respond_to?(symbol, include_private)
+    end
+
+    def visible(entry)
+      if entry.instance_of? Array
+        entry.select { |child| visible(child) }
+      else
+        filter(@pathname + entry)
+      end
+    end
+
+    def filter(pathname)
+      fail 'Non-absolute pathname' unless pathname.absolute?
+      @filter.call(pathname.cleanpath)
+    end
+
+  end
+
+end