rubikon 0.5.3 → 0.6.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009, Sebastian Staudt
+Copyright (c) 2009-2011, Sebastian Staudt
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

data/README.md

@@ -73,13 +73,14 @@ arguments.
 Flags and options are easily added to your application's commands using
 Rubikon's DSL:
 
-    flag :more
-    option :name, [:who]
-    command :hello do
+    flag :more, 'A flag'
+    option :name, 'An option', :who
+    command :hello, 'A command' do
       puts "Hello #{who}"
     end
 
-Please see the `samples` directory for more in detail sample applications.
+Please see the [Wiki][5] for more information on the DSL or the `samples`
+directory for more in detail sample applications.
 
 **Warning**:
 
@@ -95,13 +96,14 @@ section if you want to help to make Rubikon better.
 * Built-in methods to display progress bars and throbbers
 * Built-in support for configuration files
 * Built-in support for colored output
-* Automatic generation of a application help screen
+* Automatic generation of application and command help screens
+* User defined validation of option arguments
 
 ## Future plans
 
-* User defined type safety of option arguments
 * Improved error handling
-* Automatic generation of command help screens
+* General optimizations
+* Improved tests
 
 ## Requirements
 
@@ -149,7 +151,8 @@ LICENSE file.
 
 Follow Rubikon on Twitter [@rubikonrb](http://twitter.com/rubikonrb).
 
- [1]: http://github.com/koraktor/rubikon
- [2]: http://github.com/koraktor/rubikon/issues
+ [1]: https://github.com/koraktor/rubikon
+ [2]: https://github.com/koraktor/rubikon/issues
  [3]: http://koraktor.github.com/rubikon
- [4]: http://github.com/koraktor/rubikon/wiki/Compatibility
+ [4]: https://github.com/koraktor/rubikon/wiki/Compatibility
+ [5]: https://github.com/koraktor/rubikon/wiki

data/Rakefile

@@ -19,31 +19,12 @@ Rake::TestTask.new do |t|
 end
 
 begin
-  require 'jeweler'
+  gem 'ore-tasks', '~> 0.3.0'
+  require 'ore/tasks'
 
-  gemspec = Gem::Specification.new do |gem|
-    line = File.read('lib/rubikon.rb')[/^\s*VERSION\s*=\s*.*/]
-    gem.version = line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
-  end
-
-  # Gem specification
-  Jeweler::Tasks.new(gemspec) do |gem|
-    gem.authors = ['Sebastian Staudt']
-    gem.email = 'koraktor@gmail.com'
-    gem.description = 'A simple to use, yet powerful Ruby framework for building console-based applications.'
-    gem.date = Time.now
-    gem.files = %w(.yardopts README.md Rakefile LICENSE) + samples_files + src_files + test_files
-    gem.has_rdoc = false
-    gem.homepage = 'http://koraktor.github.com/rubikon'
-    gem.name = gem.rubyforge_project = 'rubikon'
-    gem.summary = 'Rubikon - A Ruby console app framework'
-
-    gem.add_development_dependency('jeweler')
-    gem.add_development_dependency('shoulda')
-    gem.add_development_dependency('yard')
-  end
+  Ore::Tasks.new
 rescue LoadError
-  puts 'You need Jeweler to build the gem. Install it using `gem install jeweler`.'
+  puts "Run `gem install ore-tasks` to install 'ore/tasks'."
 end
 
 begin

data/gemspec.yml

@@ -0,0 +1,17 @@
+name:        rubikon
+summary:     Rubikon - A Ruby console app framework
+description: A simple to use, yet powerful Ruby framework for building
+             console-based applications.
+
+license:  BSD
+authors:  Sebastian Staudt
+email:    koraktor@gmail.com
+homepage: http://koraktor.github.com/rubikon
+has_yard: true
+
+require_paths: lib
+
+development_dependencies:
+  shoulda:   ~> 2.11.3
+  ore-tasks: ~> 0.3.0
+  yard:      ~> 0.6.4

data/lib/core_ext/enumerable.rb

@@ -0,0 +1,27 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2010, Sebastian Staudt
+
+unless Enumerable.method_defined?(:max_by)
+
+  # Extends Ruby's own Enumrable module with method #max_by? for Ruby < 1.8.7
+  #
+  # @author Sebastian Staudt
+  # @since 0.6.0
+  module Enumerable
+
+    # Returns the object in enum that gives the maximum value from the given
+    # block.
+    #
+    # @yield [obj] The block to call on each element in the enum
+    # @yieldparam [Object] obj A single object in the enum
+    # @yieldreturn [Comparable] A value that can be compared (+<=>+) with the
+    #              values of the other objects in the enum
+    def max_by(&block)
+      max { |a , b| block.call(a) <=> block.call(b) }
+    end
+
+  end
+
+end

data/lib/rubikon.rb

@@ -1,14 +1,16 @@
 # This code is free software; you can redistribute it and/or modify it under
 # the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
 libdir = File.dirname(__FILE__)
 $:.unshift(libdir) unless $:.include?(libdir)
 
+require 'core_ext/enumerable'
 require 'core_ext/object'
 require 'core_ext/string'
 require 'rubikon/application/base'
+require 'rubikon/version'
 
 # Rubikon is a simple to use, yet powerful Ruby framework for building
 # console-based applications. Rubikon aims to provide an easy to write and easy
@@ -22,8 +24,4 @@ require 'rubikon/application/base'
 # @author Sebastian Staudt
 # @since 0.1.0
 module Rubikon
-
-  # This is the current version of the Rubikon gem
-  VERSION = '0.5.3'
-
 end

data/lib/rubikon/application/dsl_methods.rb

@@ -1,7 +1,9 @@
 # This code is free software; you can redistribute it and/or modify it under
 # the terms of the new BSD License.
 #
-# Copyright (c) 2010, Sebastian Staudt
+# Copyright (c) 2010-2011, Sebastian Staudt
+
+require 'rubikon/argument_vector'
 
 module Rubikon
 
@@ -53,12 +55,22 @@ module Rubikon
       #
       # @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
       def call(command_name, *args)
-        command = @current_command
+        args.extend ArgumentVector
+        current_command = @current_command
+        current_param   = @current_param
+
         @current_command = @commands[command_name]
-        @current_command.send(:run, *args)
-        @current_command = command
+        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
@@ -67,8 +79,7 @@ module Rubikon
       #        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 [String] description A description for this Command for use in
-      #        the application's help screen
+      # @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
@@ -77,7 +88,7 @@ module Rubikon
       # @see default
       # @see Command
       # @since 0.2.0
-      def command(name, arg_count = nil, description = nil, &block)
+      def command(name, *options, &block)
         command = nil
 
         if name.is_a? Hash
@@ -91,8 +102,7 @@ module Rubikon
             end
           end
         else
-          command = Command.new(self, name, arg_count, &block)
-          command.description = description unless description.nil?
+          command = Command.new(self, name, *options, &block)
           @commands.each do |command_alias, command_name|
             if command_name == command.name
               @commands[command_alias] = command
@@ -123,8 +133,7 @@ module Rubikon
       # Define the default Command of the application, i.e. the Command that is
       # called if no matching Command parameter can be found
       #
-      # @param [String] description A description for this Command for use in
-      #        the application's help screen
+      # @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
@@ -133,12 +142,54 @@ module Rubikon
       # @see Command
       # @see command
       # @since 0.2.0
-      def default(arg_count = nil, description = nil, &block)
-        if arg_count.is_a? Symbol
-          command({ :__default => arg_count })
+      #
+      # @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
+      def default(*options, &block)
+        if options.size == 1 && options.first.is_a?(Symbol) && !block_given?
+          command :__default => options.first
         else
-          command(:__default, arg_count, description, &block)
+          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
+      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
+      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
+      def estream
+        @settings[:estream]
       end
 
       # Create a new Flag with the given name for the next Command
@@ -158,11 +209,13 @@ module Rubikon
       #  command :something do
       #    ...
       #  end
-      def flag(name, &block)
+      def flag(name, description = nil, &block)
         if name.is_a? Hash
           @parameters << name
         else
-          @parameters << Flag.new(self, name, &block)
+          flag = Flag.new(self, name, &block)
+          flag.description = description unless description.nil?
+          @parameters << flag
         end
       end
 
@@ -184,7 +237,7 @@ module Rubikon
       #  end
       # @example Define an alias to a global flag
       #  global_flag :q => :quiet
-      def global_flag(name, &block)
+      def global_flag(name, description = nil, &block)
         if name.is_a? Hash
           name.each do |alias_name, flag_name|
             flag = @global_parameters[flag_name]
@@ -197,6 +250,7 @@ module Rubikon
           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
@@ -217,15 +271,15 @@ module Rubikon
       # @see Option
       # @since 0.2.0
       #
-      # @example Define a global option
-      #  global_option :user, 1
-      # @example Define a global option with a block to execute
-      #  global_option :user, 1 do
-      #    @user = args[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
-      def global_option(name, arg_count = 0, &block)
+      def global_option(name, *options, &block)
         if name.is_a? Hash
           name.each do |alias_name, option_name|
             option = @global_parameters[option_name]
@@ -237,7 +291,7 @@ module Rubikon
             end
           end
         else
-          option = Option.new(self, name, arg_count, &block)
+          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
@@ -252,6 +306,9 @@ module Rubikon
       #
       # @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: "
@@ -261,11 +318,20 @@ module Rubikon
       #    # Do something with the data
       #    ...
       #  end
-      def input(prompt = '')
-        unless prompt.to_s.empty?
-          ostream << "#{prompt}: "
+      #
+      # @example Display a question with validated input
+      #  command :question do
+      #    good = input 'Do you feel good', 'y', 'n'
+      #    ...
+      #  end
+      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
-        @settings[:istream].gets[0..-2]
+        input
       end
 
       # Create a new Option with the given name for the next Command
@@ -275,25 +341,24 @@ module Rubikon
       #        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 [Numeric] arg_count The number of arguments this option takes.
-      #        Use +0+ for no required arguments or a negative value for an
-      #        arbitrary number of arguments
+      # @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
-      #   option :message,1
+      # @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
-      def option(name, arg_count = 0, &block)
+      def option(name, *options, &block)
         if name.is_a? Hash
           @parameters << name
         else
-          @parameters << Option.new(self, name.to_s, arg_count, &block)
+          option = Option.new(self, name.to_s, *options, &block)
+          @parameters << option
         end
       end
 
@@ -423,6 +488,7 @@ module Rubikon
       # +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
@@ -434,13 +500,46 @@ module Rubikon
       #  set :autorun, false
       def set(setting, value)
         setting = setting.to_sym
-        unless setting == :ostream
-          @settings[setting.to_sym] = value
-        else
+        if setting == :estream
+          self.estream = value
+        elsif setting == :ostream
           self.ostream = value
+        else
+          @settings[setting.to_sym] = value
         end
       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
+      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
+
       # Displays a throbber while the given block is executed
       #
       # @param [Proc] block The block to execute while the throbber is