jido 0.2.0 → 0.2.1

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/jido.rb

@@ -1,5 +1,6 @@
 require 'jido/conjugator'
 
+# Container for the conjugator. Maybe other stuff will go in here later..
 module Jido
   # Convenience method for Jido::Conjugator.load
   def Jido.load lang, options = {}

data/lib/jido/conjugator.rb

@@ -2,11 +2,27 @@ require 'rubygems'
 require 'nokogiri'
 
 module Jido
+  
+  # This is it, folks.
   class Conjugator
+    
+    # The language used in this Conjugator instance.
+    # Verbs given to this instance are expected to be in this language.
+    # This instance will conjugate verbs according to rules of this language.
     attr_reader :lang
     
-    # Accepted options:
-    #   
+    # Create a Jido::Conjugator instance.
+    # Load and parse the corresponding XML data file, and parse any provided options.
+    # 
+    # Accepted options (keys of the `options` hash should be symbols, not strings):
+    # * <code>:forms</code>: Only return conjugations for the given verb forms / tenses.
+    #     Jido::Conjugator.new 'fr', :forms => %w{prs futant}
+    # * <code>:paradigms</code>: Only return conjugations for the given paradigms.
+    #     Jido::Conjugator.new 'fr', :paradigms => [{:person => '1', :quant => 'sg'}]
+    # * <code>:forms_except</code>: Return all conjugations except those for the given verb forms / tenses.
+    #     Jido::Conjugator.new 'fr', :forms_except => 'prs'
+    # * <code>:paradigms_except</code>: Return all conjugations except those for the given paradigms.
+    #     Jido::Conjugator.new 'fr', :paradigms_except => [{:person => '3', :quant => 'pl'}]
     def initialize lang, options = {}
       @lang = lang
       
@@ -21,10 +37,35 @@ module Jido
       
       @data = Nokogiri.XML data_file, nil, 'UTF-8'
       data_file.close
+
+      self.options = options
+    end
+    
+    # Change the options for this Conjugator instance.
+    # See Conjugator::new for possible options.
+    def options= options
+      @options = options
+      @forms = check_for_list_option :forms
+      @forms_except = check_for_list_option(:forms_except) || [ ]
+      @paradigms = check_for_list_option :paradigms
+      @paradigms_except = check_for_list_option(:paradigms_except) || [ ]
+    end
+
+    # Interpret the provided option when a list is expected.
+    # Used to provide functionality like:
+    #     jido.conjugate 'be', :form => 'prs'
+    #     jido.conjugate 'be', :form => %w{prs pst prf}
+    def check_for_list_option option_name
+      return nil if @options[option_name].nil?
+
+      return [@options[option_name]] if @options[option_name].is_a?(String) or @options[option_name].is_a(Hash)
+      return @options[option_name] if @options[option_name].is_a?(Array)
+
+      raise "Invalid data type provided for option #{option_name}: a list was expected. Please provide a single string element or an array of strings."
     end
     
     # Get the possible verb form IDs for any conjugated verb.
-    #   Jido.load('fr').forms     # => ['PRS', 'PCOMP', 'IMP', ...]
+    #     Jido.load('fr').forms # => ['PRS', 'PCOMP', 'IMP', ...]
     def forms
       if @forms.nil?
         @forms = []
@@ -36,6 +77,23 @@ module Jido
       @forms
     end
     
+    # Set the forms to conjugate. Use Conjugator#forms to find possible values for a certain instance.
+    #     jido.forms = %w{prs pst imp}  # conjugate only for present, past, and imperfect tenses
+    #     jido.forms = 'futant'         # conjugate only for future anterior tense
+    #     jido.forms = jido.forms[0..4] # conjugate for the first 5 forms stored in the conjugator
+    def forms= forms
+      @options[:forms] = forms
+      @forms = check_for_list_option :forms
+    end
+    
+    # Set the forms to not conjugate. Use Conjugator#forms to find possible values for a certain instance.
+    #     jido.forms_except = 'prs' # conjugate for all forms but the present tense
+    def forms_except= forms_except
+      @options[:forms_except] = forms_except
+      @forms_except = check_for_list_option :forms_except
+    end
+    
+    # Get the fallbacks for this language, in case an exact match for a given verb is not found.
     def fallbacks
       if @fallbacks.nil?
         @fallbacks = []
@@ -47,6 +105,12 @@ module Jido
       @fallbacks
     end
     
+    # Get the possible paradigm IDs for any conjugated verb.
+    # Each paradigm is a hash, with two keys:
+    # * <code>:person</code>
+    # * <code>:quant</code>
+    # 
+    #     Jido.load('fr').paradigms # => [{:person => '1', :quant => 'sg'}, {:person => '1', :quant => 'pl'}, ...]
     def paradigms
       if @paradigms.nil?
         @paradigms = []
@@ -58,6 +122,20 @@ module Jido
       @paradigms
     end
     
+    # See Conjugator#paradigms for the expected structure of the parameter.
+    #     jido.paradigms = [{:person => '1', :quant => 'sg'}, {:person => '3', :quant => 'pl'}] # conjugate for only 1SG and 3PL
+    def paradigms= paradigms
+      @options[:paradigms] = paradigms
+      @paradigms = check_for_list_option :paradigms
+    end
+    
+    # See Conjugator#paradigms for the expected structure of the parameter.
+    def paradigms_except= paradigms_except
+      @options[:paradigms_except] = paradigms_except
+      @paradigms_except = check_for_list_option :paradigms_except
+    end
+    
+    # Hmm.. what does this do.. ?
     def conjugate verb
       @current_el = @data.at_xpath "/verbs/verb[@word='#{verb}']"
       @current_el = get_fallback_for_verb(verb) if @current_el.nil?
@@ -65,10 +143,11 @@ module Jido
       
       ret = {}
       @current_el_parents = [] # array of parents of the element, sorted by priority - parents earlier in the array will be picked over later ones
-      store_parents @current_el # populate the parents array = @current_el['inherit'].nil? ? nil : @data.at_xpath("/verbs/verbset[@id='#{@current_el['inherit']}']")
+      store_parents @current_el # populate the parents array
       
       group = nil; group_search = nil
       forms.each do |form|
+        next if @forms_except.include?(form)
         ret[form] = {}
         
         group_search = "group[@id='#{form}']"
@@ -84,6 +163,8 @@ module Jido
         pdgmgroup = nil; pdgmgroup_search = nil
         paradigm = nil; paradigm_search = nil
         paradigms.each do |paradigm|
+          next if @paradigms_except.include?(paradigm)
+
           pdgmgroup_search = "group[@id='#{form}']/pdgmgroup[@id='#{paradigm[:person]}']"
           pdgmgroup = search_current_el pdgmgroup_search
           
@@ -140,14 +221,14 @@ module Jido
       ret
     end
     
-    # Find all parents of a given verb / verbset, and store them in @current_el_parents
+    # Find all parents of a given verb / verbset, and store them in <code>@current_el_parents</code>
     # (if a verb / verbset #1 inherits a verb / verbset #2, then #2 is the parent of #1)
     # 
-    # Structure note: verbs are "final" objects. Verbs cannot be inherited; they are always at the bottom of a hierarchy.
+    # Structure note: verbs are <em>final</em> objects. Verbs cannot be inherited; they are always at the bottom of a hierarchy.
     # Verbsets can inherit / be inherited by other verbsets, and verbs can inherit verbsets.
-    # In other words.. verb = final class, verb set = abstract class
+    # In other words.. <strong>verb = final class, verb set = abstract class</strong>.
     # 
-    # Yay recursion :)
+    # Yay, recursion :)
     def store_parents el
       return if el['inherit'].nil?
       
@@ -172,6 +253,8 @@ module Jido
       nil
     end
     
+    # Find a fallback verbset whose regex matches the given verb.
+    # Used when an exact verb element cannot be matched with an input verb (that is, in most cases).
     def get_fallback_for_verb verb
       fallbacks.each do |fallback|
         if verb.match fallback[:regex]
@@ -183,8 +266,9 @@ module Jido
       false
     end
     
+    # Return a string describing the instance.
     def inspect
-      "<Conjugator @lang => '#{@lang}'>"
+      "#<Conjugator @lang=\"#{@lang}\">"
     end
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: jido
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Hans Engel
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-16 00:00:00 -07:00
+date: 2011-02-20 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -118,7 +118,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -307564322398907677
+      hash: 1316283612953836984
       segments: 
       - 0
       version: "0"