eviltrout-linguistics

= Linguistics

== Authors

• Michael Granger [e-mail]
• Martin Chase [e-mail]

== Requirements

• Ruby >= 1.8.6

== Optional

• Ruby-WordNet (>= 0.0.5) - adds integration for the Ruby binding for the WordNet� lexical refrence system.

  URL: http://deveiate.org/projects/Ruby-WordNet

• LinkParser (>= 1.0.2) - adds integration for the Ruby Link Grammar Parser by Martin Chase.

  URL: http://dev.faeriemud.org/~stillflame/linkparse.html Download: http://www.faeriemud.org/code/Ruby-LinkParser-0.0.4.tgz

== General Information

Linguistics is a framework for building linguistic utilities for Ruby objects in any language. It includes a generic language-independant front end, a module for mapping language codes into language names, and a module which contains various English-language utilities.

=== Method Interface

The Linguistics module comes with a language-independant mechanism for extending core Ruby classes with linguistic methods.

It consists of three parts: a core linguistics module which contains the class-extension framework for languages, a generic inflector class that serves as a delegator for linguistic methods on Ruby objects, and one or more language-specific modules which contain the actual linguistic functions.

The module works by adding a single instance method for each language named after the language's two-letter code (or three-letter code, if no two-letter code is defined by ISO639) to various Ruby classes. This allows many language-specific methods to be added to objects without cluttering up the interface or risking collision between them, albeit at the cost of three or four more characters per method invocation.

If you don't like extending core Ruby classes, the language modules should also allow you to use them as a function library as well.

For example, the English-language module contains a #plural function which can be accessed via a method on a core class:

Linguistics::use( :en ) "goose".en.plural

=> "geese"

or via the Linguistics::EN::plural function directly:

include Linguistics::EN plural( "goose" )

=> "geese"

The class-extension mechanism actually uses the functional interface behind the scenes.

A new feature with the 0.02 release: You can now omit the language-code method for unambiguous methods by calling Linguistics::use with the +:installProxy+ configuration key, with the language code of the language module whose methods you wish to be available. For example, instead of having to call:

"goose".en.plural

from the example above, you can now do this:

Lingusitics::use( :en, :installProxy => :en ) "goose".plural

=> "geese"

More about how this works in the documentation for Linguistics::use.

==== Adding Language Modules

To add a new language to the framework, create a file named the same as the ISO639 2- or 3-letter language code for the language you're adding. It must be placed under lib/linguistics/ to be recognized by the linguistics module, but you can also just require it yourself prior to calling Linguistics::use(). This file should define a module under Linguistics that is an all-caps version of the code used in the filename. Any methods you wish to be exposed to users should be declared as module functions (ie., using Module#module_function).

You may also wish to add your module to the list of default languages by adding the appropriate symbol to the Linguistics::DefaultLanguages array.

For example, to create a Portuguese-language module, create a file called 'lib/linguistics/pt.rb' which contains the following:

module Linguistics module PT Linguistics::DefaultLanguages << :pt

  module_function
  <language methods here>
end

end

See the English language module (lib/linguistics/en.rb) for an example.

=== English Language Module

See the README.english file for a synopsis.

The English-language module currently contains linguistic functions ported from a few excellent Perl modules:

Lingua::EN::Inflect Lingua::Conjunction Lingua::EN::Infinitive

See the lib/linguistics/en.rb file for specific attributions.

New with version 0.02: integration with the Ruby WordNet� and LinkParser modules (which must be installed separately).

== To Do

• I am planning on improving the results from the infinitive functions, which currently return useful results only part of the time. Investigations into additional stemming functions and some other strategies are ongoing.

• Martin Chase is working on an integration module for his excellent work on a Ruby interface to the CMU Link Grammar (an english-sentence parser). This will make writing fairly accurate natural language parsers in Ruby much easier.

• Suggestions (and patches) for any of these items or additional features are welcomed.

== Legal

This module is Open Source Software which is Copyright (c) 2003 by The FaerieMUD Consortium. All rights reserved.

You may use, modify, and/or redistribute this software under the terms of the Perl Artistic License, a copy of which should have been included in this distribution (See the file Artistic). If it was not, a copy of it may be obtained from http://language.perl.com/misc/Artistic.html or http://www.faeriemud.org/artistic.html).

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

$Id$