linen 0.7.0 → 0.8.0

data/LICENSE

@@ -1,2 +1,28 @@
-Linen is copyright (c) 2007, LAIKA Inc.  Linen is proprietary software
-and is not available for use outside LAIKA.
+Copyright (c) 2007, LAIKA Inc.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+  * Neither the name of the LAIKA, Inc nor the names of its contributors
+    may be used to endorse or promote products derived from this software
+    without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -1,15 +1,25 @@
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Based heavily on Ben Bleything's Rakefile for plist, which #
-# is in turn based on Geoffrey Grosenbach's Rakefile for     #
-# gruff.                                                     #
-#                                                            #
-# Includes whitespace-fixing task based on code from Typo.   #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#!/usr/bin/env ruby
+#
+# Based heavily on Ben Bleything's Rakefile for plist, which
+# is in turn based on Geoffrey Grosenbach's Rakefile for
+# gruff.
+#
+# Includes whitespace-fixing task based on code from Typo.
+# 
+# == Authors
+# 
+# * Ben Bleything <bbleything@laika.com>
+# 
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+# 
+# This code released under the terms of the BSD license.
+# 
+# == Version
+#
+#  $Id: Rakefile 273 2007-07-25 20:41:32Z bbleything $
+#
 
 require 'fileutils'
 require 'rubygems'
@@ -18,24 +28,18 @@ require 'rake/testtask'
 require 'rake/rdoctask'
 require 'rake/packagetask'
 require 'rake/gempackagetask'
-require 'rake/contrib/rubyforgepublisher'
 
 $:.unshift(File.dirname(__FILE__) + "/lib")
 require 'linen'
 
 PKG_NAME      = 'linen'
 PKG_VERSION   = Linen::VERSION
-PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
-
-RELEASE_NAME  = "REL #{PKG_VERSION}"
-
-RUBYFORGE_PROJECT = "linen"
-RUBYFORGE_USER    = ENV['RUBYFORGE_USER']
 
 TEXT_FILES    = %w( Rakefile README LICENSE )
 TEST_FILES    = Dir.glob('test/test_*').delete_if { |item| item.include?( "\.svn" ) }
 LIB_FILES     = Dir.glob('lib/**/*').delete_if { |item| item.include?( "\.svn" ) }
-RELEASE_FILES = TEXT_FILES + LIB_FILES + TEST_FILES
+EXAMPLE_FILES = Dir.glob('examples/*.rb')
+RELEASE_FILES = TEXT_FILES + LIB_FILES + TEST_FILES + EXAMPLE_FILES
 
 task :default => [ :test ]
 
@@ -138,8 +142,6 @@ Linen is a library which can be used to build a command-line interface for any p
   s.authors  = "LAIKA, Inc."
   s.homepage = "http://opensource.laika.com"
 
-  s.rubyforge_project = RUBYFORGE_PROJECT
-
   s.has_rdoc = true
 
   s.files      = RELEASE_FILES

data/examples/host.rb

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+#
+# Demonstrates more complex arguments and commands than
+# math.rb, including a two-phase command (edit).
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: host.rb 274 2007-07-25 21:06:42Z bbleything $
+#
+
+require 'rubygems'
+require 'linen'
+require 'ostruct'
+require 'ping'
+require 'socket'
+
+class HostPlugin < Linen::Plugin
+	description "Inspect and check machines on your network."
+
+	argument :ip,
+	         :prompt  => 'Please enter the IP address: ',
+             :regex   => /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/,
+	         :process => lambda { |ip|
+	         	ip.split('.').each do |octet|
+	         		octet = octet.to_f
+
+					fail "#{ip} is not valid: #{octet.to_i} must be between 0 and 255." if octet < 0 or octet > 255
+	         	end
+
+				return ip
+	         }
+			
+	argument :hostname,
+	         :prompt => 'Please enter the hostname: ',
+	         :regex  => /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$/
+	         # pattern yoinked from http://regexlib.com/REDetails.aspx?regexp_id=391
+	
+	argument :mac,
+	         :prompt => 'Please enter the MAC address: ',
+	         :process => proc {|mac|
+				stripped_mac = mac.gsub( /:/, '' )
+				fail "MAC Address is too short." unless stripped_mac.length == 12
+				fail "MAC Address contains invalid characters." unless stripped_mac =~ /^[0-9a-f]*/i
+
+				return stripped_mac.scan( /../ ).join( ':' )
+			}
+
+	command :lookup do
+		help_message "Attempts to do a DNS lookup on the IP or hostname provided."
+
+		one_of :ip, :hostname
+
+		action do
+			ip_addr_info = Socket.getaddrinfo( ip, nil ) rescue nil
+			hn_addr_info = Socket.getaddrinfo( hostname, nil ) rescue nil
+
+			if ip_addr_info
+				say "IP address #{ip} has hostname #{ip_addr_info[0][2]}."
+			elsif hn_addr_info
+				say "Hostname '#{hostname}' has IP address #{hn_addr_info[0][3]}."
+			else
+				say "You said something I do not understand.  I am sorry."
+			end
+		end
+	end
+
+	command :check do
+		help_message "Attempts to ping the IP or hostname provided."
+
+		one_of :ip, :hostname
+
+		require_confirmation
+
+		action do
+			to_check = ip || hostname
+
+			if Ping.pingecho( to_check, 5 )
+				say "Host #{to_check} is alive!"
+			else
+				say "Host #{to_check} appears to be dead :("
+			end
+		end
+	end
+	
+	command :edit, :lookup_first => true do
+		help_message "Lets you pretend to change the host's IP and MAC addresses.  Lookup by hostname."
+
+		lookup_by :hostname do |hostname|
+			out          = OpenStruct.new
+			out.hostname = hostname
+			out.ip       = Socket.getaddrinfo( hostname, nil )[0][3]
+			
+			# yoinked this from a thread on ruby-talk about UUID generation
+			# http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/242664
+			out.mac = ("%012x" % rand(1 << 12*4)).scan( /../ ).join( ':')
+			
+			# return
+			out
+		end
+		
+		inspect do
+			say "Hostname:    #{hostname.hostname}"
+			say "IP Address:  #{hostname.ip}"
+			say "MAC Address: #{hostname.mac}"
+		end
+		
+		editable_attributes :ip, :mac
+		
+		action do
+			say "If this was real, you would have just changed #{hostname.hostname}'s IP address to " +
+				"#{ip.empty? ? 'nothing' : ip} and its MAC address to #{mac.empty? ? 'nothing' : mac}.  " +
+				"It's not real, though, so rest easy."
+		end
+	end
+end
+
+Linen::CLI.prompt = "host > "
+Linen.start

data/examples/math.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+#
+# Demonstrates a simple plugin that does basic math.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: math.rb 274 2007-07-25 21:06:42Z bbleything $
+#
+
+require 'rubygems'
+require 'linen'
+
+class MathPlugin < Linen::Plugin
+	description "Perform simple mathematical operations.  Currently supports addition, subtraction, multiplication, and division."
+
+	floating_point_regex = /^\d+(\.\d+)?$/
+
+	argument :lhs, 
+	         :prompt  => 'Please enter the left-hand operand: ',
+	         :regex   => floating_point_regex,
+	         :process => Proc.new {|i| i.to_f }
+
+	argument :rhs, 
+	         :prompt  => 'Please enter the right-hand operand: ', 
+	         :regex   => floating_point_regex,
+	         :process => Proc.new {|i| i.to_f }
+
+	command :add do
+		help_message "Adds two operands. (lhs + rhs)"
+
+		required_arguments :lhs, :rhs
+
+		action do
+			say "#{lhs} + #{rhs} = #{lhs + rhs}"
+		end
+	end
+
+	command :subtract do
+		help_message "Subtracts the second operand from the first. (lhs - rhs)"
+
+		required_arguments :lhs, :rhs
+
+		action do
+			say "#{lhs} - #{rhs} = #{lhs - rhs}"
+		end
+	end
+
+	command :multiply do
+		help_message "Multiplies two operands. (lhs * rhs)"
+
+		required_arguments :lhs, :rhs
+
+		action do
+			say "#{lhs} * #{rhs} = #{lhs * rhs}"
+		end
+	end
+
+	command :divide do
+		help_message "Divides the first operand by the second. (lhs / rhs)"
+
+		required_arguments :lhs, :rhs
+
+		action do
+			say "#{lhs} / #{rhs} = #{lhs / rhs}"
+		end
+	end
+end
+
+Linen::CLI.prompt = "math > "
+Linen.start

data/lib/indifferent_hash.rb

@@ -1,11 +1,22 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# Contains IndifferentHash, which can be deferenced by
+# strings or symbols.  It doesn't care, it's laid back.
+# 
+# == Authors
+# 
+# * Ben Bleything <bbleything@laika.com>
+# 
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+# 
+# This code released under the terms of the BSD license.
+# 
+# == Version
+#
+#  $Id: indifferent_hash.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class IndifferentHash < Hash
 	def []( key )

data/lib/linen.rb

@@ -1,11 +1,23 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# Linen is a framework for creating applications that use a command line
+# interface. It features a simple plugin system, readline integration
+# for history and completion, and other features.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: linen.rb 276 2007-07-25 21:14:39Z bbleything $
+#
 
 ### External libraries
 require 'abbrev'
@@ -18,8 +30,8 @@ require 'string_extensions'
 
 
 module Linen
-	VERSION = "0.7.0"
-	SVNRev  = %q$Rev: 231 $
+	VERSION = "0.8.0"
+	SVNRev  = %q$Rev: 276 $
 
 
 	def self::plugins

data/lib/linen/argument.rb

@@ -1,11 +1,22 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# Contains Linen::Argument, which encapsulates most of the
+# argument parsing/processing logic.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: argument.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Plugin::Argument
 	attr_reader :prompt

data/lib/linen/exceptions.rb

@@ -1,11 +1,21 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# Defines a number of exceptions used throughout Linen.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: exceptions.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Plugin::ArgumentError < ArgumentError ; end
 class Linen::Plugin::PluginError   < TypeError     ; end
@@ -13,6 +23,9 @@ class Linen::Plugin::PluginError   < TypeError     ; end
 class Linen::CLI::PluginNotFoundError  < NameError ; end
 class Linen::CLI::CommandNotFoundError < NameError ; end
 
+### ambiguity errors can sometimes carry a payload of possible
+### completions for the ambiguous input; those are stored in the
+### exception when it's raised.
 class Linen::CLI::AbstractAmbiguityError < NameError
 	attr_accessor :candidates, :input
 

data/lib/linen/handler.rb

@@ -1,11 +1,22 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# The abstract handler from which all other handlers must
+# inherit.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: handler.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Handler
 	def self::say( input = '' )

data/lib/linen/handlers/cli.rb

@@ -1,11 +1,23 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# The CLI handler.  This uses Readline and friends to provide
+# a command-line-like interface to the loaded plugins.  It is 
+# the default handler.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: cli.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::CLI < Linen::Handler
 	class << self

data/lib/linen/plugin.rb

@@ -1,11 +1,24 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# Defines Linen::Plugin, which defines the structure of
+# a plugin, as well as the DSL used to write a plugin.
+#
+# Also includes some "meta-functions", like help.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: plugin.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Plugin
 	class << self

data/lib/linen/plugin_registry.rb

@@ -1,11 +1,21 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# An array-like register of all loaded plugins.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: plugin_registry.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 require 'singleton'
 

data/lib/linen/simple_command.rb

@@ -1,11 +1,21 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# A simple, single-phased command.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: simple_command.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Plugin::SimpleCommand
 	attr_reader :name

data/lib/linen/two_phase_command.rb

@@ -1,11 +1,21 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# A two-phase command, commonly used for editing data.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: two_phase_command.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Plugin::TwoPhaseCommand
 	attr_reader :name, :editable_attrs, :lookup_attr

data/lib/linen/workspace.rb

@@ -1,11 +1,21 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# The semi-specialized binding in which commands are executed.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: workspace.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class Linen::Workspace
 	def self::register_handler( handler_class )

data/lib/string_extensions.rb

@@ -1,15 +1,25 @@
 #!/usr/bin/env ruby
-
-##############################################################
-# Copyright 2007, LAIKA, Inc.                                #
-#                                                            #
-# Authors:                                                   #
-#  * Ben Bleything <bbleything@laika.com>                    #
-##############################################################
+#
+# Adds String#wrap, which can be used to wrap at a particular column.
+#
+# == Authors
+#
+# * Ben Bleything <bbleything@laika.com>
+#
+# == Copyright
+#
+# Copyright (c) 2007 Laika, Inc.
+#
+# This code released under the terms of the BSD license.
+#
+# == Version
+#
+#  $Id: string_extensions.rb 274 2007-07-25 21:06:42Z bbleything $
+#
 
 class String
+	### Wraps a string at the given column (or 72, if none provided)
 	def wrap(line_width = 72)
 		self.gsub(/\n/, "\n\n").gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").chomp
 	end
 end
-

metadata

@@ -3,14 +3,14 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: linen
 version: !ruby/object:Gem::Version 
-  version: 0.7.0
+  version: 0.8.0
 date: 2007-09-10 00:00:00 -07:00
 summary: Linen - A pluggable command-line interface library
 require_paths: 
 - lib
 email: 
 homepage: http://opensource.laika.com
-rubyforge_project: linen
+rubyforge_project: 
 description: Linen is a library which can be used to build a command-line interface for any purpose.  It features a plugin architecture to specify new tasks, Readline support, history, and more.
 autorequire: linen
 default_executable: 
@@ -49,6 +49,8 @@ files:
 - test/test_cli.rb
 - test/test_indifferent_hash.rb
 - test/test_plugins.rb
+- examples/host.rb
+- examples/math.rb
 test_files: 
 - test/test_cli.rb
 - test/test_indifferent_hash.rb