automate-it 0.9.0

data/lib/automateit/platform_manager/windows.rb

@@ -0,0 +1,40 @@
+# == PlatformManager::Windows
+#
+# A PlatformManager driver for Windows systems.
+class AutomateIt::PlatformManager::Windows < AutomateIt::PlatformManager::Struct
+  def available?
+    return RUBY_PLATFORM.match(/mswin/) ? true : false
+  end
+
+  def suitability(method, *args) # :nodoc:
+    # Must be higher than PlatformManager::Struct
+    return available? ? 3 : 0
+  end
+
+  def _prepare
+    return if @struct[:release]
+    @struct[:os] = "windows"
+    @struct[:arch] = ENV["PROCESSOR_ARCHITECTURE"]
+    @struct[:distro] = "microsoft"
+
+    # VER values: http://www.ss64.com/nt/ver.html
+    ver = `ver`.strip
+    if match = ver.match(/Windows (\w+)/)
+      @struct[:release] = match[1].downcase
+    elsif match = ver.match(/Windows \[Version 6\.0\./)
+      @struct[:release] = "vista"
+    end
+
+    @struct
+  end
+  private :_prepare
+
+  def query(search)
+    _prepare
+    super(search)
+  end
+
+  def single_vendor?
+    return true
+  end
+end

data/lib/automateit/plugin.rb

@@ -0,0 +1,7 @@
+module AutomateIt
+  class Plugin # :nodoc:
+    require 'automateit/plugin/base'
+    require 'automateit/plugin/manager'
+    require 'automateit/plugin/driver'
+  end
+end

data/lib/automateit/plugin/base.rb

@@ -0,0 +1,32 @@
+module AutomateIt
+  class Plugin
+    # == Plugin::Base
+    #
+    # An AutomateIt Plugin provides the Interpreter with the functionality that
+    # users actually care about, such as installing packages or adding users.
+    # The Plugin::Base class isn't useful by itself but provides behavior
+    # that's inherited by the Plugin::Manager and Plugin::Driver classes.
+    class Base < Common
+      def setup(opts={}) # :nodoc:
+        super(opts)
+        @interpreter ||= opts[:interpreter] \
+          || AutomateIt::Interpreter.new(:parent => self)
+      end
+
+      # Get token for the plugin. The token is a symbol that represents the
+      # classname of the underlying object.
+      #
+      # Example:
+      #   AddressManager.token # => :address_manager
+      #   AddressManager::Portable.token => :portable
+      def token
+        self.class.token
+      end
+
+      # See #token.
+      def self.token
+        return to_s.demodulize.underscore.to_sym
+      end
+    end
+  end
+end

data/lib/automateit/plugin/driver.rb

@@ -0,0 +1,256 @@
+module AutomateIt
+  class Plugin
+    # == Plugin::Driver
+    #
+    # A driver provides the low-level functionality for features, e.g., the
+    # PackageManager::APT driver is responsible for installing a software
+    # package using the Debian <tt>apt-get</tt> command. Multiple drivers
+    # providing common functionality are managed by a single Manager class,
+    # e.g., drivers that install software packages are managed by the
+    # PackageManager.
+    #
+    # A driver may only be available on certain platforms and provides its
+    # manager with an idea of when it's suitable. For example, if a platform
+    # doesn't have the <tt>apt-get</tt> command, the PackageManager::APT driver
+    # must tell the PackageManager class that it's not suitable.
+    #
+    # === Writing your own drivers
+    #
+    # To write a driver, find the most similar driver available for a specific
+    # plugin, copy it, and rework its code. Save the code for the new driver in
+    # a file ending with .rb into the project’s +lib+ directory, it will be
+    # automatically loaded whenever the Interpreter for that project is run.
+    # Please test and contribute drivers so that others can benefit.
+    #
+    # IMPORTANT GOTCHA: You must prefix the AutomateIt module name with a "::"!
+    #
+    # Here's a minimalistic PackageManager that can be dropped into +lib+:
+    #
+    #   class MyDriver < ::AutomateIt::PackageManager::BaseDriver
+    #     depends_on :nothing
+    #
+    #     def suitability(method, *args) # :nodoc:
+    #       # Never select as default driver
+    #       return 0
+    #     end
+    #   end
+    class Driver < Base
+      # Driver classes. Represented as a hash of manager tokens to arrays of
+      # their driver classes, for example:
+      #
+      #  { :package_manager => [
+      #                          AutomateIt::PackageManager::APT,
+      #                          AutomateIt::PackageManager::YUM,
+      #                          ...
+      cattr_accessor :classes
+      self.classes = {}
+
+      # Returns the Plugin::Manager instance for this Driver.
+      attr_accessor :manager
+
+      # Setup a Driver.
+      #
+      # Options:
+      # * :manager -- The Plugin::Manager instance controlling this driver.
+      def setup(opts={})
+        self.manager = opts[:manager] if opts[:manager]
+        super(opts)
+      end
+
+      # Retrieve the manager token for this driver
+      def self.manager_token
+        fragments = base_driver.to_s.split(/::/)
+        return fragments[fragments.size-2].underscore.to_sym
+      end
+
+      BASE_DRIVER_NAME = "BaseDriver"
+
+      # Is this a base driver?
+      def self.base_driver?
+        to_s =~ /::#{BASE_DRIVER_NAME}/
+      end
+
+      # Retrieve the base driver class for this driver.
+      def self.base_driver
+        ancestors.select{|t| t.to_s =~ /::#{BASE_DRIVER_NAME}/}.last
+      end
+
+      # Register drivers. Concrete drivers are added to a class-wide data
+      # structure which maps them to the manager they belong to.
+      def self.inherited(subclass) # :nodoc:
+        base_driver = subclass.base_driver
+        if subclass.base_driver?
+          # Ignore, base drivers should never be registered
+        elsif base_driver
+          manager_token = subclass.manager_token
+          classes[manager_token] ||= []
+
+          unless classes[manager_token].include?(subclass)
+            classes[manager_token] << subclass
+          end
+
+          ### puts "manager_token %s / driver %s" % [manager_token, subclass]
+        else
+          # XXX Should this really raise an exception?
+          raise TypeError.new("Can't determine manager for driver: #{subclass}")
+        end
+      end
+
+      # Declare that this driver class is abstract. It can be subclassed but
+      # will not be instantiated by the Interpreter's Managers. BaseDriver
+      # classes are automatically declared abstract.
+      def self.abstract_driver
+        if base_driver?
+          # Ignore, base drivers should never have been registered
+        elsif manager = manager_token
+          classes[manager].delete(self)
+        else
+          raise TypeError.new("Can't find manager for abstract plugin: #{self}")
+        end
+      end
+
+      # Defines resources this driver depends on.
+      #
+      # Options:
+      # * :files -- Array of filenames that must exist.
+      # * :directories -- Array of directories that must exist.
+      # * :programs -- Array of programs, checked with +which+, that must exist.
+      # * :callbacks -- Array of lambdas that must return true.
+      # * :libraries -- Array of libraries to +require+.
+      #
+      # Example:
+      #   class APT < Plugin::Driver
+      #     depends_on :programs => %w(apt-get dpkg)
+      #     # ...
+      #  end
+      def self.depends_on(opts)
+        meta_eval do
+          attr_accessor :_depends_on_opts, :_is_available, :_missing_dependencies
+        end
+        self._depends_on_opts = opts
+      end
+
+      # Is this driver available on this platform? Queries the dependencies set
+      # by #depends_on to make sure that they're all present, otherwise raises
+      # a NotImplementedError. If a driver author needs to do some other kind
+      # of check, it's reasonable to override this method.
+      #
+      # For example, this method is used by the PackageManager driver for APT
+      # to determine if the "apt-get" program is installed.
+      #
+      # What's the difference between #available? and #suitability? The
+      # #available? method is used to determine if the driver *can* do the
+      # work, while the #suitability method determines if the driver *should*
+      # be automatically selected.
+      def available?
+        # Some drivers don't run +depends_on+, so assume they're available.
+        return true unless self.class.respond_to?(:_depends_on_opts)
+        opts = self.class._depends_on_opts
+
+        # Driver said that it +depends_on :nothing+, so it's available.
+        return true if opts == :nothing
+
+        is_available = self.class._is_available
+        if is_available.nil? and opts.nil?
+          #log.debug(PNOTE+"don't know if driver #{self.class} is available, maybe it doesn't state what it +depends_on+")
+          return false
+        elsif is_available.nil?
+          all_present = true
+          missing = {}
+
+          # Check callbacks last
+          kinds = opts.keys
+          callbacks = kinds.delete(:callbacks)
+          kinds << callbacks if callbacks
+
+          begin
+            for kind in kinds
+              next unless opts[kind]
+              for item in [opts[kind]].flatten
+                present = \
+                  case kind
+                  when :files
+                    File.exists?(item)
+                  when :directories
+                    File.directory?(item)
+                  when :programs
+                    # TODO Driver#available? - Find better way to locate the platform's #which driver and use it to check if a program exists. This is tricky because this #available? method is the one that handles detection, yet we have to bypass it.
+                    result = nil
+                    for variant in %w(unix windows)
+                      variant_token = "which_#{variant}".to_sym
+                      begin
+                        driver = interpreter.shell_manager[variant_token]
+                        result = driver.which!(item)
+                        ### puts "%s : %s for %s" % [variant, result, item]
+                        break
+                      rescue ArgumentError, NotImplementedError, NoMethodError => e
+                        # Exceptions are expected, only print for debugging
+                        ### puts e.inspect
+                      end
+                    end
+                    result
+                  when :requires, :libraries
+                    begin
+                      require item
+                      true
+                    rescue LoadError
+                      false
+                    end
+                  when :callbacks
+                    item.call() ? true : false
+                  else
+                    raise TypeError.new("Unknown kind: #{kind}")
+                  end
+                unless present
+                  all_present = false
+                  missing[kind] ||= []
+                  missing[kind] << item
+
+                  # Do not continue scanning if dependency is missed
+                  raise EOFError.new("break")
+                end
+              end
+            end
+          rescue EOFError => e
+            # Ignore expected "break" warning
+            raise e unless e.message == "break"
+          end
+          self.class._missing_dependencies = missing
+          self.class._is_available = all_present
+          log.debug(PNOTE+"Driver #{self.class} #{all_present ? "is" : "isn't"} available")
+        end
+        return self.class._is_available
+      end
+
+      # Raise a NotImplementedError if this driver is called but is not
+      # #available?.
+      def _raise_unless_available
+        unless available?
+          msg = ""
+          for kind, elements in self.class._missing_dependencies
+            msg << "; " unless msg == ""
+            msg << "%s: %s" % [kind, elements.sort.join(', ')]
+          end
+          raise NotImplementedError.new("Missing dependencies -- %s" % msg)
+        end
+      end
+      protected :_raise_unless_available
+
+      # What is this driver's suitability for automatic detection? The Manager
+      # queries its drivers when there isn't a driver specified with a
+      # <tt>:with</tt> or #default so it can choose a suitable driver for the
+      # +method+ and +args+. Any driver that returns an integer 1 or greater
+      # claims to be suitable. The Manager will then select the driver with the
+      # highest suitability level. Drivers that return an integer less than 1
+      # are excluded from automatic detection.
+      #
+      # The <tt>available?</tt> method is used to determine if the driver can
+      # do the work, while the <tt>suitability</tt> method determines if the
+      # driver should be automatically selected.
+      def suitability(method, *args, &block)
+        log.debug("driver #{self.class} doesn't implement the +suitability+ method")
+        return -1
+      end
+    end
+  end
+end

data/lib/automateit/plugin/manager.rb

@@ -0,0 +1,224 @@
+module AutomateIt
+  class Plugin
+    # == Plugin::Manager
+    #
+    # A manager provides high-level wrappers for features, e.g.
+    # installing software packages. It does not actually implement these
+    # features, but instead manages a set of drivers. When one of the manager's
+    # wrapper methods is called, it queries the drivers to find the most
+    # suitable one and dispatches the user's request to that driver.
+    #
+    # For example, the PlatformManager is a Manager class that manages a set of
+    # Driver instances, including PlatformManager::Uname and
+    # PlatformManager::LSB. When you invoke the high-level
+    # PlatformManager#query wrapper method, it interrogates the drivers to find
+    # which one is best-suited for this method and then dispatches the request
+    # to that driver's low-level implementation of this method.
+    #
+    # The manager subclasses typically have no functionality of their own and
+    # just contain wrapper methods and documentation.
+    class Manager < Base
+      # Array of all managers.
+      cattr_accessor :classes
+      self.classes = []
+
+      # Register managers.
+      def self.inherited(subclass) # :nodoc:
+        classes << subclass unless classes.include?(subclass)
+      end
+
+      # Declare that this manager class is abstract. It can be subclassed but
+      # will not be instantiated by the Interpreter.
+      def self.abstract_manager
+        classes.delete(self)
+      end
+
+      # List of aliased methods for this manager, populated by ::alias_methods.
+      class_inheritable_accessor :aliased_methods
+
+      # Methods to alias into the Interpreter, specified as an array of symbols.
+      def self.alias_methods(*methods)
+        self.aliased_methods ||= Set.new
+        self.aliased_methods.merge(methods.flatten)
+      end
+
+      # Drivers for this manager as a hash of driver tokens to driver
+      # instances.
+      attr_accessor :drivers
+
+      # Driver classes used by this Manager.
+      def self.driver_classes
+        Driver.classes[token] || []
+      end
+
+      # Options:
+      # * :default -- The token of the driver to set as the default.
+      def setup(opts={})
+        super(opts)
+
+        @default ||= nil
+
+        instantiate_drivers
+
+        if driver = opts[:default] || opts[:driver]
+          default(opts[:default]) if opts[:default]
+          @drivers[driver].setup(opts)
+        end
+      end
+
+      # Instantiate drivers for this manager. This method is smart enough that
+      # it can be called multiple times and will only instantiate drivers it
+      # hasn't instantiated yet. All drivers will share an instance of the
+      # Interpreter, thus providing common state storage.
+      def instantiate_drivers
+        @drivers ||= {}
+        self.class.driver_classes.each do |driver_class|
+          driver_token = driver_class.token
+          unless @drivers[driver_token]
+            @drivers[driver_token] = driver_class.allocate
+          end
+        end
+        self.class.driver_classes.each do |driver_class|
+          driver_token = driver_class.token
+          @drivers[driver_token].setup(
+            :interpreter => @interpreter, :manager => self)
+        end
+      end
+
+      # Returns the Driver with the specified token. E.g., +:apt+ will return
+      # the +APT+ driver.
+      def [](token)
+        return @drivers[token]
+      end
+
+      # Manipulate the default driver. Without arguments, gets the driver token
+      # as a symbol. With argument, sets the default driver to the +token+,
+      # e.g., the argument <tt>:apt</tt> will make the +APT+ driver the default.
+      def default(token=nil)
+        if token.nil?
+          @default
+        else
+          @default = token
+        end
+      end
+
+      # Set the default driver to the +token+. See also #default.
+      def default=(token)
+        default(token)
+      end
+
+      # Dispatch a method by guessing its name. This is the recommended way to
+      # write wrappers for a Manager methods.
+      #
+      # Example:
+      #   class MyManager < Plugin::Manager
+      #     # Your RDoc here
+      #     def my_method(*args)
+      #       # Will guess that you want to +dispatch_to+ the +my_method+ by
+      #       # introspecting the name of the wrapper method.
+      #       dispatch(*args)
+      #     end
+      #     ...
+      #   end
+      def dispatch(*args, &block)
+        # Extract caller's method as symbol to save user from having to specify it
+        method = caller[0].match(/:in `(.+?)'/)[1].to_sym
+        dispatch_to(method, *args, &block)
+      end
+
+      # Dispatch the +method+ with +args+ and +block+ to the appropriate
+      # driver. If the arguments include an option of the form <tt>:with =>
+      # :mytoken</tt> argument, then the method will be dispatched to the
+      # driver represented by <tt>:mytoken</tt>. If no :with argument is
+      # specified, the most-suitable driver will be automatically selected. If
+      # no suitable driver is available, a NotImplementedError will be raised.
+      #
+      # Examples:
+      #   # Run 'hostnames' method on most appropriate AddressManager driver:
+      #   address_manager.dispatch_to(:hostnames)
+      #
+      #   # Run AddressManager::Portable#hostnames
+      #   address_manager.dispatch_to(:hostnames, :with => :portable)
+      #
+      # You will typically not want to use this method directly and instead
+      # write wrappers that call #dispatch because it can guess the name of
+      # the +method+ argument for you.
+      def dispatch_to(method, *args, &block)
+        list, options = args_and_opts(*args)
+        driver = \
+          if options and options[:with]
+            @drivers[options[:with].to_sym]
+          elsif default
+            @drivers[default.to_sym]
+          else
+            driver_for(method, *args, &block)
+          end
+        driver.send(method, *args, &block)
+      end
+
+      # Same as #dispatch_to but returns nil if couldn't dispatch, rather than
+      # raising an exception.
+      def dispatch_safely_to(method, *args, &block)
+        begin
+          dispatch_to(method, *args, &block)
+        rescue NotImplementedError
+          nil
+        end
+      end
+
+      # Same as #dispatch but returns nil if couldn't dispatch, rather than
+      # raising an exception.
+      def dispatch_safely(*args, &block)
+        method = caller[0].match(/:in `(.+?)'/)[1].to_sym
+        dispatch_safely_to(method, *args, &block)
+      end
+
+      # Returns structure which helps choose a suitable driver for the +method+
+      # and +args+. Result is a hash of driver tokens and their suitability
+      # levels.
+      #
+      # For example, if we ask the AddressManager for suitability levels for
+      # the AddressManager#hostnames method, we might find that there are two
+      # drivers (:portable is the token for AddressManager::Portable) and that
+      # the :linux driver is most appropriate because it has the highest
+      # suitability level:
+      #
+      #   address_manager.driver_suitability_levels_for(:hostnames)
+      #   # => {:portable=>1, :linux=>2}
+      def driver_suitability_levels_for(method, *args, &block)
+        results = {}
+        @drivers.each_pair do |name, driver|
+          next unless driver.respond_to?(method)
+          results[name] = driver.suitability(method, *args, &block)
+        end
+        return results
+      end
+
+      # Get the most suitable driver for this +method+ and +args+. Uses
+      # automatic-detection routines and returns the most suitable driver
+      # instance found, else raises a NotImplementedError if no suitable driver
+      # is found.
+      def driver_for(method, *args, &block)
+        driver, level = driver_suitability_levels_for(method, *args, &block).sort_by{|k,v| v}.last
+        if driver and level > 0
+          return @drivers[driver]
+        else
+          raise NotImplementedError.new("can't find driver for method '#{method}' with arguments: #{args.inspect}")
+        end
+      end
+
+      # Is a driver available for this +method+ and +args+? Uses
+      # automatic-detection routines and returns a boolean to indicate if a
+      # suitable driver is available. Unlike #driver_for, this will not raise
+      # an exception.
+      def available?(method, *args, &block)
+        begin
+          driver_for(method, *args, &block)
+          true
+        rescue NotImplementedError
+          false
+        end
+      end
+    end
+  end
+end