coglius 0.0.1

data/lib/coglius/command_line_token.rb

@@ -0,0 +1,62 @@
+module Coglius
+  # Abstract base class for a logical element of a command line, mostly so that subclasses can have similar
+  # initialization and interface
+  class CommandLineToken
+    attr_reader :name #:nodoc:
+    attr_reader :aliases #:nodoc:
+    attr_reader :description #:nodoc:
+    attr_reader :long_description #:nodoc:
+
+    def initialize(names,description,long_description=nil) #:nodoc:
+      @description = description
+      @long_description = long_description
+      @name,@aliases,@names = parse_names(names)
+    end
+
+    def usage #:nodoc:
+      all_forms
+    end
+
+    # Sort based on primary name
+    def <=>(other)
+      self.name.to_s <=> other.name.to_s
+    end
+
+    private
+    # Returns a string of all possible forms
+    # of this flag.  Mostly intended for printing
+    # to the user.
+    def all_forms(joiner=', ')
+      forms = all_forms_a
+      forms.join(joiner)
+    end
+
+
+    # Handles dealing with the "names" param, parsing
+    # it into the primary name and aliases list
+    def parse_names(names)
+      # Allow strings; convert to symbols
+      names = [names].flatten.map { |name| name.to_sym } 
+      names_hash = {}
+      names.each do |name| 
+        raise ArgumentError.new("#{name} has spaces; they are not allowed") if name.to_s =~ /\s/
+        names_hash[self.class.name_as_string(name)] = true
+      end
+      name = names.shift
+      aliases = names.length > 0 ? names : nil
+      [name,aliases,names_hash]
+    end
+
+    def negatable?
+      false;
+    end
+
+    def all_forms_a
+      forms = [self.class.name_as_string(name,negatable?)]
+      if aliases
+        forms |= aliases.map { |one_alias| self.class.name_as_string(one_alias,negatable?) }.sort { |one,two| one.length <=> two.length }
+      end
+      forms
+    end
+  end
+end

data/lib/coglius/command_support.rb

@@ -0,0 +1,214 @@
+module Coglius
+  # Things unrelated to the true public interface of Command that are needed for bookkeeping
+  # and help support.  Generally, you shouldn't be calling these methods; they are technically public
+  # but are essentially part of Coglius's internal implementation and subject to change
+  module CommandSupport
+    # The parent of this command, either the Coglius app, or another command
+    attr_accessor :parent
+
+    def context_description
+      "in the command #{name}"
+    end
+
+    # Return true to avoid including this command in your help strings
+    def nodoc
+      false
+    end
+
+    # Return the arguments description
+    def arguments_description 
+      @arguments_description
+    end
+
+    def arguments_options
+      @arguments_options
+    end
+
+    # If true, this command doesn't want the pre block run before it executes
+    def skips_pre 
+      @skips_pre
+    end
+
+    # If true, this command doesn't want the post block run before it executes
+    def skips_post 
+      @skips_post
+    end
+
+    # If true, this command doesn't want the around block called
+    def skips_around
+      @skips_around
+    end
+
+    # Return the Array of the command's names
+    def names 
+      all_forms
+    end
+
+    # Get an array of commands, ordered by when they were declared
+    def commands_declaration_order # :nodoc:
+      @commands_declaration_order
+    end
+
+    def flag(*names)
+      new_flag = if parent.kind_of? Command
+                   parent.flag(*names)
+                 else
+                   super(*names)
+                 end
+      new_flag.associated_command = self
+      new_flag
+    end
+
+    def switch(*names)
+      new_switch = if parent.kind_of? Command
+                     parent.switch(*names)
+                   else
+                     super(*names)
+                   end
+      new_switch.associated_command = self
+      new_switch
+    end
+
+    def desc(d)
+      if parent.kind_of? Command
+        parent.desc(d)
+      else
+        super(d)
+      end
+    end
+
+    def long_desc(d)
+      if parent.kind_of? Command
+        parent.long_desc(d)
+      else
+        super(d)
+      end
+    end
+
+    def arg_name(d,options=[])
+      if parent.kind_of? Command
+        parent.arg_name(d,options)
+      else
+        super(d,options)
+      end
+    end
+
+    def default_value(d)
+      if parent.kind_of? Command
+        parent.default_value(d)
+      else
+        super(d)
+      end
+    end
+
+    # Get the usage string
+    # CR: This should probably not be here
+    def usage 
+      usage = name.to_s
+      usage += ' [command options]' if !flags.empty? || !switches.empty?
+      usage += ' ' + @arguments_description if @arguments_description
+      usage
+    end
+
+    # Return the flags as a Hash
+    def flags 
+      @flags ||= {}
+    end
+    # Return the switches as a Hash
+    def switches 
+      @switches ||= {}
+    end
+
+    def commands # :nodoc:
+      @commands ||= {}
+    end
+
+    def default_description
+      @default_desc
+    end
+
+    # Executes the command
+    def execute(global_options,options,arguments) 
+      subcommand,arguments = find_subcommand(arguments)
+      if subcommand
+        subcommand.execute(global_options,options,arguments)
+      else
+        get_action(arguments).call(global_options,options,arguments)
+      end
+    end
+
+    def topmost_ancestor
+      some_command = self
+      top = some_command
+      while some_command.kind_of? self.class
+        top = some_command
+        some_command = some_command.parent
+      end
+      top
+    end
+
+    def has_action?
+      !!@action
+    end
+
+    def get_default_command
+      @default_command
+    end
+
+  private
+
+    def get_action(arguments)
+      if @action
+        @action
+      else
+        generate_error_action(arguments)
+      end
+    end
+
+    def generate_error_action(arguments)
+      lambda { |global_options,options,arguments|
+        if am_subcommand?
+          if arguments.size > 0
+            raise UnknownCommand,"Unknown command '#{arguments[0]}'"
+          else
+            raise BadCommandLine,"Command '#{name}' requires a subcommand"
+          end
+        elsif have_subcommands?
+          raise BadCommandLine,"Command '#{name}' requires a subcommand"
+        else
+          raise "Command '#{name}' has no action block"
+        end
+      }
+    end
+
+    def am_subcommand?
+      parent.kind_of?(Command)
+    end
+
+    def have_subcommands?
+      !self.commands.empty?
+    end
+
+    def find_subcommand(arguments)
+      subcommand = find_explicit_subcommand(arguments)
+      if subcommand
+        [subcommand,arguments[1..-1]]
+      else
+        if !@default_command.nil?
+          [find_explicit_subcommand([@default_command.to_s]),arguments]
+        else 
+          [false,arguments]
+        end
+      end
+    end
+
+    def find_explicit_subcommand(arguments)
+      arguments = Array(arguments)
+      return false if arguments.empty?
+      subcommand_name = arguments.first
+      self.commands.values.find { |command|
+        [command.name,Array(command.aliases)].flatten.map(&:to_s).any? { |name| name == subcommand_name }
+      }
+    end
+  end
+end

data/lib/coglius/commands/compound_command.rb

@@ -0,0 +1,42 @@
+module Coglius
+  module Commands
+    # A command that calls other commands in order
+    class CompoundCommand < Command
+      # base:: object that respondes to +commands+
+      # configuration:: Array of arrays: index 0 is the array of names of this command and index 1
+      #                 is the names of the compound commands.
+      def initialize(base,configuration,options={})
+        name = configuration.keys.first
+        super(options.merge(:names => [name]))
+
+        command_names = configuration[name]
+
+        check_for_unknown_commands!(base,command_names)
+
+        @wrapped_commands = command_names.map { |name| self.class.find_command(base,name) }
+      end
+
+      def execute(global_options,options,arguments) #:nodoc:
+        @wrapped_commands.each do |command| 
+          command.execute(global_options,options,arguments)
+        end
+      end
+
+    private 
+
+      def check_for_unknown_commands!(base,command_names)
+        known_commands = base.commands.keys.map(&:to_s)
+        unknown_commands = command_names.map(&:to_s) - known_commands
+
+        unless unknown_commands.empty?
+          raise "Unknown commands #{unknown_commands.join(',')}"
+        end
+      end
+
+      def self.find_command(base,name)
+        base.commands.values.find { |command| command.name == name }
+      end
+
+    end
+  end
+end

data/lib/coglius/commands/doc.rb

@@ -0,0 +1,215 @@
+module Coglius
+  module Commands
+    # Takes a DocListener which will be called with all of the meta-data and documentation
+    # about your app, so as to create documentation in whatever format you want
+    class Doc < Command
+      FORMATS = {
+        'rdoc' => Coglius::Commands::RdocDocumentListener,
+      }
+      # Create the Doc generator based on the Coglius app passed in
+      def initialize(app)
+        super(:names       => "_doc",
+              :description => "Generate documentation of your application's UI",
+              :long_desc   => "Introspects your application's UI meta-data to generate documentation in a variety of formats.  This is intended to be extensible via the DocumentListener interface, so that you can provide your own documentation formats without them being a part of Coglius",
+              :skips_pre   => true, :skips_post => true, :skips_around => true, :hidden => true)
+
+        @app = app
+
+        desc          'The format name of the documentation to generate or the class name to use to generate it'
+        default_value 'rdoc'
+        arg_name      'name_or_class'
+        flag          :format
+
+        action do |global_options,options,arguments|
+          self.document(format_class(options[:format]).new(global_options,options,arguments))
+        end
+      end
+
+      def nodoc
+        true
+      end
+
+      # Generates documentation using the listener
+      def document(document_listener)
+        document_listener.beginning
+        document_listener.program_desc(@app.program_desc) unless @app.program_desc.nil?
+        document_listener.program_long_desc(@app.program_long_desc) unless @app.program_long_desc.nil?
+        document_listener.version(@app.version_string)
+        if any_options?(@app)
+          document_listener.options 
+        end
+        document_flags_and_switches(document_listener,
+                                    @app.flags.values.sort(&by_name),
+                                    @app.switches.values.sort(&by_name))
+        if any_options?(@app)
+          document_listener.end_options 
+        end
+        document_listener.commands
+        document_commands(document_listener,@app)
+        document_listener.end_commands
+        document_listener.ending
+      end
+
+      # Interface for a listener that is called during various parts of the doc process
+      class DocumentListener
+        # Called before processing begins
+        def beginning
+          abstract!
+        end
+
+        # Called when processing has completed
+        def ending
+          abstract!
+        end
+
+        # Gives you the program description
+        def program_desc(desc)
+          abstract!
+        end
+
+        # Gives you the program long description
+        def program_long_desc(desc)
+          abstract!
+        end
+
+        # Gives you the program version
+        def version(version)
+          abstract!
+        end
+
+        # Called at the start of options for the current context
+        def options
+          abstract!
+        end
+
+        # Called when all options for the current context have been vended
+        def end_options
+          abstract!
+        end
+
+        # Called at the start of commands for the current context
+        def commands
+          abstract!
+        end
+
+        # Called when all commands for the current context have been vended
+        def end_commands
+          abstract!
+        end
+
+        # Gives you a flag in the current context
+        def flag(name,aliases,desc,long_desc,default_value,arg_name,must_match,type)
+          abstract!
+        end
+
+        # Gives you a switch in the current context
+        def switch(name,aliases,desc,long_desc,negetable)
+          abstract!
+        end
+
+        # Gives you the name of the current command in the current context
+        def default_command(name)
+          abstract!
+        end
+
+        # Gives you a command in the current context and creates a new context of this command
+        def command(name,aliases,desc,long_desc,arg_name,arg_options)
+          abstract!
+        end
+
+        # Ends a command, and "pops" you back up one context
+        def end_command(name)
+          abstract!
+        end
+
+      private
+        def abstract!
+          raise "Subclass must implement"
+        end
+      end
+
+    private
+
+      def format_class(format_name)
+        FORMATS.fetch(format_name) { 
+          begin
+            return format_name.split(/::/).reduce(Kernel) { |context,part| context.const_get(part) }
+          rescue => ex
+            raise IndexError,"Couldn't find formatter or class named #{format_name}"
+          end
+        }
+      end
+
+      def document_commands(document_listener,context)
+        context.commands.values.reject {|_| _.nodoc }.sort(&by_name).each do |command|
+          call_command_method_being_backwards_compatible(document_listener,command)
+          document_listener.options if any_options?(command)
+          document_flags_and_switches(document_listener,command_flags(command),command_switches(command))
+          document_listener.end_options if any_options?(command)
+          document_listener.commands if any_commands?(command)
+          document_commands(document_listener,command)
+          document_listener.end_commands if any_commands?(command)
+          document_listener.end_command(command.name)
+        end
+        document_listener.default_command(context.get_default_command)
+      end
+
+      def call_command_method_being_backwards_compatible(document_listener,command)
+        command_args = [command.name,
+                        Array(command.aliases),
+                        command.description,
+                        command.long_description,
+                        command.arguments_description]
+        if document_listener.method(:command).arity == 6
+          command_args << command.arguments_options
+        end
+        document_listener.command(*command_args)
+      end
+
+      def by_name
+        lambda { |a,b| a.name.to_s <=> b.name.to_s }
+      end
+
+      def command_flags(command)
+        command.topmost_ancestor.flags.values.select { |flag| flag.associated_command == command }.sort(&by_name)
+      end
+
+      def command_switches(command)
+        command.topmost_ancestor.switches.values.select { |switch| switch.associated_command == command }.sort(&by_name)
+      end
+
+      def document_flags_and_switches(document_listener,flags,switches)
+        flags.each do |flag|
+          document_listener.flag(flag.name,
+                                 Array(flag.aliases),
+                                 flag.description,
+                                 flag.long_description,
+                                 flag.safe_default_value,
+                                 flag.argument_name,
+                                 flag.must_match,
+                                 flag.type)
+        end
+        switches.each do |switch|
+          document_listener.switch(switch.name,
+                                   Array(switch.aliases),
+                                   switch.description,
+                                   switch.long_description,
+                                   switch.negatable)
+        end
+      end
+
+      def any_options?(context)
+        options = if context.kind_of?(Command)
+                    command_flags(context) + command_switches(context)
+                  else
+                    context.flags.values + context.switches.values
+                  end
+        !options.empty?
+      end
+
+      def any_commands?(command)
+        !command.commands.empty?
+      end
+    end
+  end
+end