Comonicon.jl - Fast, Simple and Light weight CLI generator

I’m pleased to announce a new package https://github.com/Roger-luo/Comonicon.jl
for making CLI (Command Line Interface) in Julia. Comonicon is now on beta, I’ll be happy to see some feedbacks and potential collaborations from the community.

Comonicon features

Colorful and Neat Help Info

You can see an example created by Comonicon below at IonCLI

Comonicon will parse your markdown docstring and reformat it as your terminal help message.

Fast Start-Up

The long start-up time of Julia scripts has always been a painful part in creating CLI. Even creating a simple CLI that parses 2 arguments and 2 options via ArgParse will take about 4s on the author’s laptop.

But with the improvements from PackageCompiler, and recent Julia compiler updates, this is actually not true. By making use of these Comonicon provides you a way faster start-up time on creating CLIs with Julia without compromise on simplicity, color and many other features.

➜  Comonicon git:(master) ✗ hyperfine "julia example/comonicon_zero.jl 2"
Benchmark #1: julia example/comonicon_zero.jl 2
  Time (mean ± σ):     399.5 ms ±   8.5 ms    [User: 556.6 ms, System: 121.7 ms]
  Range (min … max):   389.7 ms … 409.0 ms    10 runs

➜  Comonicon git:(master) hyperfine "julia --project example/comonicon.jl 2"
Benchmark #1: julia --project example/comonicon.jl 2
  Time (mean ± σ):     781.2 ms ±   4.3 ms    [User: 926.5 ms, System: 132.4 ms]
  Range (min … max):   773.1 ms … 787.5 ms    10 runs

➜  Comonicon git:(master) ✗ hyperfine "julia example/fire.jl 2"
Benchmark #1: julia example/fire.jl 2
  Time (mean ± σ):     722.5 ms ±   4.4 ms    [User: 870.3 ms, System: 130.3 ms]
  Range (min … max):   717.9 ms … 729.6 ms    10 runs

➜  Comonicon git:(master) ✗ hyperfine "julia example/argmacros.jl 2"
Benchmark #1: julia example/argmacros.jl 2
  Time (mean ± σ):     668.8 ms ±   2.7 ms    [User: 814.7 ms, System: 136.2 ms]
  Range (min … max):   664.4 ms … 674.9 ms    10 runs

➜  Comonicon git:(master) hyperfine "julia --project example/argparse.jl 2"
Benchmark #1: julia --project example/argparse.jl 2
  Time (mean ± σ):      3.885 s ±  0.038 s    [User: 3.997 s, System: 0.159 s]
  Range (min … max):    3.839 s …  3.964 s    10 runs

Comonicon parses your command line into an internal intermediate representation and then generates a human-readable Julia script that has zero dependencies on Comonicon itself. You can choose to run using the compile cache created by Comonicon (comonicon.jl) or you can just get rid of Comonicon entirely (comonicon_zero.jl) to achieve the best scripting performance.

Moreover, Comonicon allows you to decrease the start-up time further using compile=min or building system image when you build a Comonicon CLI package.

Simple Interface

In most cases, all you need to know about Comonicon is only two macros @cast and @main, it uses a python-fire like interface plus a docopt flavor annotation to your commands - it will not only parse your expression, but also your markdown doc string.

a glance of how you use it (the code in example/comonicon.jl)

using Comonicon

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

Zero Dependency

Comonicon can generate a human readable Julia script that contains one function command_main to process your command line interfaces that has zero dependency on Comonicon itself. Thus after you generate the script, you can choose to remove Comonicon itself.

Planned Features

  • shell auto-completion
  • distributable system image (so users don’t need to compile it locally but download as an artifact)

Fore more details about this package please refer to the website: https://rogerluo.me/Comonicon.jl/ and the doc: https://rogerluo.me/Comonicon.jl/dev/

30 Likes

Excellent work. This look quite useful.

SHELL completion for ZSH is supported in the new v0.5 version, the system image CI is also supported using a new build system. I think all planned features are at least implemented now.

still need BASH support, if someone knows how to write BASH autocompletes. and I’m not sure about how to support command lines for Windows given it’s in powershell.

I also registered the IonCLI, which I will make an announcement about it later, but you can see how the system image works in the CI and get downloaded automatically via this project.

2 Likes