module Rubikon::Application::DSLMethods

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.

@author Sebastian Staudt @see Application::Base @since 0.3.0

Attributes

base_file[R]

@return [String] The (first) file where the application has been

defined
config[R]

@return [Hash] The active configuration of the application

path[R]

@return [String] The absolute path of the application

Private Instance Methods

active?(name) click to toggle source

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

@param [#to_sym] name The name of the parameter to check @see Parameter @since 0.2.0

@example

flag :status
command :something do
  print_status if active? :status
end
# 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
Also aliased as: given?
call(command_name, *args) click to toggle source

Call another named command with the given arguments

@param [Symbol] command_name The name of the command to call @param [Array<String>] args The arguments to pass to the called command @see ArgumentVector#params! @see Command#run

# 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) click to toggle source

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

@param [String, Hash] name 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. <tt>{
:alias => :command }</tt>.

@param options (see HasArguments#initialize) @param [Proc] block 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

@return [Command] @see default @see Command @since 0.2.0

# 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) click to toggle source

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

@since 0.2.0

# File lib/rubikon/application/dsl_methods.rb, line 129
def debug(message)
  ostream.puts message if $DEBUG
end
default(*options, &block) click to toggle source

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

@param options (see HasArguments#initialize) @param [Proc] block 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

@return [Command] The default Command object @see Command @see command @since 0.2.0

@example Define a default command with an argument

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

@example Use another command as default

default :other_command
# 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) click to toggle source

Set the default configuration for this application

@param [Hash] config The default configuration to use @see config @since 0.6.0

# 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) click to toggle source

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

@param [String] text The text to write into the error output stream @since 0.6.0

# File lib/rubikon/application/dsl_methods.rb, line 178
def error(text = nil)
  estream.puts text
end
estream() click to toggle source

Convenience method for accessing the user-defined error output stream

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

@return [IO] The error output stream object - usually +$stderr+ @since 0.6.0

@example

estream.flush
# File lib/rubikon/application/dsl_methods.rb, line 191
def estream
  @settings[:estream]
end
flag(name, description = nil, &block) click to toggle source

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

@param [Symbol, to_sym] name The name of the flag (without dashes).

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

@param [Proc] block An optional code block that should be executed if

this flag is used

@since 0.2.0

@example

flag :status
flag :st => :status
command :something do
  ...
end
# 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
given?(name)
Alias for: active?
global_flag(name, description = nil, &block) click to toggle source

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.

@param (see flag) @see flag @see Flag @since 0.2.0

@example Define a global flag

global_flag :quiet

@example Define a global flag with a block to execute

global_flag :quiet do
  @quiet = true
end

@example Define an alias to a global flag

global_flag :q => :quiet
# 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) click to toggle source

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.

@param (see option) @see option @see Option @since 0.2.0

@example Define a global option with an optional argument

global_option :user, :login => :optional

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

global_option :user, :login do
  @user = login
end

@example Define an alias to a global option

global_option :u => :user
# 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) click to toggle source

Prompts the user for input

@param [String, to_s] prompt A String or other Object responding to

+to_s+ used for displaying a prompt to the user

@param [Array<String>] expected 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

@example Display a prompt “Please type something: ”

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

  # Do something with the data
  ...
end

@example Display a question with validated input

command :question do
  good = input 'Do you feel good', 'y', 'n'
  ...
end
# 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) click to toggle source

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

@param [Symbol, to_sym] name 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. <tt>{ :alias => :option }</tt>.

@param options (see HasArguments#initialize) @param [Proc] block An optional code block that should be executed if

this option is used

@see Option @since 0.2.0

@example Define an option (and its alias) to a command

option :message, 'A message', :text
option :m => :message
command :something do
  puts message.text
end
# 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() click to toggle source

Convenience method for accessing the user-defined output stream

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

@return [IO] The output stream object - usually +$stdout+ @since 0.2.0

@example

ostream.flush
# File lib/rubikon/application/dsl_methods.rb, line 374
def ostream
  @settings[:ostream]
end
post_execute(&block) click to toggle source

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

@param [Proc] The code block to execute after the command execution has

finished

@since 0.4.0

# File lib/rubikon/application/dsl_methods.rb, line 384
def post_execute(&block)
  @hooks[:post_execute] = block
end
post_init(&block) click to toggle source

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

@param [Proc] The code block to execute after the application has been

initialized

@since 0.4.0

# File lib/rubikon/application/dsl_methods.rb, line 394
def post_init(&block)
  @hooks[:post_init] = block
end
pre_execute(&block) click to toggle source

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

@param [Proc] The code block to execute before the command has been

started

@since 0.4.0

# File lib/rubikon/application/dsl_methods.rb, line 404
def pre_execute(&block)
  @hooks[:pre_execute] = block
end
pre_init(&block) click to toggle source

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

@param [Proc] The code block to execute before the application has been

initialized

@since 0.4.0

# File lib/rubikon/application/dsl_methods.rb, line 414
def pre_init(&block)
  @hooks[:pre_init] = block
end
progress_bar(*options, &block) click to toggle source

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#+.

@param [Hash] options A Hash of options that should be passed to the

ProgressBar object.

@param [Proc] block The block to execute @yield [ProgressBar] The given block may be used to change the values

of the progress bar

@yieldparam [ProgressBar] progress The progress bar indicating the

progress of the block

@example

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

@see ProgressBar @since 0.2.0

# 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) click to toggle source

Output text using +IO#<<+ of the output stream

@param [String] text The text to write into the output stream @since 0.2.0

# File lib/rubikon/application/dsl_methods.rb, line 456
def put(text)
  ostream << text
  ostream.flush
end
putc(char) click to toggle source

Output a character using +IO#putc+ of the output stream

@param [String, Numeric] char The character to write into the output

stream

@since 0.2.0

# File lib/rubikon/application/dsl_methods.rb, line 466
def putc(char)
  ostream.putc char
end
puts(text = nil) click to toggle source

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

@param [String] text The text to write into the output stream @since 0.2.0

# File lib/rubikon/application/dsl_methods.rb, line 474
def puts(text = nil)
  ostream.puts text
end
save_config(scope = :user) click to toggle source

Saves the current configuration into a configuration file

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

@param [:global, :local, :user, String] Either 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 default_config= @since 0.6.0

# 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) click to toggle source

Sets an application setting

@param [Symbol, to_sym] setting The name of the setting to change @param [Object] value The value the setting should be changed to @since 0.2.0

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

@example

set :name, 'My App'
set :autorun, false
# 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) click to toggle source

Displays a throbber while the given block is executed

@param [Proc] block The block to execute while the throbber is

displayed

@see Throbber @since 0.2.0 @yield While the block is executed a throbber is displayed

@example Using the throbber helper

command :slow do
  throbber do
    # Add some long running code here
    ...
  end
end
# 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