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 master

pkg> add Comonicon#master

Usage

The simplest way to use it is via @main macro, please refer to the demo in Zero Duplication.

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. You can check the example Ion here.

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.

"""
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

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