What this article is all about?
This article explains about creating the custom
mix tasks and documenting the created
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
Before diving into coding, we have to understand a few terms which are playing key role in the creation of a 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 .
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
run([binary]) :: any
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.
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.
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.
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.
So far, we have created three files
lib/mix/tasks/functions.ex which is our task file and two more files
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.
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
@moduledoc in task module . Keep your description simple and smart.
After adding the module attributes
@moduledoc, our file will look like following
You can see your task in the list here with
@shortdoc information saying #Returns functions in module
mix help my_tasks.functions
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.
Sharing is caring !! smile :-)
Happy long coding life !! :)