Comments (14)
The problem with the first approach is you can end up with collisions, although I suppose an error could be generated in that case.
@alexcrichton What do you think? I don't have any terribly strong opinions. The current approach was just something That Worked. I'm not attached to it.
from docopt.rs.
I'd avoid the first for the same reasons, and foo.options.bar
does seem a little better than foo.flag_bar
(foo.flags.bar
?). I also don't have too too strong a preference!
from docopt.rs.
I think that a single namespace is still a viable option, because when was the last time anyone had a --file
option and a <file>
argument?!
from docopt.rs.
Right, wouldn't collisions represent symbol reuse within a single pattern? That seems inadvisable to begin with. Since the first, singly-namespaced approach better matches what other docopt implementations provide, I'd vote for it over struct nesting.
from docopt.rs.
Since the first, singly-namespaced approach better matches what other docopt implementations provide
The reference docopt implementation is namespaced.
If it's truly inadvisable to have a flag and, say, a positional argument with the same name, then perhaps Docopt itself should rule it out. But as of now, it allows it, so I don't really see a reason to arbitrarily disallow it.
from docopt.rs.
If it's truly inadvisable to have a flag and, say, a positional argument with the same name, then perhaps Docopt itself should rule it out. But as of now, it allows it, so I don't really see a reason to arbitrarily disallow it.
I would totally disallow it. It just happens that some major languages have fist-class support for json-like dictionaries, so the problem never came up there.
For languages where it makes more sense to generate a custom data type (like struct in Rust and C), I think it's totally fine to raise error in case of a collision (like --file
vs <file>
).
It's just a matter if we decide on a single namespace, or on multiple nested namespaces (options, arguments, commands).
from docopt.rs.
Correct me if I'm wrong, but the ref impl generates a dictionary where the only nested data structure is the <args>
list. Options and positional arguments are inserted into the dictionary as top-level key value pairs.
Collisions could still occur across separate patterns in the event that e.g. a positional argument's name is the same as a command. I'm of the opinion that avoiding such cases of conflated terms would also remove a potential source of confusion for users.
from docopt.rs.
@evnm What you say is true, but that doesn't mean the dictionary isn't namespaced. For example, all flags start with -
or --
. Likewise, currently, struct fields that are flags start with flag_
.
Arguments are always keys of the form <arg>
and ARG
. A command, is, by definition, everything else. Therefore there is no overlap.
In the reference Docopt, you can have a flag, command and positional argument all have the same name:
Usage: program -a <a> a
And it works fine:
[andrew@Liger docopt] python examples/quick_example.py -a hi a
{'-a': True,
'<a>': 'hi',
'a': True}
In other words: namespaced.
(My understanding is that @halst does not like this? Even in the reference implementation? I don't see what native JSON dictionaries have to do with whether you have proper namespaces or not. I had assumed this namespacing was an explicit design decision, so I copied it.)
from docopt.rs.
@evnm in the reference implementation, each --option
, <argument>
and command
is inserted as key in a json-like dictionary. The values of those keys could be different:
- for
--options
it's boolaen - for
--options
with an argument, it's a string - for
--options
with an argument which could be repeated (thanks to...
operator), it's a list of values - for options which take no argument, but could be repeated (
-v...
), the value is a number (of repetitions) - for
commands
it's same as for options with no argument - for
<arguments>
it is either a single string, or a list of strings if argument could be repeated.
Since in the reference implementation keys are arbitrary strings, the cannot collide.
from docopt.rs.
@BurntSushi the ref. imp. is using full names (with characters like -<>
), not to separate them from each other, but only for readability.
from docopt.rs.
Gotcha, thank you both. Excuse my ignorance. I'm not very familiar with docopt and came across this project when poking around for Rust CLI libs.
This makes more sense now. Insofar as my less-informed opinion matters, I think the args.{command,options,arguments}
approach is a good compromise between adhering to the reference implementation and leveraging Rust structs.
from docopt.rs.
@evnm That is the way I'm leaning. Note that structs are a convenience for this library. You can still access values using a hashmap with keys like the reference Docopt implementation: https://github.com/docopt/docopt.rs/blob/master/examples/hashmap.rs
If we really think that having a usage like program -a <a> a
is a bad idea, then it should be properly codified in the Docopt spec.
from docopt.rs.
Such collision avoidance might be worth posing to the docopt folks via a separate issue on docopt/docopt, but is outside of the scope of #7. As long as the hashmap-based API has parity with the Python lib, then I think docopt.rs should have fairly free reign over the sugary struct-based API.
from docopt.rs.
I think docopt.rs should have fairly free reign over the sugary struct-based API.
๐
from docopt.rs.
Related Issues (20)
- Panic on duplicates in the options section
- argument name with `_` underscore is misaligned to `-` hyphen HOT 1
- Could not compile by docopt_macros error at macro.rs line 187 HOT 1
- Silent breaking change in docopt 0.8.2 HOT 1
- Linking error during compilation HOT 1
- Strange behavior if subcommand starts with program name
- When repeated short and long =value flags are aliases, only one is deserialised HOT 2
- trouble with argument lists split over multiple lines HOT 1
- Allow Overlapping Option and Usage Flags for Documentation
- 1.1.0 Does not compile HOT 5
- Would `docopt_macros` still require nightly? HOT 1
- -h in priority
- Optional argument parsed as None instead of Some(_) if using '_' in option name
- Huge amount of memory used and very slow when parsing many arguments HOT 2
- get_vec and the borrow checker play badly together HOT 1
- Hidden undocumented options? HOT 1
- Positional arguments are misparsed as --required arguments HOT 4
- [Issue] Optional arguments in final array HOT 1
- Does docopt-style API scale to the complex use-cases? HOT 2
- Reverse order of usage strings HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docopt.rs.