clive 0.8.1 → 1.0.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Joshua Hawxwell
+Copyright (c) 2010-12 Joshua Hawxwell
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,280 +1,381 @@
 # clive
 
-Clive is a DSL for creating a command line interface. It is for people who, like me, 
-love [OptionParser's](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html) syntax and love [GLI's](http://github.com/davetron5000/gli) commands.
+Clive lets you easily create command line interfaces, from simply checking for
+the presence of a few flags to multiple command behemoths.
 
 ## Install
 
 Install with:
-    
-    (sudo) gem install clive
-    
-
-## How To
-
-Simply include `Clive::Parser` to start using.
-A simple example:
-    
-    # test.rb
-    require 'clive'
-    
-    class CLI
-      include Clive::Parser
-      option_hash :config
-      
-      desc 'Run verbosely'
-      switch :v, :verbose do
-        config[:verbose] = true
-      end
-      
-    end
-    CLI.parse(ARGV)
-    p CLI.config
 
-This creates a very simple interface which can have one switch, you can then use the 
-long or short form to call the block.
+``` bash
+$ gem install clive
+```
 
-    test.rb -v
-    #=> {:verbose => true}
-    test.rb --verbose
-    #=> {:verbose => true}
-    
 
-### Switches
+## Usage
 
-The most basic options. When they are called by either name the block is run. To create
-a switch use `#switch`.
+> __NOTE__: Throughout I will be using the new 1.9 `{a: b}` hash syntax,
+> obviously the old `{:a => b}` syntax still works and can be used if you want
+> or where 1.8 compatibility is needed.
 
-    switch :s do
-      # code
-    end
-    # Called with '-s'
-    
-    switch :long do
-      # code
-    end
-    # Called with '--long'
-    
-    switch :b, :both do
-      # code
-    end
-    # Called with '-b' or '--both'
+Clive is generally used by creating a class to hold your command line interface
+as shown in the example below.
+
+``` ruby
+# my_app.rb
+require 'clive'
 
+module MyApp
+  VERSION = "0.1.4"
 
-### Booleans
+  # some code
 
-Boolean switches allow you to easily create a pair of switches, eg. `--force` and 
-`--no-force`. The block given is passed either true or false depending on which was 
-used.
+  class CLI < Clive
+    config name: 'myapp'
 
-    bool :f, :force do |truth|
-      p truth
+    opt :v, :version, 'Display the current version' do
+      puts MyApp::Version
+      exit 0
     end
-    # '-f' returns true
-    # '--force' returns true
-    # '--no-force' returns false
+  end
+end
 
-You must provide a long name, a short name is optional.
+result = MyApp::CLI.run
+```
 
+Then run with `my_app.rb --version` to display the version for MyApp. By default
+`#run` will use `ARGV` as the input, but you can pass something else if
+necessary.
 
-### Flags
+`.run` returns an instance of `Clive::StructHash` by default, this is a hybrid
+hash and struct allowing you to access keys by calling them or using `#[]`. It
+also stores any extra arguments that may have been passed which can be accessed
+with `#args` or `#[:args]`.
 
-Flags are like switches but take one or more arguments, these are then passed to the 
-block.
+``` ruby
+class CLI
+  opt :n, :name, args: '<first> <last>'
+  opt :age, arg: '<age>', as: Integer
+end
 
-    # Creates a flag with a mandatory argument
-    flag :with, :args => "ARG" do |arg|
-      puts arg
-    end
-    
-    # Creates a flag with an optional argument, by using []
-    flag :with, :args => "[ARG]" do |arg|
-      puts arg
-    end
-    
-    # Creates a flag with multiple arguments
-    flag :with, :args => "FIRST [OPTIONAL]" do |i, j|
-      puts i, j
-    end
+result = CLI.run %w(--name John Doe --age 23 "I like coding!")
 
-You can also provide a list of options to select from.
-    
-    flag :choose, :args => %w(small med large) do |choice|
-      puts choice
-    end
-    
-    flag :number, :args => 1..5 do |num|
-      puts num
-    end
-    
+bio  = result.args #=> "I like coding!"
+name = result.name #=> ['John', 'Doe']
+age  = result.age  #=> 23
+```
 
-### Commands 
+This simple example shows how Clive can handle multiple arguments, casting to
+types (Integer in this case) and how extra arguments are stored in `#args`.
 
-Commands allow you to group a collection of options (or more commands) under a keyword.
-The block provided is run when one of the names for the command is encountered, but the
-blocks of the options in it are only ran when they are found.
 
-    command :init, :create do
-      bool :force do |truth|
-        puts "Force"
-      end
-    end
-    # 'init --force'
-    
+## Options
 
-### Arguments
+Options are defined using `#opt` and/or `#option` they can have short (`-a`) or
+long names (`--abc`) and can also have arguments. The description can be given
+as an argument to `#opt` or can be defined before it using `#desc` (or
+`#description`).
 
-Anything that is not captured as a command, option or argument of a flag, is returned by
-\#parse in an array.
+``` ruby
+opt :v, :version, 'Display the current version' do
+  # ...
+end
 
-    class Args
-      include Clive::Parser
-      
-      switch(:hey) { puts "Hey" }
-    end
-    args = Args.parse(ARGV)
-    p args
-    
-    # `file --hey argument "A string"`
-    #=> ['argument', 'A string']
+# is equivalent to
 
+desc 'Display the current version'
+opt :v, :version do
+  # ...
+end
+```
 
-### Variables
+Longer option names, containing `_`s are called by replacing the `_` with a `-` so
 
-Usually you'll want to set up some kind of variable, such as a hash to store your 
-configuration in, or an array of items to do something with. This would be quite annoying
-due to the fact it's a class, so I addded some handy methods.
+``` ruby
+opt :longer_name_than_expected
+```
 
-    class CLI
-      option_var :ok, false
-    end
-    CLI.ok #=> false
-    CLI.ok = true 
-    CLI.ok #=> true
-    
-    class CLI
-      option_hash :config
-      #=> is same as option_var :config, {}
-      
-      flag :set, :args => "KEY VALUE" do |key, value|
-        config[key.to_sym] = value
-      end
-    
-      option_list :items
-      # or option_array :items
-      #=> are the same as option_var :items, []
-      #                   option_var :a_list, []
-      
-      flag :add, :args => "ITEM" do |item|
-        items << item
-      end
-    end
-    CLI.parse %w(--set works true --add apple --add orange)
-    CLI.config #=> {:works => true}
-    CLI.items #=> ['apple', 'orange']
+would be called with `--longer-name-than-expected`.
 
-### Option Missing Handling
+### Boolean Options
 
-You are able to intercept errors when an option does not exist in a similar way to 
-`method_missing`.
+Boolean options are options which can be called with a `no-` prefix, which then
+passes `false` to the block/state. For example,
 
-    class Missing
-      option_missing do |name|
-        puts "#{name} was used but not defined"
-      end
-    end
-    Missing.parse %w(--hey)
-    #=> hey was used but not defined
+``` ruby
+bool :a, :auto
+```
 
+Can be called with `-a` or `--auto` which would set `:auto` to `true`, or
+`--no-auto` which sets `:auto` to `false`. If a block is given you can retrieve
+the truth by adding block parameters or using the `truth` variable which is
+automatically set.
 
-### Help Formatting
+``` ruby
+bool :a, :auto do |t|
+  puts t
+end
 
-There are two built in help formats the default, with colour, and a pure white one. To 
-change the formatter call `#help_formatter` with :default, or :white.
+# OR
 
-Optionally you can create your own formatter, like so:
+bool :a, :auto do
+  puts truth
+end
+```
 
-    class CLI
-      help_formatter do |h|
-        h.switch "{prepend}{names.join(', ')} {spaces}# {desc}"
-        h.bool   "{prepend}{names.join(', ')} {spaces}# {desc}"
-        h.flag   "{prepend}{names.join(', ')} {args.join(' ')} {spaces}# {desc}" <<
-                   "{options.join('(', ', ', ')')}"
-        h.command "{prepend}{names.join(', ')} {spaces}# {desc}"
-      end
-    end
+Boolean options __must__ have a long name.
+
+
+## Commands
+
+Commands are defined using `#command`. They can be used to group related Options
+together acting like a namespace, but Commands are fully featured Options so can
+also take arguments. Commands can be created with multiple names.
+
+``` ruby
+desc 'Create a new project'
+command :new, :create, arg: '<dir>', as: Pathname do
+
+  # Set the default type to use
+  set :type, :basic
+
+  desc 'Select type of template to use'
+  opt :type, arg: '<choice>', in: %w(basic complex custom), as: Symbol
+
+  bool :force, 'Force overwrite'
+
+  action do
+    puts "Creating #{get :type} in #{dir}"
+    # do writing
+  end
+end
+```
+
+The above example also shows using the `#set` and `#get` methods, these allow
+you to set and get values from the state. Also note how the logic for executing
+the `new` command is given to `#action`, this is because the block passed to
+`#command` is used for option definition.
+
+
+## Arguments
+
+As previously talked about Options and Commands can take arguments by passing a
+hash with the key `:arg` or `:args`.
+
+``` ruby
+opt :size, args: '<height> <width>'
+```
+
+The option `--size` takes two arguments. These would be saved to state as an array,
+for instance running with `--size 10 40` would set `:size` to `['10', '40']`.
+
+Arguments can be made optional by enclosing one or more arguments with `[` and `]`:
+
+``` ruby
+# both required
+opt :size, args: '<h> <w>'
+# --size 10   #=> Error
+
+# first required
+opt :size, args: '<h> [<w>]'
+# --size 10   #=> [10, nil]
+
+# second required
+opt :size, args: '[<h>] <w>'
+# --size 10   #=> [nil, 10]
+
+# neither required
+opt :size, args: '[<h> <w>]'
+# --size 10   #=> [10, nil]
+```
+
+There are also various options that can be passed to constrain or change the
+arguments. If one of the below is passed to an option with `:arg` or `:args`
+a generic argument called `<arg>` will be added.
+
+### Types (`:types`, `:type`, `:kind` or `:as`)
+
+An argument will be checked if it matches how the type should look, then converts
+it to that type. For more information see `lib/clive/type/definitions.rb`.
+
+``` ruby
+opt :list, as: Array
+```
+
+This accepts a comma delimited list of items, `--list a,b,c` and sets `:list` to
+`['a', 'b', 'c']`.
+
+### Matches (`:matches` or `:match`)
+
+Allows you to say that an argument must match a regular expression (or any object
+which responds to `#match`).
+
+``` ruby
+opt :word, match: /^\w+$/
+```
 
-Which would look like:
+This accepts `--word hello` but not `--word 123`.
 
-    Usage: my_app [command] [options]
-    
-      Commands:
-        test            # A command
-        
-      Options:
-        -h, --help      # Display help
-        --[no-]force    # Force build
+### Withins (`:withins`, `:within` or `:in`)
 
-You have access to the variables:
+Allows you to say that an argument must be within a passed Array, Set or Range
+(any object which responds to `#include?`).
 
-* prepend - a string of spaces as specified when `#help_formatter` is called
-* names - an array of names for the option
-* spaces - a string of spaces to align the descriptions properly
-* desc - a string of the description for the option
+``` ruby
+opt :num, in: "1".."100"
+```
 
-And for flags you have access to:
+This accepts `--num 50` but not `--num 900`. The example above had to use a range
+of Strings because that is what is passed, you can use this with `:type` to use
+Integers.
 
-* args - an array of arguments for the flag
-* options - an array of options to choose from
+``` ruby
+opt :num, as: Integer, in: 1..100
+```
+
+Would work in the same way as the one above but return an Integer.
+
+### Defaults (`:defaults` or `:default`)
+
+Allows you to give a default value that should be used if an argument is not
+given.
+
+``` ruby
+opt :type, default: 'house'
+```
+
+So `--type` would set `:type` to `'house'`, but `--type shed` would set `:type`
+to `'shed'`. The default value is only set if the option is used. To set a value
+regardless of whether the option is used use `#set` in the class or commands
+body.
+
+``` ruby
+set :type, 'house'
+opt :type
+```
+
+Would always set `:type` to `'house'` even when `--type` is not used.
+
+### Constraints (`:constraint` or `:constraint`)
+
+Allows you to constrain the argument using a Proc, this is to cover the very
+few events where the above options do not satisfy the requirements.
+
+``` ruby
+opt :long_word, constraint: -> i { i.size >= 7 }
+```
+
+Accepts `--long-word eventually` but not `--long-word event`. You can also pass
+a symbol which will have `#to_proc` called on it.
+
+``` ruby
+opt :odd, as: Integer, constraint: :odd?
+```
+
+This only accepts odd Integers.
+
+
+## Runner
+
+All blocks passed to options or given to a command's action are run in the Runner
+class. This provides a few shortcuts to make life easier. Here is a quick run down
+with examples.
+
+### Argument Referencing
+
+You can reference an options or commands arguments directly by name without having
+to use block parameters.
+
+``` ruby
+opt :size, args: '<height> <width>', as: [Float, Float] do # no params!
+  puts "Area = #{height} * #{width} = #{height * width}"
+end
+```
+
+As shown earlier the truthiness of a boolean option is set to the value `truth`.
+
+### Working with the State
+
+Four fundamental methods are defined for working with the state, `#get`, `#set`,
+`#update` and `#has?`.
+
+`#get` allows you to get values previously set.
+
+``` ruby
+opt :get_some_key do
+  puts get(:some_key) #=> value set for :some_key
+end
+```
+
+`#set` allows you to set values in the state.
+
+``` ruby
+opt :set_some_key, arg: '<value>' do
+  set :some_key, value
+end
+```
+
+`#update` allows you to modify a value in the state.
+
+``` ruby
+set :list, []
+opt :add, arg: '<item>' do
+  update :list, :<<, item
+
+  # or using a block
+  update(:list) {|l| l << item }
+end
+```
+
+`#has?` tells you whether a value has been set for the key.
+
+``` ruby
+opt :has_some_key do
+  puts has?(:some_key)
+end
+```
+
+
+## Help Formatters
+
+Clive comes with two help formatters, one with colour and the other without. To use
+the plain formatter (colour is default), use
+
+``` ruby
+class CLI < Clive
+  config formatter: Clive::Formatter::Plain.new
+
+  # ...
+end
+
+CLI.run
+```
+
+To create your own formatter take a look at `lib/clive/formatter.rb`.
 
-Inside the { and } you can put any ruby, so feel free to use joins on the array.
 
- 
 ## Clive::Output
 
-This is a new bit that allows you to colourise output from the command line, by patching a 
-few methods onto String.
-
-    require 'clive/output'
-    # or require 'clive'
-    
-    puts "I'm blue".blue  # will print blue text
-    puts "I'm red".red    # will print red text
-    puts "I'm green and bold".green.bold   # will print green and bold text
-    puts "Crazy".blue.l_yellow_bg.underline
-    # etc
-
-Methods available are:
- - bold
- - underline
- - blink
- - reverse
- 
- - white
- - green
- - red
- - magenta
- - yellow
- - blue
- - cyan
- - black (light version called grey not l_black)
- 
- - + light versions of colours using l_colour)
- - + background setters using colour_bg
- - + light background using l_colour_bg
-
-    
-
-## Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself so I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+`clive/output` contains various monkey patches on String that allow you to easily
+colourise output.
+
+``` ruby
+puts "I'm blue".blue                     # will print blue text
+puts "I'm green and bold".green.bold     # will print green and bold text
+puts "Crazy".blue.l_yellow_bg.underline
+# etc
+```
+
+Colours available: white, green, red, magenta, yellow, blue, cyan, black.
+Effects available: bold, underline, blink, reverse.
+
+Light versions can be used by prepending the name with `l_`, ie. `l_red`, the light
+version of black is called grey.
+
+All colours can be used as backgrounds by appending `_bg`, ie. `red_bg`, light
+backgrounds are as expected, `l_red_bg`.
+
 
 ## Copyright
 
-Copyright (c) 2010 Joshua Hawxwell. See LICENSE for details.
+Copyright (c) 2010-12 Joshua Hawxwell. See LICENSE for details.