gith averminaluk ayh juldas mausan urdan
Roger's magic book for command line interfaces.
All the terminals are under my command.
Comonicon is a CLI (Command Line Interface) generator that features light-weight dependency (optional to have zero dependency), fast start-up time and easy to use. See the website for more info.
The simplest and most common way to use
Comonicon is to use
Missing docstring for
@main. Check Documenter's build log for details.
Let's use a simple example to show how, the following example creates a command using
using Comonicon @main function mycmd(arg; option="Sam", flag::Bool=false) @show arg @show option @show flag end
if you write this into a script file
myscript.jl and execute it using
julia myscript.jl -h
You will see the following in your terminal.
If you want to add some description to your command, you can just write it as a Julia function doc string, e.g
using Comonicon """ my first Comonicon CLI. """ @main function mycmd(arg; option="Sam", flag::Bool=false) @show arg @show option @show flag end
but you might also want to have more detailed help message for your CLI arguments and options, you can specify them via doc string:
""" my command line interface. # Arguments - `arg`: an argument # Options - `-o, --option`: an option that has short option. # Flags - `-f, --flag`: a flag that has short flag. """ @main function mycmd(arg; option="Sam", flag::Bool=false) @show arg @show option @show flag end
This will give a help message looks like below after execute this in
Now, you can directly use this script from command line in this way. But if you want to make it accessible in shell, should do the following:
- create a file without any extension called
- copy the script above
- add the following line on the top of your script
mycmd(this is called shebang):
#!<path to your julia executable>
mycmd script should look like the following
#!<path to your julia executable> using Comonicon """ my first Comonicon CLI. """ @main function mycmd(arg; option="Sam", flag::Bool=false) @show arg @show option @show flag end
- now we need to give this file permission via
chmod +x mycmd
- you can now execute this file directly via
./mycmd, if you want to be able to execute this cmd directly from anywhere in your terminal, you can move this file to
.julia/binfolder, then add
Now let me explain what
@main does here. In short it does the following things:
- parse your expression and create a command line object
- use this command line object to create an entry (See Conventions section to read about its convention)
- generate a Julia script to actually execute the command
- cache the generated Julia script into a file so it won't need to recompile your code again
For simple and small cases, a CLI script is sufficient.
However, for larger projects and more serious usage, one should create a Comonicon CLI project to use the full power of Comonicon. You will be able to gain the following features for free in a Comonicon project: