Mix Task Creation in Elixir Project

Tasks add extra cheese to your code.

What this article is all about?

This article explains about creating the custom mix tasks and documenting the created task.

Here, we fly in the space of Elixir to create mix tasks in a mix project, including with docs and short docs. Soon, you will come to know what these docs are for.

What is our Task?

Our Task is to list out the functions in the module passing as parameter to the task.

So, when you run the command mix my_tasks.functions ModuleName , it has to list out all the functions defined in the module ModuleName.

Before diving into coding, we have to understand a few terms which are playing key role in the creation of a task.

Mix.Task

This is the simple module responsible for creating and controlling the mix tasks.

To behave our module like a task, we have to follow some naming conventions.

Our module name should start with Mix.Tasks for an example, if our task name is functions then module name is Mix.Tasks.Functions and we have to use the task behavior module use Mix.Task a first line of code in our module .

run/1

This acts as a callback function to our task. All the task logic resides inside this function. This function takes a list of binary [binary] values and returns any

run([binary]) :: any

@shortdoc

This module attribute makes the task public with a short description that appears on mix help . It means when you execute a command mix help you can see all tasks available in the scope along with single line description about the task.

In addition we have two more attributes. @recursive used in umbrella projects to keep the task running continuously and @referred_cli_env which recommends environment to run task. We don’t need them now.

@moduledoc

This module attribute is used to describe the task functionality. So, when some one wants help about your task, The binary of this attribute is shown as a response to the request mix help my_tasks.functions .

Let’s Create a Task

Now, it is time to create our task which will list out all the functions defined inside the module passing as parameter.

Let’s do this.

Create a new project

mix new my_tasks

Create Task directory

After creating the project, go to your lib directory and create one nested directory as mix/tasks . This is where all our tasks reside.

$ cd path/to/your/project
$ cd lib
$ mkdir -p mix/tasks

Task Testing Module Files

Now, we will create two files in lib directory one hello.ex and other one is hi.ex with some random functions. We are going to list out those module functions using our task as proof of working.

hello.ex

hello.ex

hi.ex

hi.ex

These files do nothing with the task literally. They are just for showing the task working demo.

Creating a Task file

Now, create a file functions.ex in the directory of tasks /lib/mix/tasks and add the following content.

Task file with out shortdoc

Every module defined in the project has its own __info__ function; with that you can get all the information about the module. So, I am using this function by passing an atom :functions to get the list of functions.

Clarification

So far, we have created three files lib/mix/tasks/functions.ex which is our task file and two more files lib/hello.ex and lib/hi.ex testing module files.

Compiling the Project

So far, we have created a task but it is not available until you compile your project.

Run the following command in your project root directory.

mix compile

After successful compilation you can run your task as

$ mix my_tasks.functions Hello
[hello1: 0, hello2: 0, hello3: 0]
$mix my_tasks.functions Hi
[hi1: 0, hi2: 0, hi3: 0]

If you see the same above outputs in your terminal, it means you are good to go.

As a final touch, let’s add docs to our task.

Till now, we have just created a task. We have not provided any docs for the task. So, you cannot find your task shown in the list when you try to execute mix help or mix help my_tasks.functions to available your task in the list, you are suppose to add some module attributes to your task file.

Let’s do that now .

You have to add module attributes @shortdoc and @moduledoc in task module . Keep your description simple and smart.

After adding the module attributes @shortdoc and @moduledoc, our file will look like following

Task with @shortdoc and @moduledoc
mix help
shortdoc information of task

You can see your task in the list here with @shortdoc information saying #Returns functions in module

mix help my_tasks.functions
moduledoc information of task

Well, you have successfully created your Elixir Project Tasks. Do some funny things playing with tasks. So. you will become familiar with creation of tasks.

Your working mix task is ready to deliver :)

If you find this helpful, please recommend it so, others can benefit.

Share if you care google image search

Sharing is caring !! smile :-)

Happy long coding life !! :)