rubikon 0.2.1 → 0.3.0

data/lib/rubikon/exceptions.rb

@@ -1,26 +1,79 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 module Rubikon
 
-  class ArgumentTypeError < ArgumentError
+  # Raised by commands if no block is given and no corresponding command file
+  # exists
+  #
+  # @author Sebastian Staudt
+  # @see Command
+  # @since 0.1.0
+  class BlockMissingError < ArgumentError
   end
 
-  class BlockMissingError < ArgumentError
+  # Raised by parameters that have been supplied with more arguments than they
+  # take
+  #
+  # @author Sebastian Staudt
+  # @see Parameter
+  # @see 0.3.0
+  class ExtraArgumentError < ArgumentError
+
+    def initialize(parameter)
+      super "Parameter #{parameter} has one or more extra arguments."
+    end
+
   end
 
+  # Raised by parameters that have been supplied with not all required
+  # arguments
+  #
+  # @author Sebastian Staudt
+  # @see Parameter
+  # @since 0.1.0
   class MissingArgumentError < ArgumentError
+
+    def initialize(parameter)
+      super "Parameter #{parameter} is missing one or more arguments."
+    end
+
   end
 
-  class MissingOptionError < ArgumentError
+  # Raised if the user did not specify a command and no default command exists
+  #
+  # @author Sebastian Staudt
+  # @since 0.3.0
+  class NoDefaultCommandError < ArgumentError
+
+    def initialize
+      super 'You did not specify a command and there is no default command.'
+    end
+
+  end
+
+  # Raised if a command has been supplied that does not exist
+  #
+  # @author Sebastian Staudt
+  # @since 0.3.0
+  class UnknownCommandError < ArgumentError
+
+    def initialize(name)
+      super "Unknown command: #{name}"
+    end
+
   end
 
-  class UnknownOptionError < ArgumentError
+  # Raised if a parameter has been supplied that does not exist
+  #
+  # @author Sebastian Staudt
+  # @since 0.3.0
+  class UnknownParameterError < ArgumentError
 
-    def initialize(arg)
-      super "Unknown argument: #{arg}"
+    def initialize(name)
+      super "Unknown parameter: #{name}"
     end
 
   end

data/lib/rubikon/flag.rb

@@ -0,0 +1,56 @@
+# 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
+
+require 'rubikon/parameter'
+
+module Rubikon
+
+  # A flag is an application parameter without arguments
+  #
+  # @author Sebastian Staudt
+  # @see Application::InstanceMethods#flag
+  # @see Application::InstanceMethods#global_flag
+  # @see Parameter
+  # @since 0.3.0
+  class Flag
+
+    include Parameter
+
+    # Creates a new flag with the given name and an optional code block
+    #
+    # @param name (see Parameter#initialize)
+    # @param block (see Parameter#initialize)
+    def initialize(name, &block)
+      super(name, 0, &block)
+    end
+
+    # Adds an argument to this flag
+    #
+    # @param arg (see Parameter#<<)
+    # @raise [ExtraArgumentError] is raised because flags never take any
+    #                             arguments.
+    def <<(arg)
+      raise ExtraArgumentError.new(@name)
+    end
+
+    # Checks whether this flag has all required arguments supplied
+    #
+    # @return [true] This is always +true+ because flags never take any
+    #                arguments.
+    def args_full?
+      true
+    end
+
+    # Checks whether this flag can take more arguments
+    #
+    # @return [false] This is always +false+ because flags never take any
+    #                 arguments.
+    def more_args?
+      false
+    end
+
+  end
+
+end

data/lib/rubikon/option.rb

@@ -0,0 +1,30 @@
+# 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
+
+require 'rubikon/parameter'
+
+module Rubikon
+
+  # An option is an application parameter that may have one or more additional
+  # arguments.
+  #
+  # @author Sebastian Staudt
+  # @see Application::InstanceMethods#option
+  # @see Parameter
+  # @since 0.3.0
+  class Option
+
+    # @return [Numeric] The number of arguments this parameter takes
+    attr_reader :arg_count
+
+    # @return [Array<String>] The arguments given to this parameter
+    attr_reader :args
+    alias_method :arguments, :args
+
+    include Parameter
+
+  end
+
+end

data/lib/rubikon/parameter.rb

@@ -0,0 +1,101 @@
+# 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
+
+module Rubikon
+
+  # A parameter is any command-line argument given to the application that is
+  # not prefixed with one or two dashes. Once a parameter is supplied by the
+  # user, it is relayed to the Command it belongs to.
+  #
+  # @author Sebastian Staudt
+  # @since 0.3.0
+  module Parameter
+
+    # @return [Array<Symbol>] The alias names of this parameter
+    attr_reader :aliases
+
+    # @return [Symbol] The primary name of this parameter
+    attr_reader :name
+
+    # Creates a new parameter with the given name
+    #
+    # @param [Symbol, #to_sym] name The name of the parameter
+    # @param [Numeric] arg_count The number of arguments this parameter takes
+    #        if any
+    # @param [Proc] block An optional code block to be executed if this
+    #        parameter is used
+    #
+    # A positive argument count 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. If you need a parameter that does not allow arguments at all
+    # you should use a flag instead.
+    def initialize(name, arg_count = 0, &block)
+      @active    = false
+      @aliases   = []
+      @arg_count = arg_count
+      @args      = []
+      @block     = block
+      @name      = name.to_sym
+    end
+
+    # Adds an argument to this parameter. Parameter arguments can be accessed
+    # inside the Application code using the parameter's args method.
+    #
+    # @param [String] arg The argument to add to the supplied arguments of this
+    #        parameter
+    # @raise [ExtraArgumentError] if the parameter has all required arguments
+    #        supplied and does not take optional arguments
+    # @return [Array] The supplied arguments of this parameter
+    def <<(arg)
+      raise ExtraArgumentError.new(@name) if args_full? && @arg_count > 0
+      @args << arg
+    end
+
+    # Marks this parameter as active when it has been supplied by the user on
+    # the command-line. This also calls the code block of the parameter if it
+    # exists
+    def active!
+      @active = true
+      @block.call unless @block.nil?
+    end
+
+    # Returns whether this parameter has is active, i.e. it has been supplied
+    # by the user on the command-line
+    #
+    # @return +true+ if this parameter has been supplied on the command-line
+    def active?
+      @active
+    end
+
+    # Checks whether this parameter has all required arguments supplied
+    #
+    # @return +true+ if all required parameter arguments have been supplied
+    def args_full?
+      arg_count = @arg_count
+      arg_count = -arg_count if arg_count < 0
+
+      arg_count == 0 || @args.size >= arg_count
+    end
+
+    # Checks the arguments for this parameter
+    #
+    # @raise [MissingArgumentError] if there are not enough arguments for
+    #                               this parameter
+    def check_args
+      raise MissingArgumentError.new(@name) unless args_full?
+    end
+
+    # Checks whether this parameter can take more arguments
+    #
+    # @return +true+ if this parameter can take more arguments
+    def more_args?
+      arg_count <= 0 || @args.size < arg_count
+    end
+
+  end
+
+end

data/lib/rubikon/progress_bar.rb

@@ -1,24 +1,31 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 module Rubikon
 
   # A class for displaying and managing progress bars
+  #
+  # @author Sebastian Staudt
+  # @see Application::InstanceMethods#throbber
+  # @since 0.2.0
   class ProgressBar
 
     # Create a new ProgressBar using the given options.
     #
-    # +ostream+:: The output stream where the progress bar should be displayed
-    # +options+:: An Hash of options to customize the progress bar
+    # @param [Hash, Numeric] options A Hash of options to customize the
+    #        progress bar or the maximum value of the progress bar
+    # @see Application::InstanceMethods#progress_bar
     #
-    # Options:
-    #
-    # +char+::    The character used for progress bar display (default: +#+)
-    # +maximum+:: The maximum value of this progress bar (default: +100+)
-    # +size+::    The actual size of the progress bar (default: +20+)
-    # +start+::   The start value of the progress bar (default: +0+)
+    # @option options [String] :char ('#') The character used for progress bar
+    #         display
+    # @option options [Numeric] :maximum (100) The maximum value of this
+    #         progress bar
+    # @option options [IO] :ostream ($stdout) The output stream where the
+    #         progress bar should be displayed
+    # @option options [Numeric] :size (20) The actual size of the progress bar
+    # @option options [Numeric] :start (0) The start value of the progress bar
     def initialize(options = {})
       if options.is_a? Numeric
         @maximum = options
@@ -43,8 +50,10 @@ module Rubikon
     # This triggers a refresh of the progress bar, if the added value actually
     # changes the displayed bar.
     #
-    # Example:
+    # @param [Numeric] value The amount to add to the progress bar
+    # @return [ProgressBar] The progress bar itself
     #
+    # @example Different alternatives to increase the progress
     #  progress_bar + 1 # (will add 1)
     #  progress_bar + 5 # (will add 5)
     #  progress_bar.+   # (will add 1)
@@ -65,6 +74,8 @@ module Rubikon
         @ostream.flush
         @ostream.puts '' if @progress == @size
       end
+
+      self
     end
 
   end

data/lib/rubikon/throbber.rb

@@ -1,11 +1,15 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 module Rubikon
 
   # A class for displaying and managing throbbers
+  #
+  # @author Sebastian Staudt
+  # @see Application::InstanceMethods#throbber
+  # @since 0.2.0
   class Throbber < Thread
 
     SPINNER = '-\|/'
@@ -13,8 +17,9 @@ module Rubikon
     # Creates and runs a Throbber that outputs to the given IO stream while the
     # given thread is alive
     #
-    # # +ostream+:: The IO stream the throbber should be written to
-    # +thread+::  The thread that should be watched
+    # @param [IO] ostream the IO stream the throbber should be written to
+    # @param [Thread] thread The thread that should be watched
+    # @see Application::InstanceMethods#throbber
     def initialize(ostream, thread)
       proc = Proc.new do |ostream, thread|
           step = 0

data/lib/rubikon.rb

@@ -1,9 +1,20 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 libdir = File.dirname(__FILE__)
 $:.unshift(libdir) unless $:.include?(libdir)
 
+require 'core_ext/string'
 require 'rubikon/application/base'
+
+# A namespace module for all Rubikon related code
+#
+# @author Sebastian Staudt
+# @since 0.1.0
+module Rubikon
+
+  VERSION = '0.3.0'
+
+end

data/test/application_tests.rb

@@ -1,102 +1,66 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
 require 'test_helper'
-require 'testapp'
+require 'testapps'
 
 class ApplicationTests < Test::Unit::TestCase
 
   context 'A Rubikon application\'s class' do
 
     setup do
-      @app = RubikonTestApp.instance
+      @app = TestApp.instance
     end
 
     should 'be a singleton' do
       assert_raise NoMethodError do
-        RubikonTestApp.new
+        TestApp.new
       end
     end
 
     should 'run it\'s instance for called methods' do
-      assert_equal @app.run(%w{--object_id}), RubikonTestApp.run(%w{--object_id})
+      assert_equal @app.run(%w{object_id}), TestApp.run(%w{object_id})
     end
+
   end
 
   context 'A Rubikon application' do
 
     setup do
-      @app = RubikonTestApp
+      @app = TestApp
       @ostream = StringIO.new
       @app.set :ostream, @ostream
     end
 
     should 'exit gracefully' do
-      unknown = '--unknown'
       @app.set :raise_errors, false
       begin
-        @app.run([unknown])
+        @app.run(%w{unknown})
       rescue Exception => e
+        assert_instance_of SystemExit, e
+        assert_equal 1, e.status
       end
-      assert_instance_of SystemExit, e
-      assert_equal 1, e.status
       @ostream.rewind
       assert_equal "Error:\n", @ostream.gets
-      assert_equal "    Unknown argument: #{unknown}\n", @ostream.gets
+      assert_equal "    Unknown command: unknown\n", @ostream.gets
       @app.set :raise_errors, true
     end
 
-    should 'run it\'s default action without options' do
-      result = @app.run([])
-      assert_equal 1, result.size
-      assert_equal 'default action', result.first
-    end
-
-    should 'run with a mandatory option' do
-      result = @app.run(%w{--required arg})
-      assert_equal 1, result.size
-      assert_equal 'required argument was arg', result.first
+    should 'run its default command without arguments' do
+      assert_equal 'default command', @app.run([])
     end
 
-    should 'not run without a mandatory argument' do
-      assert_raise MissingArgumentError do
-        @app.run(%w{--required})
+    should 'raise an exception when using an unknown command' do
+      assert_raise UnknownCommandError do
+        @app.run(%w{unknown})
       end
     end
 
-    should 'require an argument type if it has been defined' do
-      assert_raise ArgumentTypeError do
-        @app.run(['--output', 6])
-      end
-      assert_raise ArgumentTypeError do
-        @app.run(['--number_string', 6, 7])
-      end
-      assert_raise ArgumentTypeError do
-        @app.run(['--number_string', 'test' , 6])
-      end
-    end
-
-    should 'raise an exception when calling an action with the wrong number of
-            arguments' do
-      assert_raise MissingArgumentError do
-        @app.run(%w{--output})
-      end
-      assert_raise ArgumentError do
-        @app.run(%w{--output}, 'test', 3)
-      end
-    end
-
-    should 'raise an exception when using an unknown option' do
-      assert_raise UnknownOptionError do
-        @app.run(%w{--unknown})
-      end
-      assert_raise UnknownOptionError do
-        @app.run(%w{--noarg --unknown})
-      end
-      assert_raise UnknownOptionError do
-        @app.run(%w{--unknown --noarg})
+    should 'raise an exception when run without arguments without default' do
+      assert_raise NoDefaultCommandError do
+        TestAppWithoutDefault.run([])
       end
     end
 
@@ -107,31 +71,54 @@ class ApplicationTests < Test::Unit::TestCase
       input_string = 'test'
       @istream.puts input_string
       @istream.rewind
-      assert_equal [input_string], @app.run(%w{--input})
+      assert_equal input_string, @app.run(%w{input})
       @ostream.rewind
       assert_equal 'input: ', @ostream.gets
     end
 
-    should 'write output to the user given output stream' do
-      input_string = 'test'
-      @app.run(['--output', input_string])
+    should "not break output while displaying a throbber or progress bar" do
+      @app.run(%w{throbber})
+      assert_equal " \b-\b\\\b|\b/\bdon't\nbreak\n", @ostream.string
       @ostream.rewind
-      assert_equal "#{input_string}\n", @ostream.gets
-      assert_equal "#{input_string}#{input_string[0].chr}", @ostream.gets
+
+      @app.run(%w{progressbar})
+      assert_equal "#" * 20 << "\n" << "test\n" * 4, @ostream.string
     end
 
-    should 'provide a throbber' do
-      @app.run(%w{--throbber})
-      @ostream.rewind
-      assert_equal " \b-\b\\\b|\b/\b", @ostream.string
-      @app.run(%w{--throbber true})
-      @ostream.rewind
-      assert_equal " \b-\b\\\b|\b/\bdon't\nbreak\n", @ostream.string
+    should 'have working command aliases' do
+      assert_equal @app.run(%w{alias_before}), @app.run(%w{object_id})
+      assert_equal @app.run(%w{alias_after}), @app.run(%w{object_id})
+    end
+
+    should 'have a global debug flag' do
+      @app.run(%w{--debug})
+      assert $DEBUG
+      $DEBUG = false
+      @app.run(%w{-d})
+      assert $DEBUG
+      $DEBUG = false
+    end
+
+    should 'have a global verbose flag' do
+      @app.run(%w{--verbose})
+      assert $VERBOSE
+      $VERBOSE = false
+      @app.run(%w{-v})
+      assert $VERBOSE
+      $VERBOSE = false
+    end
+
+    should 'have a working help command' do
+      @app.run(%w{help})
+      assert_match /Usage: [^ ]* \[--debug\|-d\] \[--gopt\|--go \.\.\.\] \[--verbose\|-v\] command \[args\]\n\nCommands:\n  help           Display this help screen\n  input          \n  object_id      \n  parameters     \n  progressbar    \n  throbber       \n/, @ostream.string
     end
 
-    should 'have working action aliases' do
-      assert_equal @app.run(%w{--alias_before}), @app.run(%w{--object_id})
-      assert_equal @app.run(%w{--alias_after}), @app.run(%w{--object_id})
+    should 'have a working DSL for command parameters' do
+      params = @app.run(%w{parameters}).values.uniq.sort { |a,b| a.name.to_s <=> b.name.to_s }
+      assert_equal :flag, params[0].name
+      assert_equal [:f], params[0].aliases
+      assert_equal :option, params[1].name
+      assert_equal [:o], params[1].aliases
     end
 
   end