diff options
author | Lee Jarvis <lee@jarvis.co> | 2011-11-04 19:44:42 -0700 |
---|---|---|
committer | Lee Jarvis <lee@jarvis.co> | 2011-11-04 19:44:42 -0700 |
commit | 660c455d2b6df3f027484b40249b1dad924d84f8 (patch) | |
tree | 9a2da38358109924b4376b35e11ff0b16f808f2a | |
parent | 18fcb3f03148656e76e808fd744e597bebfa3871 (diff) | |
download | slop-660c455d2b6df3f027484b40249b1dad924d84f8.tar.gz |
updated README and added github syntax highlighting
-rw-r--r-- | README.md | 254 |
1 files changed, 146 insertions, 108 deletions
@@ -18,20 +18,24 @@ Installation Usage ----- - # parse assumes ARGV, otherwise you can pass it your own Array - opts = Slop.parse do - on :v, :verbose, 'Enable verbose mode' # boolean value - on :n, :name, 'Your name', true # option requires a compulsory argument - on :s, :sex, 'Your sex', :optional => false # the same thing - on '-a', '--age', 'Your age', :optional => true # optional argument - end - - # if ARGV is `-v --name 'lee jarvis' -s male` - opts.verbose? #=> true - opts.name? #=> true - opts[:name] #=> 'lee jarvis' - opts.age? #=> false - opts[:age] #=> nil + +```ruby +# parse assumes ARGV, otherwise you can pass it your own Array +opts = Slop.parse do + on :v, :verbose, 'Enable verbose mode' # A boolean option + on :n, :name=, 'Your name' # This option requires an argument + on :s, :sex, 'Your sex', true # So does this one + on :a, :age, 'Your age', optional: true # This one accepts an optional argument + on '-D', '--debug', 'Enable debug' # The prefix -'s are optional +end + +# if ARGV is `-v --name 'lee jarvis' -s male` +opts.verbose? #=> true +opts.name? #=> true +opts[:name] #=> 'lee jarvis' +opts.age? #=> false +opts[:age] #=> nil +``` For more information about creating options, see the [Creating Options](https://github.com/injekt/slop/wiki/Creating-Options) @@ -39,69 +43,87 @@ wiki page. You can also return your options as a Hash - opts.to_hash #=> {:name => 'Lee Jarvis', :verbose => true, :age => nil, :sex => 'male'} +```ruby +opts.to_hash #=> { :name => 'Lee Jarvis', :verbose => true, :age => nil, :sex => 'male' } +``` If you want some pretty output for the user to see your options, you can just send the Slop object to `puts` or use the `help` method. - puts opts - puts opts.help +```ruby +puts opts +puts opts.help +``` Will output something like - -v, --verbose Enable verbose mode - -n, --name Your name - -a, --age Your age +``` +-v, --verbose Enable verbose mode +-n, --name Your name +-a, --age Your age +``` You can also add a banner using the `banner` method - opts = Slop.parse do - banner "Usage: foo.rb [options]" - end +```ruby +opts = Slop.parse do + banner "Usage: foo.rb [options]" +end +``` Helpful Help ------------ Long form: - Slop.parse do - ... - on :h, :help, 'Print this help message', :tail => true do - puts help - exit - end - end +```ruby +Slop.parse do + ... + on :h, :help, 'Print this help message', :tail => true do + puts help + exit + end +end +``` Shortcut: - Slop.parse :help => true do +```ruby +Slop.parse :help => true do ... - end +end +``` Parsing ------- Slop's pretty good at parsing, let's take a look at what it'll extract for you - Slop.parse(:multiple_switches => false) do - on 's', 'server', true - on 'p', 'port', true, :as => :integer - on 'username', true, :matches => /[^a-zA-Z]+$/ - on 'password', true - end +```ruby +Slop.parse(:multiple_switches => false) do + on 's', 'server=' + on 'p', 'port=', :as => :integer + on 'username=', :matches => /[^a-zA-Z]+$/ + on 'password=' +end +``` Now throw some options at it: - -s ftp://foobar.com -p1234 --username=FooBar --password 'hello there' +``` +-s ftp://foobar.com -p1234 --username=FooBar --password 'hello there' +``` Here's what we'll get back - { - :server => "ftp://foobar.com", - :port => 1234, - :username => "FooBar", - :password => "hello there" - } +``` +{ + :server => "ftp://foobar.com", + :port => 1234, + :username => "FooBar", + :password => "hello there" +} +``` Events ------ @@ -109,12 +131,14 @@ Events If you'd like to trigger an event when an option is used, you can pass a block to your option. Here's how: - Slop.parse do - on :V, :version, 'Print the version' do - puts 'Version 1.0.0' - exit - end - end +```ruby +Slop.parse do + on :V, :version, 'Print the version' do + puts 'Version 1.0.0' + exit + end +end +``` Now when using the `--version` option on the command line, the trigger will be called and its contents executed. @@ -127,17 +151,19 @@ they're found, just like [OptionParser](http://rubydoc.info/stdlib/optparse/1.9.2/OptionParser:order) does it. - opts = Slop.new do - on :n, :name, :optional => false - end +```ruby +opts = Slop.new do + on :n, :name, :optional => false +end - opts.parse do |arg| - puts arg - end +opts.parse do |arg| + puts arg +end - # if ARGV is `foo --name Lee bar` - foo - bar +# if ARGV is `foo --name Lee bar` +foo +bar +``` Negative Options ---------------- @@ -145,16 +171,18 @@ Negative Options Slop also allows you to prefix `--no-` to an option which will force the option to return a false value. - opts = Slop.parse do - on :v, :verbose, :default => true - end +```ruby +opts = Slop.parse do + on :v, :verbose, :default => true +end - # with no command line options - opts[:verbose] #=> true +# with no command line options +opts[:verbose] #=> true - # with `--no-verbose` - opts[:verbose] #=> false - opts.verbose? #=> false +# with `--no-verbose` +opts[:verbose] #=> false +opts.verbose? #=> false +``` Short Switches -------------- @@ -165,35 +193,39 @@ you would like to disable this, you can pass `multiple_switches => false` to a new Slop object. In which case Slop will then parse `-fbar` as the option `f` with the argument value `bar`. - Slop.parse do - on :a, 'First switch' - on :b, 'Second switch' - on :c, 'Third switch' - end +```ruby +Slop.parse do + on :a, 'First switch' + on :b, 'Second switch' + on :c, 'Third switch' +end - # Using `-ac` - opts[:a] #=> true - opts[:b] #=> false - opts[:c] #=> true +# Using `-ac` +opts[:a] #=> true +opts[:b] #=> false +opts[:c] #=> true - Slop.parse(:multiple_switches => false) do - on :a, 'Some switch', true - end +Slop.parse(:multiple_switches => false) do + on :a, 'Some switch', true +end - # Using `ahello` - opts[:a] #=> 'hello' +# Using `ahello` +opts[:a] #=> 'hello' +``` Lists ----- You can of course also parse lists into options. Here's how: - opts = Slop.parse do - opt :people, true, :as => Array - end +```ruby +opts = Slop.parse do + opt :people, true, :as => Array +end - # ARGV is `--people lee,john,bill` - opts[:people] #=> ['lee', 'john', 'bill'] +# ARGV is `--people lee,john,bill` +opts[:people] #=> ['lee', 'john', 'bill'] +``` Slop supports a few styles of list parsing. Check out [this wiki page](https://github.com/injekt/slop/wiki/Lists) for more info. @@ -204,8 +236,10 @@ Strict Mode Passing `strict => true` to `Slop.parse` causes it to raise a `Slop::InvalidOptionError` when an invalid option is found (`false` by default): - Slop.new(:strict => true).parse(%w/--foo/) - # => Slop::InvalidOptionError: Unknown option -- 'foo' +```ruby +Slop.new(:strict => true).parse(%w/--foo/) +# => Slop::InvalidOptionError: Unknown option -- 'foo' +``` Features -------- @@ -223,33 +257,37 @@ I'm not, honestly! I love OptionParser. I really do, it's a fantastic library. So why did I build Slop? Well, I find myself using OptionParser to simply gather a bunch of key/value options, usually you would do something like this: - require 'optparse' +```ruby +require 'optparse' - things = {} +things = {} - opt = OptionParser.new do |opt| - opt.on('-n', '--name NAME', 'Your name') do |name| - things[:name] = name - end +opt = OptionParser.new do |opt| + opt.on('-n', '--name NAME', 'Your name') do |name| + things[:name] = name + end - opt.on('-a', '--age AGE', 'Your age') do |age| - things[:age] = age.to_i - end + opt.on('-a', '--age AGE', 'Your age') do |age| + things[:age] = age.to_i + end - # you get the point - end + # you get the point +end - opt.parse - things #=> { :name => 'lee', :age => 105 } +opt.parse +things #=> { :name => 'lee', :age => 105 } +``` Which is all great and stuff, but it can lead to some repetition. The same thing in Slop: - require 'slop' +```ruby +require 'slop' - opts = Slop.parse do - on :n, :name, 'Your name', true - on :a, :age, 'Your age', true, :as => :int - end +opts = Slop.parse do + on :n, :name=, 'Your name' + on :a, :age=, 'Your age', :as => :int +end - opts.to_hash #=> { :name => 'lee', :age => 105 }
\ No newline at end of file +opts.to_hash #=> { :name => 'lee', :age => 105 } +```
\ No newline at end of file |