Class AutomateIt::Plugin::Driver
In: lib/automateit/plugin/driver.rb
Parent: Base

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 apt-get 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 apt-get 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

Methods

_raise_unless_available   abstract_driver   available?   base_driver   base_driver?   depends_on   manager_token   setup   suitability  

Constants

BASE_DRIVER_NAME = "BaseDriver"

Attributes

manager  [RW]  Returns the Plugin::Manager instance for this Driver.

Public Class methods

abstract_driver()

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.

base_driver()

Retrieve the base driver class for this driver.

base_driver?()

Is this a base driver?

depends_on(opts)

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
manager_token()

Retrieve the manager token for this driver

Public Instance methods

available?()

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.

setup(opts={})

Setup a Driver.

Options:

suitability(method, *args, &block)

What is this driver‘s suitability for automatic detection? The Manager queries its drivers when there isn‘t a driver specified with a :with 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 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.

Protected Instance methods

_raise_unless_available()

Raise a NotImplementedError if this driver is called but is not available?.

[Validate]