visionmedia-commander 1.2.2 → 2.4.2

data/History.rdoc

@@ -0,0 +1,85 @@
+
+=== 2.4.2 / 2009-01-12
+
+* Github! build me!
+
+=== 2.4.1 / 2009-01-11
+
+* Added ask_for_CLASS, which may be any class name such as ask_for_date, ask_for_array, etc
+* Changed doc to *.rdoc for pretty markup on github
+
+=== 2.3.0 / 2008-12-16
+
+* Removed input, output in favour of HighLines $terminal
+* Autoloading terminal formatter since it may not always be used
+* Added wrapping of text with 10 padding, defaults to 80
+* Added friendly interruption message by default, overridable with trap or int_message
+* Fixed description now showing as summary when no summary is available
+
+=== 2.2.1 / 2008-12-09
+
+* Fixed typo in String#tokenize, preventing progress bar from working
+* Fixed some small formatting issues with help output
+
+=== 2.2.0 / 2008-12-09
+
+* Additional documentation
+* Added support for arbitrary help 'blocks' using program :help, 'Your block', 'Your blocks contents'
+* Added support for description, summary, short_description, and large_description, which are displaying conditionally within help docs
+* Allowing uncaught exceptions to reach stderr, for debugging purposes
+
+=== 2.1.1 / 2008-12-01
+
+* Changed #password, now requires that the user must enter a non-empty? value
+
+=== 2.1.0 / 2008-12-01
+
+* Added progress bar
+* Added auto-inclusion of FileUtils module
+* Added stdout logging method
+* Fixed issue with options placed before sub-command
+
+=== 2.0.1 / 2008-11-24
+
+* Fixed new line after command options
+* Fixed padding for command list
+
+=== 2.0.0 / 2008-11-24
+
+* Rewrite of entire gem
+* Added auto-parsing and struct population of options
+* Added better documentation
+
+=== 1.2.2 / 2008-11-06
+
+* Forgot to add array.rb
+
+=== 1.2.0 / 2008-11-06
+
+* Added paging ability (similar to 'less')
+* Added coloring to default help generator
+
+=== 1.1.0 / 2008-11-06
+
+* Added dependency for Highline gem, which replaces Commander's user interaction lib
+
+=== 1.0.4 / 2008-11-04
+
+* Added support for --help and --version flags
+
+=== 1.0.3 / 2008-11-01
+
+* Typo causing the gem to fail build on github
+
+=== 1.0.2 / 2008-11-01
+
+* Added gemspec for github
+
+=== 1.0.1 / 2008-10-31
+
+* Added shebang line to commander init
+* Added require 'rubygems' 
+
+=== 1.0.0 / 2008-10-31
+
+* Initial release

data/Manifest

@@ -0,0 +1,33 @@
+bin/commander
+commander.gemspec
+History.rdoc
+lib/commander/command.rb
+lib/commander/core_ext/array.rb
+lib/commander/core_ext/kernel.rb
+lib/commander/core_ext/object.rb
+lib/commander/core_ext/string.rb
+lib/commander/core_ext.rb
+lib/commander/fileutils.rb
+lib/commander/help_formatters/base.rb
+lib/commander/help_formatters/terminal/command_help.erb
+lib/commander/help_formatters/terminal/help.erb
+lib/commander/help_formatters/terminal.rb
+lib/commander/help_formatters.rb
+lib/commander/import.rb
+lib/commander/runner.rb
+lib/commander/user_interaction.rb
+lib/commander/version.rb
+lib/commander.rb
+Manifest
+Rakefile
+README.rdoc
+spec/commander_spec.rb
+spec/help_formatter_spec.rb
+spec/spec_helper.rb
+tasks/docs.rake
+tasks/gemspec.rake
+tasks/spec.rake
+test/fileutils.rb
+test/progress.rb
+test/ui.rb
+Todo.rdoc

data/README.rdoc

@@ -0,0 +1,178 @@
+
+= Commander
+
+The complete solution for Ruby command-line executables. 
+Commander bridges the gap between other terminal related libraries
+you know and love (OptionParser, HighLine), while providing many new
+features, and an elegant API.
+
+== Features:
+
+* Easier than baking cookies
+* Parses options using OptionParser
+* Auto-populates struct with options ( no more { |v| options[:recursive] = v } )
+* Auto-generates help documentation via pluggable help formatters
+* Imports the highline gem for interacting with the terminal
+* Adds additional user interaction functionality
+* Highly customizable progress bar with intuative, simple usage
+* Multi-word command name support such as 'drupal module install MOD', rather than 'drupal module_install MOD'
+* Use the 'commander' executable to initialize a commander driven program
+
+== Example:
+
+For more option examples view the Commander::Command#option method. Also
+an important feature to note is that when_called may be a class to instantiate,
+as well as an object, specifying a method to call, so view the RDoc for more information.
+
+   require 'rubygems'
+   require 'commander'
+
+   program :name, 'Foo Bar'
+   program :version, '1.0.0'
+   program :description, 'Stupid command that prints foo or bar.'
+
+   command :foo do |c|
+     c.syntax = "foobar foo"
+     c.description = "Displays foo"
+     c.when_called do |args, options|
+       say "foo"
+     end
+   end
+
+   command :bar do |c|
+     c.syntax = "foobar [options] bar"
+     c.description = "Display bar with optional prefix"
+     c.option "--prefix STRING"
+     c.when_called do |args, options|
+       say "#{options.prefix} bar"
+     end
+   end
+
+== HighLine:
+
+As mentioned above the highline gem is imported into 'global scope', below
+are some quick examples for how to utilize highline in your command(s):
+   
+   # Ask for password masked with '*' character
+   ask("Password:  ") { |q| q.echo = "*" }
+  
+   # Ask for password 
+   p ask("Password:  ") { |q| q.echo = false }
+
+   # Ask if the user agrees (yes or no)
+   agree("Do something?")
+
+   # Asks on a single line (note the space after ':'
+   ask("Name: ")
+
+   # Asks with new line after "Description:"
+   ask("Description:")
+
+   # Calls Date#parse to parse the date string passed
+   ask("Birthday? ", Date)
+
+   # Ensures Integer is within the range specified
+   ask("Age? ", Integer) { |q| q.in = 0..105 }
+
+   # Asks for a list of strings, converts to array
+   ask("Fav colors?", Array)
+
+   # Provide a menu for users to choose from
+   choose do |menu|
+     menu.index = :letter
+     menu.index_suffix = ") "
+     menu.prompt = "Please choose your favorite programming language?  "
+     menu.choice :ruby do say("Good choice!") end
+     menu.choices(:python, :perl) do say("Not from around here, are you?") end
+   end
+   
+   # Custom shell
+   loop do
+     choose do |menu|
+       menu.layout = :menu_only
+       menu.shell = true
+       menu.choice(:load, "Load a file.") do |command, details|
+         say("Loading file with options:  #{details}...")
+       end
+       menu.choice(:save, "Save a file.") do |command, details|
+         say("Saving file with options:  #{details}...")
+       end
+       menu.choice(:quit, "Exit program.") { exit }
+     end
+   end
+
+== HighLine & Interaction Additions:
+
+In addition to highline's fantastic choice of methods we will continue to
+simplify common tasks using the following methods:
+
+   # Ask for password 
+   password
+   
+   # Ask for password with specific message and mask character
+   password "Enter your password please:", '-'
+
+   # Ask for CLASS, which may be any valid class responding to #parse. Date, Time, Array, etc
+   names = ask_for_array 'Names: '
+   bday = ask_for_date 'Birthday?: '
+
+   # Simple progress bar (Commander::UI::ProgressBar)
+   uris = %w[ 
+     http://vision-media.ca 
+     http://google.com 
+     http://yahoo.com
+     ]
+   progress uris do |uri|
+     res = open uri
+     # Do something with response
+   end
+
+  # 'Log' action to stdout
+  log "create", "path/to/file.rb"
+
+== FileUtils:
+
+The VerboseFileUtils module is automatically included within the main object for
+global usage. These will output 'log' messages such as:
+
+  remove  doc
+  create  path
+  create  path/to/file.rb
+    move  path/to/something path/to/destination
+  
+If you do not wish to use FileUtils in a verbose manor simply call FileUtil's
+methods directly.
+
+== ASCII Tables
+
+For feature rich ASCII tables for your terminal app check out visionmedia's terminal-table gem at
+http://github.com/visionmedia/terminal-table
+
+== Known Issues:
+  
+* none
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 TJ Holowaychuk <tj@vision-media.ca>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,34 +1,12 @@
-# -*- ruby -*-
 
-require 'rubygems'
-require 'hoe'
-require './lib/commander.rb'
+%w( rubygems rake echoe ./lib/commander.rb ).each { |lib| require lib }
 
-Hoe.new('commander', Commander::VERSION) do |p|
-  p.developer('TJ Holowaychuk', 'tj@vision-media.ca')
-  p.extra_deps << ['highline', '>= 1.5.0']
+Echoe.new("commander", Commander::VERSION::STRING) do |p|
+  p.author = "TJ Holowaychuk"
+  p.email = "tj@vision-media.ca"
+  p.summary = "The complete solution for Ruby command-line executables"
+  p.url = "http://github.com/visionmedia/commander"
+  p.runtime_dependencies = ["highline >=1.5.0"]
 end
 
-desc 'Build and install gem.'
-task :build => [:remove, :install_gem] do
-  sh "clear"
-end
-
-desc 'Remove build data.'
-task :remove => [:clean] do
-  sh "clear"
-end
-
-desc 'Run rspec suite.'
-task :spec do
-  sh "clear"
-  sh "spec ./spec/all_spec.rb"
-end
-
-desc 'Run rspec suite with specdoc format.'
-task :specd do
-  sh "clear"
-  sh "spec ./spec/all_spec.rb --format specdoc"
-end
-
-# vim: syntax=Ruby
+Dir['tasks/**/*.rake'].sort.each { |lib| load lib }

data/Todo.rdoc

@@ -0,0 +1,12 @@
+
+* Release to RubyForge as well
+* Fix excessive Dir#[] calls due to rubygems, http://rubyforge.org/tracker/index.php?func=detail&aid=23170&group_id=126&atid=575
+* Change; Have VerboseFileUtils only output basename ? 
+* Add highline paging ... clean it up
+* Add global options... change runner implementations as well as displaying in terminal formatter, OpenStruct inherit these options?
+* Add global --options switch for loading options from a filepath
+* Add; dynamically generate padding erb templates, command lists, multi-line text bodies etc
+* Add; display global options with global help
+* Change; consider reversing |options, args| so args can be |options, file, dir| etc.. adjust doc
+* Change; refactor specs
+* Publish rdoc

data/bin/commander

@@ -1,55 +1,52 @@
 #!/usr/bin/env ruby
 
+require 'rubygems'
 require 'commander'
 
-init_commander(
-    :name => 'Commander', 
-    :version => Commander::VERSION, 
-    :description => 'Commander utility program.'
-  )
+program :name, 'commander'
+program :version, Commander::VERSION::STRING
+program :description, 'Commander utility program.'
 
 command :init do |c|
-	c.syntax = 'commander init <filepath>'
-	c.description = 'Initialize an empty file with a commander skeleton.'
-	c.example 'Create a new file with a commander skeleton.', 'commander init ./bin/my_executable'
-	c.when_called do |args|
+	c.syntax = 'commander init <file>'
+	c.summary = 'Initialize a commander template'
+	c.description = 'Initialize an empty file with a commander template, allowing extremely quick creation of commader executables.'
+	c.example 'Create a new file with a commander template.', 'commander init ./bin/my_executable'
+	c.when_called do |args, options|
 	  abort "Provide a filepath." if args.empty?
-	  puts
-		name = ask 'What is your programs machine name?'
-		description = ask 'Describe your program:'
-		commands = ask 'List the sub-commands you wish to create:', Array
+		name = ask 'Machine name of program: '
+		description = ask 'Describe your program: '
+		commands = ask 'List the sub-commands you wish to create: ', Array
 		begin
-		  filepath = args.shift
-      File.open(filepath, 'w') do |f|
+      File.open(args.first, 'w') do |f|
         f.write <<-CODE
 #!/usr/bin/env ruby
 
 require 'rubygems'
 require 'commander'
+require '#{name}'
 
-init_commander(
-    :name => '#{name.capitalize}', 
-    :version => #{name.capitalize}::VERSION, 
-    :description => '#{description}'
-  )
-  
+program :name, '#{name}'
+program :version, #{name.camelcase}::VERSION::STRING
+program :description, '#{description}.'
+ 
 CODE
         commands.each do |command|
           f.write <<-CODE
 command :#{command} do |c|
   c.syntax = ''
   c.description = ''
-  c.example 'description', 'code'
-  c.when_called do |args|
-    # Do something
+  c.example 'description', 'command example'
+  c.option '--some-switch', 'Some switch that does something'
+  c.when_called do |args, options|
+    # Do something or c.when_called #{name.camelcase}::Commands::#{command.camelcase}
   end
 end
 
 CODE
         end
        end
-       say "Created commander skeleton at '#{filepath}'."
-       puts
+       say "Initialized template in #{args.first}"
 		 rescue Exception => e
        abort e
 		 end

data/commander.gemspec

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{commander}
+  s.version = "2.4.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["TJ Holowaychuk"]
+  s.date = %q{2009-01-12}
+  s.default_executable = %q{commander}
+  s.description = %q{The complete solution for Ruby command-line executables}
+  s.email = %q{tj@vision-media.ca}
+  s.executables = ["commander"]
+  s.extra_rdoc_files = ["bin/commander", "lib/commander/command.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/kernel.rb", "lib/commander/core_ext/object.rb", "lib/commander/core_ext/string.rb", "lib/commander/core_ext.rb", "lib/commander/fileutils.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters.rb", "lib/commander/import.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "lib/commander.rb", "README.rdoc", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake"]
+  s.files = ["bin/commander", "commander.gemspec", "History.rdoc", "lib/commander/command.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/kernel.rb", "lib/commander/core_ext/object.rb", "lib/commander/core_ext/string.rb", "lib/commander/core_ext.rb", "lib/commander/fileutils.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters.rb", "lib/commander/import.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "lib/commander.rb", "Manifest", "Rakefile", "README.rdoc", "spec/commander_spec.rb", "spec/help_formatter_spec.rb", "spec/spec_helper.rb", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake", "test/fileutils.rb", "test/progress.rb", "test/ui.rb", "Todo.rdoc"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/visionmedia/commander}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Commander", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{commander}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{The complete solution for Ruby command-line executables}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<highline>, [">= 1.5.0"])
+      s.add_development_dependency(%q<echoe>, [">= 0"])
+    else
+      s.add_dependency(%q<highline>, [">= 1.5.0"])
+      s.add_dependency(%q<echoe>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<highline>, [">= 1.5.0"])
+    s.add_dependency(%q<echoe>, [">= 0"])
+  end
+end