opds 0.2.0 → 0.3.0

data/README.md

@@ -17,10 +17,12 @@ Usage
 Parsing a feed is simply done. 
 
 	require "opds"
-	OPDS::Feed.parse_url("http://catalog.com/catalog.atom")
+	OPDS.access("http://catalog.com/catalog.atom")
 
 This method will return an instance of the Feed or Entry classes. Each Atom element is accessible directly via a dedicated method (ex: `feed.title`). Entry also provides a method to directly access any embeded Dublin Core metadata (`dcmeta`). The `raw_doc` attribute gives access to the Nokogiri parsed source.
 
+API documentation can be found on [rdoc.info](http://rdoc.info/github/zetaben/opds/master/frames)
+
 ### Complete atom entries ###
 
 Complete atom entries are available if detected as another instance of the Entry class. Just call `entry.complete` on the partial entry to access it.

data/Rakefile

@@ -23,6 +23,7 @@ require 'spec/rake/spectask'
 Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.libs << 'lib' << 'spec'
   spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--format=specdoc']
 end
 
 Spec::Rake::SpecTask.new(:rcov) do |spec|

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/opds/acquisition_feed.rb

@@ -1,4 +1,33 @@
 module OPDS
+	# Represents an acquisition feed
+	# @see http://opds-spec.org/specs/opds-catalog-1-0-20100830/#Acquisition_Feeds
 	class AcquisitionFeed < Feed
+
+		# Get a collection of facets groupped by opds:facetGroup
+		# @return [Hash] facets
+		def facets
+			return @facets if @facets
+			@facets={}
+			links['http://opds-spec.org/facet'].each do |facet|
+			@facets[facet.facet_group]||=[]
+			@facets[facet.facet_group].push facet
+			end
+			@facets
+		end
+
+
+		# Get a collection of active_facets by opds:facetGroup
+		# @return [Hash] active facets
+		def active_facets
+			return @selected if @selected
+			@selected={}
+			facets.each do |k,v|
+				@selected[k]=nil
+				v.each do |f|
+				@selected[k]=f if f.active_facet?
+				end
+			end
+			@selected
+		end
 	end
 end

data/lib/opds/entry.rb

@@ -1,27 +1,51 @@
 module OPDS
+	# Represents a catalog entry
 	class Entry
 		include Logging
+
+		# "Raw" Nokogiri document used while parsing.
+		# It might useful to access atom foreign markup
+		# @return [Nokogiri::XML::Document] Parsed document
 		attr_reader :raw_doc
+		# @return [String] entry title
 		attr_reader :title
+		# @return [String] entry id
 		attr_reader :id
+		# @return [Date] entry updated date
 		attr_reader :updated
+		# @return [Date] entry published date
 		attr_reader :published
+		# @return [String] entry summary
 		attr_reader :summary
+		# @return [Array] entry parsed authors
 		attr_reader :authors
+		# @return [Array] entry parsed contributors
+		attr_reader :contributors
+		# @return [OPDS::Support::LinkSet] Set of links found in the entry
 		attr_reader :links
+		# @return [Hash] Hash of found dublin core metadata found in the entry
+		# @see http://dublincore.org/documents/dcmi-terms/
 		attr_reader :dcmetas
+		# @return [Array] Categories found 
 		attr_reader :categories
+		# @return [String] content found 
 		attr_reader :content
+		# @return [String] entry right
 		attr_reader :rights
+		# @return [String] entry subtitle
 		attr_reader :subtitle
 
-		def initialize(browser=nil)
+		# @param browser (see Feed.parse_url)
+		def initialize(browser=OPDS::Support::Browser.new)
 			@browser=browser
-			@browser||=OPDS::Support::Browser.new
 		end
 
-
-		def self.from_nokogiri(content,namespaces=nil, browser=nil)
+		# Create an entry from a nokogiri fragment 
+		# @param content [Nokogiri::XML::Element] Nokogiri fragment (should be <entry>)
+		# @param namespaces Associated document namespaces
+		# @param browser (see Feed.parse_url)
+		# @return [Entry]
+		def self.from_nokogiri(content,namespaces=nil, browser=OPDS::Support::Browser.new)
 			z=self.new browser
 			z.instance_variable_set('@raw_doc',content)
 			z.instance_variable_set('@namespaces',namespaces)
@@ -29,7 +53,9 @@ module OPDS
 			z
 		end
 
-
+		# Read the provided document into the entry struct 
+		# @private
+		# @todo really make private
 		def serialize!
 			@namespaces=raw_doc.root.namespaces if @namespaces.nil?
 			@authors=[]
@@ -101,23 +127,29 @@ module OPDS
 
 		end
 
-
+		#First Author
+		# @return [Hash]
 		def author
 			authors.first
 		end
-
+		
+		# Is it a partial atom entry ?
+		# @return [boolean]
 		def partial?
 			links.by(:rel)['alternate'].any? do |l|
 				l[3]=='application/atom+xml'||l[3]=='application/atom+xml;type=entry'
 			end
 		end
-
+		
+		# @return [String] URL to the complete entry
+		# @todo accessor to the complete entry
 		def complete_url
 			links.by(:rel)['alternate'].find do |l|
 				l[3]=='application/atom+xml;type=entry'||l[3]=='application/atom+xml'
 			end unless !partial?
 		end
-
+		
+		# @return [Array] acquisition link subset
 		def acquisition_links
 			rel_start='http://opds-spec.org/acquisition'
 			[*links.by(:rel).reject do |k,_|

data/lib/opds/feed.rb

@@ -1,7 +1,16 @@
 module OPDS
+	# Feed class is used as an ancestor to NavigationFeed and AcquisitionFeed it handles
+	# all the parsing
+	# @abstract Not really abstract as it's full fledged, but it should not be used directly
 	class Feed
 		include Logging
+		# "Raw" Nokogiri document used while parsing.
+		# It might useful to access atom foreign markup
+		# @return [Nokogiri::XML::Document] Parsed document
 		attr_reader :raw_doc
+		# Entry list
+		# @see Entry
+		# @return [Array<Entry>] list of parsed entries
 		attr_reader :entries
 
 
@@ -9,7 +18,7 @@ module OPDS
 			@browser=browser
 			@browser||=OPDS::Support::Browser.new
 		end
-
+=begin
 		# access root catalog
 		def root
 			return @root unless root?
@@ -19,10 +28,23 @@ module OPDS
 		# root catalog predicate
 		def root?
 		end
-
-		def self.parse_url(url,browser=nil,parser_opts={})
+=end
+
+
+		# Parse the given url.
+		#
+		# If the resource at the give url is not an OPDS Catalog, this method will 
+		# try to find a linked catalog.
+		# If many are available it will take the first one with a priority given to 
+		# nil rel or rel="related" catalogs.
+		#
+		# @param url [String] url to parse
+		# @param browser (see Feed.parse_raw)
+		# @param parser_opts parser options (unused at the moment)
+		# @see OPDS::Support::Browser
+		# @return [AcquisitionFeed,NavigationFeed, Entry, nil] an instance of a parsed feed, entry or nil
+		def self.parse_url(url,browser=OPDS::Support::Browser.new,parser_opts={})
 			@browser=browser
-			@browser||=OPDS::Support::Browser.new
 			@browser.go_to(url)
 			if @browser.ok?
 				parsed = self.parse_raw(@browser.body,parser_opts,browser) 
@@ -44,6 +66,12 @@ module OPDS
 			end
 		end
 
+		# Will parse a text stream as an OPDS Catalog, internaly used by #parse_url
+		#
+		# @param txt [String] text to parse
+		# @param opts [Hash] options to pass to the parser
+		# @param browser [OPDS::Support::Browser] an optional compatible browser to use
+		# @return [AcquisitionFeed,NavigationFeed] an instance of a parsed feed or nil
 		def self.parse_raw(txt,opts={},browser=nil)
 			parser=OPDSParser.new(opts)
 			pfeed=parser.parse(txt,browser)
@@ -52,6 +80,11 @@ module OPDS
 			nil
 		end
 
+		
+		# Create a feed from a nokogiri document
+		# @param content [Nokogiri::XML::Document] nokogiri document
+		# @param browser (see Feed.parse_url)
+		# @return [Feed] new feed
 		def self.from_nokogiri(content,browser=nil)
 			z=self.new browser
 			z.instance_variable_set('@raw_doc',content)
@@ -59,34 +92,52 @@ module OPDS
 			z
 		end
 
-		#read xml entries into entry struct
+		# @private
+		# read xml entries into the entry list struct
+		# @todo really make private
 		def serialize!
 			@entries=raw_doc.xpath('/xmlns:feed/xmlns:entry',raw_doc.root.namespaces).map do |el|
 				OPDS::Entry.from_nokogiri(el,raw_doc.root.namespaces,@browser)
 			end
 		end
 
+		
+		# @return [String] Feed title
 		def title
 			text(raw_doc.at('/xmlns:feed/xmlns:title',raw_doc.root.namespaces))
 		end
 
+		# @return [String] Feed icon definition
 		def icon
 			text(raw_doc.at('/xmlns:feed/xmlns:icon',raw_doc.root.namespaces))
 		end
 
+		# @return [OPDS::Support::LinkSet] Set with atom feed level links
 		def links
 			if !@links || @links.size ==0
 				@links=OPDS::Support::LinkSet.new @browser
 				raw_doc.xpath('/xmlns:feed/xmlns:link',raw_doc.root.namespaces).each do |n|
 					text=nil
 					text=n.attributes['title'].value unless n.attributes['title'].nil?
+					type=n.attributes['type'].value unless n.attributes['type'].nil?
 					link=n.attributes['href'].value
 					unless n.attributes['rel'].nil?
 						n.attributes['rel'].value.split.each do |rel|
-							@links.push(rel,link,text)
+							if rel=='http://opds-spec.org/facet'
+								group=n.attribute_with_ns('facetGroup','http://opds-spec.org/2010/catalog')
+								group=group.value unless group.nil?
+								active=n.attribute_with_ns('activeFacet','http://opds-spec.org/2010/catalog')
+								active=active.value unless active.nil?
+								count=n.attribute_with_ns('count','http://purl.org/syndication/thread/1.0')
+								count=count.value unless count.nil?
+
+							@links.push_facet(link,text,type,group,active,count)
+							else
+							@links.push(rel,link,text,type)
+							end
 						end
 					else
-						@links.push(nil,link,text)
+						@links.push(nil,link,text,type)
 					end
 				end
 
@@ -94,10 +145,12 @@ module OPDS
 			@links
 		end
 
+		# @return [String] Feed id
 		def id
 			text(raw_doc.at('/xmlns:feed/xmlns:id',raw_doc.root.namespaces))
 		end
 
+		# @return [Hash] Feed author (keys : name,uri,email)
 		def author
 			{
 				:name => text(raw_doc.at('/xmlns:feed/xmlns:author/xmlns:name',raw_doc.root.namespaces)),
@@ -106,31 +159,42 @@ module OPDS
 			}
 		end
 
-
+		# @return [String] Next page url
 		def next_page_url
 			links.link_url(:rel => 'next')
 		end
 
+		# @return [String] Previous page url
 		def prev_page_url
 			links.link_url(:rel => 'prev')
 		end
 
+		# Is the feed paginated ?
+		# @return Boolean
 		def paginated?
 			!next_page_url.nil?||!prev_page_url.nil?
 		end
 
+		# Is it the first page ?
+		# @return Boolean
 		def first_page?
 			!prev_page_url if paginated?
 		end
 
+		# Is it the last page ?
+		# @return Boolean
 		def last_page?
 			!next_page_url if paginated?
 		end
 
+		# Get next page feed
+		# @return (see Feed.parse_url)
 		def next_page
 			Feed.parse_url(next_page_url,@browser)
 		end
 
+		# Get previous page feed
+		# @return (see Feed.parse_url)
 		def prev_page
 			Feed.parse_url(prev_page_url,@browser)
 		end
@@ -140,6 +204,7 @@ module OPDS
 		end
 
 		protected
+		# Convert a nokogiri node to String value if not nil
 		def text(t)
 			return t.text unless t.nil?
 			t

data/lib/opds/navigation_feed.rb

@@ -1,4 +1,21 @@
 module OPDS
+	# Represents a navigation feed 
+	# @see http://opds-spec.org/specs/opds-catalog-1-0-20100830/#Navigation_Feeds
 	class NavigationFeed  < Feed
+		# Collection of all Navigation feeds found in this feed
+		# @return [OPDS::Support::LinkSet] found links
+		def navigation_links
+			nav_links=Support::LinkSet.new @browser
+			self.links.each do |l|
+				nav_links.push_link l if l.type=='application/atom+xml'
+			end
+
+			self.entries.each do |entry|
+				entry.links.each do |l|
+					nav_links.push_link l if l.type=='application/atom+xml'
+				end
+			end
+			nav_links
+		end
 	end
 end

data/lib/opds/opds.rb

@@ -1,4 +1,8 @@
+# Module containing the whole OPDS parsing library
 module OPDS
+	# Convinience call to Feed.parse_url
+	# @see Feed.parse_url
+	# @return (see Feed.parse_url)
 	def self.access(feed)
 		Feed.parse_url(feed)
 	end

data/lib/opds/parser.rb

@@ -1,14 +1,25 @@
 require "nokogiri"
 module OPDS
+	# Class in charge of discovering the type of the given text stream.
+	# It will dispatch the pre-parsed atom content to the desired class
+	# @see OPDS::AcquisitionFeed
+	# @see OPDS::NavigationFeed
+	# @see OPDS::Entry
 	class OPDSParser
 		include Logging
+		# @return [Hash] parsing options
 		attr_accessor :options
+		# @return [Symbol] last parsed stream sniffed type (:acquisition,:navigation,:entry)
 		attr_reader :sniffed_type
 		def initialize(opts={})
 			@sniffed_type=nil
 			self.options=opts.merge({})
 		end
 
+		# Parse a text stream
+		# @param content [String] text stream
+		# @param browser (see Feed.parse_url)
+		# @return [NavigationFeed, AcquisitionFeed, Entry] the parsed structure
 		def parse(content,browser=nil)
 			@ret=Nokogiri::XML(content)
 			@sniffed_type=sniff(@ret)
@@ -20,6 +31,9 @@ module OPDS
 		end
 
 		protected 
+		# Sniff a provided nokogiri document to detect it's type 
+		# @param doc [Nokogiri::XML::Document] Document to sniff
+		# @return [:acquisition, :navigation, :entry, nil] sniffed type
 		def sniff(doc)
 			return :entry if doc.root.name=='entry'
 			entries = doc.xpath('/xmlns:feed/xmlns:entry',doc.root.namespaces)

data/lib/opds/support/browser.rb

@@ -1,8 +1,13 @@
 require "open-uri"
 module OPDS
+	# Supporting classes 
 	module Support
+		# Browser class, it will be used to access the Internet.
+		# Currently based on open-uri only
 		class Browser
 			include Logging
+			# Navigate to the provided uri
+			# @param uri [String] uri to go to
 			def go_to(uri)
 				log("Accessing #{uri}")
 				url=URI.parse(uri)
@@ -21,27 +26,35 @@ module OPDS
 				end
 			end
 
+			# Last page load was ok ?
+			# @return [boolean]
 			def ok?
 				status==200
 			end
 
-
+			# @return [integer] Last page load return code
 			def status
 				@last_response.code.to_i if @last_response
 			end
 
+			# @return [Hash] Last page HTTP headers
 			def headers
 				@last_response.to_hash if @last_response
 			end
 
+			# @return [String] Last page body
 			def body
 				@last_response.body if @last_response
 			end
 
+			# @return [String] current uri
 			def current_location
 				@current_location
 			end
 
+			# Try to discover catalog links at the given url
+			# @param [String] url to search
+			# @return [OPDS::Support::LinkSet, false] discovered links
 			def discover(url)
 				go_to(url)
 				if ok?
@@ -59,6 +72,7 @@ module OPDS
 			end
 
 			private 
+			# extracts linkset from doc + xpath expression
 			def extract_links(tab,doc, expr)
 				doc.xpath(expr).each do |n|
 					text=nil