to_lang 0.1.0 → 0.1.1

data/.gitignore

@@ -3,3 +3,5 @@ pkg/*
 .bundle
 Gemfile.lock
 coverage/*
+doc/*
+.yardoc

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--protected
+--markup textile
+-
+README.textile

data/README.textile

@@ -8,7 +8,11 @@ Simply run @gem install to_lang@.
 
 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.
+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.
+
+The dynamic methods are simply syntactic sugar for @String#translate@, which you can use directly as well.
 
 h2. Examples
 
@@ -29,6 +33,13 @@ bq. "a pie".to_spanish
 "a pie".to_spanish_from_english
 => "un pastel"
 
+Using @String#translate@ directly:
+
+bq. "hello world".translate('es')
+=> "hola mundo"
+"a pie".translate('es', :from => 'en')
+=> "un pastel"
+
 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.
@@ -87,10 +98,13 @@ h2. Supported Languages
 * to_welsh
 * to_yiddish
 
+h2. Documentation
+
+API documentation can be found at "rubydoc.info":http://rubydoc.info/github/jimmycuadra/to_lang/master/frames.
+
 h2. Roadmap
 
-- Add complete documentation for the library.
-- Add Unicode support for Ruby 1.8. *to_lang* currently works safely only under 1.9.
+* Add Unicode support for Ruby 1.8. *to_lang* currently works safely only under 1.9.
 
 h2. Feedback and Contributions
 

data/Rakefile

@@ -5,3 +5,12 @@ require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.options = [
+    '--no-private',
+    '--protected',
+    '--markup', 'textile',
+  ]
+end

data/lib/to_lang/codemap.rb

@@ -1,4 +1,6 @@
 module ToLang
+  # A list of all the languages {ToLang} supports and the language code each maps to. Strings will gain @to_language@ and @to_language_from_language@ methods for any @language@ in this list.
+  #
   CODEMAP = {
     'afrikaans' => 'af',
     'albanian' => 'sq',

data/lib/to_lang/connector.rb

@@ -1,28 +1,57 @@
-require 'rubygems'
 require 'httparty'
-require 'uri'
+require 'cgi'
 
 module ToLang
+  # Responsible for making the actual HTTP request to the Google Translate API.
+  #
   class Connector
+    # The base URL for all requests to the Google Translate API.
+    #
     API_URL = "https://www.googleapis.com/language/translate/v2"
 
+    # The Google Translate API key to use when making API calls.
+    #
+    # @return [String] The Google Translate API key.
+    #
     attr_reader :key
 
+    # Initializes a new {ToLang::Connector} and stores a Google Translate API key.
+    #
+    # @return [ToLang::Connector] The new {ToLang::Connector} instance.
     def initialize(key)
       @key = key
     end
 
+    # Makes a request to the Google Translate API.
+    #
+    # @param [String] q The string to translate.
+    # @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@.
+    #
+    # @raise [RuntimeError] Raises an error for any errors returned by Google Translate.
+    # @return [String] The translated string.
+    #
     def request(q, target, options = {})
       response = HTTParty.get request_url(q, target, options)
       raise response.parsed_response["error"]["message"] if response.parsed_response["error"] && response.parsed_response["error"]["message"]
-      response.parsed_response["data"]["translations"][0]["translatedText"]
+      CGI.unescapeHTML(response.parsed_response["data"]["translations"][0]["translatedText"])
     end
 
     private
 
+    # Constructs the URL that will be used by {#request}.
+    #
+    # @param [String] q The string to translate.
+    # @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@.
+    #
+    # @return [String] The URL to request for the API call.
+    #
     def request_url(q, target, options)
       source = options[:from]
-      url = "#{API_URL}?key=#{@key}&q=#{URI.escape(q)}&target=#{target}"
+      url = "#{API_URL}?key=#{@key}&q=#{CGI.escape(q)}&target=#{target}"
       url += "&source=#{source}" if source
       url
     end

data/lib/to_lang/string_methods.rb

@@ -0,0 +1,76 @@
+require "to_lang/codemap"
+
+module ToLang
+  # The methods {ToLang} will mix into the String class when initialized.
+  #
+  module StringMethods
+    # Translates a string to another language. All the magic methods use this internally. It, in turn, forwards
+    # everything on to {ToLang::Connector#request}
+    #
+    # @param [String] target The language code for the language to translate to.
+    # @param args Any additional arguments, such as the source language.
+    #
+    # @return [String] The translated string.
+    #
+    def translate(target, *args)
+      ToLang.connector.request(self, target, *args)
+    end
+
+    # Chain @method_missing@ in case another library has used it.
+    #
+    alias_method :original_method_missing, :method_missing
+
+    # Overrides @method_missing@ to catch and define dynamic translation methods.
+    #
+    # @private
+    #
+    def method_missing(method, *args, &block)
+      case method.to_s
+      when /^to_(.*)_from_(.*)$/
+        if CODEMAP[$1] && CODEMAP[$2]
+          new_method_name = "to_#{$1}_from_#{$2}".to_sym
+
+          self.class.send(:define_method, new_method_name) do
+            translate(CODEMAP[$1], :from => CODEMAP[$2])
+          end
+
+          return send(new_method_name)
+        else
+          original_method_missing(method, *args, &block)
+        end
+      when /^to_(.*)$/
+        if CODEMAP[$1]
+          new_method_name = "to_#{$1}".to_sym
+
+          self.class.send(:define_method, new_method_name) do
+            translate(CODEMAP[$1])
+          end
+
+          return send(new_method_name)
+        else
+          original_method_missing(method, *args, &block)
+        end
+      else
+        original_method_missing(method, *args, &block)
+      end
+    end
+
+    # Chain @respond_to?@ in case another library has used it.
+    alias_method :original_respond_to?, :respond_to?
+
+    # Overrides @respond_to?@ to make strings aware of the dynamic translation methods.
+    #
+    # @private
+    #
+    def respond_to?(method, include_private = false)
+      case method.to_s
+      when /^to_(.*)_from_(.*)$/
+        return true if CODEMAP[$1] && CODEMAP[$2]
+      when /^to_(.*)$/
+        return true if CODEMAP[$1]
+      end
+
+      original_respond_to?(method, include_private)
+    end
+  end
+end

data/lib/to_lang/version.rb

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

data/lib/to_lang.rb

@@ -1,60 +1,29 @@
-require File.expand_path("../to_lang/codemap", __FILE__)
-require File.expand_path("../to_lang/connector", __FILE__)
-
+require "to_lang/connector"
+require "to_lang/string_methods"
+
+# {ToLang} is a Ruby library that adds language translation methods to strings, backed by the Google Translate API.
+#
+# @author Jimmy Cuadra
+# @see https://github.com/jimmycuadra/to_lang Source on GitHub
+#
 module ToLang
   class << self
+    # A {ToLang::Connector} object to use for translation requests.
+    #
+    # @return [ToLang::Constructor, NilClass] An initialized {ToLang::Connector connector} or nil.
+    #
     attr_reader :connector
 
+    # Initializes {ToLang}, after which the translation methods will be available from strings.
+    #
+    # @param [String] key A Google Translate API key.
+    #
+    # @return [Class, Boolean] @String@ if initialization succeeded, @false@ if this method has already been called successfully.
+    #
     def start(key)
       return false if defined?(@connector) && !@connector.nil?
       @connector = ToLang::Connector.new(key)
       String.send(:include, StringMethods)
-      add_magic_methods
-      true
-    end
-
-    private
-
-    def add_magic_methods
-      String.class_eval do
-        def method_missing(method, *args, &block)
-          if method.to_s =~ /^to_(.*)_from_(.*)$/ && CODEMAP[$1] && CODEMAP[$2]
-            new_method_name = "to_#{$1}_from_#{$2}".to_sym
-
-            self.class.send(:define_method, new_method_name, Proc.new {
-              translate(CODEMAP[$1], :from => CODEMAP[$2])
-            })
-
-            send new_method_name
-          elsif method.to_s =~ /^to_(.*)$/ && CODEMAP[$1]
-            new_method_name = "to_#{$1}".to_sym
-
-            self.class.send(:define_method, new_method_name, Proc.new {
-              translate(CODEMAP[$1])
-            })
-
-            send new_method_name
-          else
-            super
-          end
-        end
-
-        def respond_to?(method, include_private = false)
-          if method.to_s =~ /^to_(.*)_from_(.*)$/ && CODEMAP[$1] && CODEMAP[$2]
-            true
-          elsif method.to_s =~ /^to_(.*)$/ && CODEMAP[$1]
-            true
-          else
-            super
-          end
-        end
-      end
-    end
-  end
-
-  module StringMethods
-    def translate(target, *args)
-      ToLang.connector.request(self, target, *args)
     end
   end
 end

data/spec/spec_helper.rb

@@ -3,4 +3,4 @@ SimpleCov.start do
   add_filter "/spec/"
 end
 
-require File.expand_path('../../lib/to_lang', __FILE__)
+require "to_lang"

data/spec/to_lang/connector_spec.rb

@@ -1,4 +1,4 @@
-require File.expand_path('../../spec_helper', __FILE__)
+require "spec_helper"
 
 describe ToLang::Connector do
   before :all do

data/spec/to_lang/string_methods_spec.rb

@@ -0,0 +1,68 @@
+require "spec_helper"
+
+describe "A ToLang-enabled 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
+    it "calls ToLang::Connector#request" do
+      ToLang.connector.stub(:request)
+      ToLang.connector.should_receive(:request).with("hello world", "es")
+      "hello world".translate("es")
+    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}_from_english" do
+      "hello_world".should respond_to "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", code)
+      "hello world".send("to_#{language}")
+    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
+  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 "defines the method and does not call :method_missing the next time" do
+      string = "hello world"
+      string.should_not_receive(:method_missing)
+      string.to_spanish
+      string.to_spanish_from_english
+    end
+  end
+
+  it "calls the original :method_missing if there is no language match in the first form" do
+    expect { "hello world".to_foo }.to raise_error(NoMethodError)
+  end
+
+  it "calls the original :method_missing if there is a bad language match in the second form" do
+    expect { "hello world".to_foo_from_bar }.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
+end

data/spec/to_lang_spec.rb

@@ -19,60 +19,3 @@ describe ToLang do
     end
   end
 end
-
-describe "A string" do
-  context "after ToLang has received :start" 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
-      it "calls ToLang::Connector#request" do
-        ToLang.connector.stub(:request)
-        ToLang.connector.should_receive(:request).with("hello world", "es")
-        "hello world".translate("es")
-      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}_from_english" do
-        "hello_world".should respond_to "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", code)
-        "hello world".send("to_#{language}")
-      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
-    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 "defines the method and does not call :method_missing the next time" do
-        string = "hello world"
-        string.should_not_receive(:method_missing)
-        string.to_spanish
-        string.to_spanish_from_english
-      end
-    end
-  end
-end

data/to_lang.gemspec

@@ -17,6 +17,10 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency "httparty", "~> 0.6"
+  s.add_development_dependency "bundler", "~> 1.0"
+  s.add_development_dependency "rake", "~> 0.8"
   s.add_development_dependency "rspec", "~> 2.3"
   s.add_development_dependency "simplecov", "~> 0.3"
+  s.add_development_dependency "yard", "~> 0.6"
+  s.add_development_dependency "RedCloth", "~> 4.2"
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Jimmy Cuadra
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-26 00:00:00 -08:00
+date: 2010-12-29 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -32,9 +32,37 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: bundler
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 8
+        version: "0.8"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -44,11 +72,11 @@ dependencies:
         - 3
         version: "2.3"
   type: :development
-  version_requirements: *id002
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: simplecov
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -58,7 +86,35 @@ dependencies:
         - 3
         version: "0.3"
   type: :development
-  version_requirements: *id003
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        version: "0.6"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: RedCloth
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 4
+        - 2
+        version: "4.2"
+  type: :development
+  version_requirements: *id007
 description: Adds language translation methods to strings, backed by the Google Translate API
 email: 
 - jimmy@jimmycuadra.com
@@ -70,15 +126,18 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- .yardopts
 - Gemfile
 - README.textile
 - Rakefile
 - lib/to_lang.rb
 - lib/to_lang/codemap.rb
 - lib/to_lang/connector.rb
+- lib/to_lang/string_methods.rb
 - lib/to_lang/version.rb
 - spec/spec_helper.rb
 - spec/to_lang/connector_spec.rb
+- spec/to_lang/string_methods_spec.rb
 - spec/to_lang_spec.rb
 - to_lang.gemspec
 has_rdoc: true
@@ -116,4 +175,5 @@ summary: Adds language translation methods to strings, backed by the Google Tran
 test_files: 
 - spec/spec_helper.rb
 - spec/to_lang/connector_spec.rb
+- spec/to_lang/string_methods_spec.rb
 - spec/to_lang_spec.rb