ruby-changes:45801
From: naruse <ko1@a...>
Date: Sun, 12 Mar 2017 03:09:49 +0900 (JST)
Subject: [ruby-changes:45801] naruse:r57874 (ruby_2_4): merge revision(s) 57428:
naruse 2017-03-12 03:09:45 +0900 (Sun, 12 Mar 2017) New Revision: 57874 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=57874 Log: merge revision(s) 57428: Add document for lib/rss/atom.rb [fix GH-1520] Patch by Tsehau Chao. Thanks!!! Modified directories: branches/ruby_2_4/ Modified files: branches/ruby_2_4/lib/rss/atom.rb branches/ruby_2_4/version.h Index: ruby_2_4/lib/rss/atom.rb =================================================================== --- ruby_2_4/lib/rss/atom.rb (revision 57873) +++ ruby_2_4/lib/rss/atom.rb (revision 57874) @@ -37,10 +37,12 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L37 end klass.class_eval do class << self + # Returns the Atom URI W3C Namespace def required_uri URI end + # Returns true def need_parent? true end @@ -92,9 +94,11 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L94 end # The TextConstruct module is used to define a Text construct Atom element, - # which is used to store small quantities of human-readable text + # which is used to store small quantities of human-readable text. # # The TextConstruct has a type attribute, e.g. text, html, xhtml + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#text.constructs module TextConstruct def self.append_features(klass) super @@ -122,6 +126,7 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L126 attr_writer :xhtml + # Returns or builds the XHTML content. def xhtml return @xhtml if @xhtml.nil? if @xhtml.is_a?(XML::Element) and @@ -135,11 +140,13 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L140 {"xmlns" => XHTML_URI}, children) end - # Returns true if type is "xhtml" + # Returns true if type is "xhtml". def have_xml_content? @type == "xhtml" end + # Raises a MissingTagError or NotExpectedTagError + # if the element is not properly formatted. def atom_validate(ignore_unknown_element, tags, uri) if have_xml_content? if @xhtml.nil? @@ -163,10 +170,12 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L170 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 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. # - # The PersonConstruct has a Name, Uri, and Email child elements + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#atomPersonConstruct module PersonConstruct # Adds attributes for name, uri, and email to the +klass+ @@ -187,19 +196,25 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L196 target.__send__("new_#{self.class.name.split(/::/).last.downcase}") end - # The name of the person or entity + # The name of the person or entity. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.name class Name < RSS::Element include CommonModel include ContentModel end - # The URI of the person or entity + # The URI of the person or entity. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.uri class Uri < RSS::Element include CommonModel include URIContentModel end - # The email of the person or entity + # The email of the person or entity. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.email class Email < RSS::Element include CommonModel include ContentModel @@ -245,9 +260,28 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L260 end end - # Atom feed element + # Defines the top-level element of an Atom Feed Document. + # It consists of a number of children Entry elements, + # and has the following attributes: # - # A Feed has several metadata attributes in addition to a number of Entry child elements + # * author + # * categories + # * category + # * content + # * contributor + # * entries (aliased as items) + # * entry + # * generator + # * icon + # * id + # * link + # * logo + # * rights + # * subtitle + # * title + # * updated + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.feed class Feed < RSS::Element include RootElementMixin include CommonModel @@ -322,11 +356,23 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L356 end end + # PersonConstruct that contains information regarding the author + # of a Feed or Entry. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.author class Author < RSS::Element include CommonModel include PersonConstruct end + # Contains information about a category associated with a Feed or Entry. + # It has the following attributes: + # + # * term + # * scheme + # * label + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.category class Category < RSS::Element include CommonModel @@ -344,11 +390,18 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L390 end end + # PersonConstruct that contains information regarding the + # contributors of a Feed or Entry. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.contributor class Contributor < RSS::Element include CommonModel include PersonConstruct end + # Contains information on the agent used to generate the feed. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.generator class Generator < RSS::Element include CommonModel include ContentModel @@ -369,32 +422,34 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L422 end end - # Atom Icon element + # Defines an image that provides a visual identification for a eed. + # The image should have an aspect ratio of 1:1. # - # Image that provides a visual identification for the Feed. Image should have an aspect - # ratio of 1:1 + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.icon class Icon < RSS::Element include CommonModel include URIContentModel end - # Atom ID element + # Defines the Universally Unique Identifier (UUID) for a Feed or Entry. # - # Universally Unique Identifier (UUID) for the Feed + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.id class Id < RSS::Element include CommonModel include URIContentModel end - # Defines an Atom Link element + # Defines a reference to a Web resource. It has the following + # attributes: # - # A Link has the following attributes: # * href # * rel # * type # * hreflang # * title # * length + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.link class Link < RSS::Element include CommonModel @@ -415,10 +470,10 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L470 end end - # Atom Logo element + # Defines an image that provides a visual identification for the Feed. + # The image should have an aspect ratio of 2:1 (horizontal:vertical). # - # Image that provides a visual identification for the Feed. Image should have an aspect - # ratio of 2:1 (horizontal:vertical) + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.logo class Logo < RSS::Element include CommonModel include URIContentModel @@ -433,40 +488,60 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L488 end end - # Atom Rights element + # TextConstruct that contains copyright information regarding + # the content in an Entry or Feed. It should not be used to + # convey machine readable licensing information. # - # TextConstruct that contains copyright information regarding the content in an Entry or Feed + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.rights class Rights < RSS::Element include CommonModel include TextConstruct end - # Atom Subtitle element + # TextConstruct that conveys a description or subtitle for a Feed. # - # TextConstruct that conveys a description or subtitle for a Feed + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.subtitle class Subtitle < RSS::Element include CommonModel include TextConstruct end - # Atom Title element + # TextConstruct that conveys a description or title for a Feed or Entry. # - # TextConstruct that conveys a description or title for a feed or Entry + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.title class Title < RSS::Element include CommonModel include TextConstruct end - # Atom Updated element + # DateConstruct indicating the most recent time when a Feed or + # Entry was modified in a way the publisher considers + # significant. # - # DateConstruct indicating the most recent time when an Entry or Feed was modified - # in a way the publisher considers significant + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.updated class Updated < RSS::Element include CommonModel include DateConstruct end - # Defines a child Atom Entry element for an Atom Feed + # Defines a child Atom Entry element of an Atom Feed element. + # It has the following attributes: + # + # * author + # * category + # * categories + # * content + # * contributor + # * id + # * link + # * published + # * rights + # * source + # * summary + # * title + # * updated + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.entry class Entry < RSS::Element include CommonModel include DuplicateLinkChecker @@ -490,9 +565,11 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L565 tag, URI, occurs, tag, *args) end - # Returns whether any of the following are true + # 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. + # * 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 @@ -520,9 +597,18 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L597 items.new_item end + # Feed::Author Author = Feed::Author + # Feed::Category Category = Feed::Category + # Contains or links to the content of the Entry. + # It has the following attributes: + # + # * type + # * src + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.content class Content < RSS::Element include CommonModel @@ -546,11 +632,15 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L632 content_setup add_need_initialize_variable("xml") + # Returns the element content in XML. attr_writer :xml + + # Returns true if the element has inline XML content. def have_xml_content? inline_xhtml? or inline_other_xml? end + # Returns or builds the element content in XML. def xml return @xml unless inline_xhtml? return @xml if @xml.nil? @@ -565,6 +655,7 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L655 {"xmlns" => XHTML_URI}, children) end + # Returns the element content in XHTML. def xhtml if inline_xhtml? xml @@ -573,6 +664,9 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L664 end end + # Raises a MissingAttributeError, NotAvailableValueError, + # MissingTagError or NotExpectedTagError if the element is + # not properly formatted. def atom_validate(ignore_unknown_element, tags, uri) if out_of_line? raise MissingAttributeError.new(tag_name, "type") if @type.nil? @@ -589,19 +683,27 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L683 end end + # Returns true if the element contains inline content + # that has a text or HTML media type, or no media type at all. def inline_text? !out_of_line? and [nil, "text", "html"].include?(@type) end + # Returns true if the element contains inline content that + # has a HTML media type. def inline_html? return false if out_of_line? @type == "html" or mime_split == ["text", "html"] end + # Returns true if the element contains inline content that + # has a XHTML media type. def inline_xhtml? !out_of_line? and @type == "xhtml" end + # Returns true if the element contains inline content that + # has a MIME media type. def inline_other? return false if out_of_line? media_type, subtype = mime_split @@ -609,6 +711,8 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L711 true end + # Returns true if the element contains inline content that + # has a text media type. def inline_other_text? return false unless inline_other? return false if inline_other_xml? @@ -618,6 +722,8 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L722 false end + # Returns true if the element contains inline content that + # has a XML media type. def inline_other_xml? return false unless inline_other? @@ -632,14 +738,18 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L738 false end + # Returns true if the element contains inline content + # encoded in base64. def inline_other_base64? inline_other? and !inline_other_text? and !inline_other_xml? end + # Returns true if the element contains linked content. def out_of_line? not @src.nil? end + # Splits the type attribute into an array, e.g. ["text", "xml"] def mime_split media_type = subtype = nil if /\A\s*([a-z]+)\/([a-z\+]+)\s*(?:;.*)?\z/i =~ @type.to_s @@ -649,6 +759,7 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L759 [media_type, subtype] end + # Returns true if the content needs to be encoded in base64. def need_base64_encode? inline_other_base64? end @@ -659,17 +770,43 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L770 end end + # Feed::Contributor Contributor = Feed::Contributor + # Feed::Id Id = Feed::Id + # Feed::Link Link = Feed::Link + # DateConstruct that usually indicates the time of the initial + # creation of an Entry. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.published class Published < RSS::Element include CommonModel include DateConstruct end + # Feed::Rights Rights = Feed::Rights + # Defines a Atom Source element. It has the following attributes: + # + # * author + # * category + # * categories + # * content + # * contributor + # * generator + # * icon + # * id + # * link + # * logo + # * rights + # * subtitle + # * title + # * updated + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.source class Source < RSS::Element include CommonModel @@ -692,36 +829,71 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L829 tag, URI, occurs, tag, *args) end + # Returns true if the Source element has an author. def have_author? !author.to_s.empty? end + # Feed::Author Author = Feed::Author + # Feed::Category Category = Feed::Category + # Feed::Contributor Contributor = Feed::Contributor + # Feed::Generator Generator = Feed::Generator + # Feed::Icon Icon = Feed::Icon + # Feed::Id Id = Feed::Id + # Feed::Link Link = Feed::Link + # Feed::Logo Logo = Feed::Logo + # Feed::Rights Rights = Feed::Rights + # Feed::Subtitle Subtitle = Feed::Subtitle + # Feed::Title Title = Feed::Title + # Feed::Updated Updated = Feed::Updated end + # TextConstruct that describes a summary of the Entry. + # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.summary class Summary < RSS::Element include CommonModel include TextConstruct end + # Feed::Title Title = Feed::Title + # Feed::Updated Updated = Feed::Updated end end - # Defines a top-level Atom Entry element + # Defines a top-level Atom Entry element, + # used as the document element of a stand-alone Atom Entry Document. + # It has the following attributes: + # + # * author + # * category + # * categories + # * content + # * contributor + # * id + # * link + # * published + # * rights + # * source + # * summary + # * title + # * updated # + # Reference: https://validator.w3.org/feed/docs/rfc4287.html#element.entry] class Entry < RSS::Element include RootElementMixin include CommonModel @@ -746,25 +918,26 @@ module RSS https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/rss/atom.rb#L918 tag, URI, occurs, tag, *args) end - # Creates a new Atom Entry element + # 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 + # Returns the Entry in an array. def items [self] end - # (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/