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
@return [String] The (first) file where the application has been
defined
@return [Hash] The active configuration of the application
@return [String] The absolute path of the application
Private Instance Methods
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 usingColoredIO
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
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