philologic-client 0.0.11 → 0.0.13

data/lib/philologic-client/occurrence.rb

@@ -0,0 +1,79 @@
+
+module Philologic # :nodoc: 
+  class Client    # :nodoc:
+
+    #
+    # Philologic citation occurrence.
+    #
+    # Extends Philologic::Client::Response
+    #
+    # = Usage
+    #
+    #   # <li class='philologic_occurrence'>
+    #   #   <a href="./1/0/0/0/0" class='philologic_cite'>
+    #   #     <span class='philologic_property' title='author'>William Shakespeare</span>, 
+    #   #     <i>
+    #   #       <span class='philologic_cite' title='title'>
+    #   #         The First Part of King Henry the Fourth
+    #   #       </span>
+    #   #     </i>
+    #   #     :
+    #   #     <span class='philologic_property' title='who'></span>
+    #   #   </a>
+    #   # </li>
+    #   o = Philologic::Client::Occurrence.new(html)
+    #   o['author'] # 'William Shakespeare''
+    #   o['title']  # 'The First Part of King Henry the Fourth'
+    #   o['href']   # './1/0/0/0/0'
+    #
+    class Occurrence < ::Philologic::Client::Response
+
+      #
+      # Get document HTML or +nil+
+      #
+      attr_reader :html
+
+      #
+      # Get document text or +nil+
+      #
+      attr_reader :text
+
+      #
+      # Initialize Philologic::Client::Occurrence object.
+      #
+      # Params:
+      # +document+:: Nokogiri document
+      # +client+:: (optional) Philologic::Client object or +nil+
+      #
+      def initialize(document, client = nil)
+        super
+
+        @doc.css('a').each do |a|
+          @properties['href'] = a.attributes['href'].children.text
+        end
+        @doc.css('span.hit_n').each do |span|
+          @properties['hit_n'] = span.children.text.to_i
+        end
+        @doc.css('span.philologic_cite').each do |cite|
+          @properties[ cite.attributes['title'].value ] = cite.children.text
+        end
+
+        @html = @text = nil
+        unless @doc.css('div.philologic_context').first.nil?
+          @text = @doc.css('div.philologic_context').children.text
+          @html = @doc.css('div.philologic_context').children.to_html
+        end
+      end
+
+      # 
+      # Does this document contain text?
+      #
+      def text?
+        @text ? true : false
+      end
+
+    end
+
+  end # class Client
+end # module Philologic
+

data/lib/philologic-client/response.rb

@@ -0,0 +1,63 @@
+
+module Philologic # :nodoc: 
+  class Client    # :nodoc:
+
+    #
+    # Generic server response.
+    #
+    # Extended by Philologic::Client::Bibliography, Philologic::Client::Collocation,
+    # Philologic::Client::Concordance, Philologic::Client::Document, Philologic::Cilent::Frequency
+    # and Philologic::Client::Occurrence
+    #
+    class Response
+      include Enumerable
+
+      #
+      # Get Philologic::Client or +nil+
+      #
+      attr_reader :client
+
+      #
+      # Initialize Philologic::Client::Response object.
+      #
+      # Params:
+      # +document+:: Nokogiri document
+      # +client+:: (optional) Philologic::Client object or +nil+
+      #
+      def initialize(document, client = nil)
+        raise('nil document') if document.nil?
+        @client     = client
+        @doc        = document
+
+        @properties = {}
+        @doc.css('span.philologic_property').each do |p|
+          @properties[ p.attributes['title'].value ] = p.children.text
+        end
+      end
+
+      #
+      # Returns value of attribute +key+ or +nil+.
+      #
+      def [](key)
+        @properties[key]
+      end
+
+      # 
+      # Yield successive property keys.
+      #
+      def each(&block)
+        keys.each { |k| block.call(k) }
+      end
+
+      #
+      # +Array+ of sorted property keys.
+      #
+      def keys
+        @properties.keys.sort
+      end
+
+    end
+
+  end # class Client
+end # module Philologic
+

data/lib/philologic-client/version.rb

@@ -5,6 +5,6 @@ module Philologic
     #
     # Philologic::Client version
     #
-    VERSION = '0.0.11'
+    VERSION = '0.0.13'
   end
 end

data/lib/philologic-client.rb

@@ -1,10 +1,20 @@
 # encoding: utf-8
 
-require 'philologic-client/version'
-
 require 'nokogiri'
 require 'open-uri'
 
+require 'philologic-client/link'
+require 'philologic-client/frequency_row'
+require 'philologic-client/response'
+require 'philologic-client/version'
+
+require 'philologic-client/bibliography'
+require 'philologic-client/collocation'
+require 'philologic-client/concordance'
+require 'philologic-client/document'
+require 'philologic-client/frequency'
+require 'philologic-client/occurrence'
+
 #
 # = Philologic::Client - Ruby client for interacting with the Philologic API.
 #
@@ -14,50 +24,74 @@ require 'open-uri'
 #
 #  Philologic::Client.new(endpoint) do |client|
 #
-#    # Get children of root
-#    client.children.each { |child| puts child }
+#    # Get/Set encoding
+#    encoding        = client.encoding 
+#    client.encoding = 'utf-8' # Default
 #
-#    # Get document
-#    first = client.children.first
-#    doc   = first.document
-#    html  = doc.html
-#    txt   = doc.text
+#    # Get/Set endpoint
+#    endpoint        = client.endpoint
+#    client.endpoint = 'http://philologic.example.org'
 #
+#    # Get bibliography
+#    # +biblio+ is a Philologic::Client::Bibliography object
+#    biblio = client.bibliography
+#    
+#    # Get reference to first title
+#    # +first+ is a Philologic::Client::Occurrence object
+#    first  = biblio.titles.first
 #
-#    # Simple (concordance) search
-#    client.search('sartre').each { |result| puts result }
+#    # Get first title
+#    # +doc+ will be a Philologic::Client::Document object
+#    doc = client.document( first['href'] )
 #
-#    # Search by arbitrary key-value pairs
-#    client.search( :query => 'sartre', :foo => 1 ).each { |result| puts result }
+#    # Get text if present
+#    if doc.text?
+#      txt  = doc.text # Document text
+#      html = doc.html # Document HTML
+#    end
 #
+#    # Get links if present
+#    if doc.links?
+#      doc.links.each do |link|
+#       # +link+ is Philologic::Client::Link object
+#       link.url  # Link URL
+#       link.text # Link text
+#      end
+#    end
 #
-#    # Simple collocation table search.
-#    client.collocation('sartre').each { |result| puts result }
+#    # Get +Array+ of document property keys.
+#    doc.keys
 #
-#    # Collocation table search by arbitrary key-value pairs
-#    client.collocation( :query => 'sartre', :foo => 1 ).each { |result| puts result }
+#    # Get document properties
+#    doc.each { |p| puts "%s\t%s" % [ p, doc[p] ] }
 #
-#    # Links for first result in collocation table search
-#    client.collocation('sartre').first.links.each { |link| puts link }
 #
+#    # Concordance search
+#    # Returns Philologic::Client::Concordance object
+#    q = client.concordance('lion')
 #
-#    # Simple frequency table search.
-#    client.frequency('sartre').each { |result| puts result }
+#    # Get results if present.
+#    if q.results?
+#      q.results.each do |result|
+#        # +result+ is a Philologic::Client::Occurrence object
+#      end 
+#    end
 #
-#    # Frequency table search by arbitrary key-value pairs
-#    client.frequency( :query => 'sartre', :foo => 1 ).each { |result| puts result }
 #
-#    # Links for first result in frequency table search
-#    client.frequency('sartre').first.links.each { |link| puts link }
+#    # Frequency search
+#    # Returns Philologic::Client::Frequency object
+#    q = client.frequency('lion')
 #
+#    # Get results if present
+#    if q.results?
+#      q.results.each do |result|
+#        # +result+ is a Philologic::Client::FrequencyRow object
+#      end
+#    end
 #
-#    # Get/Set encoding
-#    encoding        = client.encoding 
-#    client.encoding = 'utf-8' # Default
 #
-#    # Get/Set endpoint
-#    endpoint        = client.endpoint
-#    client.endpoint = 'http://philologic.example.org'
+#    # Collocation search
+#    # TODO - Pending implementation update
 #
 #  end
 #
@@ -76,9 +110,7 @@ require 'open-uri'
 #
 # == To Do
 #
-# * Add +children+ to Philologic::Document
-# * Add +parent+ to Philologic::Document
-# * Unify (as much as possible) Philologic::Document, Philologic::Link, Philologic::TableRow
+# * Collocation searches
 # * Cache results?
 #
 module Philologic # :nodoc:
@@ -116,71 +148,51 @@ module Philologic # :nodoc:
       self
     end
 
+    # 
+    # Returns Philologic::Client::Bibliography object or +nil+
     #
-    # Return +Array+ of Philologic::Link objects.
-    #
-    # Params:
-    # +path+:: Return children of this path (defaults to +/+)
-    #
-    def children( path = '/' )
-      doc = _get(path)
-      return doc.kind_of?(Array) ? doc : nil
+    def bibliography
+      result = _query( 'title' => '' )
+      return result.kind_of?(Philologic::Client::Bibliography) ? result : nil
     end
 
     #
-    # Return +Array+ of Philologic::TableRow objects.
-    #
-    # *NOTE:* Currently only returns the first page of results by default.
+    # Return Philologic::Client::Concordance objet or +nil+.
     #
     # Params:
-    # +query+:: Search for this query +String+ or +Hash+ key-value pairs.
+    # +query+:: Search for this +query+ string.
     #
-    def collocation(query)
-      raise('no query specified') if ( query.nil? || !( [ Hash,  String ].include?( query.class ) )) || query.empty?
-      defaults = { :report => 'frequency', :field => 'collocates' }
-      doc = search( query.kind_of?(String) ? defaults.merge(:query => query) : defaults.merge(query) )
-      return doc.kind_of?(Array) ? doc : nil
+    def concordance(query)
+      raise('nil query') if ( query.nil? || !( [ Hash,  String ].include?( query.class ) )) || query.empty?
+      defaults = {}
+      r = _query( query.kind_of?(String) ? defaults.merge( :q => query ) : defaults.merge(query) )
+      return r.kind_of?(Philologic::Client::Concordance) ? r : nil
     end
 
     #
-    # Return Philologic::Document object or +nil+.
+    # Return object extending Philologic::Client::Document class or +nil+.
     #
     # Params:
-    # +path+:: Return document at this path (defaults to +/+)
+    # +path+:: Return document at this path
     #
-    def document( path = '/' )
+    def document(path)
       doc = _get(path)
-      return doc.kind_of?(::Philologic::Document) ? doc : nil
+      doc.kind_of?(::Philologic::Client::Document) ? doc : nil
     end
 
     #
-    # Return +Array+ of Philologic::TableRow objects.
-    #
-    # *NOTE:* Currently only returns the first page of results by default.
+    # Return Philologic::Client::Frequency objet or +nil+.
     #
     # Params:
-    # +query+:: Search for this query +String+ or +Hash+ key-value pairs.
+    # +query+:: Search for this +query+ string.
     #
     def frequency(query)
-      raise('no query specified') if ( query.nil? || !( [ Hash,  String ].include?( query.class ) )) || query.empty?
+      raise('nil query') if ( query.nil? || !( [ Hash,  String ].include?( query.class ) )) || query.empty?
       defaults = { :report => 'frequency' }
-      doc = search( query.kind_of?(String) ? defaults.merge(:query => query) : defaults.merge(query) )
-      return doc.kind_of?(Array) ? doc : nil
+      r = _query( query.kind_of?(String) ? defaults.merge( :q => query ) : defaults.merge(query) )
+      return r.kind_of?(Philologic::Client::Frequency) ? r : nil
     end
 
-    #
-    # Return +Array+ of Philologic::Link objects.
-    #
-    # *NOTE:* Currently only returns the first page of results by default.
-    #
-    # Params:
-    # +query+:: Search for this query +String+ or +Hash+ key-value pairs.
-    #
-    def search(query)
-      raise('no query specified') if ( query.nil? || !( [ Hash, String ].include?( query.class ) )) || query.empty?
-      doc = _query( query.kind_of?(String) ? { :query => query } : query )
-      return doc.kind_of?(Array) ? doc : nil
-    end
 
     private
 
@@ -199,7 +211,7 @@ module Philologic # :nodoc:
       # TODO Use +URI+
       raise('no endpoint specified') if @endpoint.nil?
       uri = "#{ @endpoint }#{ @endpoint.end_with?('/') ? '' : '/' }#{path}".gsub( %r{/+$}, '/' )
-      _parse( Nokogiri::XML( open(uri).read, nil, @encoding ) )
+      _parse( Nokogiri::HTML( open(uri).read, nil, @encoding ) )
     end
 
     #
@@ -207,31 +219,20 @@ module Philologic # :nodoc:
     #
     # TODO This needs some love.
     def _parse(doc)
-      if    !doc.css('div.philologic_cite_list').first.nil?
-        children = []
-        doc.css('div.philologic_cite_list').css('a.philologic_cite').each do |cite|
-          children << Philologic::Link.new(self, cite) # TODO Why not a select?
-        end
-        return children
-      elsif !doc.css('div.philologic_concordance').first.nil?
-        results = []
-        doc.css('div.philologic_concordance').css('li.philologic_occurence').each do |occurence|
-          results << Philologic::Link.new(self, occurence) # TODO Why not a select?
-        end
-        return results
-      elsif !doc.css('div.philologic_object').first.nil?
-        return Philologic::Document.new( doc.css('div.philologic_object').first )
-      elsif !doc.css('table.philologic_frequency').first.nil?
-        results = []
-        # Results are keyed off of this field.
-        field = doc.css('table.philologic_frequency').first.attributes['title'].value
-        doc.css('table.philologic_frequency').css('tr.philologic_frequency_row').each do |row|
-          results << Philologic::TableRow.new(self, field, row)
-        end
-        return results
-      # TODO else
-      #  warn "WARNING: could not parse document"
+      return nil if doc.css('div.philologic_response').first.nil?
+
+      if    doc.css('ol.philologic_cite_list').first
+        return Philologic::Client::Bibliography.new(doc)
+      elsif doc.css('ol.philologic_concordance').first
+        return Philologic::Client::Concordance.new(doc)
+      elsif doc.css('div.philologic_navigation').first
+        return Philologic::Client::Document.new(doc)
+      elsif doc.css('div.philologic_object').first
+        return Philologic::Client::Document.new(doc)
+      elsif doc.css('table.philologic_table > tr.freq_header_row').first
+        return Philologic::Client::Frequency.new(doc)
       end
+
       nil
     end
 
@@ -244,190 +245,5 @@ module Philologic # :nodoc:
 
   end # class Philologic::Client
 
-
-  #
-  # Philologic document.
-  #
-  class Document
-
-    #
-    # Initialize Philologic::Document object.
-    #
-    # Params:
-    # +document+:: Nokogiri document
-    #
-    def initialize(document)
-      @doc  = document
-      @text = nil
-    end
-
-    #
-    # Returns value of attribute +key+ or +nil+.
-    #
-    def [](key)
-      @doc.attributes.key?(key) ? @doc.attributes[key].value : nil
-    end
-
-    #
-    # Returns document HTML.
-    #
-    def html
-      @doc.css('div.context_container').to_html
-    end
-
-    #
-    # Returns document text.
-    #
-    def text
-      @text = @doc.text.lstrip.rstrip if @text.nil?
-      @text
-    end
-
-  end # class Philologic::Document
-
-
-  #
-  # Philologic link.
-  #
-  class Link
-
-    #
-    # Initialize Philologic::Link object.
-    #
-    # Params:
-    # +client+:: Philologic::Client object
-    # +document+:: Nokogiri document
-    #
-    def initialize(client, document)
-      raise('nil client') if client.nil?
-      raise('nil document') if document.nil?
-      @client     = client
-      @doc        = document
-      @properties = {}
-
-      if !@doc.css('a.philologic_cite').first.nil?
-        @doc.css('a.philologic_cite').each do |a|
-          a.attributes.keys.each { |k| @properties[k] = a.attributes[k].value }
-        end
-      end
-      if @doc.respond_to?(:attributes)
-        @doc.attributes.keys.each { |k| @properties[k] = @doc.attributes[k].value }
-      end
-      @doc.css('span.philologic_property').each do |span|
-        @properties[ span.attributes['title'].value ] = span.children.text
-      end
-    end
-
-    #
-    # Returns value of attribute +key+ or +nil+.
-    #
-    def [](key)
-      @properties[key]
-    end
-
-    #
-    # Returns Philologic::Document referenced by this Philologic::Link object.
-    #
-    def document
-      @client.document( self['href'] )
-    end
-
-    #
-    # Returns Philologic::Link text.
-    #
-    def text
-      @doc.text.strip
-    end
-
-    #
-    # Return String representation of object.
-    #
-    def to_s
-      [ self['href'], self['title'], self['author'] ].join(' | ')
-    end
-
-  end # class Philologic::Link
-
-
-  #
-  # Philologic table row.
-  #
-  class TableRow
-
-    #
-    # Get +count+
-    #
-    attr_reader :count
-
-    #
-    # Get +field+
-    #
-    attr_reader :field
-
-    #
-    # Get +href+
-    #
-    attr_reader :href
-
-    #
-    # Get +text+
-    #
-    attr_reader :text
-
-
-    #
-    # Initialize Philologic::TableRow object.
-    #
-    # Params:
-    # +client+:: Philologic::Client object
-    # +field+:: Row is keyed off of this field
-    # +document+:: Nokogiri document
-    #
-    def initialize(client, field, document)
-      @client = client
-      @field  = field
-      @doc    = document
-
-      @doc.css('td.philologic_frequency_key').each do |key|
-        key.css('a').each do |a|
-          @href = a.attributes['href'].value
-          @text = a.text.lstrip.rstrip
-          break
-        end
-      end
-      raise('invalid TableRow - no href') unless @href
-      raise('invalid TableRow - no text') unless @text
-
-      @doc.css('td.philologic_frequency_value').each do |value|
-        @count = value.text.to_i
-        break
-      end
-      raise('invalid TableRow - no count') unless @count
-
-    end
-
-    #
-    # Returns value of attribute +key+ or +nil+.
-    #
-    def [](key)
-      @doc.attributes.key?(key) ? @doc.attributes[key].value : nil
-    end
-
-    #
-    # Returns Philologic::Link objects referenced by this Philologic::TableRow object.
-    #
-    def links
-      q = @href.sub( %r{^\./\?}, '' ).split('&')
-      @client.search( Hash[ *q.collect { |v| v.split('=', 2) }.flatten ] )
-    end
-
-    #
-    # Return String representation of object.
-    #
-    def to_s
-      [ @field, @count, @text ].join(' | ')
-    end
-
-  end # class Philologic::TableRow
-
 end # module Philologic
+