merb-slices 0.9.4

data/lib/merb-slices/module.rb

@@ -0,0 +1,338 @@
+module Merb
+  module Slices
+    
+    VERSION = "0.9.4"
+    
+    class << self
+    
+      # Retrieve a slice module by name 
+      #
+      # @param <#to_s> The slice module to check for.
+      # @return <Module> The slice module itself.
+      def [](module_name)
+        Object.full_const_get(module_name.to_s) if exists?(module_name)
+      end
+      
+      # Helper method to transform a slice filename to a module Symbol
+      def filename2module(slice_file)
+        File.basename(slice_file, '.rb').gsub('-', '_').camel_case.to_sym
+      end
+    
+      # Register a Slice by its gem/lib path for loading at startup
+      #
+      # This is referenced from gems/<slice-gem-x.x.x>/lib/<slice-gem>.rb
+      # Which gets loaded for any gem. The name of the file is used
+      # to extract the Slice module name.
+      #
+      # @param slice_file<String> The path of the gem 'init file'
+      # @param force<Boolean> Whether to overwrite currently registered slice or not.
+      #
+      # @return <Module> The Slice module that has been setup.
+      #
+      # @example Merb::Slices::register(__FILE__)
+      # @example Merb::Slices::register('/path/to/my-slice/lib/my-slice.rb')
+      def register(slice_file, force = true)
+        # do what filename2module does, but with intermediate variables
+        identifier  = File.basename(slice_file, '.rb')
+        underscored = identifier.gsub('-', '_')
+        module_name = underscored.camel_case
+        slice_path  = File.expand_path(File.dirname(slice_file) + '/..')
+        # check if slice_path exists instead of just the module name - more flexible
+        if !self.paths.include?(slice_path) || force
+          Merb.logger.info!("Registered slice '#{module_name}' located at #{slice_path}") if force
+          self.files[module_name] = slice_file
+          self.paths[module_name] = slice_path
+          slice_mod = setup_module(module_name)
+          slice_mod.identifier = identifier
+          slice_mod.identifier_sym = underscored.to_sym
+          slice_mod.root = slice_path
+          slice_mod.file = slice_file
+          slice_mod.registered
+          slice_mod
+        else
+          Merb.logger.info!("Already registered slice '#{module_name}' located at #{slice_path}")
+          Object.full_const_get(module_name)
+        end
+      end
+      
+      # Look for any slices in Merb.root / 'slices' (the default) or if given, 
+      # Merb::Plugins.config[:merb_slices][:search_path] (String/Array)
+      def register_slices_from_search_path!
+        slice_files_from_search_path.each do |slice_file|
+          absolute_path = File.expand_path(slice_file)
+          Merb.logger.info!("Found slice '#{File.basename(absolute_path, '.rb')}' in search path at #{absolute_path.relative_path_from(Merb.root)}")
+          Merb::Slices::Loader.load_classes(absolute_path)
+        end
+      end
+      
+      # Unregister a Slice at runtime
+      #
+      # This clears the slice module from ObjectSpace and reloads the router.
+      # Since the router doesn't add routes for any disabled slices this will
+      # correctly reflect the app's routing state.
+      #
+      # @param slice_module<#to_s> The Slice module to unregister.
+      def unregister(slice_module)
+        if (slice = self[slice_module]) && self.paths.delete(module_name = slice.name)
+          slice.loadable_files.each { |file| Merb::Slices::Loader.remove_file file }
+          Object.send(:remove_const, module_name)
+          unless Object.const_defined?(module_name)
+            Merb.logger.info!("Unregistered slice #{module_name}")
+            Merb::Slices::Loader.reload_router!
+          end
+        end
+      end
+      
+      # Activate a Slice module at runtime
+      #
+      # Looks for previously registered slices; then searches :search_path for matches.
+      #
+      # @param slice_module<#to_s> Usually a string of version of the slice module name.
+      def activate(slice_module)  
+        unless slice_file = self.files[slice_module.to_s]
+          module_name_underscored = slice_module.to_s.snake_case.escape_regexp
+          module_name_dasherized  = module_name_underscored.tr('_', '-').escape_regexp
+          regexp = Regexp.new(/\/(#{module_name_underscored}|#{module_name_dasherized})\/lib\/(#{module_name_underscored}|#{module_name_dasherized})\.rb$/)
+          slice_file = slice_files_from_search_path.find { |path| path.match(regexp) } # from search path(s)
+        end
+        activate_by_file(slice_file) if slice_file
+      rescue => e
+        Merb.logger.error!("Failed to activate slice #{slice_module} (#{e.message})")
+      end
+      
+      # Register a Slice by its gem/lib init file path and activate it at runtime
+      #
+      # Normally slices are loaded using BootLoaders on application startup.
+      # This method gives you the possibility to add slices at runtime, all
+      # without restarting your app. Together with #deactivate it allows
+      # you to enable/disable slices at any time. The router is reloaded to
+      # incorporate any changes. Disabled slices will be skipped when 
+      # routes are regenerated.
+      #
+      # @param slice_file<String> The path of the gem 'init file'
+      #
+      # @example Merb::Slices.activate_by_file('/path/to/gems/slice-name/lib/slice-name.rb')
+      def activate_by_file(slice_file)
+        Merb::Slices::Loader.load_classes(slice_file)
+        slice = register(slice_file, false) # just to get module by slice_file
+        slice.load_slice # load the slice
+        Merb::Slices::Loader.reload_router!
+        slice.init     if slice.respond_to?(:init)
+        slice.activate if slice.respond_to?(:activate) && slice.routed?
+        slice
+      rescue
+        Merb::Slices::Loader.reload_router!
+      end
+      alias :register_and_load :activate_by_file
+      
+      # Deactivate a Slice module at runtime
+      #
+      # @param slice_module<#to_s> The Slice module to unregister.
+      def deactivate(slice_module)
+        if slice = self[slice_module]
+          slice.deactivate if slice.respond_to?(:deactivate) && slice.routed?
+          unregister(slice)
+        end
+      end
+      
+      # Deactivate a Slice module at runtime by specifying its slice file
+      #
+      # @param slice_file<String> The Slice location of the slice init file to unregister.
+      def deactivate_by_file(slice_file)
+        if slice = self.slices.find { |s| s.file == slice_file }
+          deactivate(slice.name)
+        end
+      end
+      
+      # Reload a Slice at runtime
+      #
+      # @param slice_module<#to_s> The Slice module to reload.
+      def reload(slice_module)
+        if slice = self[slice_module]
+          deactivate slice.name
+          activate_by_file slice.file
+        end
+      end
+      
+      # Reload a Slice at runtime by specifying its slice file
+      #
+      # @param slice_file<String> The Slice location of the slice init file to reload.
+      def reload_by_file(slice_file)
+        if slice = self.slices.find { |s| s.file == slice_file }
+          reload(slice.name)
+        end
+      end
+      
+      # Watch all specified search paths to dynamically load/unload slices at runtime
+      #
+      # If a valid slice is found it's automatically registered and activated;
+      # once a slice is removed (or renamed to not match the convention), it
+      # will be unregistered and deactivated. Runs in a Thread.
+      #
+      # @example Merb::BootLoader.after_app_loads { Merb::Slices.start_dynamic_loader! }
+      # 
+      # @param interval<Numeric> 
+      #   The interval in seconds of checking the search path(s) for changes.
+      def start_dynamic_loader!(interval = nil)
+        DynamicLoader.start(interval)
+      end
+      
+      # Stop watching search paths to dynamically load/unload slices at runtime
+      def stop_dynamic_loader!
+        DynamicLoader.stop
+      end
+      
+      # @return <Hash>
+      #   The configuration loaded from Merb.root / "config/slices.yml" or, if
+      #   the load fails, an empty hash.
+      def config
+        @config ||= begin
+          empty_hash = Hash.new { |h,k| h[k] = {} }
+          File.exists?(Merb.root / "config" / "slices.yml") ? YAML.load(File.read(Merb.root / "config" / "slices.yml")) || empty_hash : empty_hash
+        end
+      end
+    
+      # All registered Slice modules
+      #
+      # @return <Array[Module]> A sorted array of all slice modules.
+      def slices
+        slice_names.map do |name|
+          Object.full_const_get(name) rescue nil
+        end.compact
+      end
+    
+      # All registered Slice module names
+      #
+      # @return <Array[String]> A sorted array of all slice module names.
+      def slice_names
+        self.paths.keys.sort
+      end
+    
+      # Check whether a Slice exists
+      # 
+      # @param <#to_s> The slice module to check for.
+      def exists?(module_name)
+        slice_names.include?(module_name.to_s) && Object.const_defined?(module_name.to_s)
+      end
+    
+      # A lookup for finding a Slice module's path
+      #
+      # @return <Hash> A Hash mapping module names to root paths.
+      # @note Whenever a slice is deactivated, its path is removed from the lookup.
+      def paths
+        @paths ||= {}
+      end
+      
+      # A lookup for finding a Slice module's slice file path
+      #
+      # @return <Hash> A Hash mapping module names to slice files.
+      # @note This is unaffected by deactivating a slice; used to reload slices by name.
+      def files
+        @files ||= {}
+      end
+  
+      # Iterate over all registered slices
+      #
+      # By default iterates alphabetically over all registered modules. 
+      # If Merb::Plugins.config[:merb_slices][:queue] is set, only the
+      # defined modules are loaded in the given order. This can be
+      # used to selectively load slices, and also maintain load-order
+      # for slices that depend on eachother.
+      #
+      # @yield Iterate over known slices and pass in the slice module.
+      # @yieldparam module<Module> The Slice module.
+      def each_slice(&block)
+        loadable_slices = Merb::Plugins.config[:merb_slices].key?(:queue) ? Merb::Plugins.config[:merb_slices][:queue] : slice_names
+        loadable_slices.each do |module_name|
+          if mod = self[module_name]
+            block.call(mod)
+          end
+        end
+      end
+      
+      # Slice file locations from all search paths; this default to host-app/slices.
+      #
+      # Look for any slices in those default locations or if given, 
+      # Merb::Plugins.config[:merb_slices][:search_path] (String/Array).
+      # Specify files, glob patterns or paths containing slices.
+      def slice_files_from_search_path
+        search_paths = Array(Merb::Plugins.config[:merb_slices][:search_path] || [Merb.root / "slices"])
+        search_paths.inject([]) do |files, path|
+          # handle both Pathname and String
+          path = path.to_s
+          if File.file?(path) && File.extname(path) == ".rb"
+            files << path
+          elsif path.include?("*")
+            files += glob_search_path(path)
+          elsif File.directory?(path)
+            files += glob_search_path(path / "**/lib/*.rb")
+          end
+          files
+        end
+      end
+    
+      private
+    
+      # Prepare a module to be a proper Slice module
+      #
+      # @param module_name<#to_s> The name of the module to prepare
+      #
+      # @return <Module> The module that has been setup
+      def setup_module(module_name)
+        Object.make_module(module_name)
+        slice_mod = Object.full_const_get(module_name)
+        slice_mod.extend(ModuleMixin)
+        slice_mod
+      end
+      
+      # Glob slice files
+      #
+      # @param glob_pattern<String> A glob path with pattern
+      # @return <Array> Valid slice file paths.
+      def glob_search_path(glob_pattern)
+        # handle both Pathname and String
+        glob_pattern = glob_pattern.to_s
+        Dir[glob_pattern].inject([]) do |files, libfile|
+          basename = File.basename(libfile, '.rb')
+          files << libfile if File.basename(File.dirname(File.dirname(libfile))) == basename
+          files
+        end
+      end
+      
+    end
+    
+    class DynamicLoader
+      
+      cattr_accessor :lookup
+      
+      def self.start(interval = nil)
+        self.lookup ||= Set.new(Merb::Slices.slice_files_from_search_path)
+        @thread = self.every(interval || Merb::Plugins.config[:merb_slices][:autoload_interval] || 1.0) do
+          current_files = Set.new(Merb::Slices.slice_files_from_search_path)
+          (current_files - self.lookup).each { |f| Merb::Slices.activate_by_file(f) }
+          (self.lookup - current_files).each { |f| Merb::Slices.deactivate_by_file(f) }
+          self.lookup = current_files
+        end
+      end
+      
+      def self.stop
+        @thread.exit if @thread.is_a?(Thread)
+      end
+      
+      private
+      
+      def self.every(seconds, &block)
+        Thread.abort_on_exception = true
+        Thread.new do
+          loop do
+            sleep(seconds)
+            block.call
+          end
+          Thread.exit
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/merb-slices/module_mixin.rb

@@ -0,0 +1,535 @@
+module Merb
+  module Slices
+    module ModuleMixin
+      
+      def self.extended(slice_module)
+        slice_module.meta_class.module_eval do
+          attr_accessor :identifier, :identifier_sym, :root, :file
+          attr_accessor :routes, :named_routes
+          attr_accessor :description, :version, :author
+        end
+      end
+    
+      # Stub that gets triggered when a slice has been registered.
+      #
+      # @note This is rarely needed but still provided for edge cases.
+      def registered; end
+    
+      # Stub classes loaded hook - runs before LoadClasses BootLoader
+      # right after a slice's classes have been loaded internally.
+      def loaded; end
+    
+      # Stub initialization hook - runs before AfterAppLoads BootLoader.
+      def init; end
+    
+      # Stub activation hook - runs after AfterAppLoads BootLoader.
+      def activate; end
+    
+      # Stub deactivation method - not triggered automatically.
+      def deactivate; end
+    
+      # Stub to setup routes inside the host application.
+      def setup_router(scope); end
+      
+      # Check if there have been any routes setup.
+      def routed?
+        self.routes && !self.routes.empty?
+      end
+      
+      # Return a value suitable for routes/urls.
+      def to_param
+        self.identifier
+      end
+
+      # @param <Symbol> The configuration key.
+      # @return <Object> The configuration value.
+      def [](key)
+        self.config[key]
+      end
+      
+      # @param <Symbol> The configuration key.
+      # @param <Object> The configuration value.
+      def []=(key, value)
+        self.config[key] = value
+      end
+      
+      # @return <Hash> The configuration for this slice.
+      def config
+        Merb::Slices::config[self.identifier_sym] ||= {}
+      end
+      
+      # Load slice and it's classes located in the slice-level load paths.
+      # 
+      # Assigns collected_slice_paths and collected_app_paths, then loads
+      # the collected_slice_paths and triggers the #loaded hook method.
+      def load_slice
+        # load application.rb (or similar) for thin slices
+        Merb::Slices::Loader.load_file self.dir_for(:application) if File.file?(self.dir_for(:application))
+        # assign all relevant paths for slice-level and app-level
+        self.collect_load_paths
+        # load all slice-level classes from paths
+        Merb::Slices::Loader.load_classes self.collected_slice_paths
+        # call hook if available
+        self.loaded if self.respond_to?(:loaded)
+        Merb.logger.info!("Loaded slice '#{self}' ...")
+      rescue => e
+        Merb.logger.warn!("Failed loading #{self} (#{e.message})")
+      end
+      
+      # The slice-level load paths that have been used when the slice was loaded.
+      # 
+      # This may be a subset of app_paths, which includes any path to look for.
+      #
+      # @return <Array[String]> load paths (with glob pattern)
+      def collected_slice_paths
+        @collected_slice_paths ||= []
+      end
+      
+      # The app-level load paths that have been used when the slice was loaded.
+      # 
+      # This may be a subset of app_paths, which includes any path to look for.
+      #
+      # @return <Array[String]> Application load paths (with glob pattern)
+      def collected_app_paths
+        @collected_app_paths ||= []
+      end
+      
+      # Generate a url - takes the slice's :path_prefix into account.
+      #
+      # This is only relevant for default routes, as named routes are
+      # handled correctly without any special considerations.
+      #
+      # @param name<#to_sym,Hash> The name of the URL to generate.
+      # @param rparams<Hash> Parameters for the route generation.
+      #
+      # @return String The generated URL.
+      #
+      # @notes If a hash is used as the first argument, a default route will be
+      #   generated based on it and rparams.
+      def url(name, rparams = {}, defaults = {})
+        defaults = rparams if name.is_a?(Hash) && defaults.empty?
+        rparams  = name    if name.is_a?(Hash)
+        
+        if name.is_a?(Symbol)
+          raise "Named route not found: #{name}" unless self.named_routes[name]
+          uri = Merb::Router.generate(name, rparams, defaults)
+        else
+          defaults[:controller] = defaults[:controller].gsub(%r|^#{self.identifier_sym}/|, '') if defaults[:controller]
+          uri = Merb::Router.generate(name, rparams, defaults)
+          uri = self[:path_prefix] / uri unless self[:path_prefix].blank?
+          uri = "/#{uri}" unless uri[0,1] == '/'
+        end
+        
+        Merb::Config[:path_prefix] ? Merb::Config[:path_prefix] + uri : uri
+      end
+    
+      # The slice-level load paths to use when loading the slice.
+      #
+      # @return <Hash> The load paths which make up the slice-level structure.
+      def slice_paths
+        @slice_paths ||= Hash.new { [self.root] }
+      end
+    
+      # The app-level load paths to use when loading the slice.
+      #
+      # @return <Hash> The load paths which make up the app-level structure.
+      def app_paths
+        @app_paths ||= Hash.new { [Merb.root] }
+      end
+    
+      # @param *path<#to_s>
+      #   The relative path (or list of path components) to a directory under the
+      #   root of the application.
+      #
+      # @return <String> The full path including the root.
+      def root_path(*path) File.join(self.root, *path) end
+    
+      # Retrieve the absolute path to a slice-level directory.
+      #
+      # @param type<Symbol> The type of path to retrieve directory for, e.g. :view.
+      #
+      # @return <String> The absolute path for the requested type.
+      def dir_for(type) self.slice_paths[type].first end
+    
+      # @param type<Symbol> The type of path to retrieve glob for, e.g. :view.
+      #
+      # @return <String> The pattern with which to match files within the type directory.
+      def glob_for(type) self.slice_paths[type][1] end
+
+      # Retrieve the absolute path to a app-level directory. 
+      #
+      # @param type<Symbol> The type of path to retrieve directory for, e.g. :view.
+      #
+      # @return <String> The directory for the requested type.
+      def app_dir_for(type) self.app_paths[type].first end
+    
+      # @param type<Symbol> The type of path to retrieve glob for, e.g. :view.
+      #
+      # @return <String> The pattern with which to match files within the type directory.
+      def app_glob_for(type) self.app_paths[type][1] end
+    
+      # Retrieve the relative path to a public directory.
+      #
+      # @param type<Symbol> The type of path to retrieve directory for, e.g. :view.
+      #
+      # @return <String> The relative path to the public directory for the requested type.
+      def public_dir_for(type)
+        dir = type.is_a?(Symbol) ? self.app_dir_for(type) : self.app_dir_for(:public) / type
+        dir = dir.relative_path_from(Merb.dir_for(:public)) rescue '.'
+        dir == '.' ? '/' : "/#{dir}"
+      end
+      
+      # Construct a path relative to the public directory
+      # 
+      # @param <Symbol> The type of component.
+      # @param *segments<Array[#to_s]> Path segments to append.
+      #
+      # @return <String> 
+      #  A path relative to the public directory, with added segments.
+      def public_path_for(type, *segments)
+        File.join(self.public_dir_for(type), *segments)
+      end
+      
+      # Construct an app-level path.
+      # 
+      # @param <Symbol> The type of component.
+      # @param *segments<Array[#to_s]> Path segments to append.
+      #
+      # @return <String> 
+      #  A path within the host application, with added segments.
+      def app_path_for(type, *segments)
+        prefix = type.is_a?(Symbol) ? self.app_dir_for(type) : self.app_dir_for(:root) / type
+        File.join(prefix, *segments)
+      end
+      
+      # Construct a slice-level path.
+      # 
+      # @param <Symbol> The type of component.
+      # @param *segments<Array[#to_s]> Path segments to append.
+      #
+      # @return <String> 
+      #  A path within the slice source (Gem), with added segments.
+      def slice_path_for(type, *segments)
+        prefix = type.is_a?(Symbol) ? self.dir_for(type) : self.dir_for(:root) / type
+        File.join(prefix, *segments)
+      end
+    
+      # This is the core mechanism for setting up your slice-level layout.
+      #
+      # @param type<Symbol> The type of path being registered (i.e. :view)
+      # @param path<String> The full path
+      # @param file_glob<String>
+      #   A glob that will be used to autoload files under the path. Defaults to "**/*.rb".
+      def push_path(type, path, file_glob = "**/*.rb")
+        enforce!(type => Symbol)
+        slice_paths[type] = [path, file_glob]
+      end
+    
+      # Removes given types of application components
+      # from slice-level load path this slice uses for autoloading.
+      #
+      # @param *args<Array[Symbol]> Components names, for instance, :views, :models
+      def remove_paths(*args)
+        args.each { |arg| self.slice_paths.delete(arg) }
+      end
+    
+      # This is the core mechanism for setting up your app-level layout.
+      #
+      # @param type<Symbol> The type of path being registered (i.e. :view)
+      # @param path<String> The full path
+      # @param file_glob<String>
+      #   A glob that will be used to autoload files under the path. Defaults to "**/*.rb".
+      def push_app_path(type, path, file_glob = "**/*.rb")
+        enforce!(type => Symbol)
+        app_paths[type] = [path, file_glob]
+      end
+    
+      # Removes given types of application components
+      # from app-level load path this slice uses for autoloading.
+      #
+      # @param *args<Array[Symbol]> Components names, for instance, :views, :models
+      def remove_app_paths(*args)
+        args.each { |arg| self.app_paths.delete(arg) }
+      end
+      
+      # Return all *.rb files from valid component paths
+      #
+      # @return <Array> Full paths to loadable ruby files.
+      def loadable_files
+        app_components.inject([]) do |paths, type|
+          paths += Dir[dir_for(type) / '**/*.rb'] if slice_paths.key?(type)
+          paths += Dir[app_dir_for(type) / '**/*.rb'] if app_paths.key?(type)
+          paths
+        end        
+      end
+      
+      # Return all application path component types
+      #
+      # @return <Array[Symbol]> Component types.
+      def app_components
+        [:view, :model, :controller, :helper, :mailer, :part]
+      end
+      
+      # Return all public path component types
+      #
+      # @return <Array[Symbol]> Component types.
+      def public_components
+        [:stylesheet, :javascript, :image]
+      end
+    
+      # Return all path component types to mirror
+      #
+      # If config option :mirror is set return a subset, otherwise return all types.
+      #
+      # @return <Array[Symbol]> Component types.
+      def mirrored_components
+        all = slice_paths.keys
+        config[:mirror].is_a?(Array) ? config[:mirror] & all : all
+      end
+      
+      # Return all application path component types to mirror
+      #
+      # @return <Array[Symbol]> Component types.
+      def mirrored_app_components
+        mirrored_components & app_components
+      end
+      
+      # Return all public path component types to mirror
+      #
+      # @return <Array[Symbol]> Component types.
+      def mirrored_public_components
+        mirrored_components & public_components
+      end
+      
+      # Return all slice files mapped from the source to their relative path
+      #
+      # @param type<Symbol> Which type to use; defaults to :root (all)
+      # @return <Array[Array]> An array of arrays [abs. source, relative dest.]
+      def manifest(type = :root)
+        files = if type == :root
+          Dir.glob(self.root / "**/*")
+        elsif slice_paths.key?(type)
+          glob = ((type == :view) ? view_templates_glob : glob_for(type) || "**/*")
+          Dir.glob(dir_for(type) / glob)
+        else 
+          []
+        end
+        files.map { |source| [source, source.relative_path_from(root)] }
+      end
+      
+      # Clone all files from the slice to their app-level location; this will
+      # also copy /lib, causing merb-slices to pick up the slice there.
+      # 
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      def clone_slice!
+        app_slice_root = app_dir_for(:root)
+        copied, duplicated = [], []
+        manifest.each do |source, relative_path|
+          mirror_file(source, app_slice_root / relative_path, copied, duplicated)
+        end
+        [copied, duplicated]
+      end
+      
+      # Unpack a subset of files from the slice to their app-level location; 
+      # this will also copy /lib, causing merb-slices to pick up the slice there.
+      # 
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      #
+      # @note Files for the :stub component type are skipped.
+      def unpack_slice!
+        app_slice_root = app_dir_for(:root)
+        copied, duplicated = mirror_public!
+        manifest.each do |source, relative_path|
+          next unless unpack_file?(relative_path)
+          mirror_file(source, app_slice_root / relative_path, copied, duplicated)
+        end
+        [copied, duplicated]
+      end
+      
+      # Copies all files from mirrored_components to their app-level location
+      #
+      # This includes application and public components. 
+      # 
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      def mirror_all!
+        mirror_files_for mirrored_components + mirrored_public_components
+      end
+      
+      # Copies all files from the (optional) stubs directory to their app-level location
+      #
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      def mirror_stubs!
+        mirror_files_for :stub
+      end
+      
+      # Copies all application files from mirrored_components to their app-level location
+      #
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      def mirror_app!
+        components = mirrored_app_components
+        components << :application if application_file?
+        mirror_files_for components
+      end
+      
+      # Copies all application files from mirrored_components to their app-level location
+      #
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      def mirror_public!
+        mirror_files_for mirrored_public_components
+      end
+      
+      # Copy files from specified component path types to their app-level location
+      #
+      # App-level overrides are preserved by creating duplicates before writing gem-level files.
+      # Because of their _override postfix they will load after their original implementation.
+      # In the case of views, this won't work, but the user override is preserved nonetheless.
+      # 
+      # @return <Array[Array]> 
+      #   Array of two arrays, one for all copied files, the other for overrides 
+      #   that may have been preserved to resolve collisions.
+      #
+      # @note Only explicitly defined component paths will be taken into account to avoid
+      #   cluttering the app's Merb.root by mistake - since undefined paths default to that.
+      def mirror_files_for(*types)
+        seen, copied, duplicated = [], [], [] # keep track of files we copied
+        types.flatten.each do |type|
+          if app_paths.key?(type) && (source_path = dir_for(type)) && (destination_path = app_dir_for(type))
+            manifest(type).each do |source, relative_path| # this relative path is not what we need here
+              next if seen.include?(source)
+              mirror_file(source, destination_path / source.relative_path_from(source_path), copied, duplicated)
+              seen << source
+            end
+          end
+        end
+        [copied, duplicated]
+      end
+      
+      # This sets up the default slice-level and app-level structure.
+      # 
+      # You can create your own structure by implementing setup_structure and
+      # using the push_path and push_app_paths. By default this setup matches
+      # what the merb-gen slice generator creates.
+      def setup_default_structure!
+        self.push_app_path(:root, Merb.root / 'slices' / self.identifier, nil)
+        
+        self.push_path(:stub, root_path('stubs'), nil)
+        self.push_app_path(:stub, app_dir_for(:root), nil)
+        
+        self.push_path(:application, root_path('app'), nil)
+        self.push_app_path(:application, app_dir_for(:root) / 'app', nil)
+      
+        app_components.each do |component|
+          self.push_path(component, dir_for(:application) / "#{component}s")
+          self.push_app_path(component, app_dir_for(:application) / "#{component}s")
+        end
+      
+        self.push_path(:public, root_path('public'), nil)
+        self.push_app_path(:public,  Merb.dir_for(:public) / 'slices' / self.identifier, nil)
+      
+        public_components.each do |component|
+          self.push_path(component, dir_for(:public) / "#{component}s", nil)
+          self.push_app_path(component, app_dir_for(:public) / "#{component}s", nil)
+        end
+      end   
+      
+      protected
+      
+      # Collect slice-level and app-level load paths to load from.
+      #
+      # @param modify_load_path<Boolean> 
+      #   Whether to add certain paths to $LOAD_PATH; defaults to true.
+      # @param push_merb_path<Boolean> 
+      #   Whether to add app-level paths using Merb.push_path; defaults to true.
+      def collect_load_paths(modify_load_path = true, push_merb_path = true)
+        self.collected_slice_paths.clear; self.collected_app_paths.clear
+        self.slice_paths.each do |component, path|
+          if File.directory?(component_path = path.first)
+            $LOAD_PATH.unshift(component_path) if modify_load_path && component.in?(:model, :controller, :lib) && !$LOAD_PATH.include?(component_path)
+            # slice-level component load path - will be preceded by application/app/component - loaded next by Setup.load_classes
+            self.collected_slice_paths << path.first / path.last if path.last
+            # app-level component load path (override) path - loaded by BootLoader::LoadClasses
+            if (app_glob = self.app_glob_for(component)) && File.directory?(app_component_dir = self.app_dir_for(component))
+              self.collected_app_paths << app_component_dir / app_glob
+              Merb.push_path(:"#{self.name.snake_case}_#{component}", app_component_dir, app_glob) if push_merb_path
+            end
+          end
+        end
+      end
+      
+      # Helper method to copy a source file to destination while resolving any conflicts.
+      #
+      # @param source<String> The source path.
+      # @param dest<String> The destination path.
+      # @param copied<Array> Keep track of all copied files - relative paths.
+      # @param duplicated<Array> Keep track of all duplicated files - relative paths.
+      # @param postfix<String> The postfix to use for resolving conflicting filenames.
+      def mirror_file(source, dest, copied = [], duplicated = [], postfix = '_override')
+        base, rest = split_name(source)
+        dst_dir = File.dirname(dest)
+        dup_path = dst_dir / "#{base}#{postfix}.#{rest}"           
+        if File.file?(source)
+          FileUtils.mkdir_p(dst_dir) unless File.directory?(dst_dir)
+          if File.exists?(dest) && !File.exists?(dup_path) && !FileUtils.identical?(source, dest)
+            # copy app-level override to *_override.ext
+            FileUtils.copy_entry(dest, dup_path, false, false, true)
+            duplicated << dup_path.relative_path_from(Merb.root)
+          end
+          # copy gem-level original to location
+          if !File.exists?(dest) || (File.exists?(dest) && !FileUtils.identical?(source, dest))
+            FileUtils.copy_entry(source, dest, false, false, true) 
+            copied << dest.relative_path_from(Merb.root)
+          end
+        end
+      end
+      
+      # Predicate method to check if a file should be taken into account when unpacking files
+      #
+      # By default any public component paths and stubs are skipped; additionally you can set
+      # the :skip_files in the slice's config for other relative paths to skip.
+      #
+      # @param file<String> The relative path to test.
+      # @return <TrueClass,FalseClass> True if the file may be mirrored.
+      def unpack_file?(file)
+        @mirror_exceptions_regexp ||= begin
+          skip_paths = (mirrored_public_components + [:stub]).map { |type| dir_for(type).relative_path_from(self.root) }
+          skip_paths += config[:skip_files] if config[:skip_files].is_a?(Array)
+          Regexp.new("^(#{skip_paths.join('|')})")
+        end
+        not file.match(@mirror_exceptions_regexp)
+      end
+      
+      # Predicate method to check if the :application component is a file
+      def application_file?
+        File.file?(dir_for(:application) / glob_for(:application))
+      end
+      
+      # Glob pattern matching all valid template extensions
+      def view_templates_glob
+        "**/*.{#{Merb::Template.template_extensions.join(',')}}"
+      end
+      
+      # Split a file name so a postfix can be inserted
+      #
+      # @return <Array[String]> 
+      #   The first element will be the name up to the first dot, the second will be the rest.
+      def split_name(name)
+        file_name = File.basename(name)
+        mres = /^([^\/\.]+)\.(.+)$/i.match(file_name)
+        mres.nil? ? [file_name, ''] : [mres[1], mres[2]]
+      end
+      
+    end
+  end
+end