automateit 0.70923

data/lib/automateit/edit_manager.rb

@@ -0,0 +1,292 @@
+# == EditManager
+#
+# The EditManager provides a way of editing files and strings
+# programmatically.
+#
+# See documentation for EditManager::EditSession.
+class AutomateIt::EditManager < AutomateIt::Plugin::Manager
+  alias_methods :edit
+
+  # Creates an editing session. See documentation for EditManager::EditSession.
+  def edit(*opts, &block) dispatch(*opts, &block) end
+end
+
+# == EditManager::BaseDriver
+#
+# Base class for all EditManager drivers.
+class AutomateIt::EditManager::BaseDriver < AutomateIt::Plugin::Driver
+end
+
+# == EditManager::Simple
+#
+# Provides a way to edit files and strings.
+#
+# See documentation for EditSession.
+class AutomateIt::EditManager::Simple < AutomateIt::EditManager::BaseDriver
+  depends_on :nothing
+
+  def suitability(method, *args) # :nodoc:
+    1
+  end
+
+  # Creates an editing session. See documentation for EditSession#edit.
+  def edit(*opts, &block)
+    AutomateIt::EditManager::EditSession.new(:interpreter => @interpreter).edit(*opts, &block)
+  end
+end # class Base
+
+# == EditSession
+#
+# EditSession provides a way to edit files and strings.
+#
+# For example, here's how to edit a string from the Interpreter:
+#
+#   edit(:text => "# hello") do
+#     uncomment "llo"
+#     append "world"
+#   end
+#   # => "hello\nworld"
+#
+# The above example edits a text string containing "# hello". The editing
+# session uncomments the line containing "llo" and then appends a line with the
+# word "world". The edited result is returned, containing two lines: "hello"
+# and "world".
+#
+# The edit session only makes changes if they're needed. In the above example,
+# once the "hello" line is uncommented, the "uncomment" command won't do
+# anything. Similarly, once the word "world" has been appended, it won't be
+# appended again. So if you re-edit the resulting string, it won't be changed
+# because it's already in the desired state.
+#
+# This approach simplifies editing because you only need to specify the
+# commands that are needed to change the file, and the session will figure out
+# which ones to run.
+class AutomateIt::EditManager::EditSession < AutomateIt::Common
+  # Create an EditSession.
+  #
+  # Options:
+  # * :interpreter -- AutomateIt Interpreter, required. Will be automatically
+  #   set if you use AutomateIt::Interpreter#edit.
+  def initialize(*args)
+    super(*args)
+    interpreter.add_method_missing_to(self)
+  end
+
+  # Edit a file or string.
+  #
+  # Requires a filename argument or options hash -- e.g.,.
+  # <tt>edit("foo")</tt> and <tt>edit(:file => "foo")</tt> will both edit a
+  # file called +foo+.
+  #
+  # Options:
+  # * :file -- File to edit.
+  # * :text -- String to edit.
+  # * :params -- Hash to make available to editor session.
+  # * :create -- Create the file if it doesn't exist? Defaults to false.
+  # * :mode, :user, :group -- Set permissions on generated file, see ShellManager#chperm
+  #
+  # Edit a string:
+  #
+  #   edit(:text => "foo") do
+  #     replace "o", "@"
+  #   end
+  #   # => "f@@"
+  #
+  # Edit a file and pass parameters to the editing session:
+  #
+  #   edit(:file => "myfile", :params => {:greet => "world"} do
+  #     prepend "MyHeader"
+  #     append "Hello "+params[:greet]
+  #   end
+  #
+  # Edit a file, create it and set permissions if necessary:
+  #
+  #   edit("/tmp/foo", :create => true, :mode => 0600, :user => :root) do
+  #     prepend "Hello world!"
+  #   end
+  def edit(*a, &block)
+    args, opts = args_and_opts(*a)
+    if args.first
+      @filename = args.first
+    else
+      raise ArgumentError.new("no file or text specified for editing") unless opts[:file] or opts[:text]
+      @filename = opts.delete(:file)
+      @contents = opts.delete(:text)
+    end
+    @params = opts.delete(:params) || {}
+    @comment_prefix = "# "
+    @comment_suffix = ""
+    begin
+      @contents ||= _read || ""
+    rescue Errno::ENOENT => e
+      if opts[:create]
+        @contents = ""
+      else
+        raise e
+      end
+    end
+    @original_contents = @contents.clone
+
+    raise ArgumentError.new("no block given") unless block
+    instance_eval(&block)
+    if @filename
+      _write if different?
+
+      chperm_opts = {}
+      for key in [:owner, :user, :group, :mode]
+        chperm_opts[key] = opts[key] if opts[key]
+      end
+      chperm(@filename, chperm_opts) unless chperm_opts.empty?
+
+      return different?
+    else
+      return contents
+    end
+  end
+
+  # File that was read for editing.
+  attr_accessor :filename
+
+  # Current contents of the editing buffer.
+  attr_accessor :contents
+
+  # Original contents of the editing buffer before any changes were made.
+  attr_accessor :original_contents
+
+  # Hash of parameters to make available to the editing session.
+  attr_accessor :params
+
+  # Comment prefix, e.g., "/*"
+  attr_accessor :comment_prefix
+
+  # Comment suffix, e.g., "*/"
+  attr_accessor :comment_suffix
+
+  # Prepend +line+ to the top of the buffer, but only if it's not in this
+  # file already.
+  #
+  # Options:
+  # * :unless -- Look for this String or Regexp instead and don't prepend
+  #   if it matches.
+  #
+  # Example:
+  #   # Buffer's contents are 'add    this line'
+  #
+  #   # This will prepend a line because they're not identical.
+  #   prepend("add this line")
+  #
+  #   # Won't prepend line because Regexp matches exisint line in buffer.
+  #   prepend("add this line", :unless => /add\s*this\*line/)
+  def prepend(line, opts={})
+    query = Regexp.new(opts[:unless] || line)
+    query = Regexp.escape(query) if query.is_a?(String)
+    return if contains?(query)
+    @contents = "%s\n%s" % [line, @contents]
+  end
+
+  # Append +line+ to the bottom of the buffer, but only if it's not in
+  # this file already.
+  #
+  # Options:
+  # * :unless -- Look for this String or Regexp instead and don't append
+  #   if it matches.
+  #
+  # See example for #prepend.
+  def append(line, opts={})
+    query = opts[:unless] || line
+    if query.is_a?(String)
+      query = Regexp.new(Regexp.escape(query))
+    end
+    return if contains?(query)
+    @contents = "%s\n%s\n" % [@contents.chomp, line]
+  end
+
+  # Does the buffer contain anything that matches the String or Regexp +query+?
+  def contains?(query)
+    if query.is_a?(String)
+      query = Regexp.new(Regexp.escape(query))
+    end
+    ! @contents.match(query).nil?
+  end
+
+  # Delete lines matching the String or Regexp +query+
+  def delete(query, opts={})
+    query = Regexp.escape(query) if query.is_a?(String)
+    query = Regexp.new(query+"\n?")
+    @contents.gsub!(query, "")
+  end
+
+  # Specify the comment style's +prefix+ and +suffix+.
+  #
+  # Example:
+  #   # C style comments
+  #   comment_style "/*", "*/"
+  def comment_style(prefix, suffix="")
+    @comment_prefix = prefix
+    @comment_suffix = suffix
+  end
+
+  # Comment out lines matching the String or Regexp +query+.
+  def comment(query, opts={})
+    query = Regexp.escape(query) if query.is_a?(String)
+    query = Regexp.new("^([^\n]*%s[^\n]*)(\n*)" % query)
+    return false unless @contents.match(query)
+    @contents.gsub!(query, "%s%s%s%s" % [@comment_prefix, $1, @comment_suffix, $2])
+  end
+
+  # Uncomment lines matching the String or Regexp +query+.
+  def uncomment(query, opts={})
+    query = Regexp.escape(query) if query.is_a?(String)
+    query = Regexp.new("^(%s)([^\n]*%s[^\n]*)(%s)(\n*)" % [@comment_prefix, query, @comment_suffix])
+    return false unless @contents.match(query)
+    @contents.gsub!(query, "%s%s" % [$2, $4])
+  end
+
+  # Replace contents matching the String or Regexp +query+ with the +string+.
+  def replace(query, string, opts={})
+    if query.is_a?(String)
+      query = Regexp.new(Regexp.escape(query))
+    end
+    @contents.gsub!(query, string)
+  end
+
+  # Manipulate the buffer. The result of your block will replace the
+  # buffer. This is very useful for complex edits.
+  #
+  # Example:
+  #   manipulate do |buffer|
+  #     buffer.gsub(/foo/, "bar")
+  #   end
+  def manipulate(&block) # :yields: buffer
+    @contents = block.call(@contents)
+  end
+
+  # Is the buffer currently different than its original contents?
+  def different?
+    @contents != @original_contents
+  end
+
+  # Read contents from #filename. Called by the #edit command to load text
+  # into the buffer.
+  def _read
+    @contents = \
+    if writing? or (preview? and @filename and File.exists?(@filename))
+      File.read(@filename)
+    else
+      nil
+    end
+  end
+  protected :_read
+
+  # Write contents to #filename. Used by the #edit command to write the buffer
+  # to a file.
+  def _write
+    log.info(PNOTE+"Edited '#{@filename}'")
+    if preview?
+      true
+    else
+      File.open(@filename, "w+"){|writer| writer.write(@contents)}
+    end
+  end
+  protected :_write
+end # class EditSession

data/lib/automateit/error.rb

@@ -0,0 +1,10 @@
+module AutomateIt
+  # == AutomateIt::Error
+  #
+  # Wraps errors while preserving their cause. Used by the Interpreter to
+  # display user-friendly error messages.
+  #
+  # See NestedError for class API.
+  class Error < ::NestedError
+  end
+end

data/lib/automateit/field_manager.rb

@@ -0,0 +1,103 @@
+# == FieldManager
+#
+# The FieldManager provides a way of accessing a hash of constants. These are
+# useful for storing configuration data seperately from recipes. # Fields are
+# typically stored in a Project's <tt>config/fields.yml</tt> file.
+#
+# Fields can also be queried from the Unix shell using +aifield+, run
+# <tt>aifield --help</tt> for details.
+class AutomateIt::FieldManager < AutomateIt::Plugin::Manager
+  alias_methods :lookup
+
+  # Lookup a field.
+  #
+  # For example, consider a <tt>field.yml</tt> that contains YAML like:
+  #   foo: bar
+  #   my_app:
+  #     my_key: my_value
+  #
+  # With the above file, we can query the fields like this:
+  #   lookup(:foo) # => "bar"
+  #   lookup("foo") # => "bar"
+  #   lookup("my_app#my_key") # => "my_value"
+  #   lookup("my_app#my_branch") # => "my_value"
+  #
+  # You can get a reference to the entire hash:
+  #   lookup("*")
+  #
+  # If a field isn't found, a IndexError is raised.
+  def lookup(search=nil) dispatch(search) end
+end
+
+# == FieldManager::BaseDriver
+#
+# Base class for all FieldManager drivers.
+class AutomateIt::FieldManager::BaseDriver < AutomateIt::Plugin::Driver
+end
+
+# == FieldManager::Struct
+#
+# A FileManager driver that queries a data structure.
+class AutomateIt::FieldManager::Struct < AutomateIt::FieldManager::BaseDriver
+  depends_on :nothing
+
+  def suitability(method, *args) # :nodoc:
+    return 1
+  end
+
+  # Options:
+  # * :struct -- Hash to use as the fields data structure.
+  def setup(opts={})
+    super(opts)
+
+    if opts[:struct]
+      @struct = opts[:struct]
+    else
+      @struct ||= {}
+    end
+  end
+
+  # See FieldManager#lookup
+  def lookup(search=nil)
+    return @struct if search.nil? or search == "*"
+    ref = @struct
+    for key in search.to_s.split("#")
+      ref = ref[key]
+    end
+    if ref
+      return ref
+    else
+      raise IndexError.new("can't find value for: #{search}")
+    end
+  end
+end
+
+# == FieldManager::YAML
+#
+# A FieldManager driver that reads its data structure from a file.
+class AutomateIt::FieldManager::YAML < AutomateIt::FieldManager::Struct
+  depends_on :nothing
+
+  def suitability(method, *args) # :nodoc:
+    return 5
+  end
+
+  # Options:
+  # * :file -- Filename to read data structure from. Contents will be
+  #   parsed with ERB and then handed to YAML.
+  def setup(opts={})
+    if filename = opts.delete(:file)
+      contents = _read(filename)
+      binder = interpreter.send(:binding)
+      output = HelpfulERB.new(contents, filename).result(binder)
+
+      opts[:struct] = ::YAML::load(output)
+    end
+    super(opts)
+  end
+
+  def _read(filename)
+    return File.read(filename)
+  end
+  private :_read
+end

data/lib/automateit/interpreter.rb

@@ -0,0 +1,641 @@
+module AutomateIt
+  # == Interpreter
+  #
+  # The Interpreter runs AutomateIt commands.
+  #
+  # The TUTORIAL.txt[link:files/TUTORIAL_txt.html] file provides hands-on examples
+  # for using the Interpreter.
+  #
+  # === Aliased methods
+  #
+  # The Interpreter provides shortcut aliases for certain plugin commands.
+  #
+  # For example, the following commands will run the same method:
+  #
+  #   shell_manager.sh "ls"
+  #
+  #   sh "ls"
+  #
+  # The full set of aliased methods:
+  #
+  # * cd -- AutomateIt::ShellManager#cd
+  # * chmod -- AutomateIt::ShellManager#chmod
+  # * chmod_R -- AutomateIt::ShellManager#chmod_R
+  # * chown -- AutomateIt::ShellManager#chown
+  # * chown_R -- AutomateIt::ShellManager#chown_R
+  # * chperm -- AutomateIt::ShellManager#chperm
+  # * cp -- AutomateIt::ShellManager#cp
+  # * cp_r -- AutomateIt::ShellManager#cp_r
+  # * edit -- AutomateIt::EditManager#edit
+  # * hosts_tagged_with -- AutomateIt::TagManager#hosts_tagged_with
+  # * install -- AutomateIt::ShellManager#install
+  # * ln -- AutomateIt::ShellManager#ln
+  # * ln_s -- AutomateIt::ShellManager#ln_s
+  # * ln_sf -- AutomateIt::ShellManager#ln_sf
+  # * lookup -- AutomateIt::FieldManager#lookup
+  # * mkdir -- AutomateIt::ShellManager#mkdir
+  # * mkdir_p -- AutomateIt::ShellManager#mkdir_p
+  # * mktemp -- AutomateIt::ShellManager#mktemp
+  # * mktempdir -- AutomateIt::ShellManager#mktempdir
+  # * mktempdircd -- AutomateIt::ShellManager#mktempdircd
+  # * mv -- AutomateIt::ShellManager#mv
+  # * pwd -- AutomateIt::ShellManager#pwd
+  # * render -- AutomateIt::TemplateManager#render
+  # * rm -- AutomateIt::ShellManager#rm
+  # * rm_r -- AutomateIt::ShellManager#rm_r
+  # * rm_rf -- AutomateIt::ShellManager#rm_rf
+  # * rmdir -- AutomateIt::ShellManager#rmdir
+  # * sh -- AutomateIt::ShellManager#sh
+  # * tagged? -- AutomateIt::TagManager#tagged?
+  # * tags -- AutomateIt::TagManager#tags
+  # * tags_for -- AutomateIt::TagManager#tags_for
+  # * touch -- AutomateIt::ShellManager#touch
+  # * umask -- AutomateIt::ShellManager#umask
+  # * which -- AutomateIt::ShellManager#which
+  # * which! -- AutomateIt::ShellManager#which!
+  #
+  # [[[ <a name="embedding"> ]]]
+  # === Embedding the Interpreter
+  # [[[ </a> ]]]
+  #
+  # The AutomateIt Interpreter can be embedded inside a Ruby program:
+  #
+  #   require 'rubygems'
+  #   require 'automateit'
+  #
+  #   interpreter = AutomateIt.new
+  #
+  #   # Use the interpreter as an object:
+  #   interpreter.sh "ls -la"
+  #
+  #   # Have it execute a recipe:
+  #   interpreter.invoke "myrecipe.rb"
+  #
+  #   # Or execute recipes within a block
+  #   interpreter.instance_eval do
+  #     puts superuser?
+  #     sh "ls -la"
+  #   end
+  #
+  # See the #include_in and #add_method_missing_to methods for instructions on
+  # how to more easily dispatch commands from your program to the Interpreter
+  # instance.
+  class Interpreter < Common
+    # Plugin instance that instantiated the Interpreter.
+    attr_accessor :parent
+    private :parent
+    private :parent=
+
+    # Access IRB instance from an interactive shell.
+    attr_accessor :irb
+
+    # Project path for this Interpreter. If no path is available, nil.
+    attr_accessor :project
+
+    # Hash of parameters to make available to the Interpreter. Mostly useful
+    # when needing to pass arguments to an embedded Interpreter before doing an
+    # #instance_eval.
+    attr_accessor :params
+
+    # The Interpreter throws friendly error messages by default that make it
+    # easier to see what's wrong with a recipe. These friendly messages display
+    # the cause, a snapshot of the problematic code, shortened paths, and only
+    # the relevant stack frames.
+    #
+    # However, if there's a bug in the AutomateIt internals, these friendly
+    # messages may inadvertently hide the cause, and it may be necessary to
+    # turn them off to figure out what's wrong.
+    #
+    # To turn off friendly exceptions:
+    #
+    #   # From a recipe or the AutomateIt interactive shell:
+    #   self.friendly_exceptions = false
+    #
+    #   # For an embedded interpreter at instantiation:
+    #   AutomateIt.new(:friendly_exceptions => false)
+    #
+    #   # From the UNIX command line when invoking a recipe:
+    #   automateit --trace myrecipe.rb
+    attr_accessor :friendly_exceptions
+
+    # Setup the Interpreter. This method is also called from Interpreter#new.
+    #
+    # Options for users:
+    # * :verbosity -- Alias for :log_level
+    # * :log_level -- Log level to use, defaults to Logger::INFO.
+    # * :preview -- Turn on preview mode, defaults to false.
+    # * :project -- Set project path.
+    # * :friendly_exceptions -- Throw user-friendly exceptions that make it
+    #   easier to see errors in recipes, defaults to true.
+    #
+    # Options for internal use:
+    # * :parent -- Parent plugin instance.
+    # * :log -- QueuedLogger instance.
+    # * :guessed_project -- Boolean of whether the project path was guessed. If
+    #   guessed, won't throw exceptions if project wasn't found at the
+    #   specified path. If not guessed, will throw exception in such a
+    #   situation.
+    def setup(opts={})
+      super(opts.merge(:interpreter => self))
+
+      self.params ||= {}
+
+      if opts[:irb]
+        @irb = opts[:irb]
+      end
+
+      if opts[:parent]
+        @parent = opts[:parent]
+      end
+
+      if opts[:log]
+        @log = opts[:log]
+      elsif not defined?(@log) or @log.nil?
+        @log = QueuedLogger.new($stdout)
+        @log.level = Logger::INFO
+      end
+
+      if opts[:log_level] or opts[:verbosity]
+        @log.level = opts[:log_level] || opts[:verbosity]
+      end
+
+      if opts[:preview].nil? # can be false
+        self.preview = false unless preview?
+      else
+        self.preview = opts[:preview]
+      end
+
+      if opts[:friendly_exceptions].nil?
+        @friendly_exceptions = true unless defined?(@friendly_exceptions)
+      else
+        @friendly_exceptions = opts[:friendly_exceptions]
+      end
+
+      # Instantiate core plugins so they're available to the project
+      _instantiate_plugins
+
+      if project_path = opts[:project] || ENV["AUTOMATEIT_PROJECT"] || ENV["AIP"]
+        # Only load a project if we find its env file
+        env_file = File.join(project_path, "config", "automateit_env.rb")
+        if File.exists?(env_file)
+          @project = File.expand_path(project_path)
+          log.debug(PNOTE+"Loading project from path: #{@project}")
+
+          tag_file = File.join(@project, "config", "tags.yml")
+          if File.exists?(tag_file)
+            log.debug(PNOTE+"Loading project tags: #{tag_file}")
+            tag_manager[:yaml].setup(:file => tag_file)
+          end
+
+          field_file = File.join(@project, "config", "fields.yml")
+          if File.exists?(field_file)
+            log.debug(PNOTE+"Loading project fields: #{field_file}")
+            field_manager[:yaml].setup(:file => field_file)
+          end
+
+          lib_files = Dir[File.join(@project, "lib", "*.rb")] + Dir[File.join(@project, "lib", "**", "init.rb")]
+          lib_files.each do |lib|
+            log.debug(PNOTE+"Loading project library: #{lib}")
+            invoke(lib)
+          end
+
+          # Instantiate project's plugins so they're available to the environment
+          _instantiate_plugins
+
+          if File.exists?(env_file)
+            log.debug(PNOTE+"Loading project env: #{env_file}")
+            invoke(env_file)
+          end
+        elsif not opts[:guessed_project]
+          raise ArgumentError.new("Couldn't find project at: #{project_path}")
+        end
+      end
+    end
+
+    # Hash of plugin tokens to plugin instances for this Interpreter.
+    attr_accessor :plugins
+
+    def _instantiate_plugins
+      @plugins ||= {}
+      # If a parent is defined, use it to prep the list and avoid re-instantiating it.
+      if defined?(@parent) and @parent and Plugin::Manager === @parent
+        @plugins[@parent.class.token] = @parent
+      end
+      plugin_classes = AutomateIt::Plugin::Manager.classes.reject{|t| t == @parent if @parent}
+      for klass in plugin_classes
+        _instantiate_plugin(klass)
+      end
+    end
+    private :_instantiate_plugins
+
+    def _instantiate_plugin(klass)
+      token = klass.token
+      unless plugin = @plugins[token]
+        plugin = @plugins[token] = klass.new(:interpreter => self)
+        #puts "!!! ip #{token}"
+        unless respond_to?(token.to_sym)
+          self.class.send(:define_method, token) do
+            @plugins[token]
+          end
+        end
+        _expose_plugin_methods(plugin)
+      end
+      plugin.instantiate_drivers
+    end
+    private :_instantiate_plugin
+
+    def _expose_plugin_methods(plugin)
+      return unless plugin.class.aliased_methods
+      plugin.class.aliased_methods.each do |method|
+        #puts "!!! epm #{method}"
+        unless respond_to?(method.to_sym)
+          # Must use instance_eval because methods created with define_method
+          # can't accept block as argument. This is a known Ruby 1.8 bug.
+          self.instance_eval <<-EOB
+            def #{method}(*args, &block)
+              @plugins[:#{plugin.class.token}].send(:#{method}, *args, &block)
+            end
+          EOB
+        end
+      end
+    end
+    private :_expose_plugin_methods
+
+    # Set the QueuedLogger instance for the Interpreter.
+    attr_writer :log
+
+    # Get or set the QueuedLogger instance for the Interpreter, a special
+    # wrapper around the Ruby Logger.
+    def log(value=nil)
+      if value.nil?
+        return defined?(@log) ? @log : nil
+      else
+        @log = value
+      end
+    end
+
+    # Set preview mode to +value+. See warnings in ShellManager to learn how to
+    # correctly write code for preview mode.
+    def preview(value)
+      self.preview = value
+    end
+
+    # Is Interpreter running in preview mode?
+    def preview?
+      @preview
+    end
+
+    # Preview a block of custom commands. When in preview mode, displays the
+    # +message+ but doesn't execute the +block+. When not previewing, will
+    # execute the block and not display the +message+.
+    #
+    # For example:
+    #
+    #   preview_for("FOO") do
+    #     puts "BAR"
+    #   end
+    #
+    # In preview mode, this displays:
+    #
+    #   => FOO
+    #
+    # When not previewing, displays:
+    #
+    #   BAR
+    def preview_for(message, &block)
+      if preview?
+        log.info(message)
+        :preview
+      else
+        block.call
+      end
+    end
+
+    # Set preview mode to +value.
+    def preview=(value)
+      @preview = value
+    end
+
+    # Set noop (no-operation mode) to +value+. Alias for #preview.
+    def noop(value)
+      self.noop = value
+    end
+
+    # Set noop (no-operation mode) to +value+. Alias for #preview=.
+    def noop=(value)
+      self.preview = value
+    end
+
+    # Are we in noop (no-operation) mode? Alias for #preview?.
+    def noop?
+      preview?
+    end
+
+    # Set writing to +value+. This is the opposite of #preview.
+    def writing(value)
+      self.writing = value
+    end
+
+    # Set writing to +value+. This is the opposite of #preview=.
+    def writing=(value)
+      self.preview = !value
+    end
+
+    # Is Interpreter writing? This is the opposite of #preview?.
+    def writing?
+      !preview?
+    end
+
+    # Does this platform provide euid (Effective User ID)?
+    def euid?
+      begin
+        euid
+        return true
+      rescue
+        return false
+      end
+    end
+
+    # Return the effective user id.
+    def euid
+      begin
+        return Process.euid
+      rescue NoMethodError => e
+        output = `id -u 2>&1`
+        raise e unless output and $?.exitstatus.zero?
+        begin
+          return output.match(/(\d+)/)[1].to_i
+        rescue IndexError
+          raise e
+        end
+      end
+
+    end
+
+    # Does the current user have superuser (root) privileges?
+    def superuser?
+      euid.zero?
+    end
+
+    # Create an Interpreter with the specified +opts+ and invoke
+    # the +recipe+. The opts are passed to #setup for parsing.
+    def self.invoke(recipe, opts={})
+      opts[:project] ||= File.join(File.dirname(recipe), "..")
+      AutomateIt.new(opts).invoke(recipe)
+    end
+
+    # Invoke the +recipe+. The recipe may be expressed as a relative or fully
+    # qualified path. When invoked within a project, the recipe can also be the
+    # name of a recipe.
+    #
+    # Example:
+    #  invoke "/tmp/recipe.rb"  # Run "/tmp/recipe.rb"
+    #  invoke "recipe.rb"       # Run "./recipe.rb". If not found and in a
+    #                           # project, will try running "recipes/recipe.rb"
+    #  invoke "recipe"          # Run "recipes/recipe.rb" in a project
+    def invoke(recipe)
+      filenames = [recipe]
+      filenames << File.join(project, "recipes", recipe) if project
+      filenames << File.join(project, "recipes", recipe + ".rb") if project
+
+      for filename in filenames
+        log.debug(PNOTE+" invoking "+filename)
+        if File.exists?(filename)
+          data = File.read(filename)
+          begin
+            return instance_eval(data, filename, 1)
+          rescue Exception => e
+            if @friendly_exceptions
+              # TODO Extract this routine and its companion in HelpfulERB
+
+              # Capture initial stack in case we add a debug/breakpoint after this
+              stack = caller
+
+              # Extract trace for recipe after the Interpreter#invoke call
+              preresult = []
+              for line in e.backtrace
+                # Stop at the Interpreter#invoke call
+                break if line == stack.first
+                preresult << line
+              end
+
+              # Extract the recipe filename
+              preresult.last.match(/^([^:]+):(\d+):in `invoke'/)
+              recipe = $1
+
+              # Extract trace for most recent block
+              result = []
+              for line in preresult
+                # Ignore manager wrapper and dispatch methods
+                next if line =~ %r{lib/automateit/.+manager\.rb:\d+:in `.+'$}
+                result << line
+                # Stop at the first mention of this recipe
+                break if line =~ /^#{recipe}/
+              end
+
+              # Extract line number
+              if e.is_a?(SyntaxError)
+                line_number = e.message.match(/^[^:]+:(\d+):/)[1].to_i
+              else
+                result.last.match(/^([^:]+):(\d+):in `invoke'/)
+                line_number = $2.to_i
+              end
+
+              msg = "Problem with recipe '#{recipe}' at line #{line_number}\n"
+
+              # Extract recipe text
+              begin
+                lines = File.read(recipe).split(/\n/)
+
+                min = line_number - 7
+                min = 0 if min < 0
+
+                max = line_number + 1
+                max = lines.size if max > lines.size
+
+                width = max.to_s.size
+
+                for i in min..max
+                  n = i+1
+                  marker = n == line_number ? "*" : ""
+                  msg << "\n%2s %#{width}i %s" % [marker, n, lines[i]]
+                end
+
+                msg << "\n"
+              rescue Exception => e
+                # Ignore
+              end
+
+              msg << "\n(#{e.exception.class}) #{e.message}"
+
+              # Append shortened trace
+              for line in result
+                msg << "\n  "+line
+              end
+
+              # Remove project path
+              msg.gsub!(/#{@project}\/?/, '') if @project
+
+              raise AutomateIt::Error.new(msg, e)
+            else
+              raise e
+            end
+          end
+        end
+      end
+      raise Errno::ENOENT.new(recipe)
+    end
+
+    # Path of this project's "dist" directory. If a project isn't available or
+    # the directory doesn't exist, this will throw a NotImplementedError.
+    def dist
+      if @project
+        result = File.join(@project, "dist/")
+        if File.directory?(result)
+          return result
+        else
+          raise NotImplementedError.new("can't find dist directory at: #{result}")
+        end
+      else
+        raise NotImplementedError.new("can't use dist without a project")
+      end
+    end
+
+    # Set value to share throughout the Interpreter. Use this instead of
+    # globals so that different Interpreters don't see each other's variables.
+    # Creates a method that returns the value and also adds a #params entry.
+    #
+    # Example:
+    #  set :asdf, 9 # => 9
+    #  asdf         # => 9
+    #
+    # This is best used for frequently-used variables, like paths. For
+    # infrequently-used variables, use #lookup and #params. A good place to use
+    # the #set is in the  Project's <tt>config/automateit_env.rb</tt> file so
+    # that paths are exposed to all recipes like this:
+    #
+    #  set :helpers, project+"/helpers"
+    def set(key, value)
+      key = key.to_sym
+      params[key] = value
+      eval <<-HERE
+        def #{key}
+          return params[:#{key}]
+        end
+      HERE
+      value
+    end
+
+    # Retrieve a #params entry.
+    #
+    # Example:
+    #  params[:foo] = "bar"  # => "bar"
+    #  get :foo              # => "bar"
+    def get(key)
+      params[key.to_sym]
+    end
+
+    # Creates wrapper methods in +object+ to dispatch calls to an Interpreter instance.
+    #
+    # *WARNING*: This will overwrite all methods and variables in the target +object+ that have the same names as the Interpreter's methods. You should considerer specifying the +methods+ to limit the number of methods included to minimize surprises due to collisions. If +methods+ is left blank, will create wrappers for all Interpreter methods.
+    #
+    # For example, include an Interpreter instance into a Rake session, which will override the FileUtils commands with AutomateIt equivalents:
+    #
+    #   # Rakefile
+    #
+    #   require 'automateit'
+    #   @ai = AutomateIt.new
+    #   @ai.include_in(self, %w(preview? sh)) # Include #preview? and #sh methods
+    #
+    #   task :default do
+    #     puts preview?   # Uses Interpreter#preview?
+    #     sh "id"         # Uses Interpreter#sh, not FileUtils#sh
+    #     cp "foo", "bar" # Uses FileUtils#cp, not Interpreter#cp
+    #   end
+    #
+    # For situations where you don't want to override any existing methods, consider using #add_method_missing_to.
+    def include_in(object, *methods)
+      methods = [methods].flatten
+      methods = unique_methods.reject{|t| t =~ /^_/} if methods.empty?
+
+      object.instance_variable_set(:@__automateit, self)
+
+      for method in methods
+        object.instance_eval <<-HERE
+          def #{method}(*args, &block)
+            @__automateit.send(:#{method}, *args, &block)
+          end
+        HERE
+      end
+    end
+
+    # Creates #method_missing in +object+ that dispatches calls to an Interpreter instance. If a #method_missing is already present, it will be preserved as a fall-back using #alias_method_chain.
+    #
+    # For example, add #method_missing to a Rake session to provide direct access to Interpreter instance's methods whose names don't conflict with the names existing variables and methods:
+    #
+    #   # Rakefile
+    #
+    #   require 'automateit'
+    #   @ai = AutomateIt.new
+    #   @ai.add_method_missing_to(self)
+    #
+    #   task :default do
+    #     puts preview? # Uses Interpreter#preview?
+    #     sh "id"       # Uses FileUtils#sh, not Interpreter#sh
+    #   end
+    #
+    # For situations where it's necessary to override existing methods, such as the +sh+ call in the example, consider using #include_in.
+    def add_method_missing_to(object)
+      object.instance_variable_set(:@__automateit, self)
+      chain = object.respond_to?(:method_missing)
+
+      # XXX The solution below is evil and ugly, but I don't know how else to solve this. The problem is that I want to *only* alter the +object+ instance, and NOT its class. Unfortunately, #alias_method and #alias_method_chain only operate on classes, not instances, which makes them useless for this task.
+
+      template = <<-HERE
+        def method_missing<%=chain ? '_with_automateit' : ''%>(method, *args, &block)
+          ### puts "mm+a(%s, %s)" % [method, args.inspect]
+          if @__automateit.respond_to?(method)
+            @__automateit.send(method, *args, &block)
+          else
+            <%-if chain-%>
+              method_missing_without_automateit(method, *args, &block)
+            <%-else-%>
+              super
+            <%-end-%>
+          end
+        end
+        <%-if chain-%>
+          @__method_missing_without_automateit = self.method(:method_missing)
+
+          def method_missing_without_automateit(*args)
+            ### puts "mm-a %s" % args.inspect
+            @__method_missing_without_automateit.call(*args)
+          end
+
+          def method_missing(*args)
+            ### puts "mm %s" % args.inspect
+            method_missing_with_automateit(*args)
+          end
+        <%-end-%>
+      HERE
+
+      text = ::HelpfulERB.new(template).result(binding)
+      object.instance_eval(text)
+    end
+
+    # Use to manage nitpick message for debugging AutomateIt internals.
+    #
+    # Arguments:
+    # * nil -- Returns boolean of whether nitpick messages will be displayed.
+    # * Boolean -- Sets nitpick state.
+    # * String or Symbol -- Displays nitpick message if state is on.
+    def nitpick(value=nil)
+      case value
+      when NilClass: @nitpick
+      when TrueClass, FalseClass: @nitpick = value
+      when String, Symbol: puts "%% #{value}" if @nitpick
+      else raise TypeError.new("Unknown nitpick type: #{value.class}")
+      end
+    end
+  end
+end