directory_template 1.0.0

data/lib/directory_template/erb_template.rb

@@ -0,0 +1,239 @@
+# encoding: utf-8
+
+
+
+require 'erb'
+require 'directory_template/blank_slate'
+
+
+
+class DirectoryTemplate
+
+  # @author Stefan Rusterholz <stefan.rusterholz@gmail.com>
+  #
+  # A helper class for ERB. Allows constructs like the one in the examples to
+  # enable simple use of variables/methods in templates.
+  #
+  # @example A simple ERB template being rendered
+  #     tmpl = DirectoryTemplate::ErbTemplate.new("Hello <%= name %>!")
+  #     tmpl.result(self, :name => 'world') # => 'Hello World!'
+  #
+  class ErbTemplate
+
+    # @author Stefan Rusterholz <stefan.rusterholz@gmail.com>
+    #
+    # Variables is similar to OpenStruct, but slightly optimized for create once, use once
+    # and giving diagnostics on exceptions/missing keys.
+    #
+    # @example
+    #   variables = Variables.new(delegator, :x => "Value of X") { |exception|
+    #     do_something_with(exception)
+    #   }
+    #   variables.x # => "Value of X"
+    #
+    class Variables < BlankSlate
+
+      # A proc for &on_error in DirectoryTemplate::ErbTemplate::Variables::new or
+      # DirectoryTemplate::ErbTemplate#result.
+      # Raises the error further on.
+      Raiser = proc { |e|
+        raise(e)
+      }
+
+      # A proc for &on_error in DirectoryTemplate::ErbTemplate::Variables.new or
+      # DirectoryTemplate::ErbTemplate#result.
+      # Inserts <<error_class: error_message>> in the place where the error
+      # occurred.
+      Teller = proc { |e|
+        "<<#{e.class}: #{e}>>"
+      }
+
+      # An empty Hash
+      EmptyHash     = {}.freeze
+
+      # Regex to match setter method names
+      SetterPattern = /=\z/.freeze
+
+      # @param [Object] delegate
+      #   All method calls and undefined variables are delegated to this object as method
+      #   call.
+      # @param [Hash<Symbol,Object>] variables
+      #   A hash with variables in it, keys must be Symbols.
+      # @param [Symbol] on_error_name
+      #   Instead of a block you can pass the name of an existing handler, e.g. :Raiser
+      #   or :Teller.
+      #
+      # @yield [exception] description
+      #   The block is yielded in case of an exception with the exception as argument.
+      #
+      def initialize(delegate=nil, variables={}, on_error_name=nil, &on_error)
+        @delegate = delegate
+        @table    = (@delegate ? Hash.new { |h,k| @delegate.send(k) } : EmptyHash).merge(variables)
+        if !on_error && on_error_name then
+          @on_error = self.class.const_get(on_error_name)
+        else
+          @on_error = on_error || Raiser
+        end
+      end
+
+      # @return [Array<Symbol>]
+      #   All keys this Variables instance provides, if the include_delegate argument is
+      #   true and the object to delegate to responds to __keys__, then it will add the
+      #   keys of the delegate.
+      def __keys__(include_delegate=true)
+        @table.keys + ((include_delegate && @delegate.respond_to?(:__keys__)) ? @delegate.__keys__ : [])
+      end
+
+      # @return [Binding] Make the binding publicly available
+      def __binding__
+        binding
+      end
+
+      # @private
+      # @see Object#respond_to_missing?
+      def respond_to_missing?(key)
+        @table.respond_to?(key) || (@delegate && @delegate.respond_to?(key))
+      end
+
+      # @private
+      # Set or get the value associated with the key matching the method name.
+      def method_missing(m, *args) # :nodoc:
+        argn = args.length
+        if argn.zero? && @table.has_key?(m) then
+          @table[m]
+        elsif argn == 1 && m.to_s =~ SetterPattern
+          @table[m] = args.first
+        elsif @delegate
+          @delegate.send(m, *args)
+        end
+      rescue => e
+        @on_error.call(e)
+      end
+
+      # @private
+      # See Object#inspect
+      def inspect # :nodoc:
+        sprintf "#<%s:0x%08x @delegate=%s %s>",
+          self.class,
+          __id__,
+          @table.map { |k,v| "#{k}=#{v.inspect}" }.join(', '),
+          @delegate ? "#<%s:0x%08x ...>" %  [@delegate.class, @delegate.object_id << 1] : "nil"
+      end
+    end
+
+    # Option defaults
+    Opt = {
+      :safe_level => nil,
+      :trim_mode  => '%<>',
+      :eoutvar    => '_erbout'
+    }
+
+    # An UnboundMethod instance of instance_eval
+    InstanceEvaler  = Object.instance_method(:instance_eval)
+
+
+    # A proc for &on_error in DirectoryTemplate::ErbTemplate::Variables::new or DirectoryTemplate::ErbTemplate#result.
+    # Raises the error further on.
+    Raiser = proc { |e|
+      raise
+    }
+
+    # A proc for &on_error in DirectoryTemplate::ErbTemplate::Variables::new or DirectoryTemplate::ErbTemplate#result.
+    # Inserts <<error_class: error_message>> in the place where the error
+    # occurred.
+    Teller = proc { |e|
+      "<<#{e.class}: #{e}>>"
+    }
+
+    # The template string
+    attr_reader :string
+
+    # Like ErbTemplate.new, but instead of a template string, the path to the file
+    # containing the template. Sets :filename.
+    #
+    # @param [String] path
+    #   The path to the file to use as a template
+    #
+    # @param [Hash] options
+    #   See ErbTemplate::new for the options
+    def self.file(path, options=nil)
+      options = options ? options.merge(:filename => path) : {:filename => path}
+
+      new(File.read(path), options)
+    end
+
+    # @param [String] string
+    #   The template string
+    # @param [Hash] options
+    #   A couple of options
+    #
+    # @option options [String] :filename
+    #   The filename used for the evaluation (useful for error messages)
+    # @option options [Integer] :safe_level
+    #   See ERB.new
+    # @option options [String] :trim_mode
+    #   See ERB.new
+    # @option options [Symbol, String] :eoutvar
+    #   See ERB.new
+    def initialize(string, options={})
+      options, string = string, nil if string.kind_of?(Hash)
+      options         = Opt.merge(options)
+      filename        = options.delete(:filename)
+      raise ArgumentError, "String or filename must be given" unless string || filename
+
+      @string       = string || File.read(filename)
+      @erb          = ERB.new(@string, *options.values_at(:safe_level, :trim_mode, :eoutvar))
+      @erb.filename = filename if filename
+    end
+
+    # @return [String]
+    #   The evaluated template. Default &on_error is the
+    #   DirectoryTemplate::ErbTemplate::Raiser proc.
+    def result(variables=nil, on_error_name=nil, &on_error)
+      variables ||= {}
+      on_error  ||= Raiser
+      variables = Variables.new(nil, variables, on_error_name, &on_error)
+      @erb.result(variables.__binding__)
+    rescue NameError => e
+      raise NameError, e.message+" for #{self.inspect} with #{variables.inspect}", e.backtrace
+    end
+
+    # @param [Hash] options
+    #   A couple of options
+    #
+    # @option options [Hash] :variables
+    #   A hash with all the variables that should be available in the template.
+    # @option options [Object] :delegate
+    #   An object, to which methods should be delegated.
+    # @option options [Proc, Symbol, #to_proc] :on_error
+    #   The callback to use in case of an exception.
+    #
+    # @return [String]
+    #   The evaluated template. Default &on_error is the
+    #   DirectoryTemplate::ErbTemplate::Raiser proc.
+    def result_with(options, &block)
+      options   = options.dup
+      variables = options.delete(:variables) || {}
+      delegate  = options.delete(:delegate)
+      on_error  = options.delete(:on_error) || block
+      if on_error.is_a?(Symbol) then
+        on_error_name = on_error
+        on_error      = nil
+      end
+      variables = Variables.new(delegate, variables, on_error_name, &on_error)
+
+      @erb.result(variables.__binding__)
+    rescue NameError => e
+      raise NameError, e.message+" for #{self.inspect} with #{variables.inspect}", e.backtrace
+    end
+
+    # @private
+    # See Object#inspect
+    def inspect # :nodoc:
+      sprintf "#<%s:0x%x string=%s>",
+        self.class,
+        object_id << 1,
+        @string.inspect
+    end
+  end
+end

data/lib/directory_template/process_data.rb

@@ -0,0 +1,94 @@
+class DirectoryTemplate
+
+  # ProcessData is the value that gets passed to processors.
+  # The processor must mutate it.
+  class ProcessData
+
+    # A reference to the DirectoryTemplate of which this file/directory is part of
+    attr_reader :directory_template
+
+    # The path as it is in the current stage of processing.
+    attr_reader :path
+
+    # The filename, as it is in the current stage of processing.
+    attr_reader :filename
+
+    # The directory, as it is in the current stage of processing.
+    attr_reader :directory
+
+    # The suffix, as it is in the current stage of processing.
+    attr_reader :suffix
+
+    # The file-content, as it is in the current stage of processing (nil for directories).
+    attr_accessor :content
+
+    # Variables to be used for path preprocessing
+    attr_reader :path_variables
+
+    # Variables to be used for filecontent preprocessing
+    attr_reader :content_variables
+
+    # Variables to be used for both, path- and filecontent preprocessing
+    attr_reader :variables
+
+
+    # A content of nil means this is a directory
+    # @param [Hash] env
+    #   A hash with additional information, used to parametrize and preprocess the template.
+    #   @options env [Hash<Symbol,String>] :variables
+    #     Variables used for both, path- and filecontent processing.
+    #   @options env [Hash<Symbol,String>] :path_variables
+    #     Variables only used for path-processing.
+    #   @options env [Hash<Symbol,String>] :content_variables
+    #     Variables only used for filecontent processing.
+    def initialize(directory_template, path, content, env)
+      @directory_template = directory_template
+      @content            = content
+      @variables          = env[:variables] || {}
+      @path_variables     = @variables.merge(env[:path_variables] || {})
+      @content_variables  = @variables.merge(env[:content_variables] || {})
+      self.path           = path
+    end
+
+    # Whether the processor is suitable for the given ProcessData.
+    # Simply delegates the job to the Processor.
+    #
+    # @see Processor#===
+    def ===(processor)
+      processor === self
+    end
+
+    # @return [Boolean]
+    #   Whether the item is a file. The alternative is, that it is a directory.
+    #
+    # @see #directory?
+    def file?
+      !!@content
+    end
+
+    # @return [Boolean]
+    #   Whether the item is a directory. The alternative is, that it is a file.
+    #
+    # @see #file?
+    def directory?
+      !@content
+    end
+
+    # @param [String] value
+    #   The new path
+    #
+    # Sets the path, filename, directory and suffix of this item.
+    def path=(value)
+      @path       = value
+      @filename   = File.basename(value)
+      @directory  = File.dirname(value)
+      @suffix     = File.extname(value)
+    end
+
+    # Removes the current suffix. E.g. "foo/bar.baz.quuz" would be "foo/bar.baz" after the
+    # operation.
+    def chomp_suffix!
+      self.path   = @path.chomp(@suffix)
+    end
+  end
+end

data/lib/directory_template/processor/erb.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+
+
+require 'directory_template/erb_template'
+
+
+
+class DirectoryTemplate
+  class Processor
+
+    # The ERB Processor treats the file-content as ERB template.
+    Erb = Processor.register(:erb, '*.erb', 'ERB Template Processor') do |data|
+      data.content = ErbTemplate.new(data.content).result(data.content_variables)
+      data.chomp_suffix!
+    end
+  end
+end

data/lib/directory_template/processor/format.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+
+
+class DirectoryTemplate
+  class Processor
+
+    # The standard processor for file- and directory-paths. It simply uses String#% style
+    # keyword replacement. I.e., `%{key}` is replaced by the variable value passed with
+    # :key.
+    Format = Processor.new(:format, nil, '%{variable} format processor') do |data|
+      data.path = data.path % data.path_variables if data.path_variables
+    end
+  end
+end

data/lib/directory_template/processor/markdown.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+
+
+class DirectoryTemplate
+  class Processor
+
+    # The ERB Processor treats the file-content as ERB template.
+    Markdown = Processor.register(:markdown_to_html, '*.html.markdown', 'Markdown to HTML Template Processor') do |data|
+      Markdown.require 'kramdown'
+      data.content = Kramdown::Document.new(data.content).to_html
+      data.chomp_suffix!
+    end
+  end
+end

data/lib/directory_template/processor/stop.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+
+
+class DirectoryTemplate
+  class Processor
+
+    # The 
+    Stop = Processor.register(:stop, '*.stop', 'Terminate processing queue', 'After .stop, no processor will be run anymore') do |data|
+      data.chomp_suffix!
+      throw :stop_processing
+    end
+  end
+end

data/lib/directory_template/processor.rb

@@ -0,0 +1,127 @@
+# encoding: utf-8
+
+class DirectoryTemplate
+
+  # The definition of a processor
+  #
+  # Use {Processor.register} to register a processor. A registered processor is available
+  # in all DirectoryTemplate instances.
+  #
+  # Processor::register takes the same arguments as {Processor#initialize Processor::new}, so look there for how
+  # to define a processor.
+  #
+  # Take a look at {ProcessData} to see what data your processor gets and can work on.
+  class Processor
+
+    # A matcher-proc to never match
+    Never = proc { |data| false }
+
+    # Searches for all processors and registers them
+    def self.register_all
+      $LOAD_PATH.each do |path|
+        Dir.glob(File.join(path, 'directory_template', 'processor', '**', '*.rb')) do |processor|
+          require processor
+        end
+      end
+    end
+
+    # Creates a Processor and registers it.
+    # The arguments are passed verbatim to Processor::new.
+    #
+    # @return [Processor]
+    def self.register(*arguments, &block)
+      processor = new(*arguments, &block)
+      DirectoryTemplate.register(processor)
+
+      processor
+    end
+
+    # The pattern matching proc used to figure whether the processor applies to a
+    # ProcessData or not.
+    attr_reader :pattern
+
+    # The source used to create the pattern proc. I.e., the value passed to ::new as the
+    # pattern parameter.
+    attr_reader :pattern_source
+
+    # A human identifiable name
+    attr_reader :name
+
+    # A human understandable description of the processor
+    attr_reader :description
+
+    # The implementation of the processor. I.e., the block passed to ::new.
+    attr_reader :execute
+
+    # @param [Symbol] id
+    #   A (in the set of Processors) unique id
+    #
+    # @param [String, Regexp, Proc, #to_proc, nil] pattern
+    #   The pattern determines upon what {ProcessData} this processor is being invoked.
+    #
+    #   If you provide a String, it is interpreted as a glob-like-pattern, e.g.
+    #   '*.html.haml' will match any files whose suffix is '.html.haml'.
+    #   See File::fnmatch for an extensive documentation of glob-patterns.
+    #   
+    #   If you provide a Regexp, the filename is matched against that regexp.
+    #
+    #   If you provide a Proc (or anything that is converted to a proc), the proc gets
+    #   the ProcessData as sole argument and should return true/false, to indicate,
+    #   whether the Processor should be invoked or not.
+    #
+    #   If you pass nil as pattern, the Processor will never be invoked. This is useful
+    #   for processors that serve only as path processors.
+    #
+    # @param [String] name
+    #   The name of the processor
+    #
+    # @param [String] description
+    #   A description, what the processor does
+    #
+    # @param [#call] execute
+    #   The implementation of the processor
+    def initialize(id, pattern, name=nil, description=nil, &execute)
+      raise ArgumentError, "ID must be a Symbol" unless id.is_a?(Symbol)
+      @id             = id
+      @pattern_source = pattern
+      @pattern        = case pattern
+        when String then proc { |data| File.fnmatch?(pattern, data.path) }
+        when Regexp then proc { |data| pattern =~ data.path }
+        when Proc   then pattern
+        when nil    then Never
+        else
+          raise ArgumentError, "Expected a String, Regexp or Proc as pattern, but got #{pattern.class}"
+      end
+      @name         = name
+      @description  = description
+      @execute      = execute
+    end
+
+    # @return [Boolean]
+    #   Whether the processor is suitable for the given ProcessData
+    def ===(process_data)
+      @pattern.call(process_data)
+    end
+
+    # Apply the processor on a ProcessData instance.
+    #
+    # @param [DirectoryTemplate::ProcessData] process_data
+    #   The process data to apply this processor on.
+    #
+    # @return [DirectoryTemplate::ProcessData]
+    #   The process_data passed to this method.
+    def call(process_data)
+      @execute.call(process_data)
+
+      process_data
+    end
+
+    # Invokes Kernel#require, and fails with a custom error message.
+    # @see Kernel#require
+    def require(lib)
+      super(lib)
+    rescue LoadError
+      raise "The #{@name || @id} processor requires #{lib} in order to work"
+    end
+  end
+end

data/lib/directory_template/version.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+begin
+  require 'rubygems/version' # newer rubygems use this
+rescue LoadError
+  require 'gem/version' # older rubygems use this
+end
+
+class DirectoryTemplate
+
+  # The version of DirectoryTemplate
+  Version = Gem::Version.new("1.0.0")
+end