caty 0.0.1

data/HISTORY.markdown

@@ -0,0 +1,7 @@
+0.0.1
+=====
+
+*   First release
+*   Support for tasks, parameters, global
+    and task-specific options
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+/*---- DON'T PANIC License 1.1 -----------
+
+  Don't panic, this piece of software is
+  free, i.e. you can do with it whatever
+  you like, including, but not limited to:
+  
+    * using it
+    * copying it
+    * (re)distributing it
+    * burning/burying/shredding it
+    * eating it
+    * using it to obtain world domination
+    * and ignoring it
+  
+  Under the sole condition that you
+  
+    * CONSIDER buying the author a strong
+      brownian motion producer, say a nice
+      hot cup of tea, should you ever meet
+      him in person.
+
+----------------------------------------*/

data/README.markdown

@@ -0,0 +1,92 @@
+# Caty #
+
+*   http://github.com/karottenreibe/caty
+
+
+## Description ##
+
+Caty is a command line parser that operates on the same
+principle as Yehuda Katz's Thor (http://github.com/wycats/thor/tree/master).
+It maps the arguments given by the user to instance methods of a class
+and can automatically parse options.
+
+
+## Features ##
+
+* Define tasks that get mapped directly to instance methods of a class
+* Define global (e.g. --beer) and task-specific (e.g. -rootbeer) options
+* Have String, Integer and Boolean options
+* Have options with default values
+
+
+## Synopsis ##
+
+    require 'rubygems'
+    require 'caty'
+
+    class Kitty < Caty
+
+        global_options do
+            boolean :quiet, false
+        end
+
+        desc('WHAT', cut("
+            Kitty's hungry!
+            You can specify any amount of food to feed the kitty.
+        "))
+
+        task_options :amount => 1
+
+        def eat( something )
+            unless global_options.quiet
+                puts "I'm eating #{something}. I'm #{task_options.speed}!"
+            end
+        end
+
+        help_task
+
+    end
+
+    Kitty.start!
+
+
+    #
+    # now you can do:
+    # $> kitty eat fish -amount=5 --quiet
+    # $> kitty help
+    # ...
+    #
+
+
+
+## Install ##
+
+* sudo gem install karottenreibe-caty --source http://gems.github.com
+* sudo gem install caty
+
+
+## License ##
+
+/*---- DON'T PANIC License 1.1 -----------
+
+  Don't panic, this piece of software is
+  free, i.e. you can do with it whatever
+  you like, including, but not limited to:
+  
+    * using it
+    * copying it
+    * (re)distributing it
+    * burning/burying/shredding it
+    * eating it
+    * using it to obtain world domination
+    * and ignoring it
+  
+  Under the sole condition that you
+  
+    * CONSIDER buying the author a strong
+      brownian motion producer, say a nice
+      hot cup of tea, should you ever meet
+      him in person.
+
+----------------------------------------*/
+

data/Rakefile

@@ -0,0 +1,33 @@
+require 'jeweler'
+
+task :release do
+    sh "vim HISTORY.markdown"
+    sh "vim README.markdown"
+    sh "git commit -a -m 'prerelease adjustments'; true"
+end
+
+Jeweler::Tasks.new do |gem|
+    gem.name = 'caty'
+    gem.summary = gem.description =
+        'Caty is a command line parser that maps arguments to instance methods'
+    gem.email = 'karottenreibe@gmail.com'
+    gem.homepage = 'http://github.com/karottenreibe/caty'
+    gem.authors = ['Fabian Streitel']
+    gem.rubyforge_project = 'k-gems'
+    gem.add_dependency('ohash')
+end
+
+Jeweler::RubyforgeTasks.new
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'Caty'
+  rdoc.rdoc_files.include('lib/*.rb')
+  rdoc.rdoc_files.include('lib/*/*.rb')
+end
+
+task :test do
+    sh 'bacon -Ilib test/test_*.rb'
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/caty.gemspec

@@ -0,0 +1,73 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{caty}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Fabian Streitel"]
+  s.date = %q{2009-09-08}
+  s.description = %q{Caty is a command line parser that maps arguments to instance methods}
+  s.email = %q{karottenreibe@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+     "README.markdown"
+  ]
+  s.files = [
+    "HISTORY.markdown",
+     "LICENSE.txt",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "caty.gemspec",
+     "lib/caty.rb",
+     "lib/caty/converters.rb",
+     "lib/caty/errors.rb",
+     "lib/caty/global_option.rb",
+     "lib/caty/has_description.rb",
+     "lib/caty/help_system.rb",
+     "lib/caty/helpers.rb",
+     "lib/caty/indirection.rb",
+     "lib/caty/option.rb",
+     "lib/caty/option_array.rb",
+     "lib/caty/option_constructor.rb",
+     "lib/caty/task.rb",
+     "lib/caty/task_hash.rb",
+     "test/kitty.rb",
+     "test/test_caty.rb",
+     "test/test_option.rb",
+     "test/test_option_array.rb",
+     "test/test_structure.rb",
+     "test/test_task.rb"
+  ]
+  s.homepage = %q{http://github.com/karottenreibe/caty}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{k-gems}
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Caty is a command line parser that maps arguments to instance methods}
+  s.test_files = [
+    "test/kitty.rb",
+     "test/test_caty.rb",
+     "test/test_option.rb",
+     "test/test_option_array.rb",
+     "test/test_structure.rb",
+     "test/test_task.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ohash>, [">= 0"])
+    else
+      s.add_dependency(%q<ohash>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<ohash>, [">= 0"])
+  end
+end

data/lib/caty.rb

@@ -0,0 +1,341 @@
+#
+# Caty is a command line parser that supports tasks as well as
+# options and maps user input directly to instance methods.
+#
+# To find out more about caty, file bug reports and other stuff,
+# go to http://karottenreibe.github.com/caty.
+#
+# Inspired by Thor (http://www.yehudakatz.com/2008/05/12/by-thors-hammer)
+#
+# Kudos to Yehuda Katz.
+#
+
+#
+# Handles command line parsing.
+#
+# Subclass this and add public methods.
+# These methods will become tasks, which will be
+# callable via
+#
+#     app method_name
+#
+# Use the #global_options() and #task_options()
+# methods to add global or task-specific options.
+#
+# Use the ::map() method to create aliases for
+# tasks.
+#
+# Use the ::start!() method to start parsing.
+#
+# Use ::default() to set a default task.
+#
+# Use ::before() and ::after() to define Rails-style
+# before and after filters.
+#
+class Caty
+
+    #
+    # Returns the options for the called task as
+    # an OpenHash.
+    #
+    attr_accessor :task_options
+
+    #
+    # Returns the global options for this invocation as
+    # an OpenHash.
+    #
+    attr_accessor :global_options
+
+    class << self
+
+        #
+        # Starts command line parsing.
+        #
+        #     Subclass.start!( arguments_array )
+        #     Subclass.start!
+        #
+        # Returns true on success, false when an ArgumentError
+        # was detected.
+        # 
+        def start!( args = ARGV )
+            initialize_instance
+
+            begin
+                caty = self.new
+                caty.global_options = @global_options.grep!(args)
+
+                task_name = args.delete_at(0) || @default
+                raise Caty::NoSuchTaskError, "You need to provide a task" if task_name.nil?
+
+                task = @tasks.resolve(task_name.to_sym)
+
+                if task.nil?
+                    raise Caty::NoSuchTaskError, "There is no task named `#{task_name}'"
+                else
+                    caty.task_options = task.parse!(args)
+
+                    caty.instance_exec(task_name.to_sym, &@before) unless @before.nil?
+                    task.execute(caty)
+                    caty.instance_exec(task_name.to_sym, &@after)  unless @after.nil?
+                end
+
+                return true
+
+            rescue Caty::NoSuchTaskError, Caty::OptionArgumentError => e
+                $stdout.puts e.message
+                return false
+
+            rescue ArgumentError => e
+                # verify that this is actually the task throwing the error
+                if is_task_argument_error(e.backtrace, task_name)
+                    $stdout.puts "Bad arguments for task #{task.name}."
+                    $stdout.puts "Usage: #{task.to_s}"
+                    return false
+                else
+                    raise
+                end
+            end
+        end
+
+        #
+        # Simply class_evals the given block on
+        # your Caty subtype, thus allowing you to
+        # add new tasks in different source files.
+        #
+        #     class X < Caty
+        #     end
+        #
+        #     X.append do
+        #         def bar
+        #             puts 'bar task'
+        #         end
+        #     end
+        #
+        #     X.start!(%w{bar})
+        #
+        def append( &block )
+            self.class_eval(&block)
+        end
+
+        #
+        # Methods to be used by the inheriting class.
+        #
+        protected
+
+        #
+        # Can be used to cut off whitespace in front of
+        # #desc() descriptions, so it can be written more
+        # nicely in the source.
+        #
+        # Describing this method accurately is terribly complicated,
+        # so here's an example:
+        #
+        #   cut("
+        #       first
+        #         second
+        #       third
+        #   ")
+        #
+        # produces the string
+        #
+        #   "first\n  second\nthird"
+        #
+        # Notice the preserved whitespace in front of
+        # 'second'!
+        #
+        def cut( description )
+            description.sub!(%r{\A\n+}, '')
+            description =~ %r{\A([ \t]*)}
+
+            unless $1.nil?
+                space = $1
+                description.gsub!(%r{^#{space}}, '')
+            end
+
+            description.gsub(%r{\n\Z}, '')
+        end
+
+        #
+        # Adds options for the task defined next.
+        #
+        #   task_options :option_name => default, :option2 ...
+        #
+        def task_options( options_hash )
+            initialize_instance
+            options_hash.each do |name,default|
+                @task_options << Caty::Option.new(name.to_sym, default)
+            end
+        end
+
+        #
+        # Adds global options.
+        #
+        # The first option will be decorated with the latest description
+        # defined via #desc().
+        #
+        #     global_options do
+        #         desc('description')
+        #         string  'option_name' => 'default'
+        #
+        #         desc('desc2')
+        #         integer 'option2'
+        #     end
+        #
+        def global_options( &block )
+            initialize_instance
+            constructor = Caty::OptionConstructor.new(Caty::GlobalOption)
+            @global_options.concat(constructor.construct(&block))
+        end
+
+        #
+        # Creates aliases for tasks.
+        #
+        #     map :alias            => :task_name
+        #     map %w{alias1 alias2} => :task_name
+        #
+        def map( mapping_hash )
+            initialize_instance
+
+            mapping_hash.each do |mappings,target|
+                mappings = [mappings] unless mappings.is_a?(Array)
+
+                mappings.each do |mapping|
+                    @tasks[mapping.to_sym] = Caty::Indirection.new(mapping.to_sym, target.to_sym)
+                end
+            end
+        end
+
+        #
+        # Defines a block of code that will be executed right
+        # before any task is called.
+        # _self_ will point to the Caty instance and the name of
+        # the task (Symbol) will be given as the only argument.
+        #
+        #     before do |task|
+        #         puts task
+        #     end
+        #
+        def before( &block )
+            @before = block
+        end
+
+        #
+        # Defines a default task.
+        #
+        #     default :task
+        #
+        def default( task )
+            @default = task.to_sym
+        end
+
+        #
+        # Defines a block of code that will be executed right
+        # after any task is called.
+        # _self_ will point to the Caty instance and the name of
+        # the task (Symbol) will be given as the only argument.
+        #
+        # NOTE: this code will not be executed if an error occured
+        # during task execution.
+        #
+        #     after do |task|
+        #         puts task
+        #     end
+        #
+        def after( &block )
+            @after = block
+        end
+
+        #
+        # Decorates the next definition with a description and
+        # optionally a usage string.
+        #
+        #     desc 'usage info', 'long description'
+        #     desc 'long description'
+        #
+        def desc( usage, description = nil )
+            if description.nil?
+                @description = usage
+            else
+                @description, @usage = description, usage
+            end
+        end
+
+        #
+        # Methods to be used by Caty itself.
+        #
+        private
+
+        #
+        # Metaprogramming.
+        #
+        # See Module#method_added.
+        # Creates a new task, if the method that was added, was
+        # public.
+        #
+        def method_added( meth )
+            initialize_instance
+            name = meth.to_s
+
+            # only add public methods as tasks
+            if self.public_instance_methods.include?(name)
+                method = self.instance_method(name)
+                task = @tasks[meth] || Caty::Task.new(meth, method, @task_options)
+                task.description = @description
+                task.usage = @usage
+
+                @tasks[meth] = task
+                reset_decorators
+            end
+        end
+
+        #
+        # Tests whether the given backtrace is from
+        # an argument error in task invocation.
+        #
+        def is_task_argument_error( backtrace, task_name )
+            backtrace[0].end_with?("in `#{task_name}'") and  # inside the task method
+            backtrace[1].end_with?("in `call'")         and  # in Task#call
+            backtrace[2].end_with?("in `execute'")      and  # in Task#execute
+            backtrace[3].end_with?("in `start!'")            # in Caty::start!
+        end
+        
+        #
+        # Resets the decorators applied via #desc() and #task_options().
+        #
+        def reset_decorators
+            @task_options = OptionArray.new
+            @description = nil
+            @usage = nil
+        end
+
+        #
+        # Initializes the tasks', options' and global options'
+        # storage instance variables.
+        #
+        def initialize_instance
+            @task_options ||= Caty::OptionArray.new
+            @global_options ||= Caty::OptionArray.new
+            @tasks ||= Caty::TaskHash.new
+        end
+
+    end
+
+end
+
+require 'caty/help_system'
+Caty.extend(Caty::HelpSystem)
+
+require 'caty/helpers'
+require 'caty/errors'
+require 'caty/has_description'
+
+require 'caty/task_hash'
+require 'caty/task'
+require 'caty/indirection'
+
+require 'caty/option_array'
+require 'caty/option_constructor'
+require 'caty/converters'
+require 'caty/option'
+require 'caty/global_option'
+