mattbrictson/tomo

View on GitHub
docs/api/PluginDSL.md

Summary

Maintainability
Test Coverage
# Tomo::PluginDSL

A tomo plugin is defined by a Ruby module that extends Tomo::PluginDSL. A plugin definition can specify three things:

- Default settings
- Tasks
- Helpers

Here is the bundler plugin as an example:

```ruby
require_relative "bundler/helpers"
require_relative "bundler/tasks"

module Tomo::Plugin::Bundler
  extend Tomo::PluginDSL

  tasks Tomo::Plugin::Bundler::Tasks
  helpers Tomo::Plugin::Bundler::Helpers

  defaults bundler_config_path: ".bundle/config",
           bundler_deployment:  true,
           bundler_gemfile:     nil,
           bundler_jobs:        "4",
           bundler_path:        "%{shared_path}/bundle",
           bundler_retry:       "3",
           bundler_version:     nil,
           bundler_without:     %w[development test]
end
```

The above plugin defines several default settings, defines tasks using a [TaskLibrary](TaskLibrary.md) named `Tomo::Plugin::Bundler::Tasks`, and defines helpers in a module named `Tomo::Plugin::Bundler::Helpers`.

Refer to the [Publishing a Plugin](../tutorials/publishing-a-plugin.md) tutorial for more information about packaging and distributing tomo plugins.

## Instance methods

### defaults(hash)

Specify default settings that will be applied when this plugin is loaded. Although not strictly necessary, it is best practice to list all required and optional settings that are used by the plugin, even if the default values are `nil`. This lets other developers know what setting names are expected when using the plugin.

Settings must use symbol keys and typically String values, although any Ruby type is possible. Strings can contain [interpolated values](../configuration.md#interpolation).

```ruby
module Tomo::Plugin::Bundler
  extend Tomo::PluginDSL

  defaults bundler_config_path: ".bundle/config",
           bundler_deployment:  true,
           bundler_gemfile:     nil,
           bundler_jobs:        "4",
           bundler_path:        "%{shared_path}/bundle",
           bundler_retry:       "3",
           bundler_version:     nil,
           bundler_without:     %w[development test]
end
```

### tasks(\*task_library_class)

Specify the tasks that will be defined by this plugin by supplying one or more [TaskLibrary](TaskLibrary.md) classes. The public instance methods of each class will be turned into tomo tasks.

```ruby
class Tomo::Plugin::Git::Tasks < Tomo::TaskLibrary
  def clone
    # ...
  end

  def create_release
    # ...
  end
end

class Tomo::Plugin::Git
  extend Tomo::PluginDSL

  tasks Tomo::Plugin::Git::Tasks
end
```

You can use `tasks self` to define a plugin and its tasks together as a single class:

```ruby
class Tomo::Plugin::Git < Tomo::TaskLibrary
  extend Tomo::PluginDSL
  tasks self

  def clone
    # ...
  end

  def create_release
    # ...
  end
end
```

### helpers(\*module)

Specify the helpers that will be defined by this plugin by supplying one or more plain Ruby modules. The modules will be mixed in at runtime to extend the [Remote](Remote.md) interface with additional methods.

```ruby
module Tomo::Plugin::Core::Helpers
  def ln_sf(target, link, **run_opts)
    # ...
  end

  def mkdir_p(*directories, **run_opts)
    # ...
  end
end

module Tomo::Plugin::Core
  extend Tomo::PluginDSL

  helpers Tomo::Plugin::Core::Helpers
end
```