linecook 0.6.2 → 1.0.0

data/lib/linecook/proxy.rb

@@ -0,0 +1,19 @@
+module Linecook
+  # A proxy used to chain method calls back to a recipe.
+  class Proxy
+    def initialize(recipe)
+      @recipe = recipe
+    end
+    
+    # Proxies to recipe.chain.
+    def method_missing(*args, &block)
+      @recipe.chain(*args, &block)
+    end
+    
+    # Returns an empty string, such that the proxy makes no text when it is
+    # accidentally put into a target by a helper.
+    def to_s
+      ''
+    end
+  end
+end

data/lib/linecook/recipe.rb

@@ -1,103 +1,362 @@
-require 'linecook/template'
 require 'linecook/attributes'
-require 'linecook/package'
+require 'linecook/proxy'
 require 'linecook/utils'
+require 'erb'
+require 'stringio'
 
 module Linecook
-  class Recipe < Template
-    class << self
-      def build(env)
-        package = Package.new(env)
-        
-        package.recipes.each do |recipe_name, target_name|
-          new(target_name, env).evaluate(recipe_name)
-        end
-        
-        package.close
-        package
-      end
-    end
+  # Recipe is the context in which recipes are evaluated (literally).  Recipe
+  # uses compiled ERB snippets to build text using method calls. For example:
+  #
+  #   module Helper
+  #     # This is an ERB template compiled to write to a Recipe.
+  #     #
+  #     #   compiler = ERB::Compiler.new('<>')
+  #     #   compiler.put_cmd = "write"
+  #     #   compiler.insert_cmd = "write"
+  #     #   compiler.compile("echo '<%= args.join(' ') %>'\n")
+  #     #
+  #     def echo(*args)
+  #       write "echo '"; write(( args.join(' ') ).to_s); write "'\n"
+  #     end
+  #   end
+  #
+  #   package = Package.new
+  #   recipe  = package.setup_recipe
+  #
+  #   recipe.extend Helper
+  #   recipe.instance_eval do
+  #     echo 'a', 'b c'
+  #     echo 'X Y'.downcase, :z
+  #   end
+  #
+  #   "\n" + recipe.result
+  #   # => %{
+  #   # echo 'a b c'
+  #   # echo 'x y z'
+  #   # }
+  #
+  class Recipe
+    
+    # The recipe package
+    attr_reader :_package_
+    
+    # The recipe target
+    attr_reader :_target_
+    
+    # The target name of self in package
+    attr_reader :_target_name_
+    
+    # The recipe proxy
+    attr_reader :_proxy_
     
-    alias target erbout
+    # The current target for self set as needed during captures; equal to
+    # _target_ otherwise.
+    attr_reader :target
     
+    # The current target_name for self set as needed during captures; equal to
+    # _target_name_ otherwise.
     attr_reader :target_name
     
-    def initialize(target_name, env={})
-      @target_name = target_name
-      @package     = Package.init(env)
-      @attributes  = Attributes.new(@package.env)
-      @erbout      = @package.build(target_name)
+    def initialize(package, target_name, mode)
+      @_package_     = package
+      @_target_name_ = target_name
+      @_target_      = package.setup_tempfile(target_name, mode)
+      @_proxy_       = Proxy.new(self)
+      
+      @target_name   = @_target_name_
+      @target        = @_target_
+      
+      @chain       = false
+      @attributes  = {}
+      @indents     = []
+      @outdents    = []
     end
     
-    def source_path(*relative_path)
-      path = File.join(*relative_path)
-      @package.manifest[path] or raise "no such file in manifest: #{path.inspect}"
+    # Closes _target_ and returns self.
+    def close
+      unless closed?
+        _target_.close
+      end
+      self
     end
     
-    def target_path(source_path)
-      @package.build_path(source_path) ||
-      @package.register(source_path, File.join("#{target_name}.d", File.basename(source_path)))
+    # Returns true if _target_ is closed.
+    def closed?
+      _target_.closed?
     end
     
-    def target_file(name, content=nil)
-      tempfile = @package.build File.join("#{target_name}.d", name)
+    # Returns the current contents of target, or the contents of _target_ if
+    # closed? is true.
+    def result
+      if closed?
+        _package_.content(_target_name_)
+      else
+        target.flush
+        target.rewind
+        target.read
+      end
+    end
+    
+    # Loads the specified attributes file and merges the results into attrs. A
+    # block may be given to specify attrs as well; it will be evaluated in the
+    # context of an Attributes instance.
+    def attributes(attributes_name=nil, &block)
+      attributes = _package_.load_attributes(attributes_name)
       
-      tempfile << content if content
-      yield(tempfile) if block_given?
+      if block_given?
+        attributes.instance_eval(&block)
+      end
       
-      target_path tempfile.path
+      @attributes = Utils.deep_merge(@attributes, attributes.to_hash)
+      @attrs = nil
+      self
     end
     
+    # Returns the package env merged over any attrs specified by attributes.
+    # The attrs hash should be treated as if it were read-only because changes
+    # could alter the package env and thereby spill over into other recipes.
     def attrs
-      @attributes.current
+      @attrs ||= Utils.deep_merge(@attributes, _package_.env)
+    end
+    
+    # Looks up and extends self with the specified helper.
+    def helpers(helper_name)
+      extend _package_.load_helper(helper_name)
+    end
+    
+    # Returns an expression that evaluates to the package dir, assuming that
+    # $0 evaluates to the full path to the current recipe.
+    def package_dir
+      "${0%/#{target_name}}"
+    end
+    
+    # The path to the named target as it should be referenced in the final
+    # script, specifically target_name joined to package_dir.
+    def target_path(target_name)
+      File.join(package_dir, target_name)
+    end
+    
+    # Registers the specified file into package and returns the target_path to
+    # the file.
+    def file_path(file_name, target_name=file_name, mode=0600)
+      _package_.build_file(target_name, file_name, mode)
+      target_path target_name
+    end
+    
+    # Looks up, builds, and registers the specified template and returns the
+    # target_path to the resulting file.
+    def template_path(template_name, target_name=template_name, mode=0600, locals={'attrs' => attrs})
+      _package_.build_template(target_name, template_name, mode, locals)
+      target_path target_name
+    end
+    
+    # Looks up, builds, and registers the specified recipe and returns the
+    # target_path to the resulting file.
+    def recipe_path(recipe_name, target_name=recipe_name, mode=0700)
+      _package_.build_recipe(target_name, recipe_name, mode)
+      target_path target_name
     end
     
-    def attributes(attributes_name)
-      path = source_path('attributes', "#{attributes_name}.rb")
+    # Captures the output for a block, registers it, and returns the
+    # target_path to the resulting file.  The current target and target_name
+    # are updated for the duration of the block.
+    def capture_path(target_name, mode=0600)
+      tempfile = _package_.setup_tempfile(target_name, mode)
+      capture_block(tempfile) do
+        current = @target_name
+        
+        begin
+          @target_name = target_name
+          yield
+        ensure
+          @target_name = current
+        end
+        
+      end
+      tempfile.close
       
-      @attributes.instance_eval(File.read(path), path)
-      @attributes.reset(false)
-      self
+      target_path target_name
     end
     
-    def helpers(helper_name)
-      require Utils.underscore(helper_name)
-      extend Utils.constantize(helper_name)
+    # Captures output to the target for the duration of a block.  Returns the
+    # capture target.
+    def capture_block(target=StringIO.new)
+      current = @target
+
+      begin
+        @target = target
+        yield
+      ensure
+        @target = current
+      end
+
+      target
+    end
+    
+    # Captures and returns output for the duration of a block by redirecting
+    # target to a temporary buffer.
+    def capture_str
+      capture_block { yield }.string
+    end
+    
+    # Writes input to target using 'write'.  Returns self.
+    def write(input)
+      target.write input
+      self
     end
     
-    def evaluate(recipe_name=target_name)
-      path = source_path('recipes', "#{recipe_name}.rb")
-      instance_eval(File.read(path), path)
+    # Writes input to target using 'puts'.  Returns self.
+    def writeln(input)
+      target.puts input
       self
     end
     
-    def file_path(file_name)
-      path = source_path('files', file_name)
-      target_path path
+    # Truncates the contents of target starting at the first match of pattern
+    # and returns the resulting match data. If a block is given then rewrite
+    # yields the match data to the block and returns the block result.
+    # 
+    # ==== Notes
+    #
+    # Rewrites can be computationally expensive because they require the
+    # current target to be flushed, rewound, and read in it's entirety.  In
+    # practice the performance of rewrite is almost never an issue because
+    # recipe output is usually small in size.
+    #
+    # If performance becomes an issue, then wrap the rewritten bits in a
+    # capture block to reassign the current target to a StringIO (which is
+    # much faster to rewrite), and to limit the scope of the rewritten text.
+    def rewrite(pattern)
+      if match = pattern.match(result)
+        start = match.begin(0)
+        target.pos = start
+        target.truncate start
+      end
+      
+      block_given? ? yield(match) : match
     end
     
-    def capture_path(name, &block)
-      content = capture(false) { instance_eval(&block) }
-      target_file(name, content)
+    # Strips whitespace from the end of target and returns the stripped
+    # whitespace, or an empty string if no whitespace is available.
+    def rstrip
+      match = rewrite(/\s+\z/)
+      match ? match[0] : ''
     end
     
-    def recipe_path(recipe_name, target_name = recipe_name)
-      source_path = 
-        @package.built?(target_name) ?
-        @package.source_path(target_name) :
-        Recipe.new(target_name, @package).evaluate(recipe_name).target.path
+    # Indents the output of the block.  Indents may be nested. To prevent a
+    # section from being indented, enclose it within outdent which resets
+    # indentation to nothing for the duration of a block.
+    #
+    # Example:
+    #
+    #   writeln 'a'
+    #   indent do
+    #     writeln 'b'
+    #     outdent do
+    #       writeln 'c'
+    #       indent do
+    #         writeln 'd'
+    #       end
+    #       writeln 'c'
+    #     end
+    #     writeln 'b'
+    #   end
+    #   writeln 'a'
+    #
+    #   "\n" + result
+    #   # => %q{
+    #   # a
+    #   #   b
+    #   # c
+    #   #   d
+    #   # c
+    #   #   b
+    #   # a
+    #   # }
+    #
+    def indent(indent='  ')
+      @indents << @indents.last.to_s + indent
+      str = capture_str { yield }
+      @indents.pop
+
+      unless str.empty?
+        str.gsub!(/^/, indent)
+
+        if @indents.empty?
+          @outdents.each do |flag|
+            str.gsub!(/#{flag}(\d+):(.*?)#{flag}/m) do
+              $2.gsub!(/^.{#{$1.to_i}}/, '')
+            end
+          end
+          @outdents.clear
+        end
+
+        writeln str
+      end
+
+      self
+    end
+
+    # Resets indentation to nothing for a section of text indented by indent.
+    #
+    # === Notes
+    #
+    # Outdent works by setting a text flag around the outdented section; the
+    # flag and indentation is later stripped out using regexps.  For that
+    # reason, be sure flag is not something that will appear anywhere else in
+    # the section.
+    #
+    # The default flag is like ':outdent_N:' where N is a big random number.
+    def outdent(flag=nil)
+      current_indent = @indents.last
+      
+      if current_indent.nil?
+        yield
+      else
+        flag ||= ":outdent_#{rand(10000000)}:"
+        @outdents << flag
+        
+        write "#{flag}#{current_indent.length}:#{rstrip}"
+        @indents << ''
+        
+        yield
+        
+        @indents.pop
+        
+        write "#{flag}#{rstrip}"
+      end
       
-      target_path source_path
+      self
     end
     
-    def template_path(template_name, locals={})
-      path = source_path('templates', "#{template_name}.erb")
-      target_file template_name, Template.build(File.read(path), locals, path)
+    # Sets chain? to true and calls the method (thereby allowing the method to
+    # invoke chain-specific behavior).  Chain is invoked via the chain_proxy
+    # which is returned by helper methods.
+    def chain(method_name, *args, &block)
+      @chain = true
+      send(method_name, *args, &block)
     end
     
-    def close
-      @package.close
-      @package.registry
+    # Returns true if the current context was invoked through chain.
+    def chain?
+      @chain
+    end
+    
+    # Sets chain to false and returns the proxy.
+    def chain_proxy
+      @chain = false
+      _proxy_
+    end
+    
+    # Captures a block of output and concats to the named callback.
+    def callback(name)
+      target = _package_.callbacks[name]
+      capture_block(target) { yield }
+    end
+    
+    # Writes the specified callback to the current target.
+    def write_callback(name)
+      write _package_.callbacks[name].string
     end
   end
 end

data/lib/linecook/template.rb

@@ -1,111 +1,17 @@
-require 'ostruct'
-require 'stringio'
 require 'erb'
+require 'ostruct'
 
 module Linecook
   class Template
-    class << self
-      def build(template, locals, template_path=nil)
-        ERB.new(template).result(OpenStruct.new(locals).send(:binding))
-      end
-    end
-    
-    attr_reader :erbout
-    
-    def initialize
-      @erbout = StringIO.new
-    end
-    
-    # Returns self (not the underlying erbout storage that actually receives
-    # the output lines).  In the ERB context, this method directs erb outputs
-    # to Template#concat and into the redirect mechanism.
-    def _erbout
-      self
-    end
-    
-    # Sets the underlying erbout storage to input.
-    def _erbout=(input)
-    end
-    
-    # Concatenates the specified input to the underlying erbout storage.
-    def concat(input)
-      erbout << input
-      self
-    end
-    
-    def capture(strip=true)
-      current, redirect = erbout, StringIO.new
-      
-      begin
-        @erbout = redirect
-        yield
-      ensure
-        @erbout = current
-      end
-      
-      str = redirect.string
-      str.strip! if strip
-      str
-    end
-    
-    def indent(indent='  ', &block)
-      capture(&block).split("\n").each do |line|
-        concat "#{indent}#{line}\n"
-      end
-      self
-    end
-    
-    def nest(*nestings)
-      options  = nestings.last.kind_of?(Hash) ? nestings.pop : {}
-      indent   = options[:indent] || "  "
-      line_sep = options[:line_sep] || "\n"
-      
-      content = capture { yield }
-      return content if nestings.empty?
-      
-      depth = nestings.length
-      lines = [indent * depth + content.gsub(/#{line_sep}/, line_sep + indent * depth)]
-
-      nestings.reverse_each do |(start_line, end_line)|
-        depth -= 1
-        lines.unshift(indent * depth + start_line)
-        lines << (indent * depth + end_line)
-      end
-
-      concat lines.join(line_sep)
-    end
-    
-    def rstrip(n=10)
-      yield if block_given?
-      
-      pos = erbout.pos
-      n = pos if pos < n
-      start = pos - n
-      
-      erbout.pos = start
-      tail = erbout.read(n).rstrip
-      
-      erbout.pos = start
-      erbout.truncate start
-      
-      tail.length == 0 && start > 0 ? rstrip(n * 2) : concat(tail)
-    end
-    
-    def close
-      erbout.close unless closed?
-      self
-    end
+    attr_reader :erb
     
-    def closed?
-      erbout.closed?
+    def initialize(filename)
+      @erb = ERB.new File.read(filename)
+      @erb.filename = filename
     end
     
-    def result(&block)
-      instance_eval(&block) if block
-      
-      erbout.flush
-      erbout.rewind
-      erbout.read
+    def build(locals={})
+      erb.result OpenStruct.new(locals).send(:binding)
     end
   end
 end