to_lang 0.1.1 → 0.2.0

data/README.textile

@@ -10,7 +10,7 @@ h2. Usage
 
 To use *to_lang*, require the library, then call @ToLang.start@ with your Google Translate API key. At this point you will have access to all the new translation methods, which take the form @to_language@, where "language" is the language you wish to translate to.
 
-Google Translate attempts to detect the source language, but you can specify it explicitly by calling methods in the form @to_language_from_source_language@, where "source_language" is the source language. These methods are generated dynamically and will not appear in a call to @String.new.methods@ until they have been called once. Strings will, however, @respond_to?@ these methods prior to their dynamic definition.
+Google Translate attempts to detect the source language, but you can specify it explicitly by calling methods in the form @to_target_language_from_source_language@, where "target language" is the language you are translating to and "source_language" is the language you are starting with. An inverted form with equivalent functionality, @from_source_language_to_target_language@ is also available. These methods are generated dynamically and will not appear in a call to @String.new.methods@ until they have been called once. Strings will, however, @respond_to?@ these methods prior to their dynamic definition.
 
 The dynamic methods are simply syntactic sugar for @String#translate@, which you can use directly as well.
 
@@ -18,36 +18,62 @@ h2. Examples
 
 Load and initialize *to_lang*:
 
-bq. require 'to_lang'
+<pre><code>require 'to_lang'
 ToLang.start('YOUR_GOOGLE_TRANSLATE_API_KEY')
+</code></pre>
 
 Translate some text to Spanish:
 
-bq. "Very cool gem!".to_spanish
+<pre><code>"Very cool gem!".to_spanish
 => "Muy fresco joya!"
+</code></pre>
 
 A case where the source language is ambiguous:
 
-bq. "a pie".to_spanish
+<pre><code>"a pie".to_spanish
 => "a pie"
 "a pie".to_spanish_from_english
 => "un pastel"
+</code></pre>
+
+Or equivalently:
+
+<pre><code>"a pie".from_english_to_spanish
+=> "un pastel"
+</code></pre>
 
 Using @String#translate@ directly:
 
-bq. "hello world".translate('es')
+<pre><code>"hello world".translate('es')
 => "hola mundo"
 "a pie".translate('es', :from => 'en')
 => "un pastel"
+</code></pre>
+
+h2. Debugging
+
+@String#translate@ also has the advantage of allowing you to get debug output for a translation. @String#translate@ accepts a @:debug@ option with three possible values: @:request@, @:response@, and @:all@. @:request@ will cause the method to return the generated URL for the Google Translate API call. @:response@ will cause the method to return the full response from the API call as a hash. @:all@ will cause the method to return a hash which contains both the generated request URL and the full response.
+
+<pre><code>"hello world".translate('es', :debug => :response)
+=> https://www.googleapis.com/language/translate/v2?key=my_key&q=hello+world&target=es
+</code></pre>
+
+<pre><code>"hello world".translate('es', :debug => :response)
+=> {"data"=>{"translations"=>[{"translatedText"=>"hola mundo"}]}}
+</code></pre>
+
+<pre><code>"hello world".translate('es', :debug => :all)
+=> {:request=>"https://www.googleapis.com/language/translate/v2?key=my_key&q=hello+world&target=es",
+   :response=>{"data"=>{"translations"=>[{"translatedText"=>"hola mundo"}]}}}
+</code></pre>
 
 h2. Supported Languages
 
-*to_lang* adds the following methods to strings. Each of these methods can be called with an explicit source language by appending @_to_source_language@ to the method name.
+*to_lang* adds the following methods to strings. Each of these methods can be called with an explicit source language by appending @_from_source_language@ or prepending @from_source_language_@ to the method name.
 
 * to_afrikaans
 * to_albanian
 * to_arabic
-* to_basque
 * to_belarusian
 * to_bulgarian
 * to_catalan
@@ -104,8 +130,8 @@ API documentation can be found at "rubydoc.info":http://rubydoc.info/github/jimm
 
 h2. Roadmap
 
-* Add Unicode support for Ruby 1.8. *to_lang* currently works safely only under 1.9.
+* Investigate Unicode support for Ruby 1.8. *to_lang* has only been tested with 1.9.
 
 h2. Feedback and Contributions
 
-Feedback is greatly appreciated, as are patch contributions. Feel free to fork the project and send me a pull request.
+Feedback is greatly appreciated. If you have any problems with *to_lang*, please open a new issue. Make sure you are using the latest version of the gem, or HEAD if you've cloned the Git repository directly. Please include debugging output from using @String#translate@'s @:debug@ option, if relevant to your issue. If you'd like to fix bugs, add features, or improve the library in general, feel free to fork the project and send me a pull request with your changes.

data/lib/to_lang/codemap.rb

@@ -5,7 +5,6 @@ module ToLang
     'afrikaans' => 'af',
     'albanian' => 'sq',
     'arabic' => 'ar',
-    'basque' => 'eu',
     'belarusian' => 'be',
     'bulgarian' => 'bg',
     'catalan' => 'ca',

data/lib/to_lang/connector.rb

@@ -28,12 +28,19 @@ module ToLang
     # @param [String] target The language code for the language to translate to.
     # @param [Hash] options A hash of options.
     # @option options [String] :from The language code for the language of @q@.
+    # @option options [Symbol] :debug Debug output to return instead of the translated string. Must be one of @:request@, @:response@, or @:all@.
     #
-    # @raise [RuntimeError] Raises an error for any errors returned by Google Translate.
-    # @return [String] The translated string.
+    # @raise [RuntimeError] Raises an exception for any errors returned by Google Translate.
+    # @return [String, Hash] The translated string or debugging output, as requested.
     #
     def request(q, target, options = {})
-      response = HTTParty.get request_url(q, target, options)
+      request = request_url(q, target, options)
+      return request if options[:debug] == :request
+
+      response = HTTParty.get(request)
+      return { :request => request, :response => response.parsed_response } if options[:debug] == :all
+      return response.parsed_response if options[:debug] == :response
+
       raise response.parsed_response["error"]["message"] if response.parsed_response["error"] && response.parsed_response["error"]["message"]
       CGI.unescapeHTML(response.parsed_response["data"]["translations"][0]["translatedText"])
     end

data/lib/to_lang/string_methods.rb

@@ -34,6 +34,18 @@ module ToLang
             translate(CODEMAP[$1], :from => CODEMAP[$2])
           end
 
+          return send(new_method_name)
+        else
+          original_method_missing(method, *args, &block)
+        end
+      when /^from_(.*)_to_(.*)$/
+        if CODEMAP[$1] && CODEMAP[$2]
+          new_method_name = "from_#{$1}_to_#{$2}".to_sym
+
+          self.class.send(:define_method, new_method_name) do
+            translate(CODEMAP[$2], :from => CODEMAP[$1])
+          end
+
           return send(new_method_name)
         else
           original_method_missing(method, *args, &block)
@@ -66,6 +78,8 @@ module ToLang
       case method.to_s
       when /^to_(.*)_from_(.*)$/
         return true if CODEMAP[$1] && CODEMAP[$2]
+      when /^from_(.*)_to_(.*)$/
+        return true if CODEMAP[$1] && CODEMAP[$2]
       when /^to_(.*)$/
         return true if CODEMAP[$1]
       end

data/lib/to_lang/version.rb

@@ -1,5 +1,5 @@
 module ToLang
   # The current version of the Ruby gem.
   #
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/spec/to_lang/connector_spec.rb

@@ -9,7 +9,7 @@ describe ToLang::Connector do
     @connector.key.should_not be_nil
   end
 
-  context "when sent :request" do
+  describe "#request" do
     def stub_response(parsed_response)
       mock_response = mock('HTTParty::Response', :parsed_response => parsed_response)
       HTTParty.stub(:get).and_return(mock_response)
@@ -18,11 +18,13 @@ describe ToLang::Connector do
     def stub_good_response(translated_text)
       parsed_response = { "data" => { "translations" => [ { "translatedText" => translated_text } ] } }
       stub_response(parsed_response)
+      parsed_response
     end
 
     def stub_bad_response(error_message)
       parsed_response = { "error" => { "message" => error_message } }
       stub_response(parsed_response)
+      parsed_response
     end
 
     context "with only a target language" do
@@ -54,5 +56,27 @@ describe ToLang::Connector do
         expect { @connector.request("a pie", "en", :from => "en") }.to raise_error(RuntimeError, "Bad language pair: en|en")
       end
     end
+
+    context "when debugging the request" do
+      it "returns the request URL" do
+        HTTParty.stub(:get)
+        @connector.request("hello world", "es", :from => "en", :debug => :request).should == "https://www.googleapis.com/language/translate/v2?key=apikey&q=hello+world&target=es&source=en"
+      end
+    end
+
+    context "when debugging the response" do
+      it "returns the full parsed response" do
+        expected_response = stub_good_response("hola mundo")
+        @connector.request("hello world", "es", :from => "en", :debug => :response).should == expected_response
+      end
+    end
+
+    context "when debugging the request and the response" do
+      it "returns a hash with the request URL and the full parsed response" do
+        expected_response = stub_good_response("hola mundo")
+        output = @connector.request("hello world", "es", :from => "en", :debug => :all)
+        output.should == { :request => "https://www.googleapis.com/language/translate/v2?key=apikey&q=hello+world&target=es&source=en", :response => expected_response }
+      end
+    end
   end
 end

data/spec/to_lang/string_methods_spec.rb

@@ -1,15 +1,11 @@
 require "spec_helper"
 
-describe "A ToLang-enabled string" do
+describe String do
   before :all do
     ToLang.start('apikey')
   end
 
-  it "responds to :translate" do
-    String.new.should respond_to :translate
-  end
-
-  context "when sent :translate" do
+  describe "#translate" do
     it "calls ToLang::Connector#request" do
       ToLang.connector.stub(:request)
       ToLang.connector.should_receive(:request).with("hello world", "es")
@@ -17,41 +13,47 @@ describe "A ToLang-enabled string" do
     end
   end
 
-  ToLang::CODEMAP.each do |language, code|
-    it "will respond_to :to_#{language}" do
-      "hello_world".should respond_to "to_#{language}"
-    end
+  it "will respond to :to_<language>" do
+    "hello world".should respond_to :to_spanish
+  end
 
-    it "will respond to :to_#{language}_from_english" do
-      "hello_world".should respond_to "to_#{language}_from_english"
-    end
+  it "will respond to :to_<target>_from_<source>" do
+    "hello world".should respond_to :to_spanish_from_english
+  end
 
-    it "translates to #{language} when sent :to_#{language}" do
-      ToLang.connector.stub(:request)
-      ToLang.connector.should_receive(:request).with("hello world", code)
-      "hello world".send("to_#{language}")
-    end
+  it "will respond to :from_<source>_to_<target>" do
+    "hello world".should respond_to :from_english_to_spanish
+  end
 
-    it "translates to #{language} from english when sent :to_#{language}_from_english" do
-      ToLang.connector.stub(:request)
-      ToLang.connector.should_receive(:request).with("hello world", code, :from => 'en')
-      "hello world".send("to_#{language}_from_english")
-    end
+  it "translates to <language> when sent :to_<language>" do
+    ToLang.connector.stub(:request)
+    ToLang.connector.should_receive(:request).with("hello world", 'es')
+    "hello world".send(:to_spanish)
   end
 
-  context "when a magic method has been called once" do
-    before :each do
-      ToLang.connector.stub(:request)
-      "hello world".to_spanish
-      "hello world".to_spanish_from_english
-    end
+  it "translates to <target> from <source> when sent :to_<target>_from_<source>" do
+    ToLang.connector.stub(:request)
+    ToLang.connector.should_receive(:request).with("hello world", 'es', :from => 'en')
+    "hello world".send(:to_spanish_from_english)
+  end
 
-    it "defines the method and does not call :method_missing the next time" do
-      string = "hello world"
-      string.should_not_receive(:method_missing)
+  it "translates to <target> from <source> when sent :from_<source>_to_<target>" do
+    ToLang.connector.stub(:request)
+    ToLang.connector.should_receive(:request).with("hello world", 'es', :from => 'en')
+    "hello world".send(:from_english_to_spanish)
+  end
+
+  it "defines magic methods when first called and doesn't call :method_missing after that" do
+    ToLang.connector.stub(:request)
+    string = "hello world"
+    magic_methods = lambda do
       string.to_spanish
       string.to_spanish_from_english
+      string.from_english_to_spanish
     end
+    magic_methods.call
+    string.should_not_receive(:method_missing)
+    magic_methods.call
   end
 
   it "calls the original :method_missing if there is no language match in the first form" do
@@ -62,6 +64,10 @@ describe "A ToLang-enabled string" do
     expect { "hello world".to_foo_from_bar }.to raise_error(NoMethodError)
   end
 
+  it "calls the original :method_missing if there is a bad language match in the reversed second form" do
+    expect { "hello world".from_bar_to_foo }.to raise_error(NoMethodError)
+  end
+
   it "calls the original :method_missing if the method does not match either form" do
     expect { "hello world".foo }.to raise_error(NoMethodError)
   end

data/spec/to_lang_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
 describe ToLang do
-  context "when sent :start" do
+  describe ".start" do
     before :all do
       ToLang.start('apikey')
     end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jimmy Cuadra
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-29 00:00:00 -08:00
+date: 2011-01-04 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency