ruby-changes:28423
From: zzak <ko1@a...>
Date: Fri, 26 Apr 2013 14:37:01 +0900 (JST)
Subject: [ruby-changes:28423] zzak:r40475 (trunk): * lib/rss/atom.rb: Documentation for RSS::Atom based on a patch by
zzak 2013-04-26 14:36:51 +0900 (Fri, 26 Apr 2013) New Revision: 40475 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=40475 Log: * lib/rss/atom.rb: Documentation for RSS::Atom based on a patch by Michael Denomy * lib/rss/maker.rb: Documentation for RSS::Maker also by @mdenomy Modified files: trunk/ChangeLog trunk/lib/rss/atom.rb trunk/lib/rss/maker.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 40474) +++ ChangeLog (revision 40475) @@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Fri Apr 26 14:35:00 2013 Zachary Scott <zachary@z...> + + * lib/rss/atom.rb: Documentation for RSS::Atom based on a patch by + Michael Denomy + * lib/rss/maker.rb: Documentation for RSS::Maker also by @mdenomy + Fri Apr 26 12:41:22 2013 Tanaka Akira <akr@f...> * ext/curses/extconf.rb: Test linkability of curses_version at first. Index: lib/rss/maker.rb =================================================================== --- lib/rss/maker.rb (revision 40474) +++ lib/rss/maker.rb (revision 40475) @@ -1,32 +1,56 @@ https://github.com/ruby/ruby/blob/trunk/lib/rss/maker.rb#L1 require "rss/rss" module RSS + ## + # + # Provides a set of builders for various RSS objects + # + # * Feeds + # * RSS 0.91 + # * RSS 1.0 + # * RSS 2.0 + # * Atom 1.0 + # + # * Elements + # * Atom::Entry + module Maker + + # Collection of supported makers MAKERS = {} class << self + # Builder for an RSS object + # Creates an object of the type passed in +args+ + # + # Executes the +block+ to populate elements of the created RSS object def make(version, &block) self[version].make(&block) end + # Returns the maker for the +version+ def [](version) maker_info = maker(version) raise UnsupportedMakerVersionError.new(version) if maker_info.nil? maker_info[:maker] end + # Adds a maker to the set of supported makers def add_maker(version, normalized_version, maker) MAKERS[version] = {:maker => maker, :version => normalized_version} end + # Returns collection of supported maker versions def versions MAKERS.keys.uniq.sort end + # Returns collection of supported makers def makers - MAKERS.values.collect {|info| info[:maker]}.uniq + MAKERS.values.collect { |info| info[:maker] }.uniq end + # Returns true if the version is supported def supported?(version) versions.include?(version) end Index: lib/rss/atom.rb =================================================================== --- lib/rss/atom.rb (revision 40474) +++ lib/rss/atom.rb (revision 40475) @@ -1,6 +1,14 @@ https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L1 require 'rss/parser' module RSS + ## + # Atom is an XML-based document format that is used to describe 'feeds' of related information. + # A typical use is in a news feed where the information is periodically updated and which users + # can subscribe to. The Atom format is described in http://tools.ietf.org/html/rfc4287 + # + # The Atom module provides support in reading and creating feeds. + # + # See the RSS module for examples consuming and creating feeds module Atom ## @@ -82,6 +90,10 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L90 end end + # The TextConstruct module is used to define a Text construct Atom element, + # which is used to store small quantities of human-readable text + # + # The TextConstruct has a type attribute, e.g. text, html, xhtml module TextConstruct def self.append_features(klass) super @@ -108,6 +120,7 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L120 end attr_writer :xhtml + def xhtml return @xhtml if @xhtml.nil? if @xhtml.is_a?(XML::Element) and @@ -121,6 +134,7 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L134 {"xmlns" => XHTML_URI}, children) end + # Returns true if type is "xhtml" def have_xml_content? @type == "xhtml" end @@ -148,7 +162,13 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L162 end end + # The PersonConstruct module is used to define a Person Atom element that can be + # used to describe a person, corporation, or similar entity + # + # The PersonConstruct has a Name, Uri, and Email child elements module PersonConstruct + + # Adds attributes for name, uri, and email to the +klass+ def self.append_features(klass) super klass.class_eval do @@ -166,22 +186,30 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L186 target.__send__("new_#{self.class.name.split(/::/).last.downcase}") end + # The name of the person or entity class Name < RSS::Element include CommonModel include ContentModel end + # The URI of the person or entity class Uri < RSS::Element include CommonModel include URIContentModel end + # The email of the person or entity class Email < RSS::Element include CommonModel include ContentModel end end + # Element used to describe an Atom date and time in the ISO 8601 format + # + # Examples: + # * 2013-03-04T15:30:02Z + # * 2013-03-04T10:30:02-05:00 module DateConstruct def self.append_features(klass) super @@ -191,12 +219,17 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L219 end end + # Raises NotAvailableValueError if element content is nil def atom_validate(ignore_unknown_element, tags, uri) raise NotAvailableValueError.new(tag_name, "") if content.nil? end end module DuplicateLinkChecker + # Checks if there are duplicate links with the same type and hreflang attributes + # that have an alternate (or empty) rel attribute + # + # Raises a TooMuchTagError if there are duplicates found def validate_duplicate_links(links) link_infos = {} links.each do |link| @@ -211,6 +244,9 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L244 end end + # Atom feed element + # + # A Feed has several metadata attributes in addition to a number of Entry child elements class Feed < RSS::Element include RootElementMixin include CommonModel @@ -238,6 +274,7 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L274 tag, URI, occurs, tag, *args) end + # Creates a new Atom feed def initialize(version=nil, encoding=nil, standalone=nil) super("1.0", version, encoding, standalone) @feed_type = "atom" @@ -246,6 +283,8 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L283 alias_method :items, :entries + # Returns true if there are any authors for the feed or any of the Entry + # child elements have an author def have_author? authors.any? {|author| !author.to_s.empty?} or entries.any? {|entry| entry.have_author?(false)} @@ -329,16 +368,32 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L368 end end + # Atom Icon element + # + # Image that provides a visual identification for the Feed. Image should have an aspect + # ratio of 1:1 class Icon < RSS::Element include CommonModel include URIContentModel end + # Atom ID element + # + # Universally Unique Identifier (UUID) for the Feed class Id < RSS::Element include CommonModel include URIContentModel end + # Defines an Atom Link element + # + # A Link has the following attributes: + # * href + # * rel + # * type + # * hreflang + # * title + # * length class Link < RSS::Element include CommonModel @@ -359,6 +414,10 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L414 end end + # Atom Logo element + # + # Image that provides a visual identification for the Feed. Image should have an aspect + # ratio of 2:1 (horizontal:vertical) class Logo < RSS::Element include CommonModel include URIContentModel @@ -373,26 +432,40 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L432 end end + # Atom Rights element + # + # TextConstruct that contains copyright information regarding the content in an Entry or Feed class Rights < RSS::Element include CommonModel include TextConstruct end + # Atom Subtitle element + # + # TextConstruct that conveys a description or subtitle for a Feed class Subtitle < RSS::Element include CommonModel include TextConstruct end + # Atom Title element + # + # TextConstruct that conveys a description or title for a feed or Entry class Title < RSS::Element include CommonModel include TextConstruct end + # Atom Updated element + # + # DateConstruct indicating the most recent time when an Entry or Feed was modified + # in a way the publisher considers significant class Updated < RSS::Element include CommonModel include DateConstruct end + # Defines a child Atom Entry element for an Atom Feed class Entry < RSS::Element include CommonModel include DuplicateLinkChecker @@ -416,6 +489,10 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L489 tag, URI, occurs, tag, *args) end + # Returns whether any of the following are true + # * There are any authors in the feed + # * If the parent element has an author and the +check_parent+ parameter was given. + # * There is a source element that has an author def have_author?(check_parent=true) authors.any? {|author| !author.to_s.empty?} or (check_parent and @parent and @parent.have_author?) or @@ -642,6 +719,8 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L719 end end + # Defines a top-level Atom Entry element + # class Entry < RSS::Element include RootElementMixin include CommonModel @@ -666,21 +745,25 @@ module RSS https://github.com/ruby/ruby/blob/trunk/lib/rss/atom.rb#L745 tag, URI, occurs, tag, *args) end + # Creates a new Atom Entry element def initialize(version=nil, encoding=nil, standalone=nil) super("1.0", version, encoding, standalone) @feed_type = "atom" @feed_subtype = "entry" end + # Returns the Entry in an array def items [self] end + # sets up the +maker+ for constructing Entry elements def setup_maker(maker) maker = maker.maker if maker.respond_to?("maker") super(maker) end + # Returns where there are any authors present or there is a source with an author def have_author? authors.any? {|author| !author.to_s.empty?} or (source and source.have_author?) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/