Mix.Task
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 a list of 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
- runs the task recursively in umbrella projects -
@preferred_cli_env
- recommends environment to run task. It is used in absence of a Mix project recommendation, or explicitMIX_ENV
Documentation
Users can read the documentation for public Mix tasks by running 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 child 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 runs it as normal.
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 the original 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–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/mix/1.4.5/Mix.Task.html