sprinkle 0.7.1.1 → 0.7.2

data/lib/sprinkle/installers/transfer.rb

@@ -79,7 +79,6 @@ module Sprinkle
 
       def render_template(template, context, prefix)
         require 'tempfile'
-        require 'erubis'
 
         output = @package.template(template, context)
 

data/lib/sprinkle/installers/user.rb

@@ -1,6 +1,6 @@
 module Sprinkle
   module Installers
-    # The user installer helps add users.  You may pass flags as an option.
+    # The user installer add users.  You may pass :flags as an option.
     # 
     # == Example Usage
     #
@@ -8,7 +8,7 @@ module Sprinkle
     #     add_user 'admin', :flags => "--disabled-password"
     #
     #     verify do
-    #       has_user 'admin', :in_group = "root"
+    #       has_user 'admin', :in_group => "root"
     #     end
     #   end
     

data/lib/sprinkle/installers/yum.rb

@@ -7,14 +7,11 @@ module Sprinkle
     # Installing the magic_beans RPM via Yum. Its all the craze these days.
     #
     #   package :magic_beans do
-    #     yum 'magic_beans'
-    #     verify { has_yum 'magic_beans' }
-    #   end
-    #
-    # You may also specify multiple rpms as arguments or an array:
-    #
-    #   package :magic_beans do
-    #     yum "magic_beans", "magic_sauce"
+    #     yum 'magic_beans', 'magic_corn'
+    #     verify do
+    #       has_yum 'magic_beans' 
+    #       has_yum 'magic_corn' 
+    #     end
     #   end
     #
     # To install a specific version just add that version after the name
@@ -24,6 +21,10 @@ module Sprinkle
     #   end
     class Yum < PackageInstaller
 
+      ##
+      # installs the RPM packages passed
+      # :method: yum
+      # :call-seq: yum(*packages)
       auto_api
 
       verify_api do

data/lib/sprinkle/installers/zypper.rb

@@ -19,7 +19,11 @@ module Sprinkle
     #     zypper "magic_beans", "magic_sauce"
     #   end
     class Zypper < PackageInstaller
-      
+    
+      ##
+      # installs the ZYpp packages passed
+      # :method: zypper
+      # :call-seq: zypper(*packages)
       auto_api
 
       protected

data/lib/sprinkle/package.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 module Sprinkle
   # = Packages
   #
@@ -36,6 +37,20 @@ module Sprinkle
   # provision the server with Ruby to make sure the requirements are met.
   # In turn, if ruby has requirements, it installs those first, and so on.
   #
+  # == Defaults
+  #
+  # Packages can be given defaults.
+  # These default options are available as a hash in opts.
+  #
+  #   package :deploy_user do
+  #     defaults :username => 'deploy'
+  #     add_user opts[:username]
+  #   end
+  #
+  # Options given when requiring a package are merged over the defaults
+  #
+  #   requires :deploy_user, :username => 'deployer'
+  #
   # == Verifications
   #
   # Most of the time its important to know whether the software you're 
@@ -142,7 +157,7 @@ module Sprinkle
       
       def instance(*args)
         p=Package.new(name, @metadata) {}
-        p.opts = args.extract_options!
+        p.opts = defaults.merge(args.extract_options!)
         p.args = args
         p.instance_variable_set("@block", @block)
         p.instance_eval &@block
@@ -156,13 +171,17 @@ module Sprinkle
       def use_sudo(flag=true)
         @use_sudo = flag
       end
-            
+
+      def defaults(s=nil)
+        s ? @defaults = s : @defaults ||= Hash.new
+      end
+
       def args
-        @args || []
+        @args ||= []
       end
       
       def opts
-        @opts || {}
+        @opts ||= defaults.clone
       end
       
       class ContextError < StandardError #:nodoc:
@@ -172,9 +191,9 @@ module Sprinkle
         raise ContextError, "Cannot call get inside a package, must be inside an Installer block"
       end
       
-      # meta installer
-      # TODO - fix to be atomic
+      # TODO - remove
       def push_file(file, options ={}, &block)
+        ActiveSupport::Deprecation.warn("push_file is depreciated and will be removed in v0.9.  Use the new `file` installer instead.")
         raise "need content" unless options[:content]
         runner "#{"sudo " if sudo?}rm -f #{file}"
         push_text options[:content], file, options, &block
@@ -182,11 +201,15 @@ module Sprinkle
                   
       def verify(description = '', &block)
         @verifications << Sprinkle::Verify.new(self, description, &block)
-      end  
+      end
       
       def process(deployment, roles)
         logger.info "  * #{name}"
         return if meta_package?
+        opts.each_with_index do |(k, v), index| 
+          branch = (index == opts.size - 1) ? "└" : "├"
+          logger.debug "    #{branch}─ #{k}: #{v}" 
+        end
         
         # Run a pre-test to see if the software is already installed. If so,
         # we can skip it, unless we have the force option turned on!
@@ -224,7 +247,7 @@ module Sprinkle
           v.process(roles)
         end
       end
-                  
+
       def requires(*packages)
         add_dependencies packages, :dependencies
       end

data/lib/sprinkle/package/chooser.rb

@@ -1,5 +1,5 @@
 module Sprinkle::Package
-  class Chooser
+  class Chooser #:nodoc:
     def self.select_package(name, packages)
       if packages.size <= 1
         package = packages.first

data/lib/sprinkle/package/package_repository.rb

@@ -1,5 +1,5 @@
 module Sprinkle::Package
-  class PackageRepository
+  class PackageRepository #:nodoc:
     
     # sets up an empty repository
     def initialize

data/lib/sprinkle/package/rendering.rb

@@ -4,24 +4,27 @@ require 'digest/md5'
 module Sprinkle::Package
   module Rendering
     extend ActiveSupport::Concern
-    
+
     included do
       self.send :include, Helpers
     end
-    
-    def template(src, bound=binding)
+
+    def template(src, context=binding)
       eruby = Erubis::Eruby.new(src)
-      output = eruby.result(bound)
+      output = eruby.result(context)
     rescue Object => e
-      raise Sprinkle::Errors::TemplateError.new(e, src, bound)
+      raise Sprinkle::Errors::TemplateError.new(e, src, context)
     end
     
-    def render(file)
-      contents=File.read(expand_filename(file))
-      template(contents)
+    def render(filename, context=binding)
+      contents=File.read(expand_filename(filename))
+      template(contents, context)
     end
     
+    # Helper methods can be called from inside your package and 
+    # verification code
     module Helpers
+      # return the md5 of a string (as a hex string)
       def md5(s)
         Digest::MD5.hexdigest(s)
       end
@@ -29,13 +32,13 @@ module Sprinkle::Package
     
     private 
     
-    def expand_filename(n)
+    def expand_filename(n) #:nodoc:
       return n.to_s if n.to_s.starts_with? "/"
       ["./templates/#{n}","./templates/#{n}.erb"].each do |f|
         return f if File.exist?(f)
       end
       raise "template file not found"
     end
-    
+
   end
 end

data/lib/sprinkle/policy.rb

@@ -1,20 +1,31 @@
 require 'highline/import'
 
 module Sprinkle
+  class NoMatchingServersError < StandardError #:nodoc:
+    def initialize(name, roles)
+      @name = name
+      @roles = roles
+    end
+    
+    def to_s
+      "Policy #{@name} is to be installed on #{@roles.inspect} but no server has such a role."
+    end
+  end
+
   # = Policies
   #
-  # A policy defines a set of packages which are required for a certain
+  # Policies define a set of packages which are required for a certain
   # role (app, database, etc.). All policies defined will be run and all
   # packages required by the policy will be installed. So whereas defining
   # a Sprinkle::Package merely defines it, defining a Sprinkle::Policy 
   # actually causes those packages to install. 
   #
-  # == A Basic Example
+  # == Example
   #
   #   policy :blog, :roles => :app do
-  #     require :webserver
-  #     require :database
-  #     require :rails
+  #     requires :webserver
+  #     requires :database
+  #     requires :rails
   #   end
   #
   # This says that for the blog on the app role, it requires certain 
@@ -38,91 +49,77 @@ module Sprinkle
   # no software will be installed twice, so you may require a webserver on
   # multiple packages within the same role without having to wait for
   # that package to install repeatedly.
-  module Policy
-    POLICIES = [] #:nodoc:
-
-    # Defines a single policy. Currently the only option, which is also
-    # required, is :roles, which defines which servers a policy is
-    # used on.
-    def policy(name, options = {}, &block)
-      p = Policy.new(name, options, &block)
-      POLICIES << p
-      p
+  class Policy
+    attr_reader :name 
+    # roles for which a policy should be installed [required]
+    attr_reader :roles 
+
+    # creates a new policy, 
+    # although policies are typically not created directly but
+    # rather via the Core#policy helper.
+    def initialize(name, metadata = {}, &block)
+      raise 'No name provided' unless name
+      raise 'No roles provided' unless metadata[:roles]
+
+      @name = name
+      @roles = metadata[:roles]
+      @packages = []
+      self.instance_eval(&block)
     end
-    
-    class NoMatchingServersError < StandardError #:nodoc:
-      def initialize(name, roles)
-        @name = name
-        @roles = roles
-      end
-      
-      def to_s
-        "Policy #{@name} is to be installed on #{@roles.inspect} but no server has such a role."
-      end
+
+    # tell a policy which packages are required
+    def requires(package, opts={})
+      @packages << [package, opts]
     end
     
-    class Policy #:nodoc:
-      attr_reader :name, :roles
+    def packages #:nodoc:
+       @packages.map {|x| x.first }
+     end
 
-      def initialize(name, metadata = {}, &block)
-        raise 'No name provided' unless name
-        raise 'No roles provided' unless metadata[:roles]
+    def to_s #:nodoc:
+       name; end
 
-        @name = name
-        @roles = metadata[:roles]
-        @packages = []
-        self.instance_eval(&block)
-      end
-
-      def requires(package, opts={})
-        @packages << [package, opts]
-      end
+    def process(deployment) #:nodoc:
+      raise NoMatchingServersError.new(@name, @roles) unless deployment.style.servers_for_role?(@roles)
       
-      def packages; @packages.map {|x| x.first }; end
+      all = []
+      
+      logger.info "[#{name}]"
 
-      def to_s; name; end
+      cloud_info "--> Cloud hierarchy for policy #{@name}"
 
-      def process(deployment)
-        raise NoMatchingServersError.new(@name, @roles) unless deployment.style.servers_for_role?(@roles)
-        
-        all = []
-        
-        logger.info "[#{name}]"
+      @packages.each do |p, args|
+        cloud_info "  * requires package #{p}"
 
-        cloud_info "--> Cloud hierarchy for policy #{@name}"
+        package = Sprinkle::Package::PACKAGES.find_all(p, args)
+        raise "Package definition not found for key: #{p}" unless package
+        package = Sprinkle::Package::Chooser.select_package(p, package) if package.is_a? Array # handle virtual package selection
+        # get an instance of the package and pass our config options
+        package = package.instance(*args)
 
-        @packages.each do |p, args|
-          cloud_info "  * requires package #{p}"
+        tree = package.tree do |parent, child, depth|
+          indent = "\t" * depth; cloud_info "#{indent}Package #{parent.name} requires #{child.name}"
+        end
 
-          package = Sprinkle::Package::PACKAGES.find_all(p, args)
-          raise "Package definition not found for key: #{p}" unless package
-          package = Sprinkle::Package::Chooser.select_package(p, package) if package.is_a? Array # handle virtual package selection
-          # get an instance of the package and pass our config options
-          package = package.instance(*args)
+        all << tree
+      end
 
-          tree = package.tree do |parent, child, depth|
-            indent = "\t" * depth; cloud_info "#{indent}Package #{parent.name} requires #{child.name}"
-          end
+      normalize(all).each do |package|
+        package.process(deployment, @roles)
+      end
+    end
 
-          all << tree
-        end
+    private
 
-        normalize(all) do |package|
-          package.process(deployment, @roles)
-        end
+      def normalize(all, &block)
+        all = all.flatten.uniq {|x| [x.name, x.version] }
+        cloud_info "--> Normalized installation order for all packages: #{all.collect(&:name).join(', ')}\n"
+        all
       end
 
-      private
-
-        def cloud_info(message)
-          logger.info(message) if Sprinkle::OPTIONS[:cloud] or logger.debug?
-        end
+      def cloud_info(message)
+        logger.info(message) if Sprinkle::OPTIONS[:cloud] or logger.debug?
+      end
 
-        def normalize(all, &block)
-          all = all.flatten.uniq {|x| [x.name, x.version] }
-          cloud_info "--> Normalized installation order for all packages: #{all.collect(&:name).join(', ')}\n"
-          all.each &block
-        end
-    end
   end
 end

data/lib/sprinkle/script.rb

@@ -1,7 +1,7 @@
 module Sprinkle
-  # = Programmatically Run Sprinkle
+  # = Scripting
   #
-  # Sprinkle::Script gives you a way to programatically run a given
+  # Script gives you a way to programatically run a given
   # sprinkle script. 
   class Script
     include Sprinkle::Deployment

data/lib/sprinkle/utility/log_recorder.rb

@@ -1,5 +1,5 @@
 module Sprinkle
-  module Utility
+  module Utility #:nodoc:
     class LogRecorder #:nodoc:
       
       attr_accessor :err, :out, :command, :code

data/lib/sprinkle/verifiers/file.rb

@@ -12,11 +12,27 @@ module Sprinkle
     #
     module File
       Sprinkle::Verify.register(Sprinkle::Verifiers::File)
-      
+
+      # tests that the file <tt>path</tt> exists
       def has_file(path)
         test "-f #{path}"
       end
       
+      # Tests that the directory <tt>dir</tt> exists.
+      def has_directory(dir)
+        test "-d #{dir}"
+      end
+      
+      # Checks that <tt>symlink</tt> is a symbolic link. If <tt>file</tt> is 
+      # given, it checks that <tt>symlink</tt> points to <tt>file</tt>
+      def has_symlink(symlink, file = nil)
+        if file.nil?
+          test "-L #{symlink}"
+        else
+          test "'#{file}' = `readlink #{symlink}`"
+        end
+      end
+      
       def no_file(path)
         test "! -f #{path}"
       end