Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Help request #13

Closed
schoettl opened this issue May 6, 2015 · 8 comments
Closed

Help request #13

schoettl opened this issue May 6, 2015 · 8 comments

Comments

@schoettl
Copy link

schoettl commented May 6, 2015

I try for days and don't get it work:

How to access an argument of an option (... --out=file ...)?

I copied the first example from Hackage and added an argument to the option --caps. Then I added three lines at the bottom of the main.

I run the program and get an error:

$ ./program echo --caps=test hallo
HALLO
argument expected for: Argument "test"


docopt-sample version 0.1.0

Usage:
  docopt-sample cat <file>
  docopt-sample echo [--caps=<test>] <string>

Options:
  -c, --caps=<test>    Caps-lock the echoed argument

Maybe it's a trivial error and anyone can help me?

@ryanartecona
Copy link
Member

Sorry you've had trouble with it! The good news is it's an easy fix. :)

On this line, change argument "test" to longOption "caps". When you have an option like --caps=<test>, the <test> part only serves to communicate that --caps expects an argument, and is otherwise ignored. The argument expected for:... message is what getArgOrExitWith does when its lookup fails.

Maybe cases like this should treat the <test> as a synonym with --caps, as in the argument can be looked up with either argument or longOption? I'll think about this a bit. At the very least, this could be clearer in the docs.

@schoettl
Copy link
Author

schoettl commented May 6, 2015

Ahh. Thank you!

If it is not really trivial to "treat the <test> as a synonym with --caps", it's probably not worth the effort.

One problem that can occur, when trying to fix this, are name collisions. Example:

usage:
  program [options] FILE
options:
  --offset N  offset in the file
  --bytes N   number of bytes
  --output FILE  the output file

Especially in large usage messages, this can happen. Sure, the developer can avoid this, but then he really have to read the Docopt documentation! And priorization for this case is not really obvious to a new developer.

An example how to use options with arguments in the README would be great and helpful.

@ryanartecona
Copy link
Member

Well, I did, earlier today. :) Do you think that's enough, or that it should be more prominent? Or rather, do you think that that would've been enough to point you in the right direction if it had been in the README before?

@schoettl
Copy link
Author

schoettl commented May 6, 2015

I commented on your commit.

@ryanartecona
Copy link
Member

Thanks for that. I'll make those changes, and also update the haddock documentation to make note of this case.

@ryanartecona
Copy link
Member

Take a look at 7283baa and see if that will work. I made the changes you suggested, and also added notes along side the haddock descriptions of the argument and longOption/shortOption functions.

I'd like to eventually have everything that's currently in the README instead in a System.Console.Docopt.Tutorial module, so that all the documentation can be had without leaving hackage, and also locally if the package's docs are compiled when it's installed.

Let me know (open more issues) if anything else sticks out that could be made clearer! Otherwise, feel free to close this issue, and I'll upload the new docs to hackage.

@schoettl
Copy link
Author

schoettl commented May 8, 2015

Thanks for your commitment :)

And I added two comments on your commit.

@schoettl schoettl closed this as completed May 8, 2015
@ryanartecona
Copy link
Member

@schoettl Thanks for taking the time to help me improve the docs!

I've been busy for the last week, but I just (hopefully) clarified that weird sentence in the README in 0686e2d, and updated the docs in Hackage at v.0.7.0.2 with notes that will help others avoid your problem case. 🍻

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants