README.md

Comonicon

gith averminaluk ayh juldas mausan urdan

Roger's magic book for command line interfaces.

Installation

Comonicon is a   Julia Language   package. To install Comonicon, please open Julia's interactive session (known as REPL) and press ] key in the REPL to use the package mode, then type the following command

For stable release

pkg> add Comonicon

For current main branch

pkg> add Comonicon#main

Usage

The simplest way to use it is via @main macro,

"""
ArgParse example implemented in Comonicon.

# Arguments

- `x`: an argument

# Options

- `--opt1 <arg>`: an option
- `-o, --opt2 <arg>`: another option

# Flags

- `-f, --flag`: a flag
"""
@main function main(x; opt1=1, opt2::Int=2, flag=false)
    println("Parsed args:")
    println("flag=>", flag)
    println("arg=>", x)
    println("opt1=>", opt1)
    println("opt2=>", opt2)
end

Now if you save this in a mail.jl file, you can run the following in your terminal

julia main.jl 123 --opt1 3 -o 2 -f

or use

julia main.jl --help

to print out a help message.

Although you can use Comonicon in your script, but the recommended way to build CLI with Comonicon is to use @main in a Julia project module, so the command line interface entry will get compiled by the Julia compiler.

Moreover, if you wish to create multiple commands. You can use @cast macro to annotate a function or module to create more complicated command line interfaces.

Features

Zero Duplication

The frontend @main and @cast will try to parse everything you typed and turn them into part of your command line. This includes your function or module docstrings, your argument and keyword argument names, types and default values.

We don't want to compromise on writing DRY code. If you have mentioned it in the documentation or somewhere in your script, you shouldn't write about it again in your code.

This is like Python docopt but with Fire and in Julia.

Zero Overhead

The backend code generator will generate Julia ASTs directly to parse your command line inputs all in one function main with one method main(::Vector{String}), which can be precompiled easily during module compilation.

Zero Dependency

You can get rid of Comonicon entirely after you generate the command line parsing script via write_cmd(filename, command_object). It means if you copy this file into your script, you will get a standalone Julia script (unless the script depends on something else). However, this is usually not necessary since Comonicon itself is quite fast to load, the main latency of a CLI application usually comes from other dependencies or the application itself.

License

MIT License