Comparison with DocOpt.jl

[juliohm]

Could you explain the main differences so that I can more easily choose between the available approaches in future projects?

https://github.com/docopt/DocOpt.jl

Perhaps adding a section to the README would be helpful.

[johnnychen94]

Comonicon.jl eagerly generates and saves Julia AST for the main function so there's almost no loading time overhead while still provides you all the easy-usability of DocOpt.jl or ArgParse.jl. You'll simply be annoyed if calling a CLI tool spends more than 2s in loading ArgParse and parsing the inputs, especially when the main functionality of your CLI took less than a second.

[Roger-luo]

Thanks for the question, to be short, the syntax of DocOpt is not designed for Julia but for Python, it is not Julian but Pythonic,
thus it can create a lot problems when you use it in Julia, such as compilation latency issues and is not as composable as a native
design for Julia like Comonicon.

there is also a discourse announcement: https://discourse.julialang.org/t/comonicon-jl-fast-simple-and-light-weight-cli-generator/43744

On the other hand, DocOpt is much more mature and will not change much anymore since it's been there for a while, but Comonicon
is still evolving and more things will come into this package since it is still pre-1.0.

but let me clarify a bit more and maybe even compare with some more packages

Syntax

In general, I believe the design of Comonicon is much less invasive, which is like google/fire, you won't need to learn much special syntax or API, only a @main and @cast is sufficient
the rest are just markdown documentation that is close to normal doc string syntax. Instead of stealing the design from Python like ArgParse/Fire/DocOpt, I believe we aim to design the
Julian way after learning other good designs from not only Python but also rust.

For single command CLI

there is no big difference for the interface if one only has a single function to use as CLI and only writes a script (say command_main), even this is not very Julian.

For multi command CLI

However, you will find things become inconvenient for DocOpt/ArgParse when there are multiple commands (nested commands), this is because the parsed output comes from
one centralized API such as docopt, you will need to handle the dispatch of sub-commands manually, but this should be handled automatically because you have already written that
function in Julia. Comonicon will treat your Julia modules as node commands to automatically do the dispatch for you - this is the spirit of google/fire, turn almost anything make sense to CLI.

However, google/fire has the disadvantage when you write the documentation, thus, Python community created docopt.org aims to remove the duplication between docstring of a CLI
and its implementation, but then it ignores the implementation duplication (the manual dispatch and the fact that there always an implementation as a function or object in the host language)

However, all existing Julia solutions seems to only copy the design from Python instead of taking this seriously before Comonicon.

Shell Completion

we are the only implementation supports shell completions (tho only ZSH is supported at the moment)

Performance

The compile latency problem is quite well known, Comonicon aims to reduce this latency by making things as easy as possible for Julia to compile, so that Julia compiler won't panic. I believe
Comonicon is the only implementation that cares both the syntax and latency, the other is ArgMacro it's faster than Comonicon (since we support much
more features), but the syntax is way more complicated.

@johnnychen94 however, from v0.11.x I'm thinking on a design choice not supporting compile cache for scripts, since most of the time scripts in Julia is slow anyway, this makes the start up time much slower for scripts at the moment. maintaining Comonicon's own
compile cache is actually quite evil since Julia compiler itself knows how to cache compile results as long as you write them in a project. so for whoever cares about latency, they should write their
CLI inside a project module.

Beyond CLIs

Comonicon is not just a CLI generator, it is actually a complete compiler that compiles an embeded DSL in Julia to other targets, this is why it also supports shell auto-completion and even in principle support
GUIs: https://github.com/comonicon/ComoniconGUI.jl

---

So in summary, I don't see any reason why would one wants to use DocOpt/ArgParse at all except Comonicon is less mature.

[juliohm]

Thank you all for the clarifications. It would be nice to see this information in the README 💯

[Roger-luo]

actually I think instead of generating compile cache, using deamon mode for scripts will be a better approach, but I prob won't have time to do it recently.

[xgdgsc]

I' m quite confused about it being like fire. Is there an example in doc that is similar to the function of https://github.com/orangeSi/Jfire.jl ? The example at quickstart:

@cast module NodeCommand

using Comonicon
@cast foo(x) = nothing

end

is confusing

[Roger-luo]

I' m quite confused about it being like fire. Is there an example in doc that is similar to the function of https://github.com/orangeSi/Jfire.jl ?

As pointed out by its own description the spirit of google/fire is not about its interface but is about converting a python object to CLI interface:

Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.

No there is no similar interface the point of Comonicon is to not use any non-Julian interface for Julian CLI, I think the implementation of Jfire will suffer latency problem if anyone has interested to revive that old code. What is similar here is both Fire and Comonicon transform an object to CLI, and in Julia the object is limited to modules and functions.

The example at quickstart:

Where do you find that example? The quick start example is here: https://comonicon.org/stable/

there is also an example in README

https://github.com/comonicon/Comonicon.jl#zero-duplication

[xgdgsc]

Thanks, I found that at https://comonicon.org/stable/ , you can search for the first line @cast module NodeCommand. For me I' d be happy with the latency for many small non-latency sensitive projects in exchange for the developer time.

[Roger-luo]

Thanks, I found that at https://comonicon.org/stable/ , you can search for the first line @cast module NodeCommand

I see. Yeah that is not well written indeed, I suggest you read the CLI project section instead https://comonicon.org/dev/project/ and try run it. There are more examples in the examples folder.

For me I' d be happy with the latency for many small non-latency sensitive projects in exchange for the developer time.

I'm not sure why Comonicon has more developer time than JFire, the only thing is to put @cast in front of the object you would like to appear in CLI?

I'm not sure what's your use case, but @cast and @main are already quite simple? I am happy to see a counter-example that shows these two interfaces are over-complicated - but if you don't have a concrete use case but just don't like the flavor of the Comonicon interface, then you can try the Jfire package for sure.

[juliohm]

Closing as discussion. There is no issue to be solved here.