Linguistics 1.0.3

data/lib/linguistics.rb

@@ -0,0 +1,368 @@
+#!/usr/bin/ruby
+# 
+# linguistics.rb -- provides an interface for extending core Ruby classes with
+# linguistic methods.
+# 
+# == Synopsis
+# 
+#   require 'linguistics'
+#	Linguistics::use( :en )
+#	MyClass::extend( Linguistics )
+#
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# == Copyright
+#
+# Copyright (c) 2003-2005 The FaerieMUD Consortium. All rights reserved.
+# 
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the terms of the Perl Artistic License. (See
+# http://language.perl.com/misc/Artistic.html)
+# 
+# == Version
+#
+#  $Id: linguistics.rb 78 2005-07-13 19:58:43Z ged $
+# 
+
+require 'linguistics/iso639'
+
+### A language-independent framework for adding linguistics functions to Ruby
+### classes.
+module Linguistics 
+
+	### Class constants
+
+	# Subversion revision
+	SVNRev = %q$Rev: 78 $
+
+	# Subversion ID
+	SVNid = %q$Id: linguistics.rb 78 2005-07-13 19:58:43Z ged $
+
+	# Language module implementors should do something like:
+	#   Linguistics::DefaultLanguages.push( :ja ) # or whatever
+	# so that direct requiring of a language module sets the default.
+	DefaultLanguages = []
+
+	# The list of Classes to add linguistic behaviours to.
+	DefaultExtClasses = [String, Numeric, Array]
+
+
+	#################################################################
+	###	I N F L E C T O R   C L A S S   F A C T O R Y
+	#################################################################
+
+	### A class which is inherited from by proxies for classes being extended
+	### with one or more linguistic interfaces. It provides on-the-fly creation
+	### of linguistic methods when the <tt>:installProxy</tt> option is passed
+	### to the call to Linguistics#use.
+	class LanguageProxyClass
+
+		### Class instance variable + accessor. Contains the module which knows
+		### the specifics of the language the languageProxy class is providing
+		### methods for.
+		@langmod = nil
+		class << self
+			attr_accessor :langmod
+		end
+
+
+		### Create a new LanguageProxy for the given +receiver+.
+		def initialize( receiver )
+			@receiver = receiver
+		end
+
+
+		######
+		public
+		######
+
+		### Overloaded to take into account the proxy method.
+		def respond_to?( sym )
+			self.class.langmod.respond_to?( sym ) || super
+		end
+
+
+		### Autoload linguistic methods defined in the module this object's
+		### class uses for inflection.
+		def method_missing( sym, *args )
+			return super unless self.class.langmod.respond_to?( sym )
+
+			self.class.module_eval %{
+				def #{sym}( *args, &block )
+					self.class.langmod.#{sym}( @receiver, *args, &block )
+				end
+			}, "{Autoloaded: " + __FILE__ + "}", __LINE__
+
+			self.method( sym ).call( *args )
+		end
+
+
+		### Returns a human-readable representation of the languageProxy for
+		### debugging, logging, etc.
+		def inspect
+			"<%s languageProxy for %s object %s>" % [
+				self.class.langmod.language,
+				@receiver.class.name,
+				@receiver.inspect,
+			]
+		end
+
+	end
+
+
+	### Extend the specified target object with one or more language proxy
+	### methods, each of which provides access to one or more linguistic methods
+	### for that language.
+	def self::extend_object( obj )
+		case obj
+		when Class
+			# $stderr.puts "Extending %p" % obj if $DEBUG
+			self::installLanguageProxy( obj )
+		else
+			sclass = (class << obj; self; end)
+			# $stderr.puts "Extending a object's metaclass: %p" % obj if $DEBUG
+			self::installLanguageProxy( sclass )
+		end
+
+		super
+	end
+
+
+	### Extend the including class with linguistics proxy methods.
+	def self::included( mod )
+		# $stderr.puts "Including Linguistics in %p" % mod if $DEBUG
+		mod.extend( self ) unless mod == Linguistics
+	end
+
+
+	### Make an languageProxy class that encapsulates all of the inflect operations
+	### using the given language module.
+	def self::makeLanguageProxy( mod )
+		# $stderr.puts "Making language proxy for mod %p" % [mod]
+		Class::new( LanguageProxyClass ) {
+			@langmod = mod
+		}
+	end
+
+
+	### Install the language proxy
+	def self::installLanguageProxy( klass, languages=DefaultLanguages )
+		languages.replace( DefaultLanguages ) if languages.empty?
+
+		# Create an languageProxy class for each language specified
+		languages.each {|lang|
+			# $stderr.puts "Extending the %p class with %p" %
+			#	[ klass, lang ] if $DEBUG
+
+			# Load the language module (skipping to the next if it's already
+			# loaded), make an languageProxy class that delegates to it, and figure
+			# out what the languageProxy method will be called.
+			mod = loadLanguage( lang.to_s.downcase )
+			ifaceMeth = mod.name.downcase.sub( /.*:/, '' )
+			languageProxyClass = makeLanguageProxy( mod )
+
+			# Install a hash for languageProxy classes and an accessor for the
+			# hash if it's not already present.
+			if !klass.class_variables.include?( "@@__languageProxy_class" )
+				klass.module_eval %{
+					@@__languageProxy_class = {}
+					def self::__languageProxy_class; @@__languageProxy_class; end
+				}, __FILE__, __LINE__
+			end
+
+			# Merge the current languageProxy into the hash
+			klass.__languageProxy_class.merge!( ifaceMeth => languageProxyClass )
+
+			# Set the language-code proxy method for the class unless it has one
+			# already
+			unless klass.instance_methods(true).include?( ifaceMeth )
+				klass.module_eval %{
+					def #{ifaceMeth}
+						@__#{ifaceMeth}_languageProxy ||=
+							self.class.__languageProxy_class["#{ifaceMeth}"].
+							new( self )
+					end
+				}, __FILE__, __LINE__
+			end
+		}
+	end
+
+
+
+	### Install a regular proxy method in the given klass that will delegate
+	### calls to missing method to the languageProxy for the given +language+.
+	def self::installDelegatorProxy( klass, langcode )
+
+		# Alias any currently-extant
+		if klass.instance_methods( false ).include?( "method_missing" )
+			klass.module_eval %{
+				alias_method :__orig_method_missing, :method_missing
+			}
+		end
+
+		# Add the #method_missing method that auto-installs delegator methods
+		# for methods supported by the linguistic proxy objects.
+		klass.module_eval {
+			define_method( :method_missing ) do |sym, *args|
+
+				if self.send( langcode ).respond_to?( sym )
+
+					# $stderr.puts "Installing linguistic delegator method #{sym} " \
+					#	"for the '#{langcode}' proxy"
+					self.class.module_eval %{
+						def #{sym}( *args )
+							self.#{langcode}.#{sym}( *args )
+						end
+					}
+					self.method( sym ).call( *args )
+
+				# Otherwise either call the overridden proxy method if there is
+				# one, or just let our parent deal with it.
+				else
+					if self.respond_to?( :__orig_method_missing )
+						return self.__orig_method_missing( sym, *args )
+					else
+						super( sym, *args )
+					end
+				end
+			end
+		}
+	end
+
+
+
+	#################################################################
+	###	L A N G U A G E - I N D E P E N D E N T   F U N C T I O N S
+	#################################################################
+
+	###############
+	module_function
+	###############
+
+	### Add linguistics functions for the specified languages to Ruby's core
+	### classes. The interface to all linguistic functions for a given language
+	### is through a method which is the same the language's international 2- or
+	### 3-letter code (ISO 639). You can also specify a Hash of configuration
+	### options which control which classes are extended:
+	###
+	### [<b>:classes</b>]
+	###   Specify the classes which are to be extended. If this is not specified,
+	###   the Class objects in Linguistics::DefaultExtClasses (an Array) are
+	###   extended.
+	### [<b>:installProxy</b>]
+	###   Install a proxy method in each of the classes which are to be extended
+	###   which will search for missing methods in the languageProxy for the
+	###   language code specified as the value. This allows linguistics methods
+	###   to be called directly on extended objects directly (e.g.,
+	###   12.en.ordinal becomes 12.ordinal). Obviously, methods which would
+	###   collide with the object's builtin methods will need to be invoked
+	###   through the languageProxy. Any existing proxy methods in the extended
+	###   classes will be preserved.
+	def use( *languages )
+		config = {}
+		config = languages.pop if languages.last.is_a?( Hash )
+
+		classes = config.key?( :classes ) ? config[:classes] : DefaultExtClasses
+		classes = [ classes ] unless classes.is_a?( Array )
+
+		# Install the languageProxy in each class.
+		classes.each {|klass|
+
+			# Create an languageProxy class for each installed language
+			installLanguageProxy( klass, languages )
+
+			# Install the delegator proxy if configured
+			if config[:installProxy]
+				case config[:installProxy]
+				when Symbol
+					langcode = config[:installProxy]
+				when String
+					langcode = config[:installProxy].intern
+				when TrueClass
+					langcode = DefaultLanguages[0]
+				else
+					raise ArgumentError,
+						"Unexpected value %p for :installProxy" %
+						config[:installProxy]
+				end
+
+				installDelegatorProxy( klass, langcode )
+			end
+		}
+	end
+
+
+
+	### Support Lingua::EN::Inflect-style globals in a threadsafe way by using
+	### Thread-local variables.
+
+	### Set the default count for all unspecified plurals to +val+. Setting is
+	### local to calling thread.
+	def num=( val )
+		Thread.current[:persistent_count] = val
+	end
+	alias_method :NUM=, :num=
+
+	### Get the default count for all unspecified plurals. Setting is local to
+	### calling thread.
+	def num
+		Thread.current[:persistent_count]
+	end
+	alias_method :NUM, :num
+
+	
+	### Set the 'classical pluralizations' flag to +val+. Setting is local to
+	### calling thread.
+	def classical=( val )
+		Thread.current[:classical_plurals] = val
+	end
+
+	### Return the value of the 'classical pluralizations' flag. Setting is
+	### local to calling thread.
+	def classical?
+		Thread.current[:classical_plurals] ? true : false
+	end
+
+
+	#######
+	private
+	#######
+
+	### Try to load the module that implements the given language, returning
+	### the Module object if successful.
+	def self::loadLanguage( lang )
+		raise "Unknown language code '#{lang}'" unless
+			LanguageCodes.key?( lang )
+
+		# Sort all the codes for the specified language, trying the 2-letter
+		# versions first in alphabetical order, then the 3-letter ones
+		msgs = []
+		mod = LanguageCodes[ lang ][:codes].sort {|a,b|
+			(a.length <=> b.length).nonzero? ||
+			(a <=> b)
+		}.each {|code|
+			unless Linguistics::const_defined?( code.upcase )
+				begin
+					require "linguistics/#{code}"
+				rescue LoadError => err
+					msgs << "Tried 'linguistics/#{code}': #{err.message}\n"
+					next
+				end
+			end
+
+			break Linguistics::const_get( code.upcase ) if
+				Linguistics::const_defined?( code.upcase )
+		}
+
+		if mod.is_a?( Array )
+			raise LoadError,
+				"Failed to load language extension %s:\n%s" %
+				[ lang, msgs.join ]
+		end
+		return mod
+	end
+
+end # class linguistics
+

data/redist/crosscase.rb

@@ -0,0 +1,298 @@
+#!/usr/bin/ruby
+# 
+# CrossCase - a mixin for making methods look the way you like 'em. Or for
+# making them look the way other people like 'em. Or something.
+# 
+# == Synopsis
+# 
+#   class MyClass
+#		include CrossCase
+#
+#		def underbarred_method; ...; end
+#		def camelCasedMethod; ...; end
+#	end
+#
+#	obj = MyClass::new
+#	obj.underbarredMethod
+#	obj.camel_cased_method
+#
+#	# -or-
+#
+#	class MyClass
+#		def underbarred_method; ...; end
+#		def camelCasedMethod; ...; end
+#	end
+#
+#	MyClass.extend( CrossCase )
+#	obj = MyClass::new
+#	obj.underbarredMethod
+#	obj.camel_cased_method
+#
+# == Description
+#
+# This module, when mixed into a Class or another Module, will provide
+# under_barred aliases for class or instance methods with names which follow the
+# camelCased naming conventions, and vice-versa. E.g., in a class which mixes in
+# CrossCase, defining a method which is called +foo_bar+ will also create an
+# alias for that method called +fooBar+.
+#
+# I wrote this module because I prefer camelCased method names, but also wish to
+# respect the preferences of my fellow Rubyists for whom such practices are an
+# abomination. And I'm too lazy to type
+#   alias :twinkle_twinkle :twinkleTwinkle
+# for every method. It's all about laziness. Or perhaps I'm catering to my
+# hubris. Or both; I'll shut up now.
+# 
+# == Caveats
+#
+# This module uses the +method_added+ and +singleton_method_added+ hooks to
+# generate aliases for new methods. If either or both of these methods are
+# already defined, they will be preserved as aliases when the Class or Module is
+# extended. It's up to you to return the favor should you create your own hook
+# after this module is mixed in to your class.
+#
+# == Authors
+# 
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# === Thanks To
+#
+# * The denizens of irc://irc.freenode.net/#ruby-lang, and especially dblack,
+#   oGMo, and rubyhacker1 for name suggestions.
+#
+# == Copyright
+#
+# Copyright (c) 2003 The FaerieMUD Consortium. All rights reserved.
+# 
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby
+# 
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+# == Version
+#
+#  $Id: crosscase.rb 78 2005-07-13 19:58:43Z ged $
+# 
+
+
+### A mixin which causes aliases for methods with either under_barred or
+### camelCased naming conventions to be created in the opposing
+### convention. E.g., in a class which mixes in CrossCase, defining a method
+### which is called +foo_bar+ will also create an alias for that method called
+### +fooBar+.
+module CrossCase
+
+	### Versioning constants
+	Version = /([\d\.]+)/.match( %q{$Revision: 78 $} )[1]
+	Rcsid = %q$Id: crosscase.rb 78 2005-07-13 19:58:43Z ged $
+
+	### The inclusion callback -- uses the Ouroboros trick to extend including
+	### classes.
+	def self::included( mod )
+		mod.extend( self )
+	end
+
+
+	### Object-extension callback -- installs aliases for any currently-extant
+	### class or instance methods, and installs callbacks that will create
+	### aliases for any subsequently-defined methods. Raises an error if any
+	### object except a Class or Module is extended.
+	def self::extend_object( mod )
+		raise TypeError, "Expected a Module or a Class, got a " +
+			mod.class.name unless
+			mod.is_a?( Module )
+
+		self::transformClassMethods( mod )
+		self::transformInstanceMethods( mod )
+		self::installMethodHooks( mod )
+	end
+
+
+	### Install +method_added+ and +singleton_method_added+ hooks into the given
+	### Module +mod+ which auto-generate aliases for new methods.
+	def self::installMethodHooks( mod )
+		mod.module_eval {
+			class << self
+				if respond_to?( :singleton_method_added )
+					alias :__cc_sma :singleton_method_added
+				end
+				def singleton_method_added( id )
+					if aliasName = CrossCase::transform( id )
+						CrossCase::installClassAlias( self, id, aliasName )
+					end
+					if respond_to?( :__cc_sma )
+						__cc_sma( id )
+					else
+						super
+					end
+				end
+
+				if respond_to?( :method_added )
+					alias :__cc_ma :method_added
+				end					
+				def method_added( id )
+					if instance_methods( false ).include?( id.to_s ) &&
+							( aliasName = CrossCase::transform(id) )
+					CrossCase::installAlias( self, id, aliasName )
+					end
+					if respond_to?( :__cc_ma )
+						__cc_ma( id )
+					else
+						super
+					end
+				end
+			end
+		}
+	end
+
+
+	### Search for and install aliases for either underbarred or camelCased
+	### class methods for +mod+ (a Class or Module).
+	def self::transformClassMethods( mod )
+		self::findTargetMethods( mod.singleton_methods(false) ) {|meth, aliasName|
+			self::installClassAlias( mod, meth, aliasName )
+		}
+	end
+
+
+	### Install an alias +aliasName+ for the given class method +meth+ of the
+	### Class or Module +mod+.
+	def self::installClassAlias( mod, meth, aliasName )
+		unless mod.respond_to?( aliasName )
+			code = %{
+				class << self; alias_method( :#{aliasName}, :#{meth} ); end
+			}
+			mod.module_eval( code, __FILE__, __LINE__ )
+		end
+	end
+
+
+	### Search for and install aliases for either underbarred or camelCased
+	### instance methods for +mod+ (a Class or Module).
+	def self::transformInstanceMethods( mod )
+		self::findTargetMethods( mod.instance_methods(false) ) {|meth, aliasName|
+			self::installAlias( mod, meth, aliasName )
+		}
+	end
+
+
+	### Install an alias +aliasName+ for the given instance method +meth+ of the
+	### Class or Module +mod+.
+	def self::installAlias( mod, meth, aliasName )
+		unless mod.instance_methods(true).include?( aliasName )
+			mod.module_eval %{alias_method :#{aliasName}, :#{meth}}
+		end
+	end	
+
+
+	### Find methods in the given +methodList+ which are candidates for
+	### aliasing.
+	def self::findTargetMethods( *methodList )
+		methodList.flatten.each {|meth|
+			next if /(singleton_)?method_added/ =~ meth
+			transformedName = transform( meth ) or next
+			yield( meth, transformedName )
+		}
+	end
+
+
+	### Return an alternate name for the given method id +mid+. If the method id
+	### is an under_barred method, returns a camelCased version, and
+	### vice-versa. If no alternate is called for, returns +nil+.
+	def self::transform( mid )
+		methodName = mid.to_s
+		transformedName = ''
+	
+		# camelCased methods
+		if /[A-Z]/.match( methodName ) && !/_/.match( methodName )
+			transformedName = methodName.gsub( /([a-z0-9])([A-Z])/ ) {|match|
+				$1 + '_' + $2
+			}.downcase
+			
+		# underbarred_methods
+		elsif !/A-Z/.match( methodName ) && /[a-z0-9]_[a-z]/.match( methodName )
+			transformedName = methodName.gsub( /([a-z0-9])_([a-z])/ ) {|match|
+				$1 + $2.upcase
+			}
+
+		else
+			transformedName = nil
+		end
+		
+		return transformedName
+	end
+
+
+end
+
+
+if $0 == __FILE__
+	require './utils'
+	include UtilityFunctions
+	$yaml = false
+
+	class Foo #:nodoc:
+		def self::singleton_method_added( id )
+			$stderr.puts "Original sma: Added #{id} to #{self.inspect}"
+		end
+
+		def self::method_added( id )
+			$stderr.puts "Original ma: Added #{id} to #{self.inspect}"
+		end
+
+		def self::classPreCamelMethod
+			"classPreCamelMethod"
+		end
+
+		def self::class_pre_underbarred_method
+			"class_pre_underbarred_method"
+		end
+
+		def preCamelCasedMethod
+			"preCamelCasedMethod"
+		end
+
+		def pre_underbarred_method
+			"pre_underbarred_method"
+		end
+
+		extend CrossCase
+
+		def self::classCamelMethod
+			"classCamelMethod"
+		end
+
+		def self::class_underbarred_method
+			"class_underbarred_method"
+		end
+
+		def camelCasedMethod
+			"camelCasedMethod"
+		end
+
+		def underbarred_method
+			"underbarred_method"
+		end
+	end
+
+	f = nil
+	try( "to instantiate Foo" ) { f = Foo::new }
+	%w{classPreCamelMethod class_pre_camel_method
+		class_pre_underbarred_method classPreUnderbarredMethod
+		classCamelMethod class_camel_method
+		class_underbarred_method classUnderbarredMethod
+		}.
+		sort.each {|meth|
+		try( "to call #{meth} on Foo" ) {
+			Foo.send( meth )
+		}
+	}
+	Foo.instance_methods(false).sort.each {|meth|
+		try( "to call #{meth} on the instance of Foo" ) {
+			f.send( meth )
+		}
+	}
+end
+