gli 2.0.0.rc5 → 2.0.0.rc6

data/.gitignore

@@ -9,3 +9,4 @@ cruddo.rdoc
 gli.wiki
 Gemfile.lock
 results.html
+.rbx

data/.travis.yml

@@ -1,9 +1,14 @@
+notifications:
+  email:
+    on_success: always
 script: 'bundle exec rake test features'
 rvm: 
   - 1.9.2
   - 1.9.3
   - 1.8.7
   - ree
+  - ruby-head
+  - rbx
 branches:
   only:
     - 'master'

data/README.rdoc

@@ -103,3 +103,6 @@ License:: Distributes under the Apache License, see LICENSE.txt in the source di
 * [http://www.github.com/davetron5000/gli/wiki] - Documentation Wiki
 * [http://www.github.com/davetron5000/gli/wiki/Changelog] - Changelog
 
+= <code>gli</code> CLI documentation
+
+:include:gli.rdoc

data/bin/gli

@@ -5,7 +5,7 @@ require 'gli/commands/scaffold'
 
 include GLI::App
 
-program_desc 'gli allows you to create the scaffolding for a GLI-powered application'
+program_desc 'create scaffolding for a GLI-powered application'
 
 version GLI::VERSION
 
@@ -14,7 +14,12 @@ switch :v, :desc => 'Be verbose'
 switch :n, :desc => 'Dry run; don''t change the disk'
 
 desc 'Root dir of project'
-long_desc 'This is the directory where the project''s directory will be made, so if you specify a project name ''foo'' and the root dir of ''.'', the directory ''./foo'' will be created'
+long_desc <<EOS
+This is the directory where the project''s directory will be made, so if you 
+specify a project name ''foo'' and the root dir of ''.'', the directory 
+''./foo'' will be created'
+EOS
+
 flag :r,:root, :default_value => '.'
 
 desc 'Create a new GLI-based project'

data/features/gli_executable.feature

@@ -13,7 +13,7 @@ Feature: The GLI executable works as intended
      And the output should contain:
     """
     NAME
-        gli - gli allows you to create the scaffolding for a GLI-powered application
+        gli - create scaffolding for a GLI-powered application
 
     SYNOPSIS
         gli [global options] command [command options] [arguments...]
@@ -27,6 +27,7 @@ Feature: The GLI executable works as intended
         -n             - Dry run; dont change the disk
         -r, --root=arg - Root dir of project (default: .)
         -v             - Be verbose
+        --version      - 
 
     COMMANDS
         help           - Shows a list of commands or help for one command

data/features/gli_init.feature

@@ -66,6 +66,7 @@ Feature: The scaffold GLI generates works
                                                   the default)
         --help                                  - Show this message
         -s, --[no-]switch                       - Describe some switch here
+        --version                               - 
     
     COMMANDS
         add      - Describe add here
@@ -91,6 +92,7 @@ Feature: The scaffold GLI generates works
                                                   the default)
         --help                                  - Show this message
         -s, --[no-]switch                       - Describe some switch here
+        --version                               - 
     
     COMMANDS
         add      - Describe add here

data/features/todo.feature

@@ -8,8 +8,8 @@ Feature: The todo app has a nice user interface
       And my terminal size is "80x24"
       And todo's bin directory is in my path
 
-  Scenario: Getting Help for todo in general
-    When I successfully run `todo help`
+  Scenario Outline: Getting Help for todo in general
+    When I successfully run `todo <help>`
     Then the output should contain:
     """
     NAME
@@ -26,6 +26,7 @@ Feature: The todo app has a nice user interface
         --help             - Show this message
         --[no-]otherswitch - 
         --[no-]switch      - 
+        --version          - 
 
     COMMANDS
         chained       - 
@@ -38,6 +39,10 @@ Feature: The todo app has a nice user interface
         ls            - LS things, such as tasks or contexts
         second        - 
     """
+    Examples:
+      | help      |
+      | help      |
+      | --version |
 
   Scenario: Getting Help for a top level command of todo
     When I successfully run `todo help list`
@@ -169,6 +174,14 @@ Feature: The todo app has a nice user interface
     When I successfully run `todo --flag foo --switch --no-otherswitch initconfig`
     Then the config file should contain a section for each command and subcommand
 
+  Scenario: Init Config makes a reasonable config file if one is there and we force it
+    Given a clean home directory
+    And I successfully run `todo --flag foo --switch --no-otherswitch initconfig`
+    When I run `todo --flag foo --switch --no-otherswitch initconfig`
+    Then the exit status should not be 0
+    When I run `todo --flag foo --switch --no-otherswitch initconfig --force`
+    Then the exit status should be 0
+
   Scenario: Configuration percolates to the app
     Given a clean home directory
     And a config file that specifies defaults for some commands with subcommands

data/gli.rdoc

@@ -1,51 +1,78 @@
-= <tt>gli</tt>
+== gli - gli allows you to create the scaffolding for a GLI-powered application
 
-gli allows you to create the scaffolding for a GLI-powered application
-    gli [global options] command_name [command-specific options] [--] arguments...
+v2.0.0.rc5
 
-* Use the command +help+ to get a summary of commands
-* Use the command <tt>help command_name</tt> to get a help for +command_name+
-* Use <tt>--</tt> to stop command line argument processing; useful if your arguments have dashes in them
+=== Global Options
+=== -r arg
 
-== Global Options
-These options are available for any command and are specified before the name of the command
+Root dir of project
 
-[<tt>-n</tt>] Dry run; dont change the disk
-[<tt>-r, --root=arg</tt>] Root dir of project <i>( default: <tt>.</tt>)</i>
+[Aliases] --root
+[Default Value] .
+This is the directory where the projects directory will be made, so if you specify a project name foo and the root dir of ., the directory ./foo will be created
 
-                          This is the directory where the projects directory will be made, so if you specify a project name foo and the root dir of ., the directory ./foo will be created
+=== --help
+Show this message
 
-[<tt>-v</tt>] Be verbose
-== Commands
-[<tt>help</tt>] Shows list of commands or help for one command
-[<tt>init</tt>] Create a new GLI-based project
 
-=== <tt>help [command]</tt>
 
-Shows list of commands or help for one command
 
-Gets help for the application or its commands.  Can also list the commands in a way helpful to creating a bash-style completion function
+=== -n
+Dry run; dont change the disk
 
-==== Options
-These options are specified *after* the command.
 
-[<tt>-c, --completion</tt>] List all commands one line at a time, for use with shell completion ([command] argument is partial command to match)
-=== <tt>init project_name [command[ command]*]</tt>
 
+
+=== -v
+Be verbose
+
+
+
+
+=== --version
+
+
+
+
+
+=== Commands
+==== help command
+Shows a list of commands or help for one command
+
+
+Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function
+==== init project_name [command[ command]*]
 Create a new GLI-based project
 
-*Aliases*
-* <tt><b>scaffold</b></tt>
+[Aliases] scaffold
 
 This will create a scaffold command line project that uses GLI
 for command line processing.  Specifically, this will create
 an executable ready to go, as well as a lib and test directory, all
 inside the directory named for your project
+===== Options
+===== -e
+Create an ext dir
+
+[Aliases] --[no-]ext
+
+
+
+===== --[no-]force
+Overwrite/ignore existing files and directories
+
+
+
+
+===== --notest
+Do not create a test or features dir
+
+
+
+
+===== --[no-]rvmrc
+Create an .rvmrc based on your current RVM setup
+
 
 
-==== Options
-These options are specified *after* the command.
 
-[<tt>-e, --ext</tt>] Create an ext dir
-[<tt>--force</tt>] Overwrite/ignore existing files and directories
-[<tt>--notest</tt>] Do not create a test dir

data/lib/gli.rb

@@ -16,6 +16,8 @@ require 'gli/version.rb'
 require 'gli/commands/help'
 require 'gli/commands/compound_command'
 require 'gli/commands/initconfig'
+require 'gli/commands/rdoc_document_listener'
+require 'gli/commands/doc'
 
 module GLI
 end

data/lib/gli/app.rb

@@ -138,6 +138,7 @@ module GLI
     # +version+:: String containing the version of your application.  
     def version(version)
       @version = version
+      switch :version, :negatable => false
     end
 
     # Call this with +true+ will cause the +global_options+ and

data/lib/gli/app_support.rb

@@ -32,6 +32,11 @@ module GLI
       @version
     end
 
+    # Get the default command for the entire app
+    def get_default_command
+      @default_command
+    end
+
     # Runs whatever command is needed based on the arguments. 
     #
     # +args+:: the command line ARGV array
@@ -113,7 +118,7 @@ module GLI
     end
 
     def commands # :nodoc:
-      @commands ||= {:help => GLI::Commands::Help.new(self)}
+      @commands ||= { :help => GLI::Commands::Help.new(self), :_doc => GLI::Commands::Doc.new(self) }
     end
 
     def pre_block

data/lib/gli/commands/compound_command.rb

@@ -13,11 +13,11 @@ module GLI
 
         check_for_unknown_commands!(base,command_names)
 
-        @commands = command_names.map { |name| self.class.find_command(base,name) }
+        @wrapped_commands = command_names.map { |name| self.class.find_command(base,name) }
       end
 
       def execute(global_options,options,arguments) #:nodoc:
-        @commands.each do |command| 
+        @wrapped_commands.each do |command| 
           command.execute(global_options,options,arguments)
         end
       end

data/lib/gli/commands/doc.rb

@@ -0,0 +1,201 @@
+module GLI
+  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' => GLI::Commands::RdocDocumentListener,
+      }
+      # Create the Doc generator based on the GLI 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 GLI",
+              :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)
+        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 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)
+          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|
+          document_listener.command(command.name,
+                                    Array(command.aliases),
+                                    command.description,
+                                    command.long_description,
+                                    command.arguments_description)
+          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 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.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