Module: Rubikon::Application::DSLMethods

Included in:
Base
Defined in:
lib/rubikon/application/dsl_methods.rb

Overview

This module contains all DSL-related instance methods of Application::Base and its subclasses. The methods of this module may be used to define and enhance a Rubikon application.

See Also:

Author:

  • Sebastian Staudt

Since:

  • 0.3.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#base_file ⇒ String (readonly)

Returns The (first) file where the application has been defined.

Returns:

  • (String) —

    The (first) file where the application has been defined

Since:

  • 0.3.0



23
24
25
 
# File 'lib/rubikon/application/dsl_methods.rb', line 23

def base_file
  @base_file
end

#config ⇒ Hash (readonly)

Returns The active configuration of the application.

Returns:

  • (Hash) —

    The active configuration of the application

Since:

  • 0.3.0



26
27
28
 
# File 'lib/rubikon/application/dsl_methods.rb', line 26

def config
  @config
end

#path ⇒ String (readonly)

Returns The absolute path of the application.

Returns:

  • (String) —

    The absolute path of the application

Since:

  • 0.3.0



29
30
31
 
# File 'lib/rubikon/application/dsl_methods.rb', line 29

def path
  @path
end

Instance Method Details

#active?(name) ⇒ Boolean (private) Also known as: given?

Checks whether parameter with the given name has been supplied by the user on the command-line.

Examples:

flag :status
command :something do
  print_status if active? :status
end

Parameters:

  • name (#to_sym) —

    The name of the parameter to check

Returns:

  • (Boolean)

See Also:

Since:

  • 0.2.0



45
46
47
48
49
50
51
 
# File 'lib/rubikon/application/dsl_methods.rb', line 45

def active?(name)
  name = name.to_sym
  parameter = @global_parameters[name]
  parameter = @current_command.parameters[name] if parameter.nil?
  return false if parameter.nil?
  parameter.send(:active?)
end

#call(command_name, *args) ⇒ Object (private)

Call another named command with the given arguments

Parameters:

  • command_name (Symbol) —

    The name of the command to call

  • args (Array<String>) —

    The arguments to pass to the called command

See Also:

Since:

  • 0.3.0



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/rubikon/application/dsl_methods.rb', line 60

def call(command_name, *args)
  args.extend ArgumentVector
  current_command = @current_command
  current_param   = @current_param

  @current_command = @commands[command_name]
  args.params!(@current_command.params).each do |param|
    @current_param = param
    param.send :active!
    @current_param = nil
  end
  @current_command.send :run
  @current_command = current_command
  @current_param   = current_param
end

#command(name, *options, &block) ⇒ Command (private)

Define a new application Command or an alias to an existing one

Parameters:

  • name (String, Hash) —

    The name of the Command as used in application parameters. This might also be a Hash where every key will be an alias to the corresponding value, e.g. { :alias => :command }.

  • block (Proc) —

    A block that contains the code that should be executed when this Command is called, i.e. when the application is called with the associated parameter

  • options (Array) —

    A range allows any number of arguments inside the limits of the range or array (-1 stands for an arbitrary number of arguments). A positive number indicates the exact amount of required arguments while a negative argument count indicates the amount of required arguments, but allows additional, optional arguments. A argument count of 0 means there are no required arguments, but it allows optional arguments. An array of symbols enables named arguments where the argument count is the size of the array and each argument is named after the corresponding symbol. Finally a hash may be used to specify options for named arguments. The keys of the hash will be the names of the arguments and the values are options for this argument. You may specify multiple options as an array. Possible options are:

    • :optional makes the argument optional
    • :remainder makes the argument take all remaining arguments as an array
    • One or more strings will cause the argument to be checked to be equal to one of the strings
    • One or more regular expressions will cause the argument to be checked to match one of the expressions
    • Other symbols may reference to a predefined regular expression from ARGUMENT_MATCHERS

Returns:

See Also:

Since:

  • 0.2.0



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/rubikon/application/dsl_methods.rb', line 91

def command(name, *options, &block)
  command = nil

  if name.is_a? Hash
    name.each do |alias_name, command_name|
      command = @commands[command_name]
      if command.nil?
        @commands[alias_name] = command_name
      else
        command.aliases << alias_name
        @commands[alias_name] = command
      end
    end
  else
    command = Command.new(self, name, *options, &block)
    @commands.each do |command_alias, command_name|
      if command_name == command.name
        @commands[command_alias] = command
        command.aliases << command_alias
      end
    end
    @commands[command.name] = command
  end

  unless command.nil? || @parameters.empty?
    @parameters.each do |parameter|
      command.send(:add_param, parameter)
    end
    @parameters.clear
  end

  command
end

#debug(message) ⇒ Object (private)

Prints a debug message if $DEBUG is true, e.g. if the user supplied the --debug (-d) flag.

Since:

  • 0.2.0



129
130
131
 
# File 'lib/rubikon/application/dsl_methods.rb', line 129

def debug(message)
  ostream.puts message if $DEBUG
end

#default(*options, &block) ⇒ Command (private)

Define the default Command of the application, i.e. the Command that is called if no matching Command parameter can be found

Examples:

Define a default command with an argument

default 'This is the default', :arg do
  ...
end

Use another command as default

default :other_command

Parameters:

  • block (Proc) —

    A block that contains the code that should be executed when this Command is called, i.e. when no command parameter is given to the application

  • options (Array) —

    A range allows any number of arguments inside the limits of the range or array (-1 stands for an arbitrary number of arguments). A positive number indicates the exact amount of required arguments while a negative argument count indicates the amount of required arguments, but allows additional, optional arguments. A argument count of 0 means there are no required arguments, but it allows optional arguments. An array of symbols enables named arguments where the argument count is the size of the array and each argument is named after the corresponding symbol. Finally a hash may be used to specify options for named arguments. The keys of the hash will be the names of the arguments and the values are options for this argument. You may specify multiple options as an array. Possible options are:

    • :optional makes the argument optional
    • :remainder makes the argument take all remaining arguments as an array
    • One or more strings will cause the argument to be checked to be equal to one of the strings
    • One or more regular expressions will cause the argument to be checked to match one of the expressions
    • Other symbols may reference to a predefined regular expression from ARGUMENT_MATCHERS

Returns:

  • (Command) —

    The default Command object

See Also:

Since:

  • 0.2.0



153
154
155
156
157
158
159
 
# File 'lib/rubikon/application/dsl_methods.rb', line 153

def default(*options, &block)
  if options.size == 1 && options.first.is_a?(Symbol) && !block_given?
    command :__default => options.first
  else
    command :__default, *options, &block
  end
end

#default_config=(config) ⇒ Object (private)

Set the default configuration for this application

Parameters:

  • config (Hash) —

    The default configuration to use

See Also:

Since:

  • 0.6.0



166
167
168
169
170
171
172
 
# File 'lib/rubikon/application/dsl_methods.rb', line 166

def default_config=(config)
  unless config.is_a? Hash
    raise ArgumentError.new('Configuration has to be a Hash')
  end

  @default_config = config
end

#error(text = nil) ⇒ Object (private)

Output a line of text using IO#puts of the error output stream

Parameters:

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

    The text to write into the error output stream

Since:

  • 0.6.0



178
179
180
 
# File 'lib/rubikon/application/dsl_methods.rb', line 178

def error(text = nil)
  estream.puts text
end

#estream ⇒ IO (private)

Convenience method for accessing the user-defined error output stream

Use this if you want to work directly with the error output stream

Examples:

estream.flush

Returns:

  • (IO) —

    The error output stream object - usually $stderr

Since:

  • 0.6.0



191
192
193
 
# File 'lib/rubikon/application/dsl_methods.rb', line 191

def estream
  @settings[:estream]
end

#flag(name, description = nil, &block) ⇒ Object (private)

Create a new Flag with the given name for the next Command

Examples:

flag :status
flag :st => :status
command :something do
  ...
end

Parameters:

  • name (Symbol, #to_sym) —

    The name of the flag (without dashes). Dashes will be automatically added (- for single-character flags, -- for other flags). This might also be a Hash where every key will be an alias to the corresponding value, e.g. { :alias => :flag }.

  • block (Proc) —

    An optional code block that should be executed if this flag is used

Since:

  • 0.2.0



212
213
214
215
216
217
218
219
220
 
# File 'lib/rubikon/application/dsl_methods.rb', line 212

def flag(name, description = nil, &block)
  if name.is_a? Hash
    @parameters << name
  else
    flag = Flag.new(self, name, &block)
    flag.description = description unless description.nil?
    @parameters << flag
  end
end

#global_flag(name, description = nil, &block) ⇒ Object (private)

Create a new flag with the given name to be used globally

Global flags are not bound to any command and can therefore be used throughout the application with the same result.

Examples:

Define a global flag

global_flag :quiet

Define a global flag with a block to execute

global_flag :quiet do
  @quiet = true
end

Define an alias to a global flag

global_flag :q => :quiet

Parameters:

  • name (Symbol, #to_sym) —

    The name of the flag (without dashes). Dashes will be automatically added (- for single-character flags, -- for other flags). This might also be a Hash where every key will be an alias to the corresponding value, e.g. { :alias => :flag }.

  • block (Proc) —

    An optional code block that should be executed if this flag is used

See Also:

Since:

  • 0.2.0



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/rubikon/application/dsl_methods.rb', line 240

def global_flag(name, description = nil, &block)
  if name.is_a? Hash
    name.each do |alias_name, flag_name|
      flag = @global_parameters[flag_name]
      if flag.nil?
        @global_parameters[alias_name] = flag_name
      else
        flag.aliases << alias_name
        @global_parameters[alias_name] = flag
      end
    end
  else
    flag = Flag.new(self, name, &block)
    flag.description = description unless description.nil?
    @global_parameters.each do |flag_alias, flag_name|
      if flag_name == flag.name
        @global_parameters[flag_alias] = flag
        flag.aliases << flag_alias
      end
    end
    @global_parameters[flag.name] = flag
  end
end

#global_option(name, *options, &block) ⇒ Object (private)

Create a new option with the given name to be used globally

Global options are not bound to any command and can therefore be used throughout the application with the same result.

Examples:

Define a global option with an optional argument

global_option :user, :login => :optional

Define a global option with an argument and a block to execute

global_option :user, :login do
  @user = 
end

Define an alias to a global option

global_option :u => :user

Parameters:

  • name (Symbol, #to_sym) —

    The name of the Option (without dashes). Dashes will be automatically added (+-+ for single-character options, -- for other options). This might also be a Hash where every key will be an alias to the corresponding value, e.g. { :alias => :option }.

  • block (Proc) —

    An optional code block that should be executed if this option is used

  • options (Array) —

    A range allows any number of arguments inside the limits of the range or array (-1 stands for an arbitrary number of arguments). A positive number indicates the exact amount of required arguments while a negative argument count indicates the amount of required arguments, but allows additional, optional arguments. A argument count of 0 means there are no required arguments, but it allows optional arguments. An array of symbols enables named arguments where the argument count is the size of the array and each argument is named after the corresponding symbol. Finally a hash may be used to specify options for named arguments. The keys of the hash will be the names of the arguments and the values are options for this argument. You may specify multiple options as an array. Possible options are:

    • :optional makes the argument optional
    • :remainder makes the argument take all remaining arguments as an array
    • One or more strings will cause the argument to be checked to be equal to one of the strings
    • One or more regular expressions will cause the argument to be checked to match one of the expressions
    • Other symbols may reference to a predefined regular expression from ARGUMENT_MATCHERS

See Also:

Since:

  • 0.2.0



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/rubikon/application/dsl_methods.rb', line 282

def global_option(name, *options, &block)
  if name.is_a? Hash
    name.each do |alias_name, option_name|
      option = @global_parameters[option_name]
      if option.nil?
        @global_parameters[alias_name] = option_name
      else
        option.aliases << alias_name
        @global_parameters[alias_name] = option
      end
    end
  else
    option = Option.new(self, name, *options, &block)
    @global_parameters.each do |option_alias, option_name|
      if option_name == option.name
        @global_parameters[option_alias] = option
        option.aliases << option_alias
      end
    end
    @global_parameters[option.name] = option
  end
end

#input(prompt = '', *expected) ⇒ Object (private)

Prompts the user for input

Examples:

Display a prompt "Please type something: "

command 'interactive' do
  user_provided_value = input 'Please type something'

  # Do something with the data
  ...
end

Display a question with validated input

command :question do
  good = input 'Do you feel good', 'y', 'n'
  ...
end

Parameters:

  • prompt (String, #to_s) (defaults to: '') —

    A String or other Object responding to to_s used for displaying a prompt to the user

  • expected (Array<String>) —

    A list of strings that are accepted as valid input. If not empty, input will be checked and the prompt will be repeated if required.

Since:

  • 0.2.0



327
328
329
330
331
332
333
334
335
 
# File 'lib/rubikon/application/dsl_methods.rb', line 327

def input(prompt = '', *expected)
  prompt << " [#{expected.join '/'}]" unless expected.empty?
  ostream << "#{prompt}: " unless prompt.to_s.empty?
  input = @settings[:istream].gets[0..-2]
  unless expected.empty? || expected.include?(input)
    input = input 'Please provide valid input', *expected
  end
  input
end

#option(name, *options, &block) ⇒ Object (private)

Create a new Option with the given name for the next Command

Examples:

Define an option (and its alias) to a command

option :message, 'A message', :text
option :m => :message
command :something do
  puts message.text
end

Parameters:

  • name (Symbol, #to_sym) —

    The name of the Option (without dashes). Dashes will be automatically added (+-+ for single-character options, -- for other options). This might also be a Hash where every key will be an alias to the corresponding value, e.g. { :alias => :option }.

  • block (Proc) —

    An optional code block that should be executed if this option is used

  • options (Array) —

    A range allows any number of arguments inside the limits of the range or array (-1 stands for an arbitrary number of arguments). A positive number indicates the exact amount of required arguments while a negative argument count indicates the amount of required arguments, but allows additional, optional arguments. A argument count of 0 means there are no required arguments, but it allows optional arguments. An array of symbols enables named arguments where the argument count is the size of the array and each argument is named after the corresponding symbol. Finally a hash may be used to specify options for named arguments. The keys of the hash will be the names of the arguments and the values are options for this argument. You may specify multiple options as an array. Possible options are:

    • :optional makes the argument optional
    • :remainder makes the argument take all remaining arguments as an array
    • One or more strings will cause the argument to be checked to be equal to one of the strings
    • One or more regular expressions will cause the argument to be checked to match one of the expressions
    • Other symbols may reference to a predefined regular expression from ARGUMENT_MATCHERS

See Also:

Since:

  • 0.2.0



356
357
358
359
360
361
362
363
 
# File 'lib/rubikon/application/dsl_methods.rb', line 356

def option(name, *options, &block)
  if name.is_a? Hash
    @parameters << name
  else
    option = Option.new(self, name.to_s, *options, &block)
    @parameters << option
  end
end

#ostream ⇒ IO (private)

Convenience method for accessing the user-defined output stream

Use this if you want to work directly with the output stream

Examples:

ostream.flush

Returns:

  • (IO) —

    The output stream object - usually $stdout

Since:

  • 0.2.0



374
375
376
 
# File 'lib/rubikon/application/dsl_methods.rb', line 374

def ostream
  @settings[:ostream]
end

#post_execute(&block) ⇒ Object (private)

Defines a block of code used as a hook that should be executed after the command execution has finished

Parameters:

  • The (Proc) —

    code block to execute after the command execution has finished

Since:

  • 0.4.0



384
385
386
 
# File 'lib/rubikon/application/dsl_methods.rb', line 384

def post_execute(&block)
  @hooks[:post_execute] = block
end

#post_init(&block) ⇒ Object (private)

Defines a block of code used as a hook that should be executed after the application has been initialized

Parameters:

  • The (Proc) —

    code block to execute after the application has been initialized

Since:

  • 0.4.0



394
395
396
 
# File 'lib/rubikon/application/dsl_methods.rb', line 394

def post_init(&block)
  @hooks[:post_init] = block
end

#pre_execute(&block) ⇒ Object (private)

Defines a block of code used as a hook that should be executed before the command has been started

Parameters:

  • The (Proc) —

    code block to execute before the command has been started

Since:

  • 0.4.0



404
405
406
 
# File 'lib/rubikon/application/dsl_methods.rb', line 404

def pre_execute(&block)
  @hooks[:pre_execute] = block
end

#pre_init(&block) ⇒ Object (private)

Defines a block of code used as a hook that should be executed before the application has been initialized

Parameters:

  • The (Proc) —

    code block to execute before the application has been initialized

Since:

  • 0.4.0



414
415
416
 
# File 'lib/rubikon/application/dsl_methods.rb', line 414

def pre_init(&block)
  @hooks[:pre_init] = block
end

#progress_bar(*options, &block) {|ProgressBar| ... } ⇒ Object (private)

Displays a progress bar while the given block is executed

Inside the block you have access to a instance of ProgressBar. So you can update the progress using ProgressBar#+.

Examples:

progress_bar(:maximum => 5) do |progress|
  5.times do |file|
    File.read("any#{file}.txt")
    progress.+
  end
end

Parameters:

  • options (Hash) —

    A Hash of options that should be passed to the ProgressBar object.

  • block (Proc) —

    The block to execute

Yields:

  • (ProgressBar) —

    The given block may be used to change the values of the progress bar

Yield Parameters:

  • progress (ProgressBar) —

    The progress bar indicating the progress of the block

See Also:

Since:

  • 0.2.0



441
442
443
444
445
446
447
448
449
450
 
# File 'lib/rubikon/application/dsl_methods.rb', line 441

def progress_bar(*options, &block)
  hidden_output do |ostream|
    options = options[0]
    options[:ostream] = ostream

    progress = ProgressBar.new(options)

    block.call(progress)
  end
end

#put(text) ⇒ Object (private)

Output text using IO#<< of the output stream

Parameters:

  • text (String) —

    The text to write into the output stream

Since:

  • 0.2.0



456
457
458
459
 
# File 'lib/rubikon/application/dsl_methods.rb', line 456

def put(text)
  ostream << text
  ostream.flush
end

#putc(char) ⇒ Object (private)

Output a character using IO#putc of the output stream

Parameters:

  • char (String, Numeric) —

    The character to write into the output stream

Since:

  • 0.2.0



466
467
468
 
# File 'lib/rubikon/application/dsl_methods.rb', line 466

def putc(char)
  ostream.putc char
end

#puts(text = nil) ⇒ Object (private)

Output a line of text using IO#puts of the output stream

Parameters:

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

    The text to write into the output stream

Since:

  • 0.2.0



474
475
476
 
# File 'lib/rubikon/application/dsl_methods.rb', line 474

def puts(text = nil)
  ostream.puts text
end

#save_config(scope = :user) ⇒ Object (private)

Saves the current configuration into a configuration file

The file name and format are specified in the application settings.

Parameters:

  • Either (:global, :local, :user, String) —

    one of the default scopes or a specific path. The scopes map to a special path. On UNIX systems this is /etc for global configurations, the user's home directory (+~+) for user configurations and the current working directory (+.+) for local configurations.

See Also:

Since:

  • 0.6.0



523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
 
# File 'lib/rubikon/application/dsl_methods.rb', line 523

def save_config(scope = :user)
  case scope
    when :global
      if RUBY_PLATFORM.downcase =~ /mswin(?!ce)|mingw|bccwin/
        path = ENV['ALLUSERSPROFILE']
      else
        path = '/etc'
      end
    when :local
      path = File.expand_path '.'
    when :user
      path = File.expand_path '~'
    else
      path = scope
  end

  @config_factory.save_config @config,
    File.join(path, @settings[:config_file])
end

#set(setting, value) ⇒ Object (private)

Sets an application setting

Available settings

autorun

If true, let the application run as soon as its class is defined. This is generally useful for simple "code and run" applications.

colors

If true, enables colored output using ColoredIO

config_file

The name of the config file to search

config_paths

The paths to search for config files

estream

Defines an error output stream to use

help_banner

Defines a banner for the help message

istream

Defines an input stream to use

name

Defines the name of the application

ostream

Defines an output stream to use

raise_errors

If true, raise errors, otherwise fail gracefully

Examples:

set :name, 'My App'
set :autorun, false

Parameters:

  • setting (Symbol, #to_sym) —

    The name of the setting to change

  • value (Object) —

    The value the setting should be changed to

Since:

  • 0.2.0



501
502
503
504
505
506
507
508
509
510
 
# File 'lib/rubikon/application/dsl_methods.rb', line 501

def set(setting, value)
  setting = setting.to_sym
  if setting == :estream
    self.estream = value
  elsif setting == :ostream
    self.ostream = value
  else
    @settings[setting.to_sym] = value
  end
end

#throbber(&block) { ... } ⇒ Object (private)

Displays a throbber while the given block is executed

Examples:

Using the throbber helper

command :slow do
  throbber do
    # Add some long running code here
    ...
  end
end

Parameters:

  • block (Proc) —

    The block to execute while the throbber is displayed

Yields:

  • While the block is executed a throbber is displayed

See Also:

Since:

  • 0.2.0



558
559
560
561
562
563
564
565
566
 
# File 'lib/rubikon/application/dsl_methods.rb', line 558

def throbber(&block)
  hidden_output do |ostream|
    code_thread = Thread.new { block.call }
    throbber_thread = Throbber.new(ostream, code_thread)

    code_thread.join
    throbber_thread.join
  end
end