Class: Clive::Base

Inherits:
Command show all
Includes:
StateActions
Defined in:
lib/clive/base.rb

Constant Summary collapse

DEFAULTS = 
{
  :name         => File.basename($0),
  :formatter    => Formatter::Colour.new,
  :help_command => true,
  :help         => true
}
GLOBAL_OPTIONS =

These options should be copied into each Command that is created.

[:name, :formatter, :help]

Instance Attribute Summary collapse

Attributes inherited from Command

#options

Attributes inherited from Option

#args, #description, #names

DSL Methods collapse

Instance Method Summary collapse

Methods included from StateActions

#get, #has?, #set, #update

Methods inherited from Command

#action, #boolean, #desc, #description, #end_group, #find_option, #footer, #group, #has?, #has_option?, #header, #help, #name, #option, #run_block, #to_s

Methods inherited from Option

#<=>, #block?, #inspect, long, #name, short, #to_s

Constructor Details

#initialize(config = {}, &block) ⇒ Base

You don’t need to create an instance of this, create a class extending Clive or call Clive.new instead.

Parameters:

  • config (Hash) (defaults to: {}) —

    Options to set for this Base, see #run for details of the keys that can be passed.



21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/clive/base.rb', line 21

def initialize(config={}, &block)
  super([], config, &block)

  @commands = []
  @header   = proc { "Usage: #{@config[:name]} [command] [options]" }
  @footer   = ""
  @_group   = nil
  @config   = DEFAULTS.merge(get_subhash(config, DEFAULTS.keys))

  # Need to keep a state before #run is called so #set works.
  @state = {}
  instance_exec &block if block
end

Instance Attribute Details

#commands ⇒ Object (readonly)

Returns the value of attribute commands.



4
5
6
 
# File 'lib/clive/base.rb', line 4

def commands
  @commands
end

Instance Method Details

#command(*names, description = current_desc, opts = {}, &block) ⇒ Object

Examples:


class CLI
  desc 'Creates a new thing'
  command :create, arg: '<thing>' do
    # ...
  end
end

Creates a new Command. @param names [Array<Symbol>] Names that the command can be called with. @param description [String] Description of the command. @param opts [Hash] Options to be passed to the new Command, see Command#initialize.



78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/clive/base.rb', line 78

def command(*args, &block)
  ns, d, o = [], current_desc, {}
  args.each do |i|
    case i
      when ::Symbol then ns << i
      when ::String then d = i
      when ::Hash   then o = i
    end
  end
  o = DEFAULTS.merge(Hash[global_opts]).merge(o)
  @commands << Command.new(ns, d, o.merge({:group => @_group}), &block)
end

#config(opts = nil) ⇒ Object

Set configuration values for the base, as if you passed an options hash to #initialize.

Examples:


config arg: '<dir>'

Parameters:

  • See (Hash) —

    #initialize



101
102
103
104
105
106
107
 
# File 'lib/clive/base.rb', line 101

def config(opts=nil)
  if opts
    @config = @config.merge(get_subhash(opts, DEFAULTS.keys))
  else
    @config
  end
end

#find(arg) ⇒ Object

Finds the option or command represented by arg, this can the name of a command or an option which should include the correct number of dashes. If the option or command cannot be found nil is returned.

Examples:


c = Clive.new {
  command :new
  opt :v, :version
}

c.find('-v')
#=> #<Clive::Option -v, --version>
c.find('new')
#=> #<Clive::Command new>
c.find('test')
#=> nil

Parameters:

See Also:



131
132
133
134
135
136
137
 
# File 'lib/clive/base.rb', line 131

def find(arg)
  if arg[0..0] == '-'
    super
  else
    find_command(arg.to_sym)
  end
end

#find_command(arg) ⇒ Object

Finds the command with the name given, if the command cannot be found returns nil.

Examples:


c = Clive.new {
  command :new
}

c.find_command(:new)
#=> #<Clive::Command new>

Parameters:

  • arg (Symbol, nil) 


152
153
154
 
# File 'lib/clive/base.rb', line 152

def find_command(arg)
  @commands.find {|i| i.names.include?(arg) }
end

#has_command?(arg) ⇒ Boolean

Attempts to find the command with the name given, returns true if the command exits.

Examples:


c = Clive.new {
  command :new
}

c.has_command? :new     #=> true
c.has_command? :create  #=> false

Parameters:

  • arg (Symbol)

Returns:

  • (Boolean) 


169
170
171
 
# File 'lib/clive/base.rb', line 169

def has_command?(arg)
  !!find_command(arg)
end

#run(args = ARGV, config = {}) ⇒ Object

Runs the Clive with the args passed which defaults to ARGV.

Parameters:

  • args (Array<String>) (defaults to: ARGV) —

    Command line arguments to run with

  • config (Hash) (defaults to: {})

Options Hash (config):

  • :help (Boolean) —

    Whether to create a help option.

  • :help_command (Boolean) —

    Whether to create a help command.

  • :formatter (Formatter) —

    Help formatter to use.

  • :name (String) —

    Name to use in headers, this is usually better than setting a header as commands will use this to generate their own headers for use in help.



51
52
53
54
55
56
57
58
 
# File 'lib/clive/base.rb', line 51

def run(args=ARGV, config={})
  @config = @config.merge(get_subhash(config, DEFAULTS.keys))

  add_help_option
  add_help_command

  Clive::Parser.new(self, config).parse(args, @state)
end