choosy 0.4.9 → 0.4.10

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    choosy (0.4.8)
+    choosy (0.4.9)
 
 GEM
   remote: http://rubygems.org/
@@ -11,7 +11,17 @@ GEM
       ZenTest (>= 4.4.1)
     autotest-notification (2.3.1)
       autotest (~> 4.3)
+    builder (3.0.0)
+    cucumber (1.1.9)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.2)
+      gherkin (~> 2.9.0)
+      json (>= 1.4.6)
+      term-ansicolor (>= 1.0.6)
     diff-lcs (1.1.2)
+    gherkin (2.9.3)
+      json (>= 1.4.6)
+    json (1.6.6)
     rspec (2.5.0)
       rspec-core (~> 2.5.0)
       rspec-expectations (~> 2.5.0)
@@ -20,6 +30,7 @@ GEM
     rspec-expectations (2.5.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.5.0)
+    term-ansicolor (1.0.7)
 
 PLATFORMS
   ruby
@@ -29,4 +40,5 @@ DEPENDENCIES
   autotest
   autotest-notification
   choosy!
+  cucumber
   rspec

data/README.md

@@ -0,0 +1,259 @@
+# Choosy: Picking your Arguments Carefully
+
+This is a small DSL library for creating command line clients in Ruby. It is largely inspired by the <a href="https://github.com/defunkt/choice">choice</a>, <a href="https://github.com/visionmedia/commander">commander</a>, and <a href="http://furius.ca/optcomplete/">optcomplete.py</a> libraries, though it makes some different design decisions than they do.  It is opinionated software.
+
+This library should:
+
+  - Make creating command line clients relatively easy.
+  - Make creating supercommands like git, subversion, and gem easier.
+  - Allow you to add validation logic for your arguments within the parsing phase.
+  - Allowing for dependencies between options, so that you can more easily validate related options (i.e. if the<code>--bold</code> flag requires the <code>--font Arial</code> flag, then you should be able to ask for the <code>--font</code> option to be validated first, and then the <code>--bold</code> option.
+  - Allow you to customize its output using your own formatting system, or provide several convenient defaults when you don't want to provide your own.
+
+This library should never:
+
+  - Interact with your execution logic.  You can attach executors to commands for convenience, but the execution phase should be delegated to you, not the parsing library.  Separation of concerns, people.
+  - Rely on display or user interface libraries like Highline, since this is only for parsing command lines.
+  - Pollute your namespaces with my DSL function names.  (I really, really hate it when libraries do this.) 
+
+# Examples
+
+This example is a simple date and time tool.
+
+    ```ruby
+    #!/usr/bin/env ruby
+    
+    # date-time
+    require 'choosy'
+    require 'time'
+    
+    class DateTimeCLI
+      attr_reader :command
+    
+      def run!(args)
+        @command = Choosy::Command.new :'date-time' do
+          summary "This is a command that prints out the current time"
+    
+          executor do |args, options| # An executor can just be a simple block.
+            if options[:utc]
+              puts Time.now.utc.strftime(options[:format])
+            else
+              puts Time.now.strftime(options[:format])
+            end
+          end
+    
+          section "Description" do
+            para "This tool prints out the current time, with some added effects"
+          end
+    
+          section "Options" do
+            boolean :utc, "Prints it using the UTC format"
+            string  :format, "The format of the output" do
+              default "%Y-%m-%d %H:%M:%S %z"
+            end
+          end
+    
+          help            # Enables the '-h|--help' option.
+          version "1.0"   # Enables the '--version' option.
+        end.execute!(args)
+      end
+    end
+    
+    if __FILE__ == $0
+      DateTimeCLI.new.run!(ARGV)
+    end
+    ```
+
+Another simple tool that lists directories.
+
+    ```ruby
+    #!/usr/bin/env ruby
+    
+    # list-files
+    require 'choosy'
+    
+    class ListFilesCLI
+      attr_reader :command
+    
+      def run!(args)
+        exe = self  # The following block will change 'self', so we capture context here.
+    
+        @command = Choosy::Command.new :'date-time' do
+          summary "This is a command that lists files in directories"
+          executor exe  # Commands need executors that implement 'execute!'.
+                        # We're using 'self'.
+    
+          section "Description" do
+            para "This tool prints out some information about directories"
+          end
+    
+          section "Options" do
+            integer :limit, "Limit the printed listing to a given number of files."
+            boolean :dirs_only, "Only print out directories"
+          end
+    
+          help            # Enables the '-h|--help' option.
+          version "1.0"   # Enables the '--version' option.
+    
+          arguments do
+            metaname 'PATH'   # What to display on the manpage
+            count    0..1     # The number of items allowed, restricted here by a range.
+          end
+        end.execute!(args)
+      end
+    
+      # Called by the command at the end of the 'run!'
+      def execute!(args, options)
+        limit = options[:limit] || 0
+        paths = if args.empty?
+                 ['.']
+               else
+                 args
+               end
+    
+        paths.each do |path|
+          Dir["#{path}/*"].each do |fname|
+            puts fname
+    
+            limit -= 1
+            if limit == 0
+              return
+            end
+          end
+        end
+      end
+    end
+    
+    if __FILE__ == $0
+      ListFilesCLI.new.run!(ARGV)
+    end
+    ```
+
+### Super Commands
+
+You can also combine multiple choices into an uber-choice, creating commands that look a lot like git or subversion.
+
+    ```ruby
+    #!/usr/bin/env ruby
+    
+    # git-wrapper
+    require 'choosy'
+    
+    class GitExecutor
+      def initialize(type)
+        @type = type
+      end
+    
+      def execute!(args, options)
+        exec("git #{@type}")
+      end
+    end
+    
+    class GitWrapperCLI
+      attr_reader :command
+    
+      def run!(args)
+        exe = self  # The following block will change 'self', so we capture context here.
+    
+        @command = Choosy::SuperCommand.new :'git-wrapper' do
+          summary "This is a command that lists files in directories"
+    
+          section "Description" do
+            para "This tool prints out some information about directories"
+          end
+    
+          section "Commands" do
+            command :status do
+              summary "Prints out the 'git status'"
+              executor GitExecutor.new(:status)
+    
+              help
+            end
+    
+            command :diff do
+              summary "Prints out the 'git diff'"
+              executor GitExecutor.new(:diff)
+    
+              help
+            end
+          end
+    
+          help            # Enables the '-h|--help' option.
+          version "1.0"   # Enables the '--version' option.
+        end.execute!(args)
+      end
+    end
+    
+    if __FILE__ == $0
+      GitWrapperCLI.new.run!(ARGV)
+    end
+    ```
+
+# Output Printing
+
+Choosy allows you to customize the output printing of your documentation. It exposes the internal object model to any class that implements a <code>print!(command)</code> method.  
+
+The <code>:standard</code> printer that is the default for any command can also be customized to meet some of your needs:
+
+    ``` ruby
+    Choosy::Command.new :foo do
+      printer :standard,              # The default printer 
+              :max_width => 80,       # Defaults to the column witdh of the terminal
+              :color => true,         # Default is true 
+              :header_styles => [:bold, :green],  # Defaults to [:bold, :blue]
+              :indent => '   ',       # Defaults to this width 
+              :offset => '  '         # Defaults to this width
+
+      help "Show this help command."
+    end
+    ```
+
+This above example sets some useful properties for the printer. First, the <code>:max\_width</code> limits the wrapping size on the console. By default, choosy tries to be smart and wrap to the currend column width, but you can introduce this hash parameter as a default max. Next, you can turn off and on color printing by setting <code>:color</code>. Color is on by default, so it's actually superfluous in this example -- just a demonstration of the syntax. The <code>:header\_styles</code> is an array of styles that will be applied to the headers for this document. By default, headers are <code>[:bold, :blue]</code>. Most of the ANSI colors and codes are supported, but check <code>lib/choosy/printing/color.rb</code> for additional options. The last two options given are actually formatting spacers in the output that you can customize: <code>:indent</code> is the default indent for commands and options; <code>:offset</code> is the distance between the options and commands to their associated descriptive text.
+
+For those who want the nice, manpage experience, there's also the <code>:manpage</code> printer:
+
+    ``` ruby
+    Choosy::Command.new :foo do
+      printer :manpage,
+              :max_width => 80,                  # Same as :standard
+              :color => true,                    # Same as :standard
+              :header_styles => [:bold, :green], # Same as :standard
+              :option_sytles => [:bold],         # Same as :standard
+              :indent => '   ',                  # Same as :standard
+              :offset => '  ',                   # Same as :standard
+              :version => FOO_VERSION, # Will use the version name you specify, see below.
+              :section => 1,           # Default is always '1'
+              :date => '03/24/2011',   # Date you want displayed
+              :manual => 'Foo Co.'     # The manual page group
+
+      version FOO_VERSION # If you don't supply a version above, this will be used
+    end
+    ```
+
+Because the library is super-awesome, the manpage will even be in color when piped to <code>less -R</code> (the default)! If you don't like the format of my manpage, feel free to implement your own using the <code>choosy/printing/manpage</code> class, a useful utility class for formatting manpage output correctly.
+
+If you already have some templates that you'd like to use, there is also the <code>:erb</code> template that can be customized by writing a template of your choice:
+
+    ``` ruby
+    Choosy::Command.new :foo do
+      printer :erb, 
+              :color => true,                 # Defaults to true
+              :template => 'path/to/file.erb' # Required
+    end
+    ```
+
+The ERB printer also accepts the <code>:color</code> option. The color is exposed via a <code>color</code> property in the template; the command is exposed by the <code>command</code> property.
+
+Finally, because I don't want to tell you how to print your help, I also give you the option of supplying your own printer. Just create a class with a <code>print!(command)</code> method on that class, and it will be passed in the command that it should print the help for. I have supplied some code you may find useful in <code>choosy/terminal</code> that will help with things like finding commands and determining the column width of the terminal.
+
+    ``` ruby
+    class CustomPrinter
+      def print!(command)
+        puts "I got called on help for #{command.name}"
+      end
+    end
+
+    Choosy::Command.new :foo do
+      printer CustomPrinter.new
+    end
+    ```

data/Rakefile

@@ -1,35 +1,49 @@
-require 'rubygems'
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), 'lib')
+
 require 'rake'
 require 'rspec/core/rake_task'
-
-$LOAD_PATH.unshift File.join(File.dirname(__FILE__), 'lib')
+require 'cucumber/rake/task'
 require 'choosy/rake'
 
 desc "Default task"
 task :default => [:spec]
 
-desc "Run the RSpec tests"
-RSpec::Core::RakeTask.new :spec
+desc "Run all of the specifications."
+task :spec => ['spec:default']
+namespace :spec do
+  task :default => [:rspec, :cucumber]
+
+  desc "Run the RSpec tests."
+  RSpec::Core::RakeTask.new :rspec
 
-desc "Build documentation"
-task :doc => [ :rdoc ] do
-  File.open 'docs/README.markdown', 'r'  do |template|
-    File.open 'README.markdown', 'w' do |output|
+  desc "Runs all of the cucumber tasks. Add 'tag=TAG' to run only matching tags."
+  Cucumber::Rake::Task.new :cucumber do |cucumber|
+    cucumber.cucumber_opts = ["-t #{ENV['tag'] || "all"}", "features"]
+  end
+end
+
+desc "Rebuilds the README.md file."
+task :readme do
+  File.open 'docs/README.md', 'r'  do |template|
+    File.open 'README.md', 'w' do |output|
       template.each do |line|
-        if line =~ /^>>> (.*)/
-          puts $1
+        if line =~ /^INCLUDE\((.*?),\s*(.*?)\)/
+          output.puts "    ```#{$2}"
+
           File.open $1, 'r' do |toinsert|
             exclude = false
             toinsert.each_line do |ins|
-              if ins =~ /^##-/
+              if ins =~ /^#=begin/
                 exclude = true
               end
               output.puts "    #{ins}" unless exclude
-              if ins =~ /^##\+/
+              if ins =~ /^#=end/
                 exclude = false
               end
             end
           end
+
+          output.puts "    ```"
         else
           output.puts line
         end
@@ -38,11 +52,8 @@ task :doc => [ :rdoc ] do
   end
 end
 
-desc "Create RDocs: TODO"
-task :rdoc
-
 desc "Cleans the generated files."
 task :clean => ['gem:clean']
 
 desc "Runs the full deploy"
-task :push => [:release, :clean]
+task :push => [:readme, 'choosy:release', :clean]

data/lib/VERSION.yml

@@ -1,6 +1,6 @@
---- 
-date: 07/04/2011
-version: 
-  tiny: 9
+---
+date: 24/04/2012
+version:
+  tiny: 10
   major: 0
   minor: 4

data/lib/choosy.rb

@@ -1,16 +1,44 @@
-# $:.unshift File.dirname(__FILE__)
+require 'tsort'
+require 'time'
+require 'date'
+require 'yaml'
 
-require 'choosy/command'
-require 'choosy/super_command'
-require 'choosy/converter'
 require 'choosy/errors'
-require 'choosy/option'
-require 'choosy/version'
+require 'choosy/base_command'
+require 'choosy/parse_result'
 require 'choosy/parser'
 require 'choosy/verifier'
+require 'choosy/command'
+require 'choosy/argument'
+require 'choosy/option'
+require 'choosy/terminal'
+require 'choosy/converter'
+
+require 'choosy/printing/base_printer'
+require 'choosy/printing/color'
+
+require 'choosy/dsl/base_builder'
+require 'choosy/dsl/argument_builder'
+require 'choosy/dsl/base_command_builder'
 require 'choosy/dsl/command_builder'
-require 'choosy/dsl/super_command_builder'
 require 'choosy/dsl/option_builder'
-require 'choosy/printing/color'
-require 'choosy/printing/erb_printer'
-require 'choosy/printing/help_printer'
+
+module Choosy
+  autoload :SuperCommand, 'choosy/super_command'
+  autoload :SuperParser,  'choosy/super_parser'
+  autoload :Version,      'choosy/version'
+
+  module Printing
+    autoload :ERBPrinter,        'choosy/printing/erb_printer'
+    autoload :FormattingElement, 'choosy/printing/formatting_element'
+    autoload :HelpPrinter,       'choosy/printing/help_printer'
+    autoload :Manpage,           'choosy/printing/manpage'
+    autoload :ManpageFormatter,  'choosy/printing/manpage'
+    autoload :ManpagePrinter,    'choosy/printing/manpage_printer'
+  end
+
+  module DSL
+    autoload :SuperCommandBuilder, 'choosy/dsl/super_command_builder'
+  end
+end
+

data/lib/choosy/argument.rb

@@ -1,5 +1,3 @@
-require 'choosy/errors'
-
 module Choosy
   class Argument
     ZERO_ARITY     = (0 .. 0)

data/lib/choosy/base_command.rb

@@ -1,6 +1,3 @@
-require 'choosy/errors'
-require 'tsort'
-
 module Choosy
   class OptionBuilderHash < Hash
     include TSort
@@ -53,12 +50,16 @@ module Choosy
       end
     end
 
-    def execute!(args)
-      begin
+    def execute!(args, propagate=false)
+      if propagate
         execute(args)
-      rescue Choosy::ClientExecutionError => e
-        $stderr << "#{@name}: #{e.message}\n"
-        exit 1
+      else
+        begin
+          execute(args)
+        rescue Choosy::ClientExecutionError => e
+          $stderr << "#{@name}: #{e.message}\n"
+          exit 1
+        end
       end
     end