Mix.Task behaviour
A simple module that provides conveniences for creating, loading and manipulating tasks.
A Mix task can be defined by simply using Mix.Task
in a module starting with Mix.Tasks.
and defining the run/1
function:
defmodule Mix.Tasks.Hello do use Mix.Task def run(_args) do Mix.shell.info "hello" end end
The run/1
function will receive all arguments passed to the command line.
Attributes
There are a few attributes available in Mix tasks to configure them in Mix:
-
@shortdoc
- makes the task public with a short description that appears onmix help
-
@recursive
- run the task recursively in umbrella projects -
@preferred_cli_env
- recommends environment to run task. It is used in absence of mix project recommendation, or explicit MIX_ENV.
Documentation
Users can read the documentation for public Mix tasks by doing mix help my_task
. The documentation that will be shown is the @moduledoc
of the task’s module.
Summary
Types
Functions
- alias?(task)
-
Checks if an alias called
task
exists - all_modules()
-
Returns all loaded task modules
- clear()
-
Clears all invoked tasks, allowing them to be reinvoked
- get(task)
-
Receives a task name and returns the task module if found
- get!(task)
-
Receives a task name and retrieves the task module
- load_all()
-
Loads all tasks in all code paths
- load_tasks(dirs)
-
Loads all tasks in the given
paths
- moduledoc(module)
-
Gets the moduledoc for the given task
module
- preferred_cli_env(task)
-
Gets preferred cli environment for the task
- recursive(module)
-
Checks if the task should be run recursively for all sub-apps in umbrella projects
- reenable(task)
-
Reenables a given task so it can be executed again down the stack
- rerun(task, args \\ [])
-
Reruns
task
with the given arguments - run(task, args \\ [])
-
Runs a
task
with the givenargs
- shortdoc(module)
-
Gets the shortdoc for the given task
module
- task?(module)
-
Returns
true
if given module is a task - task_name(module)
-
Returns the task name for the given
module
Callbacks
- run(list)
-
A task needs to implement
run
which receives a list of command line args
Types
task_module()
task_module() :: atom
task_name()
task_name() :: String.t | atom
Functions
alias?(task)
alias?(task_name) :: boolean
Checks if an alias called task
exists.
For more information about task aliasing, take a look at the “Aliasing” section in the docs for Mix
.
all_modules()
all_modules() :: [task_module]
Returns all loaded task modules.
Modules that are not yet loaded won’t show up. Check load_all/0
if you want to preload all tasks.
clear()
clear() :: :ok
Clears all invoked tasks, allowing them to be reinvoked.
This operation is not recursive.
get(task)
get(task_name) :: task_module | nil
Receives a task name and returns the task module if found.
Otherwise returns nil
in case the module exists but it isn’t a task or cannot be found.
get!(task)
get!(task_name) :: task_module | no_return
Receives a task name and retrieves the task module.
Exceptions
-
Mix.NoTaskError
- raised if the task could not be found -
Mix.InvalidTaskError
- raised if the task is not a validMix.Task
load_all()
load_all() :: [task_module]
Loads all tasks in all code paths.
load_tasks(dirs)
load_tasks([List.Chars.t]) :: [task_module]
Loads all tasks in the given paths
.
moduledoc(module)
moduledoc(task_module) :: String.t | nil
Gets the moduledoc for the given task module
.
Returns the moduledoc or nil
.
preferred_cli_env(task)
preferred_cli_env(task_name) :: atom | nil
Gets preferred cli environment for the task.
Returns environment (for example, :test
, or :prod
), or nil
.
recursive(module)
recursive(task_module) :: boolean
Checks if the task should be run recursively for all sub-apps in umbrella projects.
Returns true
or false
.
reenable(task)
reenable(task_name) :: :ok
Reenables a given task so it can be executed again down the stack.
Both alias and the regular stack are reenabled when this function is called.
If an umbrella project reenables a task, it is reenabled for all children projects.
rerun(task, args \\ [])
rerun(task_name, [any]) :: any
Reruns task
with the given arguments.
This function reruns the given task; to do that, it first re-enables the task and then regularly runs it.
run(task, args \\ [])
run(task_name, [any]) :: any
Runs a task
with the given args
.
If the task was not yet invoked, it runs the task and returns the result.
If there is an alias with the same name, the alias will be invoked instead of a task.
If the task or alias were already invoked, it does not run them again and simply aborts with :noop
.
It may raise an exception if an alias or a task can’t be found or the task is invalid. Check get!/1
for more information.
shortdoc(module)
shortdoc(task_module) :: String.t | nil
Gets the shortdoc for the given task module
.
Returns the shortdoc or nil
.
task?(module)
task?(task_module) :: boolean
Returns true
if given module is a task.
task_name(module)
task_name(task_module) :: task_name
Returns the task name for the given module
.
Callbacks
run(list)
run([binary]) :: any
A task needs to implement run
which receives a list of command line args.
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/mix/1.3.4/Mix.Task.html