camdict 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 86357de26d1ad3547925075d9592facaadcb39f4
+  data.tar.gz: e16be0c399d94659828ad176a9c7557d2289dfda
+SHA512:
+  metadata.gz: b35d9c52c329f91c84cd644520d440d17268f52b29c1eb4328d2ea5b90bedf2cbbcd7308eeb37a919ed0be4fbed16a1ff31d6a2909c72786ec42feaaee92e224
+  data.tar.gz: ac6ce320b885258a6108365e056cfd4b8bb8a6601d950862fcfe5806ce77525807b6894f564063e6b949970843c936f8193cc12d157ed89cf0725becfc24c969

data/README.md

@@ -0,0 +1,59 @@
+# A ruby gem - camdict
+
+## Introduction 
+
+The ruby gem camdict is a [Cambridge online dictionary][1] client.  
+You could use this excellent dictionary with a browser, but now it is possible
+to use it with this ruby API in your code.
+
+## Installation
+`gem install camdict`
+
+## Verification
+The gem can be tested by below commands in the directory where it's installed.  
+`rake`         - run all the testcases which don't need internet connection.  
+`rake itest`   - run all the testcases that need internet connection.  
+`rake testall` - run all above tests.
+
+One test may fail if the gem nokogiri hasn't pulled in the fix [here][2]. But
+it is safe to apply the patch to your nokogiri copy.
+
+## Usage
+    require 'camdict'
+
+    # Look up a new word
+    word = Camdict::Word.new "health"
+
+    # get all definitions for this word from remote dictionary and select the
+    # first one. A word usually has many definitions.
+    health = word.definitions.first
+
+    # Print the part of speech
+    puts health.part_of_speech   #=> noun
+
+    # One definition may have more than one explanations. 
+    # Just look at the details of the first one.
+    explanation1 = health.explanations.first
+
+    # What's the meaning
+    puts explanation1.meaning    #=> 
+    # the condition of the body and the degree to which it is free from 
+    # illness, or the state of being well: 
+
+    # And it may have some useful example sentences.
+    explanation1.examples.each { |e|
+      puts e.sentence            #=> 
+      # to be in good/poor health
+      # Regular exercise is good for your health.
+      # I had to give up drinking for health reasons.
+      # He gave up work because of ill health.
+    }
+
+
+There are some useful testing examples in test directory of this gem.
+
+## Licence MIT
+Copyright (c) 2014 Pan Gaoyong
+
+[1]: http://dictionary.cambridge.com "Cambridge"
+[2]: https://github.com/sparklemotion/nokogiri/pull/1020 "My Nokogiri Bug Fix"

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rake/testtask'
+
+Rake::TestTask.new(:default) do |t|
+  t.test_files = FileList['test/test_*.rb']
+end
+
+Rake::TestTask.new(:itest) do |t|
+  t.test_files = FileList['test/itest_*.rb']
+end
+
+desc "No internet connection required"
+task :default => :test
+
+desc "Needs internet connection"
+task :itest => :test
+
+desc "Run all tests"
+task :testall => :default
+task :testall => :itest
+  

data/lib/camdict/client.rb

@@ -0,0 +1,153 @@
+require "camdict/http_client"
+
+module Camdict
+
+  # The client downloads all the useful data about a word or phrase from 
+  # remote Cambridge dictionaries, but not includes the extended data. 
+  # For example,
+  # when the word "mind" is searched, all its four exactly matched entries are
+  # downloaded. However, separated entries like "turn of mind" & "open mind" 
+  # are not included.
+  class Client
+
+    # Default dictionary is british. Other possible +dict+ values: 
+    # american-english, business-english, learner-english.
+    def initialize(dict=nil)
+      @dictionary = dict || "british"
+    end
+    
+
+    # Get a word's html definition(s) by searching it from the web dictionary.
+    # The returned result could be an empty array when nothing is found, or
+    # is an array with a hash element, 
+    #   [{ word => html definition }], 
+    # or many hash elements when it has multiple entries, 
+    #   [{ entry_id => html definition }, ...].
+    # Normally, when a +word+ has more than one meanings, its entry ID format is
+    # like word_nn. Otherwise it's just the word itself.
+    def html_definition(word)
+      html = fetch(word)
+      return [] if html.nil?
+      html_defs = []
+      # some words return their only definition directly, such as aluminium.
+      if definition_page? html
+        # entry id is just the word when there is only one definition
+        html_defs << { word => di_head(html) + di_body(html) }
+      else
+        # returned page could be a spelling check suggestion page in case it is 
+        # not found, or the found page with all matched entries and related.
+        # when entry urls are not found, they are empty and spelling suggestion
+        # pages. So mentry_links() returns an empty array. Otherwise, it returns
+        # all the exactly matched entry links.
+        matched_urls = mentry_links(word, html)
+        unless matched_urls.empty?
+          matched_urls.each { |url|
+            html_defs << { entry_id(url) => get_htmldef(url) }
+          }
+        end
+      end
+      html_defs
+    end
+
+    # Get a word html page source by its entry +url+.
+    def get_htmldef(url)
+      html = Camdict::HTTP::Client.get_html(url)
+      di_head(html) + di_body(html)
+    end
+
+    private
+
+    # Fetch word searching result page.
+    # Returned result is either just a single definition page if there is only
+    # one entry, or a result page listing all possible entries, or spelling 
+    # check result. All results are objects of Nokogiri::HTML.
+    def fetch(w)
+      # search a word with this URL
+      search_url = "http://dictionary.cambridge.org/search/#{@dictionary}/?q="
+      url = search_url + w
+      begin 
+        Camdict::HTTP::Client.get_html(url)
+      rescue OpenURI::HTTPError => e
+        # "404" == e.message[0..2], When a word is not found, it returns 404
+        # Not Found and spelling suggestions page.
+      end
+    end
+
+    # To determine whether or not the input object of Nokogiri::HTML is a page 
+    # of a word definition. Return true if it has a source structure like this,
+    # <div class="di-head">
+    #   <div class="di-title">
+    #     <h1 class="hw">
+    # This works for the translation page too, like English-Spanish.
+    def single_def?(html)
+      node = html.css(".di-head .di-title .hw")
+      ! node.empty?
+    end
+
+    # Find out matched entry links from search result page
+    # <ul class="result-list">
+    #   <li><a href="entry_link1">
+    #   <li><a href="entry_link2">
+    # The search result html page should include above piece of code. 
+    # The extended links are filtered out and the matched word or phrase's 
+    # links are kept. An array of them are returned.
+    # For example, when the searched word is "related", entry links are like, 
+    #   http://dictionary.cambridge.org/dictionary/british/related_1
+    #   http://dictionary.cambridge.org/dictionary/british/related_2
+    #   http://dictionary.cambridge.org/dictionary/british/stress-related
+    #   ...
+    # Returned result should only contain the first two.
+    # Input html is an object of Nokogiri::HTML.
+    def mentry_links(word, html)
+      # suppose the word is not found in the dictionary, so it is empty.
+      links = []
+      nodes = html.css(".result-list a")
+      # when found
+      unless nodes.empty? 
+        nodes.each { |a|
+          links << a['href'] if matched_word?(word, a)
+        }
+      end
+      links
+    end
+
+    # Return true if the searched word matches the one on result page.
+    # Node is an object of Nokogiri::Node
+    # <li>
+    #   <span class="base">
+    #     <b class="phrase">out of mind, or
+    #     <b class="hw">turn of mind, or
+    #     <b class="w">mind-numbingly
+    # Match criterion: the queried word should equal to the result word; 
+    #   the result phrase should be flattened, which should equal to the
+    #   queried phrase.
+    def matched_word?(word, node)
+      li = node.css(".base")
+      resword = li.size == 1 ? li.text : li[0].text
+      if resword.include? '/'
+        resword.flatten.include?(word)
+      else
+        word == resword
+      end
+    end
+
+    # Return definition head in html source
+    def di_head(html)
+      html.css(".cdo-section-title-hw").to_html(:save_with=>0) + 
+      html.css(".di-info").to_html(:save_with=>0)
+    end
+
+    # Return definition body in html source
+    def di_body(html)
+      html.css(".di-body").to_html(:save_with=>0)
+    end
+
+    # get the last part of http://dictionary.cambridge.org/british/related_1
+    def entry_id(url)
+      url.split('/').last
+    end
+
+    alias :definition_page? :single_def?
+
+  end
+end

data/lib/camdict/common.rb

@@ -0,0 +1,136 @@
+module Camdict
+  module Common
+
+    # Extend String class.
+    String.class_eval do
+      # 'blow a kiss to/at sb'.flatten =>
+      # %q(blow a kiss to sb, blow a kiss at sb)
+      # if it doesn't include a slash, returns unchanged itself 
+      def flatten
+        return self unless self.include? '/'
+        ret = []
+        len = self.length
+        j=0     # count of the alternative words, 'to/at' has two.
+        b=[]    # b[]/e[] index of the beginning/end of a alternative word
+        e=[]
+        # set this flag when next word is expected an alternate word after slash
+        include_next = false 
+        for i in (0..len-1)
+          c = self[i] 
+          case 
+          when c =~ /[[:alpha:]\-\(\)]/
+            if b[j].nil?
+              b[j] = i
+              e[j] = i
+            else
+              e[j] = i
+            end
+          when c == " " 
+            if include_next
+              break
+            else
+              b[j] = nil
+              e[j] = nil
+            end
+          when c == "/"
+            j += 1
+            include_next = true
+          else
+            raise "Invalid char '#{c}' found in a string."
+          end
+        end
+        if j > 0
+          for i in (0..j)
+            # alternative word is not the last word and not at the beginning
+            if (e[j]+1 < len) && (b[0] > 0)
+              ret << self[0..b[0]-1] + self[b[i]..e[i]] + self[e[j]+1..len-1]
+            elsif (e[j]+1 == len) && (b[0] > 0)
+              ret << self[0..b[0]-1] + self[b[i]..e[i]]
+            elsif (e[j]+1 < len) && (b[0] == 0)
+              ret << self[b[i]..e[i]] + self[e[j]+1..len-1]
+            else
+              ret << self[b[i]..e[i]]
+            end
+          end 
+        end
+        ret
+      end
+
+      # Test whether a String includes the +word+. It's useful while testing 
+      # a variable which might be an array of phrase or just a single phrase.
+      def has?(word)
+        self.include? word
+      end
+    end
+
+    # Extend Array class.
+    Array.class_eval do
+      # Expand a phrase array into a flattened one. Example, 
+      #   ['blow your nose', 'blow a kiss to/at sb'] #=>
+      #   ['blow your nose', 'blow a kiss to sb', 'blow a kiss at sb']
+      def expand
+        ret = self.map { |p|
+          p.flatten if p.is_a? String
+        }
+        ret.flatten
+      end
+
+
+      # Test if a phrase array includes a +word+.
+      #   ['blow your nose', 'blow a kiss to/at sb'].has?("a kiss at") #=>true
+      def has?(word)
+        self.expand.each { |phr|
+          return true if phr.include? word
+        }
+        false
+      end
+
+      # Iterate an array and return two elements +a+ +b+ each time for handling.
+      def each_pair
+        len = self.length
+        i = 0
+        while (i < len)
+          a = self.at(i)
+          b = self.at(i+1)
+          yield(a, b)
+          i += 2
+        end
+      end
+    end
+
+    private
+    # Get the text selected by the css +selector+.
+    def css_text(selector)
+      node = @html.css(selector)
+      node.text unless node.empty?
+    end
+
+    # Get sth by the css +selector+ for the derived word inside its runon node 
+    def derived_css(selector)
+      runon = @html.css(".runon")
+      runon.each { |r|
+        n = r.css('[title="Derived word"]')
+        if n.text == @word 
+          node = r.css(selector)
+          yield(node)
+        end
+      }
+    end
+
+    # Get sth by the css +selector+ for the phrase inside the node phrase-block
+    def phrase_css(selector)
+      phbs = @html.css(".phrase-block")
+      phbs.each { |phb|
+        nodes = phb.css('.phrase, .v[title="Variant form"]')
+        nodes.each { |n|
+          if n.text.flatten.has? @word
+            node = phb.css(selector)
+            yield(node)
+            break
+          end
+        }
+      }
+    end
+
+  end
+end