Mix.Task поведение

Предоставляет удобства для создания, загрузки и управления задачами Mix.

Задача Mix может быть определена с помощью Mix.Task в модуле, имя которого начинается с Mix.Tasks. и который определяет функцию run/1. Обычно, модули задач находятся внутри каталога lib/mix/tasks/, а их имена файлов используют точки в качестве разделителей вместо подчёркиваний (например, deps.clean.ex) — хотя в конечном счёте имя файла не имеет значения.

Например:

# lib/mix/tasks/echo.ex
defmodule Mix.Tasks.Echo do
  @moduledoc "Printed when the user requests `mix help echo`"
  @shortdoc "Echoes arguments"

  use Mix.Task

  @impl Mix.Task
  def run(args) do
    Mix.shell().info(Enum.join(args, " "))
  end
end

Имя команды будет соответствовать части имени модуля после Mix.Tasks.. Например, имя модуля Mix.Tasks.Deps.Clean соответствует имени задачи deps.clean.

Функция run/1 получит список всех аргументов командной строки, переданных пользователем через терминал.

Например, если args в вышеупомянутой задаче echo была просмотрена, вы могли бы увидеть что-то вроде этого:

mix echo 'A and B' C --test
["A and B", "C", "--test"]

Определите атрибут @shortdoc, если хотите сделать задачу публично видимой на mix help. Опустите этот атрибут, если вы не хотите, чтобы ваша задача отображалась через mix help.

Если у задачи есть зависимости, они могут быть перечислены с помощью атрибута @requirements. Например:

@requirements ["app.config"]

Задачи обычно зависят от задачи "app.config", когда им нужно получить доступ к коду текущего проекта со всеми приложениями, уже настроенными, или от задачи «app.start», когда также требуется, чтобы эти приложения были уже запущены:

@requirements ["app.start"]

Вы также можете запускать задачи напрямую с помощью run/2.

Атрибуты

В задачах Mix доступны несколько атрибутов для их настройки в Mix:

@shortdoc - делает задачу публичной с кратким описанием, которое отображается на mix help
@recursive - запускает задачу рекурсивно в проектах umbrella
@requirements - список необходимых задач, которые должны быть выполнены перед задачей
@preferred_cli_env - рекомендует среду, в которой следует запускать задачу. Используется только в том случае, если MIX_ENV ещё не установлена. Обратите внимание, что @preferred_cli_env не загружается из зависимостей, так как нам нужно знать среду для загрузки самих зависимостей. В таких случаях вы можете установить конфигурацию preferred_cli_env в def project в вашем mix.exs

Документация

Пользователи могут прочитать документацию для публичных задач Mix, выполнив mix help my_task. Отображаемая документация — это @moduledoc модуля задачи.

Краткое описание

Функции

alias?(task): Проверяет, является ли данное имя task псевдонимом.
all_modules(): Возвращает все загруженные модули задач.
clear(): Очищает все вызванные задачи, позволяя их повторный вызов.
get(task): Принимает имя задачи и возвращает соответствующий модуль задачи, если он существует.
get!(task): Принимает имя задачи и получает соответствующий модуль задачи.
load_all(): Загружает все задачи во всех путях кода.
load_tasks(dirs): Загружает все задачи в заданных paths.
moduledoc(module): Получает moduledoc для заданной задачи module.
preferred_cli_env(task): Получает предпочтительную среду командной строки для задачи.
recursing?(): Указывает, выполняется ли текущая задача рекурсивно.
recursive(module): Проверяет, должна ли задача выполняться рекурсивно для всех подприложений в проектах umbrella.
reenable(task): Повторно включает заданную задачу, чтобы она могла быть выполнена снова по стеку.
requirements(module): Получает список требований для данной задачи.
rerun(task, args \\ []): Повторно запускает task с указанными аргументами.
run(task, args \\ []): Условно выполняет задачу (или псевдоним) с указанными args.
shortdoc(module): Получает краткое описание для данной задачи module.
task?(module): Возвращает true , если данный модуль является задачей.
task_name(module): Возвращает имя задачи для данного module.

Обработчики событий

run(command_line_args): Задача должна реализовывать run, который получает список аргументов командной строки.

Типы

task_module()

Спецификации

task_module() :: atom()

task_name()

Спецификации

task_name() :: String.t() | atom()

Функции

alias?(task)

Характеристики

alias?(task_name()) :: boolean()

Проверяет, является ли заданное имя task псевдонимом.

Возвращает false, если заданное имя не является псевдонимом или если это не задача.

Для получения дополнительной информации о псевдонимах задач, ознакомьтесь с разделом "Псевдонимы" в документации по Mix.

all_modules()

Характеристики

all_modules() :: [task_module()]

Возвращает все загруженные модули задач.

Модули, которые еще не загружены, не будут отображаться. Проверьте load_all/0, если вы хотите предварительно загрузить все задачи.

clear()

Характеристики

clear() :: :ok

Очищает все выполненные задачи, позволяя их повторное выполнение.

Данная операция не рекурсивна.

get(task)

Характеристики

get(task_name()) :: task_module() | nil

Принимает имя задачи и возвращает соответствующий модуль задачи, если он существует.

Возвращает nil если модуль не найден, если это псевдоним или если это не допустимый Mix.Task.

get!(task)

Характеристики

get!(task_name()) :: task_module()

Принимает имя задачи и получает соответствующий модуль задачи.

Исключения

Mix.NoTaskError - генерируется, если задача не найдена
Mix.InvalidTaskError - генерируется, если задача не является допустимым Mix.Task

load_all()

Характеристики

load_all() :: [task_module()]

Загружает все задачи во всех путях кода.

load_tasks(dirs)

Характеристики

load_tasks([List.Chars.t()]) :: [task_module()]

Загружает все задачи в указанных paths.

moduledoc(module)

Характеристики

moduledoc(task_module()) :: String.t() | nil | false

Получает moduledoc для заданной задачи module.

Возвращает moduledoc или nil.

preferred_cli_env(task)

Характеристики

preferred_cli_env(task_name()) :: atom() | nil

Получает предпочтительную среду командной строки для задачи.

Возвращает среду (например, :test, или :prod), или nil.

recursing?()

Характеристики

recursing?() :: boolean()

Указывает, является ли текущая задача рекурсивной.

Возвращает true, если задача помечена как рекурсивная и выполняется внутри проекта-зонтика.

recursive(module)

Характеристики

recursive(task_module()) :: boolean()

Проверяет, следует ли запускать задачу рекурсивно для всех подприложений в проектах-зонтиках.

Возвращает true или false.

reenable(task)

Характеристики

reenable(task_name()) :: :ok

Позволяет снова выполнить заданную задачу.

И псевдоним, и обычная стопка задач снова активируются, когда эта функция вызывается.

Если проект-зонтик активирует задачу, она активируется для всех дочерних проектов.

requirements(module)

Характеристики

requirements(task_module()) :: []

Получает список требований для заданной задачи.

Возвращает список строк, где строка представляет задачу, за которой необязательно следуют ее аргументы.

rerun(task, args \\ [])

Характеристики

rerun(task_name(), [any()]) :: any()

Повторно выполняет task с заданными аргументами.

Эта функция повторно выполняет заданную задачу; для этого она сначала снова включает задачу, а затем выполняет ее как обычно.

run(task, args \\ [])

Характеристики

run(task_name(), [any()]) :: any()

Условно выполняет задачу (или псевдоним) с заданными args.

Если существует задача, соответствующая заданному имени задачи, и она еще не вызвана, эта функция выполнит задачу с заданными args и вернёт результат.

Если для заданного имени задачи определён псевдоним, будет вызван псевдоним вместо исходной задачи.

Если задача или псевдоним уже вызваны, последующие вызовы run/2 прервутся без выполнения и вернут :noop.

Обратите внимание: по умолчанию задачи будут выполняться только один раз, даже при многократном вызове! Если вам нужно выполнить задачу несколько раз, необходимо активировать её повторно через reenable/1 или вызвать её с помощью rerun/2.

run/2 генерирует исключение, если псевдоним или задача не найдены или если задача недействительна. Более подробная информация в get!/1.

shortdoc(module)

Характеристики

shortdoc(task_module()) :: String.t() | nil

Получает краткое описание для заданной задачи module.

Возвращает краткое описание или nil.

task?(module)

Характеристики

task?(task_module()) :: boolean()

Возвращает true если заданный модуль является задачей.

task_name(module)

Характеристики

task_name(task_module()) :: task_name()

Возвращает имя задачи для заданного module.

Примеры

iex> Mix.Task.task_name(Mix.Tasks.Test)
"test"

Обработчики событий

run(command_line_args)

Характеристики

run(command_line_args :: [binary()]) :: any()

Задача должна реализовать run, который получает список аргументов командной строки.