caty 0.0.1

data/lib/caty/converters.rb

@@ -0,0 +1,101 @@
+#
+# Contains all the option converters.
+#
+
+#
+# Base class for all option converters.
+# Offers some metaprogramming.
+#
+class Caty::Converter
+
+    include Caty::Helpers
+
+    class << self
+
+        attr_accessor :allowed_defaults
+
+        #
+        # Registers a converter subclass for a type (symbol)
+        # and some default value classes
+        #
+        def type( type, *allowed_defaults )
+            @@types ||= Hash.new
+            @@types[type]     = self
+            Caty::OptionConstructor.register(type)
+            @allowed_defaults = allowed_defaults
+        end
+
+        #
+        # Returns a hash containing
+        #   :type => Class
+        # for all converter subclasses
+        #
+        def types
+            @@types ||= Hash.new
+        end
+
+    end
+
+end
+
+#
+# Converter for boolean values:
+#   %w(true false 1 0) << nil
+#
+class Caty::BooleanConverter < Caty::Converter
+
+    type(:boolean, TrueClass, FalseClass)
+
+    def convert( value )
+        case value
+        when 'true',  '1', nil then true
+        when 'false', '0'      then false
+        else
+            e = Caty::OptionArgumentError.new
+            e.expected = '0, 1, true, false or no argument'
+            raise e
+        end
+    end
+
+end
+
+#
+# Converter for string values:
+#   /.*/
+#
+class Caty::StringConverter < Caty::Converter
+
+    type(:string, String)
+
+    def convert( value )
+        case value
+        when nil
+            e = Caty::OptionArgumentError.new
+            e.expected = 'a string'
+            raise e
+        else value
+        end
+    end
+
+end
+
+#
+# Converter for integer values:
+#   /^[+-]?[0-9]+$/
+#
+class Caty::IntegerConverter < Caty::Converter
+
+    type(:integer, Fixnum)
+
+    def convert( value )
+        case value
+        when %r{^[+-]?[0-9]+$} then value.to_i
+        else
+            e = Caty::OptionArgumentError.new
+            e.expected = 'an integer'
+            raise e
+        end
+    end
+
+end
+

data/lib/caty/errors.rb

@@ -0,0 +1,17 @@
+#
+# Contains error classes used by Caty.
+#
+
+class Caty::NoSuchTaskError < ArgumentError
+end
+
+class Caty::OptionArgumentError < ArgumentError
+
+    attr_accessor :expected, :option
+
+    def message
+        "Bad argument to option `#{self.option}'. Expected #{self.expected}."
+    end
+
+end
+

data/lib/caty/global_option.rb

@@ -0,0 +1,40 @@
+#
+# Contains the GlobalOption class.
+#
+
+#
+# Represents a single global option.
+#
+# A GlobalOption object is created for every option
+# specified via Caty::global_options().
+# The sum of all global options parsed is accessible
+# via the Caty#global_options() method.
+#
+class Caty::GlobalOption < Caty::Option
+
+    include Caty::HasDescription
+
+    #
+    # Returns a string representation to be used by
+    # the help system.
+    #
+    def to_help
+        [ self.to_s, self.short_description, self.description ]
+    end
+
+    def to_s( ljust = 0 )
+        returning('') do |str|
+            str << "#{self.prefix}#{@name}=#{
+                @default.nil? ? '' : @default.inspect
+            }".ljust(ljust)
+        end
+    end
+
+    protected
+
+    def prefix
+        '--'
+    end
+
+end
+

data/lib/caty/has_description.rb

@@ -0,0 +1,26 @@
+#
+# Contains the HasDescription module.
+#
+
+#
+# Mixin for everything that can has description ;-)
+#
+module Caty::HasDescription
+
+    attr_accessor :description
+
+    #
+    # If a description was set for this object,
+    # this will return the first line of that desciption.
+    # Else nil will be returned.
+    #
+    def short_description
+        if self.description.nil?
+            nil
+        else
+            self.description[%r{^[^\n\r]*}]
+        end
+    end
+
+end
+

data/lib/caty/help_system.rb

@@ -0,0 +1,107 @@
+#
+# Contains the objects related to the help feature.
+#
+
+#
+# Will be mixed into the Caty class.
+#
+module Caty::HelpSystem
+
+    protected
+
+    #
+    # Interface for Caty's help system.
+    # Displays either a general help page for all tasks
+    # and options known to Caty in case no argument was given;
+    # or a page descriping a certain task/option.
+    #
+    def help( task_or_option = nil )
+        if task_or_option.nil?
+            help_overview
+        else
+            token_help(task_or_option.to_sym)
+        end
+    end
+    
+    #
+    # Applies the standard help task
+    #
+    def help_task
+        self.class_eval do
+            desc('[TOKEN]', cut("
+                Provides help about the program.
+                A TOKEN is the name of a task or an option, e.g. 'help' for
+                the help task or 'version' for the --version option.
+                If a TOKEN is given, help for that specific TOKEN is displayed.
+                Otherwise, an overview of all the tasks and options is shown.
+            "))
+            def help( task_or_option = nil )
+                self.class.help(task_or_option)
+            end
+        end
+    end
+
+    private
+
+    #
+    # Displays the auto-generated help for all tasks,
+    # options and global options known to Caty.
+    #
+    def help_overview
+        task_descs    = @tasks.to_a.reject { |task| task.is_a?(Caty::Indirection) }.map(&:to_help)
+        goption_descs = @global_options.map(&:to_help)
+        column_width  = (task_descs + goption_descs).map(&:first).map(&:length).max
+
+        $stdout.puts 'Commands'
+        $stdout.puts '========'
+        $stdout.puts
+
+        task_descs.each do |desc|
+            $stdout.puts "#{desc[0].ljust(column_width)}  # #{desc[1]}"
+        end
+
+        $stdout.puts
+        $stdout.puts 'Global Options'
+        $stdout.puts '=============='
+        $stdout.puts
+
+        goption_descs.each do |desc|
+            $stdout.puts "#{desc[0].ljust(column_width)}  # #{desc[1]}"
+        end
+    end
+
+    #
+    # Displays the auto-generated help for a certain task/option.
+    #
+    def token_help( token )
+        goptions = @global_options
+        tasks    = @tasks.to_a
+        item     = @tasks.resolve(token) || goptions.find { |item| item.name == token }
+
+        if item.nil?
+            $stdout.puts "Sorry, but I don't know `#{token}'"
+        else
+            aliases = @tasks.find_all do |_,task|
+                task.is_a?(Caty::Indirection) and task.target == item.name
+            end.map(&:first).join(', ')
+
+            help_text = item.to_help
+            $stdout.puts help_text[0]
+            $stdout.puts
+            $stdout.puts help_text[2]
+
+            unless aliases.empty?
+                $stdout.puts
+                $stdout.puts "Aliases: #{aliases}"
+            end
+        end
+    end
+
+    #
+    # Returns the tasks as an array, with all indirections and removed.
+    #
+    def taskarray
+    end
+
+end
+

data/lib/caty/helpers.rb

@@ -0,0 +1,19 @@
+#
+# Contains the Helpers module that will be
+# mixed into a number of classes.
+#
+
+module Caty::Helpers
+
+    private
+
+    #
+    # The K combinator.
+    #
+    def returning( value )
+        yield value
+        value
+    end
+
+end
+

data/lib/caty/indirection.rb

@@ -0,0 +1,26 @@
+#
+# Contains the Indirection class.
+#
+
+#
+# Used to map things to other tasks and resolve
+# those mappings at runtime.
+#
+Caty::Indirection = Struct.new(:name, :target) do
+
+    #
+    # Follows the indirection until it reaches
+    # an end point and returns that.
+    #
+    def resolve( task_hash )
+        next_item = task_hash[self.target]
+
+        if next_item.is_a?(Caty::Indirection)
+            next_item.resolve(task_hash)
+        else
+            next_item
+        end
+    end
+
+end
+

data/lib/caty/option.rb

@@ -0,0 +1,100 @@
+#
+# Contains the Option class.
+#
+
+#
+# Represents a single option.
+#
+# An Option object is created for every option
+# specified via Caty#task_options().
+# The sum of all options parsed is accessible
+# via the Caty#task_options() method.
+#
+class Caty::Option
+
+    include Caty::Helpers
+
+    attr_reader :name
+
+    #
+    # Creates a new option with the given name and default value.
+    #
+    # default may be one of the following:
+    # - :boolean
+    #   nil is the default, any given argument will be coerced
+    #   into a boolean value.
+    # - :string
+    #   nil is the default, any given argument will be coerced
+    #   into a string value.
+    # - :integer
+    #   nil is the default, any given argument will be coerced
+    #   into a integer value.
+    # - an Integer, String or Boolean value
+    #   the passed value is the default value, any given argument
+    #   will be coerced into the given type.
+    # - any other value will be treated as if a String had been
+    #   given.
+    #
+    # If the deduced argument type is boolean, not giving an argument
+    # on the command line is interpreted as giving 'true' as the argument.
+    # For all the other types, a MissingOptionArgumentError is thrown.
+    #
+    def initialize( name, default )
+        @name       = name
+        @converter  = nil
+
+        Caty::Converter.types.each do |type,converter|
+            if default == type
+                @converter   = converter.new
+                @default     = nil
+                break
+            elsif converter.allowed_defaults.any? { |klass| default.is_a?(klass) }
+                @converter   = converter.new
+                @default     = default
+                break
+            end
+        end
+
+        raise(
+            ArgumentError,
+            'Only boolean, string and integer values or :boolean, :integer, :string allowed.'
+        ) if @converter.nil?
+    end
+
+    #
+    # Tries to remove the option from the args.
+    # Returns the value grepped for this option.
+    #
+    def grep!( args )
+        rex   = %r{^#{self.prefix}#{@name}(?:=(.+))?$}
+        index = args.index { |arg| rex =~ arg }
+
+        if index.nil?
+            @default
+        else
+            match = rex.match(args.delete_at(index))
+            @converter.convert(match[1])
+        end
+    rescue Caty::OptionArgumentError  => e
+        e.option = @name
+        raise e
+    end
+
+    def to_s
+        "[#{self.prefix}#{@name}=#{
+            @default.nil? ? '' : @default.inspect
+        }]"
+    end
+
+    protected
+
+    #
+    # Defines the prefix of this option.
+    # May be overwritten by subclasses.
+    #
+    def prefix
+        '-'
+    end
+
+end
+