Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 134 lines (98 sloc) 3.554 kb
1c9367b initial commit
Lee Jarvis authored
1 Slop
2 ====
3
ffddd14 update readme, I cringe at this word but I guess it's correct
Lee Jarvis authored
4 Slop is a simple option parser with an easy to remember syntax and friendly API.
1c9367b initial commit
Lee Jarvis authored
5
198202d added build status image to readme
Lee Jarvis authored
6 [![Build Status](https://secure.travis-ci.org/injekt/slop.png)](http://travis-ci.org/injekt/slop)
7
1c9367b initial commit
Lee Jarvis authored
8 Installation
9 ------------
10
11 ### Rubygems
12
5e8d3ad @george documented :help => true
george authored
13 gem install slop
1c9367b initial commit
Lee Jarvis authored
14
15 ### GitHub
16
5e8d3ad @george documented :help => true
george authored
17 git clone git://github.com/injekt/slop.git
18 gem build slop.gemspec
19 gem install slop-<version>.gem
a3e4b6f remove 'this code sucks' notice from readme
Lee Jarvis authored
20
1c9367b initial commit
Lee Jarvis authored
21 Usage
22 -----
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
23
24 ```ruby
25 # parse assumes ARGV, otherwise you can pass it your own Array
26 opts = Slop.parse do
8f5f566 scrubbed readme for rewrite
Lee Jarvis authored
27 banner "ruby foo.rb [options]\n"
28 on :name=, 'Your name'
29 on :p, :password, 'Your password', :argument => :optional
0455a83 @lolmaus Fixed a probable typo in the readme.
lolmaus authored
30 on :v, :verbose, 'Enable verbose mode'
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
31 end
32
8f5f566 scrubbed readme for rewrite
Lee Jarvis authored
33 # if ARGV is `--name Lee -v`
34 opts.verbose? #=> true
35 opts.password? #=> false
36 opts[:name] #=> 'lee'
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
37 ```
1c9367b initial commit
Lee Jarvis authored
38
8f5f566 scrubbed readme for rewrite
Lee Jarvis authored
39 Slop supports several methods of writing options:
c92a745 added documentation for multiple short switches
Lee Jarvis authored
40
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
41 ```ruby
8f5f566 scrubbed readme for rewrite
Lee Jarvis authored
42 # These options all do the same thing
43 on '-n', '--name', 'Your name', :argument => true
44 on 'n', :name=, 'Your name'
fe6b221 added configuration options
Lee Jarvis authored
45 on :n, '--name=', 'Your name'
c92a745 added documentation for multiple short switches
Lee Jarvis authored
46
8f5f566 scrubbed readme for rewrite
Lee Jarvis authored
47 # As do these
fe6b221 added configuration options
Lee Jarvis authored
48 on 'p', '--password', 'Your password', :argument => :optional
8f5f566 scrubbed readme for rewrite
Lee Jarvis authored
49 on :p, :password, 'Your password', :optional_argument => true
fe6b221 added configuration options
Lee Jarvis authored
50 on '-p', 'password=?', 'Your password'
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
51 ```
df27a36 updated README examples
Lee Jarvis authored
52
fe6b221 added configuration options
Lee Jarvis authored
53 You can also return your options as a Hash:
6a549fa @george strict mode parses options before raising Slop::InvalidOptionError
george authored
54
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
55 ```ruby
ae2627b @no6v fix sample code in README.md
no6v authored
56 opts.to_hash #=> { :name => 'lee', :verbose => true, :password => nil }
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
57 ```
6a549fa @george strict mode parses options before raising Slop::InvalidOptionError
george authored
58
fe6b221 added configuration options
Lee Jarvis authored
59 Printing Help
60 -------------
61
62 Slop attempts to build a good looking help string to print to your users. You
63 can see this by calling `opts.help` or simply `puts opts`.
64
65 Configuration Options
66 ---------------------
67
68 All of these options can be sent to `Slop.new` or `Slop.parse` in Hash form.
69
70 * `strict` - Enable strict mode. When processing unknown options, Slop will
71 raise an `InvalidOptionError`. **default:** *false*.
72 * `help` - Automatically add the `--help` option. **default:** *false*.
73 * `banner` - Set this options banner text. **default:** *nil*.
74 * `ignore_case` - When enabled, `-A` will look for the `-a` option if `-A`
75 does not exist. **default:** *false*.
76 * `autocreate` - Autocreate options on the fly. **default:** *false*.
77 * `arguments` - Force all options to expect arguments. **default:** *false*.
78 * `optional_arguments` - Force all options to accept optional arguments.
79 **default:** *false*.
80 * `multiple_switches` - When disabled, Slop will parse `-abc` as the option `a`
81 with the argument `bc` rather than 3 separate options. **default:** *true*.
82 * `longest_flag` - The longest string flag, used to aid configuring help
83 text. **default:** *0*.
84
63b1ee7 added links to more features
Lee Jarvis authored
85 Features
86 --------
87
88 Check out the following wiki pages for more features:
89
42e46af added link to ranges wiki page and remove readme example
Lee Jarvis authored
90 * [Ranges](https://github.com/injekt/slop/wiki/Ranges)
63b1ee7 added links to more features
Lee Jarvis authored
91 * [Auto Create](https://github.com/injekt/slop/wiki/Auto-Create)
92
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
93 Woah woah, why you hating on OptionParser?
94 ------------------------------------------
95
96 I'm not, honestly! I love OptionParser. I really do, it's a fantastic library.
041cc6b fix tpyo
Lee Jarvis authored
97 So why did I build Slop? Well, I find myself using OptionParser to simply
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
98 gather a bunch of key/value options, usually you would do something like this:
99
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
100 ```ruby
101 require 'optparse'
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
102
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
103 things = {}
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
104
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
105 opt = OptionParser.new do |opt|
106 opt.on('-n', '--name NAME', 'Your name') do |name|
107 things[:name] = name
108 end
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
109
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
110 opt.on('-a', '--age AGE', 'Your age') do |age|
111 things[:age] = age.to_i
112 end
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
113
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
114 # you get the point
115 end
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
116
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
117 opt.parse
118 things #=> { :name => 'lee', :age => 105 }
119 ```
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
120
4ced2f2 fix some readme grammar
Lee Jarvis authored
121 Which is all great and stuff, but it can lead to some repetition. The same
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
122 thing in Slop:
123
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
124 ```ruby
125 require 'slop'
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
126
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
127 opts = Slop.parse do
128 on :n, :name=, 'Your name'
129 on :a, :age=, 'Your age', :as => :int
130 end
fa929f3 added Y U NO LIKE OPTPARSE?? example to readme
Lee Jarvis authored
131
660c455 updated README and added github syntax highlighting
Lee Jarvis authored
132 opts.to_hash #=> { :name => 'lee', :age => 105 }
6eb32c0 @eric1234 New support_dash option. Will treat --database-name like --database_name
eric1234 authored
133 ```
Something went wrong with that request. Please try again.