ruby_cli 0.0.1

data/README.rdoc

@@ -0,0 +1,99 @@
+= Ruby CLI
+
+Author:: Martin Velez
+Copyright:: Copyright (c) 2011 Martin Velez
+License:: Distributed under the same terms as Ruby
+
+= Description 
+
+"RubyCLI" is a Ruby library which factors out the code needed to create Ruby 
+programswith a command line interface (CLI) which follows the Unix Philosophy 
+design method outlined in http://www.faqs.org/docs/artu/ch01s06.html.
+
+Currently, RubyCLI is short and simple. It uses Ruby's core Option Parser library.
+
+= Design
+
+What does a command line application library need to do?
+	1. Provide a user interface (UI)
+		a. Process options (use Ruby's Option Parser)
+		b. Process arguments
+	2. Pass options and arguments as parameters to other functions defined in libraries or other executables.
+
+What does a command line application library need not do?
+	1. A command line application does not need to validate options or arguments. Libraries or other executables should do this.
+
+= Installation
+
+gem install ruby_cli
+
+= Alternative Tools
+
+There are other tools out there which can be used to write command line 
+applications. 
+
+- clamp[http://github.com/mdub/clamp]
+** I don't like to learn new DSLs
+- optparse[http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/index.html]
+** This library uses this to parse options.
+- Thor[http://github.com/wycats/thor]
+** It does not try to follow the Unix Philosophy.
+- Clip[http://clip.rubyforge.org/]
+** OptionParser already exists.
+
+= Usage
+
+0. New File
+1. Require the ruby_cli gem.
+2. Create a Ruby class. 
+3. Call it "App", for example.  
+4. Include the RubyCLI module.
+5. Define the command method.
+	* This is where your program does the actual work.  
+	* At this point you have options and arguments available.
+	* Pass them as parameters to library functions or as options/arguments to other executables.
+	* Be smart!  Have libraries and other executables do the heavy work.  
+	* Be smart!  Fewer lines of code (LOC) is good.
+6. Define command options and defaults (optional)
+	* This is where you define a hash for your options and set the default values.
+	* Remember, options by definition are optional.
+7. Define command arguments and defaults (optional)
+
+= Usage Example
+
+This example demonstrates how to use RubyCLI to create a 
+	#!/usr/bin/ruby
+
+	require 'ruby_cli'
+
+	class App
+		include RubyCLI	
+
+		def command
+			puts "hello world"
+		end
+
+	end
+
+	if __FILE__ == $0
+		app = App.new(ARGV)
+		app.run
+	end
+
+= Dependencies
+
+* Ruby 1.8.7 or greater
+
+= Acknowledgements
+
+Todd Werth[http://blog.toddwerth.com/entries/5]
+* I used his Ruby command line application skeleton code.  I borrowed 
+some ideas from there.
+
+= TODO
+
+* ?
+
+= Source Code
+
+https://github.com/martinvelez/ruby_cli

data/bin/hello_world

@@ -0,0 +1,17 @@
+#!/usr/bin/ruby
+
+require 'ruby_cli'
+
+class App
+	include RubyCLI	
+
+	def command
+		puts "Hello World"
+	end
+
+end
+
+if __FILE__ == $0
+	app = App.new(ARGV)
+	app.run
+end

data/lib/ruby_cli.rb

@@ -0,0 +1,121 @@
+require 'optparse'
+
+# The goal of this library is to factor out code needed to create Ruby 
+# command line applications which follow the Unix Philosophy design method 
+# (http://www.faqs.org/docs/artu/ch01s06.html).
+#
+# What does a command line application library need to do?
+#	1. Provide a UI
+#	a. Process options (use Ruby's Option Parser)
+# b. Process arguments
+# 2. Pass options and arguments as parameters to other functions defined in
+#	libraries or other executables.
+#
+# What does a command line application library need not do?
+# 1. A command line application does not need to validate options or arguments.
+# Libraries or other executables should do this.
+#
+# This module serves as a mixin for Ruby Command Line Applications (CLI).
+# Ruby commands can be written much easier by including this class and following
+# the convention that I have outlined here.
+#
+# This is the core algorithm of any Ruby CLI application.
+# def run
+#   if parse_options? && arguments_valid?
+#		process_options
+#     process_arguments
+#     output_options_and_arguments if @default_options[:verbose]
+#     command
+#   else
+#     output_help(1)
+#   end
+#  end
+module RubyCLI
+
+	# Initialization of this application requires the command line arguments.
+	def initialize(default_argv)
+		@default_argv = default_argv
+		@default_options = {:help => false, :verbose => false}
+		define_command_options
+		define_command_arguments
+		@opt_parser = nil
+	end
+
+	# This method can be overwritten if you want to set defaults for your command
+	# specific options.
+	def define_command_options() @options = {} end
+	
+	# This method can be overwritten if you want to set defaults for your command
+	# specific arguments.
+	def define_command_arguments() @arguments = {} end
+	
+	# Run the application
+  def run
+    if parse_options? && arguments_valid?
+			process_options
+      process_arguments
+      output_options_and_arguments if @default_options[:verbose]
+      command
+    else
+      output_help(1)
+    end
+  end
+		
+		
+	# Parse the options
+	# Redefine this method if you want to add command specific options
+	def parse_options?
+		#configure an OptionParser
+		@opt_parser = OptionParser.new do |opts|		
+			opts.banner = "Usage: #{__FILE__} [OPTIONS]... [ARGUMENTS]..."
+			opts.separator ""
+			opts.separator "Specific options:"
+			opts.on('-h', '--help', 'displays help information') do
+				@default_options[:help] = true
+				exit output_help(0)
+			end
+			opts.on('-V','--verbose','Run verbosely') do 
+				@default_options[:verbose] = true
+			end
+			# TODO: If you redefine, you can add command specific options here!
+		end
+		@opt_parser.parse!(@default_argv) rescue return false
+		true
+	end
+
+	# Check if the required number of arguments remains in the 
+	# argv array after it has been processed by the option parser
+	def arguments_valid?() 
+		return true if @arguments.size == 0
+		@default_argv.size == @arguments.size 
+	end
+
+	def output_options_and_arguments
+    puts "OPTIONS:"
+    @default_options.each {|name, value| puts "#{name} = #{value}"}
+    @options.each {|name, value| puts "#{name} = #{value}"}
+		puts "No options" if @options.length == 0
+		
+		puts "ARGUMENTS:"
+    @arguments.each {|name,value| puts "#{name} = #{value}"}
+		puts "No arguments" if @arguments.length == 0
+  end
+
+	# Performs post-parse processing on options
+	# For instance, some options may be mutually exclusive
+	# Redefine if you need to process options.
+	def process_options() true end	
+	
+	# Redefine if you need to process options.
+	def process_arguments() true end
+	
+	# Application logic
+	def command() raise "This method should be overwritten." end
+	
+	def output_help(exit_code) 
+		puts @opt_parser
+		puts exit_code if @default_options[:verbose]
+		return exit_code 
+	end
+	
+end # Application

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: ruby_cli
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Martin Velez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-11 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Factors out code needed to create Ruby command line applications
+email: mvelez999@gmail.com
+executables: 
+- hello_world
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/ruby_cli.rb
+- README.rdoc
+- bin/hello_world
+has_rdoc: true
+homepage: http://github.com/martinvelez/ruby_cli
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A command line application library
+test_files: []
+