clean up docs and tests

lib/sprinkle/actors/actors.rb

@@ -6,12 +6,27 @@
 #++
 
 module Sprinkle
-  # An actor is a method of command delivery to a remote machine. It is the
-  # layer between sprinkle and the SSH connection to run commands. This gives
-  # you the flexibility to define custom actors, for whatever purpose you need.
+  # An actor is a method of command delivery to a remote machine. Actors are the
+  # layer setting between Sprinkle and the systems you and wanting to apply
+  # policies to.  
   #
-  # 99% of the time, however, the two built-in actors Sprinkle::Actors::Capistrano
-  # and Sprinkle::Actors::Vlad will be enough.
+  # Sprinkle ships with actors for Capistrano, Vlad, localhost and pure SSH.
+  # 99% of the time these should be sufficient but you can always write your 
+  # own actor otherwise. 
+  #
+  # == Writing an actor
+  #
+  # Actors must provide only 3 methods:
+  # 
+  # * install (installer, roles, options)
+  # * verify (verifier, roles, options)
+  # * transfer (source, destination, roles, options)
+  #
+  # Hopefully these methods are kind of fairly obvious.  They should return true
+  # to indicate success and false to indicate failure.
+  # The actual commands you need to execute can be retrived from 
+  # +installer.install_sequence+ and +verifier.commands+.  
+
   module Actors
   end
 end

lib/sprinkle/actors/local.rb

@@ -22,7 +22,7 @@ def install(installer, roles, opts = {}) #:nodoc:
       end
 
       def verify(verifier, roles, opts = {}) #:nodoc:
-        process(installer.package.name, verifier.commands, roles)
+        process(verifier.package.name, verifier.commands, roles)
       end
 
       def transfer(name, source, destination, roles, opts ={}) #:nodoc:

lib/sprinkle/actors/ssh.rb

@@ -25,13 +25,13 @@ module Actors
     #       gateway "work.sshgateway.com"
     #     end
     #   end
-    class Ssh
+    class SSH
       attr_accessor :options #:nodoc:
 
       class SSHCommandFailure < StandardError #:nodoc:
         attr_accessor :details
       end 
-
+      
       def initialize(options = {}, &block) #:nodoc:
         @options = options.update(:user => 'root')
         @roles = {}
@@ -85,7 +85,9 @@ def teardown #:nodoc:
       end
 
       def verify(verifier, roles, opts = {}) #:nodoc:
-        process(verifier.package.name, verifier.commands, roles, 
+        # issue all the verification steps in a single SSH connection
+        commands=[verifier.commands.join(" && ")]
+        process(verifier.package.name, commands, roles, 
           :suppress_and_return_failures => true)
       end
 

lib/sprinkle/deployment.rb

@@ -52,7 +52,9 @@ def initialize(&block) #:nodoc:
       # the actor. For more information on what configuration options are
       # available, view the corresponding Sprinkle::Actors page.
       def delivery(type, &block) #:doc:
-        @style = ("Sprinkle::Actors::" + type.to_s.titleize).constantize.new &block
+        type=type.to_s.titleize
+        type="SSH" if type=="Ssh"
+        @style = ("Sprinkle::Actors::" + type).constantize.new &block
       end
 
       def method_missing(sym, *args, &block) #:nodoc:

lib/sprinkle/installers/apt.rb

@@ -1,7 +1,5 @@
 module Sprinkle
   module Installers
-    # = Apt Package Installer
-    #
     # The Apt package installer uses the +apt-get+ command to install
     # packages. The apt installer has only one option which can be
     # modified which is the +dependencies_only+ option. When this is
@@ -20,7 +18,9 @@ module Installers
     # Second, only build the magic_beans dependencies:
     #
     #   package :magic_beans_depends do
-    #     apt 'magic_beans_package' { dependencies_only true }
+    #     apt 'magic_beans_package' do
+    #       dependencies_only true 
+    #     end
     #   end
     #
     # As you can see, setting options is as simple as creating a

lib/sprinkle/installers/binary.rb

@@ -1,12 +1,17 @@
 module Sprinkle
   module Installers
-    # = Binary Installer
+    # The Binary installer will download a binary archive and then extract
+    # it in the directory specified by the prefix option.
     # 
-    # binary "http://some.url.com/archive.tar.gz" do
-    #  prefix   "/home/user/local"
-    #  archives "/home/user/sources"
-    # end 
+    # == Example Usage
     #
+    #  binary "http://some.url.com/archive.tar.gz" do
+    #    prefix   "/home/user/local"
+    #    archives "/home/user/sources"
+    #  end 
+    # 
+    # This example will download archive.tar.gz to /home/user/sources and then
+    # extract it into /home/user/local.
     class Binary < Installer
       def initialize(parent, binary_archive, options = {}, &block) #:nodoc:
         @binary_archive = binary_archive
@@ -27,11 +32,11 @@ def install_commands #:nodoc:
         commands << "bash -c \"cd #{@options[:prefix].first} && #{extract_command} '#{@options[:archives].first}/#{archive_name}'\""
       end
 
-      def archive_name
+      def archive_name #:nodoc:
         @archive_name ||= @binary_archive.split("/").last.gsub('%20', ' ')
       end
 
-      def extract_command
+      def extract_command #:nodoc:
         case archive_name
         when /(tar.gz)|(tgz)$/
           'tar xzf'

lib/sprinkle/installers/bsd_port.rb

@@ -1,10 +1,8 @@
 module Sprinkle
   module Installers
-    # = OpenBSD and FreeBSD Port Installer
-    #
-    # The Port installer installs OpenBSD and FreeBSD ports.
+    # The BSD Port installer installs OpenBSD and FreeBSD ports.
     # Before usage, the ports sytem must be installed and
-    # read on the target operating system.
+    # ready on the target operating system.
     # 
     # == Example Usage
     #

lib/sprinkle/installers/deb.rb

@@ -1,7 +1,5 @@
 module Sprinkle
   module Installers
-    # = Deb Package Installer
-    #
     # The Deb installer installs deb packages sourced from a remote URL
     # 
     # == Example Usage

lib/sprinkle/installers/freebsd_pkg.rb

@@ -1,8 +1,6 @@
 module Sprinkle
   module Installers
-    # = FreeBSD Package Installer
-    #
-    # The Pkg package installer installs FreeBSD packages.
+    # The FreeBSDPkg installer installs FreeBSD packages.
     # 
     # == Example Usage
     #
@@ -17,6 +15,7 @@ module Installers
     #   package :magic_beans do
     #     freebsd_pkg %w(magic_beans magic_sauce)
     #   end
+    #
     class FreebsdPkg < Installer
       attr_accessor :packages #:nodoc:
 

lib/sprinkle/installers/gem.rb

@@ -1,8 +1,6 @@
 module Sprinkle
   module Installers
-    # = Ruby Gem Package Installer
-    #
-    # The gem package installer installs ruby gems.
+    # The gem package installer installs Ruby gems.
     #
     # The installer has a single optional configuration: source.
     # By changing source you can specify a given ruby gems

lib/sprinkle/installers/mac_port.rb

@@ -1,8 +1,6 @@
 module Sprinkle
   module Installers
-    # = Mac OS X Port Installer (macports)
-    #
-    # The Port installer installs macports ports.
+    # The MacPort installer installs macports ports.
     # 
     # == Example Usage
     #
@@ -13,12 +11,14 @@ module Installers
     #   end
     #
     # == Notes
+    #
     # Before MacPorts packages can be installed, the PATH
     # environment variable probably has to be changed so
-    # capistrano can find the /opt/local/bin/port executable
+    # Sprinkle can find the /opt/local/bin/port executable
     #
     # You must set PATH in ~/.ssh/environment on the remote
     # system and enable 'PermitUserEnvironment yes' in /etc/sshd_config
+    #
     class MacPort < Installer
       attr_accessor :port #:nodoc:
 

lib/sprinkle/installers/openbsd_pkg.rb

@@ -1,8 +1,6 @@
 module Sprinkle
   module Installers
-    # = OpenBSD Package Installer
-    #
-    # The Pkg package installer installs OpenBSD packages.
+    # The OpenBSD package installer installs OpenBSD packages.
     # 
     # == Example Usage
     #

lib/sprinkle/installers/opensolaris_pkg.rb

@@ -1,8 +1,6 @@
 module Sprinkle
   module Installers
-    # = OpenSolaris Package Installer
-    #
-    # The Pkg package installer installs OpenSolaris packages.
+    # The OpenSolaris package installer installs OpenSolaris packages.
     # 
     # == Example Usage
     #
@@ -21,8 +19,9 @@ module Installers
     # == Note
     # If you are using capistrano as the deployment method
     # you will need to add the following lines to your deploy.rb
-    # set :sudo, 'pfexec'
-    # set :sudo_prompt, ''
+    #
+    #   set :sudo, 'pfexec'
+    #   set :sudo_prompt, ''
     class OpensolarisPkg < Installer
       attr_accessor :packages #:nodoc:
 

lib/sprinkle/installers/pacman.rb

@@ -1,21 +1,21 @@
 module Sprinkle
   module Installers
+    # The pacman installer installs Pacman packages
     class Pacman < Installer
-      attr_accessor :packages
+      attr_accessor :packages #:nodoc:
 
-      def initialize(parent, *packages, &block)
+      def initialize(parent, *packages, &block) #:nodoc:
         super parent, options, &block
 
         packages = [packages] unless packages.is_a?(Array)
         packages.flatten!
 
-
         @packages = packages
       end
 
       protected
 
-      def install_commands
+      def install_commands #:nodoc:
         "pacman -Sy #{@packages.join(' ')} --no-confirm --needed"  
       end
     end

lib/sprinkle/installers/push_text.rb

@@ -2,9 +2,7 @@ module Sprinkle
   module Installers
     # Beware, strange "installer" coming your way.
     #
-    # = Text configuration installer
-    #
-    # This installer pushes simple configuration into a file.
+    # This push text installer pushes simple configuration into a file.
     # 
     # == Example Usage
     #
@@ -22,9 +20,16 @@ module Installers
     #   end
     #
     # A special verify step exists for this very installer
-    # its known as file_contains, it will test that a file indeed
+    # its known as +file_contains+, it will test that a file indeed
     # contains a substring that you send it.
     #
+    #   package :magic_beans do
+    #     push_text 'magic_beans', '/etc/apache2/apache2.conf'
+    #     verify do
+    #       file_contains '/etc/apache2/apache2.conf', 'magic_beans'
+    #     end
+    #   end
+    #
     class PushText < Installer
       attr_accessor :text, :path #:nodoc:
 

lib/sprinkle/installers/rake.rb

@@ -1,7 +1,5 @@
 module Sprinkle
   module Installers
-    # = Rake Installer
-    #
     # This installer runs a rake command.
     # 
     # == Example Usage

lib/sprinkle/installers/rpm.rb

@@ -20,9 +20,9 @@ module Installers
     class Rpm < Installer
       attr_accessor :packages #:nodoc:
 
-      def initialize(parent, packages, &block) #:nodoc:
+      def initialize(parent, *packages, &block) #:nodoc:
         super parent, &block
-        packages = [packages] unless packages.is_a? Array
+        packages = [*packages].flatten
         @packages = packages
       end
 

lib/sprinkle/installers/runner.rb

@@ -1,5 +1,13 @@
 module Sprinkle
 	module Installers
+	  # The runner installer is great for running a single command.
+	  #
+	  # == Example Usage
+    #
+    #   package :magic_beans do
+    #     runner "make world"
+    #   end
+    #
 		class Runner < Installer
 			attr_accessor :cmd #:nodoc:
 

lib/sprinkle/verifiers/file.rb

@@ -18,6 +18,10 @@ def has_file(path)
         @commands << "test -f #{path}"
       end
 
+      def no_file(path)
+        @commands << "test ! -f #{path}"
+      end
+
       def file_contains(path, text)
         @commands << "grep '#{text}' #{path}"
       end

spec/sprinkle/actors/capistrano_spec.rb

@@ -258,7 +258,7 @@ def create_cap(&block)
     end
 
     after do
-      @cap.transfer @name, @source, @dest, @roles, false
+      @cap.transfer @name, @source, @dest, @roles, :recursive => false
     end
   end