9 ms·
Docli – A declarative language for command-line interfaces in Go
- kvakvs 8y agoPlease put the language it is intended for somewhere as close to the page top as possible. The world isn't all Go.
- bfrydl 8y agoIt's a little strange that I had to open the tutorial to find out what language this is for.
- skocznymroczny 8y agoI was going to guess Rust, but turns out it's Go.
- 99052882514569 8y agoWouldn't `gocli` be a better name then?
- Gipetto 8y agoThe solution here is clearly to write a new language named "do".
- bitcoinofficial 8y agoDoes having a programming language name in a program name make the program better? I don't get it, sorry.
- lucideer 8y agoIt certainly makes it a lot easier to understand what it's for...
- fwip 8y agoI think it's a portmanteau of "doc" and "cli" - because it's a CLI options parser that is generated from documentation.
- leshow 8y agoPersonally, I like Rust's a bit better: https://github.com/TeXitoi/structopt https://github.com/TeXitoi/structopt edit: because it's type safe!
- celicoo 8y agoHey, I'm really sorry about that! I'm still working on the details, but thank you for the feedback.
- maxaf 8y agoPrior art: http://docopt.org/ http://docopt.org/
- sametmax 8y agoI used to love doctopt, but with usage your realise: - i18n is made hard - syntax errors are not caught by tooling - you don't get automatic args checking or env var override Eventually, a well made programmative API is better.
- thechao 8y agoI used docopt in production for years, before switching off of it. My main issues were that the author of docopt doesn't know anything about language grammars & parsing. That's fine — we all start somewhere. But he insists that defining a grammar (and having a rational parser) aren't useful or even possible! If, instead, there were a normative spec (and this requires only the slightest change to edge-cases that aren't tested by his test-suite, anyways), then it'd be possible to really roll out a much more robust docopt than what currently occurs. With a grammar you'd be able to roll out AST=>AST transforms, and update the parsing strategy of the command lines, i.e., portability between CLI flavors between new/old style POSIX, Windows, etc. You'd have the ability to do i18n, you could catch errors both in the docopt spec of your parser, and in the parsing of the command line options, etc.
- cstejerean 8y agoSo did you end up making something better? I’ve been using docopt for years but I’ll gladly consider switching to a better alternative.
- celicoo 8y ago
- hwj 8y agoThis is a Go library that parses a usage string into an AST.
- AbraKdabra 8y agoThanks, it's very disappointing when a comment describes the product better than the official webpage.
- AnanasAttack 8y agoNot that unusual really. Whenever you hear about new stuff, chances are it's better to look it up on Wikipedia first.
- umvi 8y ago"Docli" makes it sound like a generic documentation generator for CLIs. IMO name should make it clear it is Go-only. Something like "GoastArgs: a Go library that parses a usage string/CLI args into an AST"
- FreeFull 8y agoI am not a Go user so I can't speak about Go specifically, but I feel like including the name of the language in the library name is in general an anti-pattern, since generally when you look for a library to do something in language A, you aren't going to get results using language B anyway.
- celicoo 8y agoThanks for the feedback umvi. I will be working on making it clear that Docli is a Go library.
- deleted 8y ago[deleted]
- matt-attack 8y agoAnyone have a recommendation for Node.js? I've been extremely frustrated with commander [1]. [1] https://www.npmjs.com/package/commander https://www.npmjs.com/package/commander
- Kamshak 8y agoTry oclif https://github.com/oclif/oclif https://github.com/oclif/oclif
- curry-castaway 8y agoI can second this recommendation – Oclif[0] is an absolute pleasure to use. I'd even encourage developers who aren't at a "full-stack Node.js shop" to give it a shot. I'm particularly impressed with the bash and zsh autocomplete support. I was delighted when I finished setting it up and everything worked perfectly on the first try. [0]: https://oclif.io/ https://oclif.io/
- jessaustin 8y agoHN had something on this a few months back, "12 Factor CLI Apps": https://news.ycombinator.com/item?id=18172689 https://news.ycombinator.com/item?id=18172689
- timdorr 8y agoLots of folks seem to like Yargs: https://github.com/yargs/yargs https://github.com/yargs/yargs
- tln 8y agoThere are lots of different approaches to defining the arguments and options. * You can build up a structure programmatically to define the arguments, as in commander, and then the usage and shape of the parsed result are implied. * You can provide the usage, as in docopt, and then the structure to define the args and shape of the parsed result are implied. * Or you can take the approach I did in fncli, which is to provide the shape of parsed result, as a function signature, and let the structure to define the args and usage be implied. https://www.npmjs.com/package/fncli https://www.npmjs.com/package/fncli This is possible because Javascript spec includes the function arguments as a string that can be parsed at run time. Because you're using ES6 syntax, you don't have to learn a new syntax (unlike docli or docopt). And although there are limitations, I've found this approach to handle modest CLI needs with an absolute minimum of fuss.
- thanatos_dem 8y agoSeems like Cobra is pretty well established in this space - https://github.com/spf13/cobra https://github.com/spf13/cobra Tho admittedly it works in reverse; it generates the doc/help info rather than parsing it into an AST. It addresses the “boilerplate” issue with code gen as well, but it has a CLI to generate code that’s pretty powerful. For instance, how does docli handle subcommands? How about global vs command specific flags? For any case beyond the basic single command CLI, it seems like there would need to be all sorts of magic and non-obvious formatting requirements on the doc string.
- celicoo 8y agoHey thanatos_dem Right now Docli can't handle those scenarios, but it will on the next big release - which it might take a while because it's not trivial to add those features and keep the API simple.
- celicoo 8y agoHey! I've opened an issue to discuss about the subcommands feature: https://github.com/celicoo/docli/issues/10 https://github.com/celicoo/docli/issues/10 I would love to know your opinion about it.
- mongol 8y agoFor my purpose, go-flags was a great fit. https://github.com/jessevdk/go-flags https://github.com/jessevdk/go-flags
- pushpop 8y agoTheir example here confuse me: https://github.com/celicoo/docli/blob/master/examples/terraform/main.go https://github.com/celicoo/docli/blob/master/examples/terraf... `workspace` isn't a boolean flag. So it isn't clear from that example how - or even if - docli can work with more complex conditional arguments. Is someone with any familiarity with this project able to advise how you'd handle that in docli?
- granra 8y agoAll the variables in in the `Commands` and `AllOtherCommands` are bools. In Go you can do `a, b, c bool` and they'll all be of type bool.
- pushpop 8y agoYeah I got that. My point is that ‘workspace’ isn’t a Boolean flag in terraform. It requires additional flags to function, eg terraform workspace new granra ‘workspace’ is effectively the CLI flags equivalent of a submenu.
- granra 8y agoOh I see. It looks like docli sets the flag as true if it was passed as a parameter to the program. So you do: var terraform Terraform args.Bind(&terraform) if terraform.Workspace { // do workspace stuff } I think. EDIT: I don't know how hackernews formatting works :/
- pushpop 8y agoThat seems really messy to be honest because you can’t then ensure flags are nested correctly. I guess for simple purposes this is fine though.
- deforciant 8y agoFor servers I prefer using: https://github.com/alecthomas/kingpin https://github.com/alecthomas/kingpin, allows you to really nicely expand based on main arguments with flags. Also, setting defaults is a joy. For CLIs - https://github.com/spf13/cobra https://github.com/spf13/cobra. However, will definitely try out Docli whenever I start building something new :)
- calebwin 8y agoI really like that graphic for the website and README! Did you make it?
- celicoo 8y agoThanks! It was a friend of mine. You can see more of his work at https://www.instagram.com/sutocreation https://www.instagram.com/sutocreation
- ilovecaching 8y agoI still feel that cobra and docopt are ungoish despite the author of cobra getting hired on. There's simply too much magic to both of them. I would much rather they improve flags, which is what I use. It really doesn't take that much with flags to add subcommands, etc, but it could be made better.
- rajangdavis 8y agoCan you elaborate on what makes cobra ungoish? I had built a CLI using it without prior knowledge of Go (but with a background in scripting languages and a some C#) and it seemed pretty straightforward. The only issue that I can tell was that you can possibly create errors that the compiler can miss, but it's been pretty solid otherwise.
- ilovecaching 8y agoCobra is very much a kitchen sink approach with a lot of gen. I'd rather have less dependency and write just using the stdlib without the kitchen sink, which is more goish.
- rajangdavis 8y agoThat makes a lot of sense. I guess the parallel for me would be using Rack as opposed to Rails for Ruby. Thanks for responding!
- weberc2 8y agoI use github.com/urfave/cli, but I almost always end up wrapping it with my own declarative framework. Gradually said framework is becoming more general purpose and suitable for general use, at which point I'll probably open source it and hopefully it will make someone's life better.
- henvic 8y agocobra is working pretty well for my needs: https://asciinema.org/a/192043 https://asciinema.org/a/192043 Nice to see a declarative approach, though. It certainly looks more natural. I'm certainly going to give it a try.
- jlesk 8y agoI really like the line art logo on the site, but it's 2.4 MB (avatar.png). Might want to size it down and run it through TinyPNG. :)
- celicoo 8y agoOh, I didn't notice how big it is! I will fix that as soon as possible. Thanks for the feedback.
- CamouflagedKiwi 8y agoNot really a fan of this approach. I don't like the duality between the help text and the struct it gets bound to - much prefer the approach of generating the help text from a struct. https://github.com/jessevdk/go-flags https://github.com/jessevdk/go-flags is my favourite option; it's lightweight but amazingly featureful, and I much prefer the declarative approach to a programmatic one like the standard library flags package