<commit_before># clive

Clive is a DSL for creating command line interfaces.

## Install

Install with:
    
    gem install clive
    

## Usage

__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.

Clive is built around the idea that it makes more sense to define a cli in a class,
this way it can be easily modified and reopened to add more options.

    # my_app.rb
    require 'clive'

    module MyApp
      VERSION = "0.1.4"
      
      # some code
      
      class CLI
        extend Clive
        
        opt :v, :version, 'Display the current version' do
          puts MyApp::Version
          exit 0
        end
        
      end
    end
    
    args, state = MyApp::CLI.run(ARGV)

Then run with `my_app.rb --version` to display the version for MyApp. `.run`
returns two arguments the first is an Array with all of the arguments that were 
not used; the second is a Hash, if any option is called which doesn't have a
block an entry is added with the name of the option and `true`.


### Options

Options are defined using `#opt` 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`.

    opt :v, :version, 'Display the current version' do
      # ...
    end
    
    # is equivelant to
    
    desc 'Display the current version'
    opt :v, :version do
      # ...
    end

Longer option names, with `_` are called by replacing the `_` with a `-` so

    opt :longer_name_than_expected

Would be called with `--longer-name-than-expected`.

#### Boolean Options

Boolean options are options which can be called with a `no-` prefix, which then
passes false to the block/state. For example,

    bool :a, :auto

Can be called with `-a` or `--auto` returning a state of `{:auto => true}`,
or `--no-auto` returning a state of `{:auto => false}`. If a block is given the
truth can be got by adding block parameters or using the `truth` variable which 
is set.

    bool :a, :auto do |t|
      puts t
    end
    
    # OR
    
    bool :a, :auto do
      puts truth
    end


### Arguments

Options can takes arguments by adding a hash with the key `:arg` or `:args`:

    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 return a state of `{:size => 
['10', '40']}`.

Arguments can be made optional by enclosing one or more arguments with `[` and `]`:

    # both required
    opt :size, args: '<h> <w>'
    
    # first required
    opt :size, args: '<h> [<w>]'
    
    # second required
    opt :size, args: '[<h>] <w>'
    
    # neither required
    opt :size, args: '[<h> <w>]'

There are also various options that can be passed to constrain or change the 
arguments. When using these if `:arg` is not given it is inferred from the
options given.


#### Types
Aliased as `:type`, `:kind`, `:as`.

Allows you to say that an argument must be converted to a specific type before
use in a block or being saved to state, but also that it should look like a 
specific type.

    opt :list, as: Array

Accepts a comma delimeted list of items, `--list a,b,c` and returns them as
an Array (ie. `['a', 'b', 'c']`).

#### Matches
Aliased as `:match`.

Allows you to say that an argument must match a regular expression (or any object
which responds to `#match`).

    opt :word, match: /^\w+$/
<commit_msg>Tiny README cleanup for new usage<commit_after># clive

Clive is a DSL for creating command line interfaces.

## Install

Install with:
    
    gem install clive
    

## Usage

__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.

Clive is built around the idea that it makes more sense to define a cli in a class,
this way it can be easily modified and reopened to add more options.

    # my_app.rb
    require 'clive'

    module MyApp
      VERSION = "0.1.4"
      
      # some code
      
      class CLI
        extend Clive
        
        opt :v, :version, 'Display the current version' do
          puts MyApp::Version
          exit 0
        end
        
      end
    end
    
    result = MyApp::CLI.run(ARGV)

Then run with `my_app.rb --version` to display the version for MyApp. `.run`
returns an instance of `Clive::StructHash` this allows you to access entries
with methods as well as using `#[]`. It also stores any spare arguments given
under `#args` or `#[:args]`. The entry will have the arguments if needed or 
`true` when an option has been given.


### Options

Options are defined using `#opt` 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`.

    opt :v, :version, 'Display the current version' do
      # ...
    end
    
    # is equivalent to
    
    desc 'Display the current version'
    opt :v, :version do
      # ...
    end

Longer option names, with `_` are called by replacing the `_` with a `-` so

    opt :longer_name_than_expected

Would be called with `--longer-name-than-expected`.

#### Boolean Options

Boolean options are options which can be called with a `no-` prefix, which then
passes false to the block/state. For example,

    bool :a, :auto

Can be called with `-a` or `--auto` returning a state of `{:auto => true}`,
or `--no-auto` returning a state of `{:auto => false}`. If a block is given the
truth can be got by adding block parameters or using the `truth` variable which 
is set.

    bool :a, :auto do |t|
      puts t
    end
    
    # OR
    
    bool :a, :auto do
      puts truth
    end


### Arguments

Options can takes arguments by adding a hash with the key `:arg` or `:args`:

    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 return a state of `{:size => 
['10', '40']}`.

Arguments can be made optional by enclosing one or more arguments with `[` and `]`:

    # both required
    opt :size, args: '<h> <w>'
    
    # first required
    opt :size, args: '<h> [<w>]'
    
    # second required
    opt :size, args: '[<h>] <w>'
    
    # neither required
    opt :size, args: '[<h> <w>]'

There are also various options that can be passed to constrain or change the 
arguments. When using these if `:arg` is not given it is inferred from the
options given.


#### Types
Aliased as `:type`, `:kind`, `:as`.

Allows you to say that an argument must be converted to a specific type before
use in a block or being saved to state, but also that it should look like a 
specific type.

    opt :list, as: Array

Accepts a comma delimited list of items, `--list a,b,c` and returns them as
an Array (ie. `['a', 'b', 'c']`).

#### Matches
Aliased as `:match`.

Allows you to say that an argument must match a regular expression (or any object
which responds to `#match`).

    opt :word, match: /^\w+$/

{'fraction_non_alphanumeric': 0.09932590452606961, 'fraction_numerical': 0.004402256156280093, 'mean_word_length': 2.7091836734693877, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1284440', 'n_tokens_mistral': 2278, 'n_tokens_neox': 2197, 'n_words': 1098}