linecook 0.6.2 → 1.0.0

data/lib/linecook.rb

@@ -1,6 +1,4 @@
-require 'linecook/helper'
-require 'linecook/script'
-require 'linecook/cookbook'
+require 'linecook/package'
 
 module Linecook
 end

data/lib/linecook/attributes.rb

@@ -1,22 +1,59 @@
-require 'linecook/utils'
-
 module Linecook
+  
+  # Attributes provides a context for specifying default attributes.  For
+  # example:
+  #
+  #   attributes = Attributes.new
+  #   attributes.instance_eval %{
+  #     attrs['a'] = 'A'
+  #     attrs['b']['c'] = 'C'
+  #   }
+  #
+  #   attributes.to_hash
+  #   # => {'a' => 'A', 'b' => {'c' => 'C'}}
+  #
+  # Note that attrs is an auto-filling nested hash, making it easy to set
+  # nested attributes, but it is not indifferent, meaning you do need to
+  # differentiate between symbols and strings.  Normally strings are
+  # preferred.
   class Attributes
-    attr_reader :attrs
-    attr_reader :context
+    # A proc used to create nest_hash hashes
+    NEST_HASH_PROC = Proc.new do |hash, key|
+      hash[key] = Hash.new(&NEST_HASH_PROC)
+    end
     
-    def initialize(context={})
-      @context = context
-      reset(true)
+    class << self
+      # Returns an auto-filling nested hash.
+      def nest_hash
+        Hash.new(&NEST_HASH_PROC)
+      end
+      
+      # Recursively disables automatic nesting of nest_hash hashes.
+      def disable_nest_hash(hash)
+        if hash.default_proc == NEST_HASH_PROC
+          hash.default = nil
+        end
+        
+        hash.each_pair do |key, value|
+          if value.kind_of?(Hash)
+            disable_nest_hash(value)
+          end
+        end
+        
+        hash
+      end
     end
     
-    def current
-      @current ||= Utils.serial_merge(attrs, context)
+    # An auto-filling nested hash
+    attr_reader :attrs
+    
+    def initialize
+      @attrs = Attributes.nest_hash
     end
     
-    def reset(full=true)
-      @attrs = Utils.nest_hash if full
-      @current = nil
+    # Disables automatic nesting and returns attrs.
+    def to_hash
+      Attributes.disable_nest_hash(attrs)
     end
   end
 end

data/lib/linecook/commands.rb

@@ -1,6 +1,11 @@
-require 'linecook/commands/init'
+require 'linecook/commands/build'
+require 'linecook/commands/env'
 require 'linecook/commands/helper'
-require 'linecook/commands/helpers'
+require 'linecook/commands/init'
 require 'linecook/commands/package'
-require 'linecook/commands/env'
-require 'linecook/commands/vbox'
+require 'linecook/commands/snapshot'
+require 'linecook/commands/ssh'
+require 'linecook/commands/start'
+require 'linecook/commands/state'
+require 'linecook/commands/stop'
+require 'linecook/commands/run'

data/lib/linecook/commands/build.rb

@@ -0,0 +1,69 @@
+require 'linecook/commands/helper'
+require 'linecook/commands/package'
+
+module Linecook
+  module Commands
+    
+    # :startdoc::desc build a project
+    #
+    # Builds some or all packages and helpers in a project, as needed.
+    #
+    class Build < Command
+      config :project_dir, '.', :short => :d              # the project directory
+      config :force, false, :short => :f, &c.flag         # force creation
+      config :quiet, false, &c.flag                       # silence output
+      
+      def glob_helpers(project_dir)
+        helpers_dir = File.expand_path('helpers', project_dir)
+        sources = {}
+        helpers = []
+        
+        Dir.glob("#{helpers_dir}/*/**/*").each do |source|
+          next if File.directory?(source)
+          (sources[File.dirname(source)] ||= []) << source
+        end
+        
+        sources.each_pair do |dir, sources|
+          name = dir[(helpers_dir.length + 1)..-1]
+          helpers << [name, sources]
+        end
+        
+        helpers.sort_by {|name, sources| name }
+      end
+      
+      def glob_package_files(package_names)
+        if package_names.empty?
+          pattern = File.expand_path('packages/*.yml', project_dir)
+          Dir.glob(pattern).select {|path| File.file?(path) }
+        else
+          package_names.collect do |package_name|
+            File.expand_path("packages/#{package_name}.yml", project_dir)
+          end
+        end
+      end
+      
+      def process(*package_names)
+        helper = Helper.new(
+          :project_dir => project_dir, 
+          :force => force,
+          :quiet => true
+        )
+        
+        helpers = glob_helpers(project_dir)
+        helpers.each do |(name, sources)|
+          helper.process(name, *sources)
+        end
+        
+        package = Package.new(
+          :project_dir => project_dir,
+          :force => force,
+          :quiet => quiet
+        )
+        
+        glob_package_files(package_names).collect do |package_file|
+          package.process(package_file)
+        end
+      end
+    end
+  end
+end

data/lib/linecook/commands/command.rb

@@ -24,16 +24,26 @@ module Linecook
       lazy_attr :args, :process
       lazy_register :process, Lazydoc::Arguments
       
-      def initialize(config)
+      attr_accessor :quiet
+      
+      def initialize(config={})
+        @quiet = true
         initialize_config(config)
       end
       
       def log(action, msg)
-        puts("      %s  %s" % [action, msg])
+        $stderr.puts("      %s  %s" % [action, msg])
       end
       
       def sh(cmd)
-        system cmd
+        puts "% #{cmd}" unless quiet
+        system(cmd)
+      end
+      
+      def sh!(cmd)
+        unless sh(cmd)
+          raise CommandError.new("", $?.exitstatus)
+        end
       end
       
       def call(argv)

data/lib/linecook/commands/command_error.rb

@@ -1,6 +1,12 @@
 module Linecook
   module Commands
     class CommandError < RuntimeError
+      attr_reader :exitstatus
+      
+      def initialize(msg, exitstatus=1)
+        @exitstatus = exitstatus
+        super(msg)
+      end
     end
   end
 end

data/lib/linecook/commands/env.rb

@@ -1,22 +1,88 @@
 require 'linecook/commands/command'
 require 'linecook/cookbook'
+require 'yaml'
 
 module Linecook
   module Commands
     
-    # ::desc prints the cookbook env
+    # :startdoc::desc prints a package env
     #
-    # Print the cookbook env.
+    # Prints the env for the current project directory.  Specifically the
+    # cookbook file is loaded and used to determine all resources that are
+    # current available.  The full build env for a package can be viewed by
+    # specifying the package file as an option.
     #
+    # A specific env value can be printed by specifying the key path to it.
     class Env < Command
-      config :cookbook_dir, '.', :short => :d       # the cookbook directory
-      config :path, nil                             # package path
+      config :project_dir, '.', :short => :d        # the project directory
+      config :package_file, nil, :short => :p       # the package file
       
-      def process(*keys)
-        current = Linecook::Cookbook.init(cookbook_dir).env(path)
-        keys.each {|key| current = current[key] if current }
+      # :stopdoc:
+      # Evaluate to replace the to_yaml function on Hash so that it will
+      # serialize keys in order.  Evaluate the OFF code to turn this hack off
+      # (and thereby ease up on the code pollution)
+      #
+      # Modified from: http://snippets.dzone.com/posts/show/5811 Original
+      # func: /usr/lib/ruby/1.8/yaml/rubytypes.rb
+      ORIGINAL_TO_YAML = 'linecook_original_to_yaml'
+      SORTED_HASH_ON_LINE = __LINE__ + 1
+      SORTED_HASH_ON = %{
+      class Hash
+        unless instance_methods.include?('#{ORIGINAL_TO_YAML}')
+          alias #{ORIGINAL_TO_YAML} to_yaml
+          undef_method :to_yaml
+          def to_yaml( opts = {} )
+            YAML::quick_emit( object_id, opts ) do |out|
+              out.map( taguri, to_yaml_style ) do |map|
+                keys.sort_by do |k|
+                  k.to_s
+                end.each do |k|
+                  map.add( k, fetch(k) )
+                end
+              end
+            end
+          end
+        end
+      end}
+      
+      SORTED_HASH_OFF_LINE = __LINE__ + 1
+      SORTED_HASH_OFF = %{
+      class Hash
+        if instance_methods.include?('#{ORIGINAL_TO_YAML}')
+          undef_method :to_yaml
+          alias to_yaml #{ORIGINAL_TO_YAML}
+          undef_method :#{ORIGINAL_TO_YAML}
+        end
+      end}
+      # :startdoc:
+      
+      def select(current, *keys)
+        keys.each do |key|
+          unless current.kind_of?(Hash)
+            return nil
+          end
+          
+          current = current[key]
+        end
         
-        YAML.dump(current, $stdout)
+        current
+      end
+      
+      # Serializes the env to the target as YAML.  Ensures hashes are
+      # serialized with their keys sorted by their to_s value.
+      def serialize(env, target="")
+        begin
+          eval SORTED_HASH_ON, TOPLEVEL_BINDING, __FILE__, SORTED_HASH_ON_LINE
+          YAML.dump(env, target)
+        ensure
+          eval SORTED_HASH_OFF, TOPLEVEL_BINDING, __FILE__, SORTED_HASH_OFF_LINE
+        end
+      end
+      
+      def process(*keys)
+        package  = Linecook::Package.init(package_file, project_dir)
+        env = select(package.env, *keys)
+        serialize(env, $stdout)
       end
     end
   end

data/lib/linecook/commands/helper.rb

@@ -1,51 +1,298 @@
 require 'linecook/commands/command'
-require 'linecook/helper'
 require 'linecook/utils'
+require 'fileutils'
+require 'erb'
 
 module Linecook
   module Commands
     
-    # ::desc generates a helper
+    # :startdoc::desc generates a helper module
+    #
+    # Generates the specified helper module from a set of source files.  Each
+    # source file becomes a method in the module, named after the source file
+    # itself.
+    #
+    # The helper module will be generated under the lib directory in a file
+    # corresponding to const_name (which can also be a constant path).  By
+    # default, all files under the corresponding helpers directory will be
+    # used as sources.  For example these are equivalent and produce the
+    # Const::Name module in 'lib/const/name.rb':
+    #
+    #   % linecook helper Const::Name
+    #   % linecook helper const/name
+    #   % linecook helper const/name helpers/const/name/*
+    #
+    # == Source Files
+    #
+    # The contents of the source file are translated into code according to
+    # the source file extname.
+    #
+    #   extname      translation
+    #   .rb          file defines method body
+    #   .erb         file defines an ERB template (compiled to ruby code)
+    #
+    # Source files can specify documenation and a method signature using a
+    # standard header separated from the body by a double-dash.  For example
+    # this:
+    #
+    #   [echo.erb]
+    #   Echo arguments out to the target.
+    #   (*args)
+    #   --
+    #   echo <%= args.join(' ') %>
+    #
+    # Is translated into something like:
+    #
+    #   # Echo arguments out to the target.
+    #   def echo(*args)
+    #     eval ERB.new("echo <%= args.join(' ') %>").src
+    #   end
+    #
+    # A second method is also generated to return the result without writing
+    # it to the target.  The latter method is prefixed by and underscore
+    # like:
+    #
+    #   # Return the output of echo, without writing to the target
+    #   def _echo(*args)
+    #     ...
+    #   end
+    #
+    # Check and bang methods can be specified by adding -check and -bang to
+    # the end of the file name.  These extensions are stripped off like:
+    #
+    #   [file-check.erb]   # => def file? ...
+    #   [make-bang.rb]     # => def make! ...
+    #
+    # Otherwise the basename of the source file must be a word; non-word
+    # basenames raise an error.
+    #
+    # == Section Files
+    #
+    # Special section files can be used to define non-standard code in the
+    # following places:
+    #
+    #   [:header]
+    #   module Const
+    #     [:doc]
+    #     module Name
+    #       [:head]
+    #       ...
+    #       [:foot]
+    #     end
+    #   end
+    #   [:footer]
+    #
+    # Section files are defined by prepending '-' to the file basename (like
+    # path/to/-header.rb) and are not processed like other source files;
+    # instead the contents are directly transcribed into the target file.
     class Helper < Command
-      config :cookbook_dir, '.', :short => :d       # the cookbook directory
-      config :namespace, 'linebook', :short => :n   # the helper namespace
+      config :project_dir, '.', :short => :d        # the project directory
       config :force, false, :short => :f, &c.flag   # force creation
+      config :quiet, false, &c.flag
       
       include Utils
       
-      def process(name, *sources)
-        name = underscore(name)
-        
-        const_path = namespace ? File.join(namespace, name) : name
+      def process(const_name, *sources)
+        const_path = underscore(const_name)
         const_name = camelize(const_path)
         
-        sources = default_sources(name) if sources.empty?
-        target  = File.expand_path(File.join('lib', "#{const_path}.rb"), cookbook_dir)
+        unless const_name?(const_name)
+          raise "invalid constant name: #{const_name.inspect}"
+        end
+        
+        sources = default_sources(const_path) if sources.empty?
+        target  = File.expand_path(File.join('lib', "#{const_path}.rb"), project_dir)
         
         if sources.empty?
-          raise CommandError, "no sources specified (and none could be found)"
+          raise CommandError, "no sources specified (and none found under 'helpers/#{const_path}')"
         end
         
-        if File.exists?(target) && !force
-          raise CommandError, "already exists: #{target}"
+        if force || !FileUtils.uptodate?(target, sources)
+          content = build(const_name, sources)
+          
+          target_dir = File.dirname(target)
+          unless File.exists?(target_dir)
+            FileUtils.mkdir_p(target_dir) 
+          end
+          
+          File.open(target, 'w') {|io| io << content }
+          $stdout.puts target unless quiet
         end
         
-        log :create, const_name
+        target
+      end
+      
+      # Returns the default source files for a given constant path, which are
+      # all files under the 'project_dir/helpers/const_path' folder.
+      def default_sources(const_path)
+        pattern = File.join(project_dir, 'helpers', const_path, '*')
+        sources = Dir.glob(pattern)
+        sources.select {|path| File.file?(path) }
+      end
+      
+      # returns true if const_name is a valid constant name.
+      def const_name?(const_name) # :nodoc:
+        const_name =~ /\A(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      end
+      
+      # helper to partition an array of source files into section and
+      # defintion files
+      def partition(sources) # :nodoc:
+        sources.partition do |path|
+          basename = File.basename(path)
+          extname  = File.extname(path)
+          basename[0] == ?- && basename.chomp(extname) != '-'
+        end
+      end
+      
+      # helper to load each section path into a sections hash; removes the
+      # leading - from the path basename to determine the section key.
+      def load_sections(paths) # :nodoc:
+        sections = {}
         
-        helper = Linecook::Helper.new(const_name, sources)
-        content = helper.build
-
-        target_dir = File.dirname(target)
-        unless File.exists?(target_dir)
-          FileUtils.mkdir_p(target_dir) 
+        paths.each do |path|
+          basename = File.basename(path)
+          extname  = File.extname(path)
+          key = basename[1, basename.length - extname.length - 1]
+          sections[key] = File.read(path)
         end
-
-        File.open(target, 'w') {|io| io << content }
+        
+        sections
       end
       
-      def default_sources(name)
-        Dir.glob File.join(cookbook_dir, 'helpers', name, '**/*')
+      # helper to load and parse a definition file
+      def load_definition(path) # :nodoc:
+        extname = File.extname(path)
+        name    = File.basename(path).chomp(extname)
+        desc, signature, body = parse_definition(File.read(path))
+        
+        [desc, parse_method_name(name), signature, method_body(body, extname)]
+      rescue CommandError
+        err = CommandError.new("#{$!.message} (#{path.inspect})")
+        err.set_backtrace($!.backtrace)
+        raise err
       end
+      
+      # helper to reformat special basenames (in particular -check and -bang)
+      # to their corresponding method_name
+      def parse_definition(str) # :nodoc:
+        head, body = str.split(/^--.*\n/, 2)
+        head, body = '', head if body.nil?
+        
+        found_signature = false
+        signature, desc = head.split("\n").partition do |line|
+          found_signature = true if line =~ /^\s*\(.*?\)/
+          found_signature
+        end
+        
+        [desc.join("\n"), found_signature ? signature.join("\n") : '()', body.to_s]
+      end
+      
+      # helper to reformat special basenames (in particular -check and -bang)
+      # to their corresponding method_name
+      def parse_method_name(basename) # :nodoc:
+        case basename
+        when /-check\z/ then basename.sub(/-check$/, '?')
+        when /-bang\z/  then basename.sub(/-bang$/, '!')
+        when /-eq\z/    then basename.sub(/-eq$/, '=')
+        when /\A\w+\z/  then basename
+        else raise CommandError.new("invalid method name: #{basename.inspect}")
+        end
+      end
+      
+      # helper to reformat a definition body according to a given extname.  rb
+      # content is rstripped to improve formatting.  erb content is compiled
+      # and the source is placed as a comment before it (to improve
+      # debugability).
+      def method_body(body, extname) # :nodoc:
+        case extname
+        when '.erb'
+          source = "#  #{body.gsub(/\n/, "\n#  ")}"
+          compiler = ERB::Compiler.new('<>')
+          compiler.put_cmd = "write"
+          compiler.insert_cmd = "write"
+          code = compiler.compile(body)
+          
+          "#{source}\n#{code}".gsub(/^(\s*)/) do |m| 
+            indent = 2 + $1.length - ($1.length % 2)
+            ' ' * indent
+          end
+          
+        when '.rb'
+          body.rstrip
+          
+        else
+          raise CommandError.new("invalid definition format: #{extname.inspect}")
+        end
+      end
+      
+      # helper to nest a module body within a const_name.  documentation
+      # can be provided for the innermost constant.
+      def module_nest(const_name, body, inner_doc=nil) # :nodoc:
+        body = body.strip.split("\n")
+        
+        const_name.split(/::/).reverse_each do |name|
+          body.collect! {|line| "  #{line}" }
+          
+          body.unshift "module #{name}"
+          body.push    "end"
+          
+          # prepend the inner doc to the innermost const
+          if inner_doc
+            body = inner_doc.strip.split("\n") + body
+            inner_doc = nil
+          end
+        end
+        
+        body.join("\n")
+      end
+      
+      # Returns the code for a const_name module as defined by the source
+      # files.
+      def build(const_name, sources)
+        section_paths, definition_paths = partition(sources)
+        sections    = load_sections(section_paths)
+        definitions = definition_paths.collect {|path| load_definition(path) }
+        
+        body = eval DEFINITION_TEMPLATE, binding, __FILE__, DEFINITION_TEMPLATE_LINE
+        code = eval MODULE_TEMPLATE, binding, __FILE__, MODULE_TEMPLATE_LINE
+        
+        code
+      end
+      
+      # :stopdoc:
+      MODULE_TEMPLATE_LINE = __LINE__ + 2
+      MODULE_TEMPLATE = ERB.new(<<-DOC, nil, '<>').src
+# Generated by Linecook
+<%= sections['header'] %>
+
+<%= module_nest(const_name, body, sections['doc']) %>
+
+<%= sections['footer'] %>
+DOC
+
+      DEFINITION_TEMPLATE_LINE = __LINE__ + 2
+      DEFINITION_TEMPLATE = ERB.new(<<-DOC, nil, '<>').src
+<%= sections['head'] %>
+<% definitions.each do |desc, method_name, signature, body| %>
+<% desc.split("\n").each do |line| %>
+# <%= line %><% end %>
+def <%= method_name %><%= signature %>
+<%= body %>
+
+  chain_proxy
+end
+
+def _<%= method_name %>(*args, &block) # :nodoc:
+  str = capture_str { <%= method_name %>(*args, &block) }
+  str.strip!
+  str
+end
+<% end %>
+
+<%= sections['foot'] %>
+DOC
+      # :startdoc:
     end
   end
 end