Recode.Task behaviour (Recode v0.8.0)

View Source

The behaviour for a recode task.

To create a recode task, you'll need to:

  1. Create a module.
  2. Call use Recode.Task in that module.
  3. Implement the callbacks run/2.
  4. Optionally, init/1 can also be implemented.

use Recode.Task

When you use Recode.Task, the Recode.Task module will set @behaviour Recode.Task.

Recode.Task will also set default implementations for the callbacks update_source/3 and new_issue/2.

Summary

Types

category()
config()
message()
task()

Callbacks

init(config)

A callback to check and manipulate config before any recode task runs.

new_issue(opts)

Creates a new issue with the given opts.

new_issue(message, opts)

Creates a new issue with the given message and opts.

run(source, opts)

Applies a task with the given source and opts.

update_source(t, opts, updates)

Update the given source with the given updates.

Functions

category(task)

Returns the category for the given task.

checker?(task)

Returns true if the given task provides a check for sources.

corrector?(task)

Returns true if the given task provides a correction functionality for sources.

shortdoc(task)

Returns the shortdoc for the given task.

Types

category()

@type category() :: atom()

config()

@type config() :: keyword()

message()

@type message() :: String.t()

task()

@type task() :: module()

Callbacks

init(config)

(optional) 
@callback init(config()) :: {:ok, config()} | {:error, message()}

A callback to check and manipulate config before any recode task runs.

The callback receives the config that is set in the recode-config.

In the implementation of this callback the config can be checked and defaults can be set.

When init returns an error tuple, the mix recode task raises an exception with the returned message.

new_issue(opts)

@callback new_issue(opts :: String.t()) :: Recode.Issue.t()

Creates a new issue with the given opts.

The default implementation of this callback creates an Recode.Issue struct with reporter: __MODULE__.

new_issue(message, opts)

@callback new_issue(message :: String.t(), opts :: Keyword.t()) :: Recode.Issue.t()

Creates a new issue with the given message and opts.

The default implementation of this callback creates an Recode.Issue struct with reporter: __MODULE__.

run(source, opts)

@callback run(source :: Rewrite.Source.t(), opts :: Keyword.t()) :: Rewrite.Source.t()

Applies a task with the given source and opts.

The opts containing:

  • The configuration for the task defined in the recode-config. When the init/1 is implemented then the opts returned by this callback are in the opts.

  • :dot_formatter - the %Rewrite.DotFormatter{} for the project.

  • :autocorrect - a boolean indicating if recode runs in auto-correction mode.

update_source(t, opts, updates)

@callback update_source(Rewrite.Source.t(), opts :: Keyword.t(), updates :: Keyword.t()) ::
  Rewrite.Source.t()

Update the given source with the given updates.

The default implementation of this callback applies any element from the updates keyword list to the source with the given opts. The keys :issue and :issues will be applied with Rewrite.Source.add_issue/2 and Rewrite.Source.add_issues/2 respectively. Any other key will be applied with Rewrite.Source.update/4, when opts contains autocorrect: true.

In updates the value for :quoted can be a Sourceror.Zipper. In this case the source is updated with the return value of Sourceror.Zipper.root/1.

The opts are extended by by: __MODULE__.

Functions

category(task)

@spec category(task()) :: category()

Returns the category for the given task.

checker?(task)

@spec checker?(task()) :: boolean()

Returns true if the given task provides a check for sources.

corrector?(task)

@spec corrector?(task()) :: boolean()

Returns true if the given task provides a correction functionality for sources.

shortdoc(task)

@spec shortdoc(task()) :: String.t() | nil

Returns the shortdoc for the given task.

Returns nil if @shortdoc is not available for the task.