Module: Quickl

Defined in:
lib/quickl.rb,
lib/quickl/errors.rb,
lib/quickl/naming.rb,
lib/quickl/command.rb,
lib/quickl/version.rb,
lib/quickl/ruby_tools.rb,
lib/quickl/command/single.rb,
lib/quickl/command/builder.rb,
lib/quickl/command/options.rb,
lib/quickl/command/delegator.rb,
lib/quickl/command/class_methods.rb,
lib/quickl/command/instance_methods.rb

Defined Under Namespace

Modules: Naming, RubyTools, Version Classes: Command, Error, Exit, Help, IOAccessError, InvalidArgument, InvalidOption, NoSuchCommand

Constant Summary collapse 

"(c) 2010-2011, Bernard Lambeau"
VERSION = 
Version.to_s

Class Method Summary collapse

Class Method Details

.build_command(command) ⇒ Object

Builds command using the current builder.

The current command builder is considered consumed and removed as a side effect. A RuntimeError is raised if no builder is currently installed.

Returns the command itself.

This method is part of Quickl’s private interface.



46
47
48
49
50
51
52
53
54
 
# File 'lib/quickl.rb', line 46

def self.build_command(command)
  unless @builder
    raise "No command builder currently installed"
  else
    @builder.run(command)
    @builder = nil
    command
  end
end

.Command(*args) ⇒ Object

Create a single command



17
18
19
20
21
22
23
24
 
# File 'lib/quickl/command/single.rb', line 17

def self.Command(*args)
  command_builder do |b|
    b.document(*args) unless args.empty?
    b.instance_module(Command::Single)
    yield(b) if block_given?
  end
  Command
end

.command_builder {|@builder| ... } ⇒ Object

Yields the block with the current command builder. A fresh new builder is created if not already done.

This method is part of Quickl’s private interface.

Yields:

  • (@builder) 


29
30
31
32
33
 
# File 'lib/quickl.rb', line 29

def self.command_builder 
  @builder ||= Command::Builder.new
  yield @builder if block_given?
  @builder
end

.command_class(cmd) ⇒ Object

When ‘cmd` is a class, returns it. When a command instance, returns `cmd.class`. Otherwise, raises an ArgumentError.



67
68
69
70
71
72
73
74
75
76
 
# File 'lib/quickl.rb', line 67

def self.command_class(cmd)
  case cmd
  when Class
    cmd
  when Command
    cmd.class
  else
    raise ArgumentError, "Not a recognized command #{cmd}"
  end
end

.command_name(cmd) ⇒ Object

Convenient method for command_class(cmd).command_name



106
107
108
 
# File 'lib/quickl.rb', line 106

def self.command_name(cmd)
  command_class(cmd).command_name
end

.Delegate(*args, &block) ⇒ Object

See Also:



67
68
69
 
# File 'lib/quickl/command/delegator.rb', line 67

def self.Delegate(*args, &block)
  self.Delegator(*args, &block)
end

.Delegator(*args) ⇒ Object

Create a delegator command



56
57
58
59
60
61
62
63
64
 
# File 'lib/quickl/command/delegator.rb', line 56

def self.Delegator(*args)
  command_builder do |b|
    b.document(*args) unless args.empty?
    b.class_module(Command::Delegator::ClassMethods)
    b.instance_module(Command::Delegator::InstanceMethods)
    yield(b) if block_given?
  end
  Command
end

.deprecated(who, instead, caller) ⇒ Object

Prints a deprecation message on STDERR if $VERBOSE is set to true



16
17
18
19
20
21
 
# File 'lib/quickl.rb', line 16

def self.deprecated(who, instead, caller)
  if $VERBOSE
    STDERR << "WARN (Quickl): #{who} is deprecated, use #{instead} "\
              "(#{caller.first})\n"
  end
end

.documentation(cmd, opts = {}) ⇒ Object

Convenient method for command_class(cmd).documentation



127
128
129
 
# File 'lib/quickl.rb', line 127

def self.documentation(cmd, opts = {})
  command_class(cmd).documentation(opts)
end

.help(cmd, opts = {}) ⇒ Object

Alias for documentation



134
135
136
 
# File 'lib/quickl.rb', line 134

def self.help(cmd, opts = {})
  command_class(cmd).help(opts)
end

.overview(cmd) ⇒ Object

Convenient method for command_class(cmd).overview



120
121
122
 
# File 'lib/quickl.rb', line 120

def self.overview(cmd)
  command_class(cmd).overview
end

.parse_commandline_args(args) ⇒ Object

Parse a string with commandline arguments and returns an array.

Example:

parse_commandline_args("--text --size=10") # => ['--text', '--size=10']



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/quickl.rb', line 165

def self.parse_commandline_args(args)
  args = args.split(/\s+/)
  result = []
  until args.empty?
    quote = ['"', "'"].find{|q| q == args.first[0,1]}
    if quote
      if args.first[-1,1] == quote
        result << args.shift[1...-1]
      else
        block = [ args.shift[1..-1] ]
        while args.first[-1,1] != quote
          block << args.shift
        end 
        block << args.shift[0...-1]
        result << block.join(" ")
      end
    else
      result << args.shift
    end  
  end
  result
end

.program_name ⇒ Object

Convenient method for File.basename($0)



59
60
61
 
# File 'lib/quickl.rb', line 59

def self.program_name
  File.basename($0)
end

.split_commandline_args(args, separator = '--') ⇒ Object

Splits an array ‘args` a separator, the option separator ’–‘ by default.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/quickl.rb', line 192

def self.split_commandline_args(args, separator = '--')
  args = args.dup
  result, current = [], []
  until args.empty?
    if (x = args.shift) == separator
      result << current
      current = []
    else
      current << x
    end
  end
  result << current
  result
end

.sub_command(cmd, name) ⇒ Object

Returns the subcommand of ‘cmd` which is called `name`, or nil.



88
89
90
 
# File 'lib/quickl.rb', line 88

def self.sub_command(cmd, name)
  command_class(cmd).subcommand_by_name(name)
end

.sub_command!(cmd, name) ⇒ Object

Returns the subcommand of ‘cmd` which is called `name`. Raises a NoSuchCommand if not found.



96
97
98
99
100
101
 
# File 'lib/quickl.rb', line 96

def self.sub_command!(cmd, name)
  unless subcmd = sub_command(cmd, name)
    raise NoSuchCommand, "No such command #{name}" 
  end
  subcmd
end

.super_command(cmd) ⇒ Object

Returns the super command of ‘cmd`, or nil.



81
82
83
 
# File 'lib/quickl.rb', line 81

def self.super_command(cmd)
  command_class(cmd).super_command
end

.usage(cmd) ⇒ Object

Convenient method for command_class(cmd).usage



113
114
115
 
# File 'lib/quickl.rb', line 113

def self.usage(cmd)
  command_class(cmd).usage
end

.valid_read_file!(file, error_class = nil, msg = nil) ⇒ String

Checks that ‘file` is a readable file or raises an error. Returns `file` on success.

Parameters:

  • file (String) —

    path to a file that should exists and be readable

  • error_class (Class) (defaults to: nil) —

    the error class to use on error (Quickl::IOAccessError by default)

  • msg (String) (defaults to: nil) —

    a dedicated error message (a default one is provided)

Returns:

  • (String) —

    file on success



148
149
150
151
152
153
154
155
156
 
# File 'lib/quickl.rb', line 148

def self.valid_read_file!(file, error_class = nil, msg = nil)
  if File.file?(file) and File.readable?(file)
    file
  else
    error_class ||= Quickl::IOAccessError
    msg ||= "Not a file or not readable: #{file}"
    raise error_class, msg, caller
  end
end