Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Updated README and CHANGELOG
git-svn-id: http://choice.rubyforge.org/svn/trunk@47 2891bcfe-6912-0410-8cba-feaf504d3ce4
  • Loading branch information
defunkt committed Jul 22, 2006
1 parent 9e1d89b commit 3b46925
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 4 deletions.
1 change: 1 addition & 0 deletions CHANGELOG
Expand Up @@ -9,6 +9,7 @@
- Added list format to options as per bug tracker suggestion in the format of --long=*LONG [Alexis Li]
- Added --long ARG format. Works with --long [ARG] and --long *ARG and --long [*ARG]
- Added :required option which insists an option is present.
- Added gamble.rb card game example.

0.1.0:
- First release
46 changes: 42 additions & 4 deletions README
Expand Up @@ -159,6 +159,7 @@ For the quick learners, here's the list:
* default
* desc
* cast
* valid (takes array)
* validate (takes regex)
* filter (takes a block)
* action (ditto)
Expand All @@ -170,10 +171,12 @@ You can define these within your option in any order which pleases you.
Defines the short switch for an option. Expected to be a dash and a single
character.

short '-s'

=== long

Defines the long switch for an option. Expected to be a double dash followed by
a string, an equal sign, and another string. No spaces.
a string, an equal sign (or a space), and another string.

There are two variants: longs where a parameter is required and longs where a
parameter is optional, in which case the value will be +true+ if the option is
Expand All @@ -193,12 +196,15 @@ we can do this:
$ ruby ftpd.rb --debug=1
debug: 1

$ ruby ftpd.rb --debug 1
debug: 1

*Required*:
long '--debug=LEVEL'

Assuming the same as above:

$ ruby ftpd.rb --debug=1
$ ruby ftpd.rb --debug 1
debug: 1

$ ruby ftpd.rb --debug
Expand All @@ -220,7 +226,7 @@ will be 'info.'
$ ftpd.rb
debug: info

$ ftpd.rb --debug=warn
$ ftpd.rb --debug warn
debug: warn

=== desc
Expand All @@ -244,6 +250,8 @@ By default, all members of the <tt>Choice.choices</tt> hash are strings. If
you want something different, like an Integer for a port number, you can use
the +cast+ statement.

cast Integer

Currently support +cast+ options:

* Integer
Expand All @@ -253,6 +261,22 @@ Currently support +cast+ options:

We'll probably add Date, Time, and DateTime in the future, if people want them.

=== valid

Giving +valid+ an array creates a whitelist of acceptable arguments.

valid %w[clubs hearts spades diamonds]

If our option is passed anything other than one of the four card suits, the help
screen will be printed. It might be a good idea to include acceptable arguments in
your option's "desc" value.

$ ruby gamble.rb -s clubs
suit: clubs

$ ruby gamble.rb -s joker
<help screen printed>

=== validate

The +validate+ statement accepts a regular expression which it will test
Expand All @@ -264,7 +288,7 @@ be printed. I love ports, so let's stick with that example:
Of course, 2100 matches this:

$ ruby ftpd.rb -p 2100
port: 21000
port: 2100

I like dogs. I wish dogs could be ports. Alas, Choice knows better (once
I've told it so):
Expand Down Expand Up @@ -315,21 +339,29 @@ options defined:
You can pass any string to the +banner+ statement to override what prints. This
might be useful if you're into ascii art.

banner "Usage: ftpd.rb"

=== header

The header is what shows up after the banner but before your option definitions
are printed. Each header call is a newline. Check out the example above.

header "ftp is a harsh and unforgiving protocol."

=== separator

As in the example above, you can put separators between options to help display
the logical groupings of your options. Or whatever.

separator "----"

=== footer

The footer is displayed after all your options are displayed. Nothing new
here, works like the other options above.

footer "That's all there is to it!"

== It looks like poetry

That's it. Not much, I know. Maybe this will make handling your command
Expand All @@ -345,3 +377,9 @@ This'll run the unit tests. Also, if you would, send me a bit of information
on your platform. Choice was tested on OS X and RHEL with a 2.4 kernel but who
knows. Thanks a lot.

== Thanks to

For bug reports, patches, and ideas I'd be honored to thank the following:

- Justin Bailey
- Alexis Li

0 comments on commit 3b46925

Please sign in to comment.