atom-tools 0.9.0 → 2.0.5

data/doc/fr_method_index.html

@@ -20,42 +20,117 @@
 <div id="index">
   <h1 class="section-bar">Methods</h1>
   <div id="index-entries">
-    <a href="classes/Atom/Feed.html#M000015"><< (Atom::Feed)</a><br />
-    <a href="classes/Atom/Element.html#M000032">[] (Atom::Element)</a><br />
-    <a href="classes/Atom/Element.html#M000033">[]= (Atom::Element)</a><br />
-    <a href="classes/Atom/HTTP.html#M000024">delete (Atom::HTTP)</a><br />
-    <a href="classes/Atom/Collection.html#M000029">delete! (Atom::Collection)</a><br />
-    <a href="classes/Atom/Feed.html#M000009">each (Atom::Feed)</a><br />
-    <a href="classes/Atom/Entry.html#M000002">edit_url (Atom::Entry)</a><br />
-    <a href="classes/Atom/Entry.html#M000001">from_yaml (Atom::Entry)</a><br />
-    <a href="classes/Atom/HTTP.html#M000021">get (Atom::HTTP)</a><br />
-    <a href="classes/Atom/HTTP.html#M000019">get_atom_entry (Atom::HTTP)</a><br />
-    <a href="classes/Atom/Feed.html#M000010">get_everything! (Atom::Feed)</a><br />
-    <a href="classes/Atom/Text.html#M000017">html (Atom::Text)</a><br />
-    <a href="classes/Atom/Feed.html#M000013">merge (Atom::Feed)</a><br />
-    <a href="classes/Atom/Feed.html#M000012">merge! (Atom::Feed)</a><br />
-    <a href="classes/Atom/Feed.html#M000011">merge_entries! (Atom::Feed)</a><br />
-    <a href="classes/Atom/Feed.html#M000008">new (Atom::Feed)</a><br />
-    <a href="classes/Atom/Collection.html#M000026">new (Atom::Collection)</a><br />
-    <a href="classes/Atom/App.html#M000006">new (Atom::App)</a><br />
-    <a href="classes/Atom/Entry.html#M000003">parse (Atom::Entry)</a><br />
-    <a href="classes/Atom/Feed.html#M000007">parse (Atom::Feed)</a><br />
-    <a href="classes/Atom/HTTP.html#M000022">post (Atom::HTTP)</a><br />
-    <a href="classes/Atom/Collection.html#M000027">post! (Atom::Collection)</a><br />
-    <a href="classes/Atom/Collection.html#M000030">post_media! (Atom::Collection)</a><br />
-    <a href="classes/Atom/HTTP.html#M000023">put (Atom::HTTP)</a><br />
-    <a href="classes/Atom/Collection.html#M000028">put! (Atom::Collection)</a><br />
-    <a href="classes/Atom/HTTP.html#M000020">put_atom_entry (Atom::HTTP)</a><br />
-    <a href="classes/Atom/Collection.html#M000031">put_media! (Atom::Collection)</a><br />
-    <a href="classes/Atom/Entry.html#M000005">tag_with (Atom::Entry)</a><br />
-    <a href="classes/Atom/Element.html#M000034">to_element (Atom::Element)</a><br />
-    <a href="classes/Atom/Text.html#M000016">to_s (Atom::Text)</a><br />
-    <a href="classes/Atom/Element.html#M000036">to_s (Atom::Element)</a><br />
-    <a href="classes/Atom/Element.html#M000035">to_xml (Atom::Element)</a><br />
-    <a href="classes/Atom/Feed.html#M000014">update! (Atom::Feed)</a><br />
-    <a href="classes/Atom/Entry.html#M000004">updated! (Atom::Entry)</a><br />
-    <a href="classes/Atom/HTTP.html#M000025">when_auth (Atom::HTTP)</a><br />
-    <a href="classes/Atom/Text.html#M000018">xml (Atom::Text)</a><br />
+    <a href="classes/Atom/FileCache.html#M000061">[] (Atom::FileCache)</a><br />
+    <a href="classes/Atom/AttrEl.html#M000023">[] (Atom::AttrEl)</a><br />
+    <a href="classes/Atom/NilCache.html#M000064">[] (Atom::NilCache)</a><br />
+    <a href="classes/Atom/FileCache.html#M000062">[]= (Atom::FileCache)</a><br />
+    <a href="classes/Atom/NilCache.html#M000065">[]= (Atom::NilCache)</a><br />
+    <a href="classes/Atom/AttrEl.html#M000024">[]= (Atom::AttrEl)</a><br />
+    <a href="files/lib/atom/cache_rb.html#M000004">_entry_disposition (lib/atom/cache.rb)</a><br />
+    <a href="files/lib/atom/cache_rb.html#M000002">_parse_cache_control (lib/atom/cache.rb)</a><br />
+    <a href="files/lib/atom/cache_rb.html#M000003">_updateCache (lib/atom/cache.rb)</a><br />
+    <a href="classes/Atom/Collection.html#M000103">accepts (Atom::Collection)</a><br />
+    <a href="classes/Atom/Collection.html#M000104">accepts= (Atom::Collection)</a><br />
+    <a href="classes/Atom/Element.html#M000095">append_elem (Atom::Element)</a><br />
+    <a href="classes/Atom/Converters.html#M000046">atom_attrb (Atom::Converters)</a><br />
+    <a href="classes/Atom/Converters.html#M000041">atom_element (Atom::Converters)</a><br />
+    <a href="classes/Atom/Converters.html#M000044">atom_elements (Atom::Converters)</a><br />
+    <a href="classes/Atom/Converters.html#M000047">atom_link (Atom::Converters)</a><br />
+    <a href="classes/Atom/Tools.html#M000033">atom_options (Atom::Tools)</a><br />
+    <a href="classes/Atom/Converters.html#M000037">atom_string (Atom::Converters)</a><br />
+    <a href="classes/Atom/Converters.html#M000039">atom_time (Atom::Converters)</a><br />
+    <a href="classes/Atom/Converters.html#M000045">attrb (Atom::Converters)</a><br />
+    <a href="classes/Atom/Element.html#M000088">build (Atom::Element)</a><br />
+    <a href="classes/Atom/Converters.html#M000036">build_plain (Atom::Converters)</a><br />
+    <a href="classes/Atom/Element.html#M000085">builders (Atom::Element)</a><br />
+    <a href="classes/Atom/Service.html#M000099">collections (Atom::Service)</a><br />
+    <a href="classes/Atom/Element.html#M000090">def_get (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000091">def_set (Atom::Element)</a><br />
+    <a href="classes/Atom/NilCache.html#M000066">delete (Atom::NilCache)</a><br />
+    <a href="classes/Atom/FileCache.html#M000063">delete (Atom::FileCache)</a><br />
+    <a href="classes/Atom/HTTP.html#M000071">delete (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Collection.html#M000109">delete! (Atom::Collection)</a><br />
+    <a href="classes/Atom/DigestAuth.html#M000022">digest_authenticate (Atom::DigestAuth)</a><br />
+    <a href="classes/Atom/Tools.html#M000026">dir_to_entries (Atom::Tools)</a><br />
+    <a href="classes/Atom/Service.html#M000100">discover (Atom::Service)</a><br />
+    <a href="classes/Atom/Element.html#M000084">do_parsing (Atom::Element)</a><br />
+    <a href="classes/Atom/Converters.html#M000040">element (Atom::Converters)</a><br />
+    <a href="classes/Atom/Converters.html#M000043">elements (Atom::Converters)</a><br />
+    <a href="classes/Atom/HTTPResponse.html#M000009">end2end_headers (Atom::HTTPResponse)</a><br />
+    <a href="classes/Atom/Tools.html#M000029">entries_to_dir (Atom::Tools)</a><br />
+    <a href="classes/Atom/Tools.html#M000028">entries_to_http (Atom::Tools)</a><br />
+    <a href="classes/Atom/Tools.html#M000030">entries_to_stdout (Atom::Tools)</a><br />
+    <a href="classes/Atom/HasLinks.html#M000011">find_link (Atom::HasLinks)</a><br />
+    <a href="classes/Atom/Service.html#M000101">from_rsd (Atom::Service)</a><br />
+    <a href="classes/Atom/HTTP.html#M000068">get (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Element.html#M000096">get (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000081">get_atom_attrb (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000079">get_atom_elem (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000080">get_atom_elems (Atom::Element)</a><br />
+    <a href="classes/Atom/HTTP.html#M000073">get_atom_entry (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Element.html#M000077">get_elem (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000078">get_elems (Atom::Element)</a><br />
+    <a href="classes/Atom/DigestAuth.html#M000020">h (Atom::DigestAuth)</a><br />
+    <a href="classes/Atom/Text.html#M000054">html (Atom::Text)</a><br />
+    <a href="classes/Atom/Tools.html#M000025">http_to_entries (Atom::Tools)</a><br />
+    <a href="classes/Atom/HasLinks.html#M000010">included (Atom::HasLinks)</a><br />
+    <a href="classes/Atom/HasCategories.html#M000017">included (Atom::HasCategories)</a><br />
+    <a href="classes/Atom/Element.html#M000076">is_atom_element (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000075">is_element (Atom::Element)</a><br />
+    <a href="classes/Atom/DigestAuth.html#M000021">kd (Atom::DigestAuth)</a><br />
+    <a href="classes/Object.html#M000007">meta_def (Object)</a><br />
+    <a href="classes/Object.html#M000006">meta_eval (Object)</a><br />
+    <a href="classes/Object.html#M000005">metaclass (Object)</a><br />
+    <a href="classes/Atom/FileCache.html#M000058">new (Atom::FileCache)</a><br />
+    <a href="classes/Atom/Collection.html#M000105">new (Atom::Collection)</a><br />
+    <a href="classes/Atom/Service.html#M000098">new (Atom::Service)</a><br />
+    <a href="classes/Atom/Text.html#M000051">new (Atom::Text)</a><br />
+    <a href="classes/Atom/Element.html#M000092">new (Atom::Element)</a><br />
+    <a href="classes/Atom/HTTP.html#M000067">new (Atom::HTTP)</a><br />
+    <a href="files/lib/atom/cache_rb.html#M000001">normalize_header_names (lib/atom/cache.rb)</a><br />
+    <a href="classes/Atom/Tools.html#M000034">obtain_password (Atom::Tools)</a><br />
+    <a href="classes/Atom/Element.html#M000083">on_build (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000093">on_init (Atom::Element)</a><br />
+    <a href="classes/Atom/Parsers.html#M000012">on_parse (Atom::Parsers)</a><br />
+    <a href="classes/Atom/Parsers.html#M000013">on_parse_attr (Atom::Parsers)</a><br />
+    <a href="classes/Atom/Parsers.html#M000014">on_parse_many (Atom::Parsers)</a><br />
+    <a href="classes/Atom/Parsers.html#M000015">on_parse_root (Atom::Parsers)</a><br />
+    <a href="classes/Atom/Link.html#M000050">parse (Atom::Link)</a><br />
+    <a href="classes/Atom/Element.html#M000086">parse (Atom::Element)</a><br />
+    <a href="classes/Atom/Collection.html#M000106">parse (Atom::Collection)</a><br />
+    <a href="classes/Atom/Tools.html#M000031">parse_input (Atom::Tools)</a><br />
+    <a href="classes/Atom/Parsers.html#M000016">parse_plain (Atom::Parsers)</a><br />
+    <a href="classes/Atom/DigestAuth.html#M000019">parse_wwwauth_digest (Atom::DigestAuth)</a><br />
+    <a href="classes/Atom/HTTP.html#M000069">post (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Collection.html#M000107">post! (Atom::Collection)</a><br />
+    <a href="classes/Atom/Collection.html#M000110">post_media! (Atom::Collection)</a><br />
+    <a href="classes/Atom/HTTP.html#M000070">put (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Collection.html#M000108">put! (Atom::Collection)</a><br />
+    <a href="classes/Atom/HTTP.html#M000074">put_atom_entry (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Collection.html#M000111">put_media! (Atom::Collection)</a><br />
+    <a href="classes/Atom/Link.html#M000049">rel (Atom::Link)</a><br />
+    <a href="classes/Atom/Element.html#M000094">run_initters (Atom::Element)</a><br />
+    <a href="classes/Atom/FileCache.html#M000060">safe (Atom::FileCache)</a><br />
+    <a href="classes/Atom/Categories.html#M000057">scheme= (Atom::Categories)</a><br />
+    <a href="classes/Atom/Element.html#M000097">set (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000082">set_atom_attrb (Atom::Element)</a><br />
+    <a href="classes/Atom/Tools.html#M000035">setup_http (Atom::Tools)</a><br />
+    <a href="classes/Atom/Content.html#M000048">src= (Atom::Content)</a><br />
+    <a href="classes/Atom/Tools.html#M000027">stdin_to_entries (Atom::Tools)</a><br />
+    <a href="classes/Atom/Converters.html#M000042">strings (Atom::Converters)</a><br />
+    <a href="classes/Atom/HasCategories.html#M000018">tag_with (Atom::HasCategories)</a><br />
+    <a href="classes/Atom/Converters.html#M000038">time (Atom::Converters)</a><br />
+    <a href="classes/Atom/Collection.html#M000102">title (Atom::Collection)</a><br />
+    <a href="classes/Atom/FileCache.html#M000059">to_file (Atom::FileCache)</a><br />
+    <a href="classes/Atom/Text.html#M000053">to_s (Atom::Text)</a><br />
+    <a href="classes/Atom/Element.html#M000089">to_s (Atom::Element)</a><br />
+    <a href="classes/Atom/Element.html#M000087">to_xml (Atom::Element)</a><br />
+    <a href="classes/Atom/Text.html#M000052">type (Atom::Text)</a><br />
+    <a href="classes/Atom/Text.html#M000056">type= (Atom::Text)</a><br />
+    <a href="classes/Atom/HTTPResponse.html#M000008">validate_content_type (Atom::HTTPResponse)</a><br />
+    <a href="classes/Atom/HTTP.html#M000072">when_auth (Atom::HTTP)</a><br />
+    <a href="classes/Atom/Tools.html#M000032">write_output (Atom::Tools)</a><br />
+    <a href="classes/Atom/Text.html#M000055">xml (Atom::Text)</a><br />
   </div>
 </div>
 </body>

data/lib/atom/cache.rb

@@ -0,0 +1,178 @@
+# portions of this ported from httplib2 <http://code.google.com/p/httplib2/>
+# copyright 2006, Joe Gregorio
+#
+# used under the terms of the MIT license
+
+require "digest/md5"
+
+def normalize_header_names _headers
+  headers = {}
+  _headers.each { |k,v| headers[k.downcase] = v }
+  headers
+end
+
+def _parse_cache_control headers
+  retval = {}
+  headers = normalize_header_names(headers) if headers.is_a? Hash
+
+  if headers['cache-control']
+    parts = headers['cache-control'].split(',')
+    parts.each do |part|
+      if part.match(/=/)
+        k, v = part.split('=').map { |p| p.strip }
+        retval[k] = v
+      else
+        retval[part.strip] = 1
+      end
+    end
+  end
+
+  retval
+end
+
+def _updateCache request_headers, response, cache, cachekey
+  cc = _parse_cache_control request_headers
+  cc_response = _parse_cache_control response
+  if cc['no-store'] or cc_response['no-store']
+    cache.delete cachekey
+  else
+    result = "HTTP/#{response.http_version} #{response.code} #{response.message}\r\n"
+
+    response.each_capitalized_name do |field|
+      next if ['status', 'content-encoding', 'transfer-encoding'].member? field.downcase
+      response.get_fields(field).each do |value|
+        result += "#{field}: #{value}\r\n"
+      end
+    end
+
+    cache[cachekey] = result + "\r\n" + response.body
+  end
+end
+
+=begin
+    Determine freshness from the Date, Expires and Cache-Control headers.
+
+    We don't handle the following:
+
+    1. Cache-Control: max-stale
+    2. Age: headers are not used in the calculations.
+
+    Not that this algorithm is simpler than you might think
+    because we are operating as a private (non-shared) cache.
+    This lets us ignore 's-maxage'. We can also ignore
+    'proxy-invalidate' since we aren't a proxy.
+    We will never return a stale document as
+    fresh as a design decision, and thus the non-implementation
+    of 'max-stale'. This also lets us safely ignore 'must-revalidate'
+    since we operate as if every server has sent 'must-revalidate'.
+    Since we are private we get to ignore both 'public' and
+    'private' parameters. We also ignore 'no-transform' since
+    we don't do any transformations.
+    The 'no-store' parameter is handled at a higher level.
+    So the only Cache-Control parameters we look at are:
+
+    no-cache
+    only-if-cached
+    max-age
+    min-fresh
+=end
+def _entry_disposition(response_headers, request_headers)
+  request_headers = normalize_header_names(request_headers)
+
+  cc = _parse_cache_control(request_headers)
+  cc_response = _parse_cache_control(response_headers)
+
+  if request_headers['pragma'] and request_headers['pragma'].downcase.match(/no-cache/)
+    unless request_headers.key? 'cache-control'
+      request_headers['cache-control'] = 'no-cache'
+    end
+    :TRANSPARENT
+  elsif cc.key? 'no-cache'
+    :TRANSPARENT
+  elsif cc_response.key? 'no-cache'
+    :STALE
+  elsif cc.key? 'only-if-cached'
+    :FRESH
+  elsif response_headers.key? 'date'
+    date = Time.rfc2822(response_headers['date'])
+    diff = Time.now - date
+    current_age = (diff > 0) ? diff : 0
+    if cc_response.key? 'max-age'
+      freshness_lifetime = cc_response['max-age'].to_i
+    elsif response_headers.key? 'expires'
+      expires = Time.rfc2822(response_headers['expires'])
+      diff = expires - date
+      freshness_lifetime = (diff > 0) ? diff : 0
+    else
+      freshness_lifetime = 0
+    end
+
+    if cc.key? 'max-age'
+      freshness_lifetime = cc['max-age'].to_i
+    end
+
+    if cc.key? 'min-fresh'
+      min_fresh = cc['min-fresh'].to_i
+      current_age += min_fresh
+    end
+
+    if freshness_lifetime > current_age
+      :FRESH
+    else
+      :STALE
+    end
+  end
+end
+
+module Atom
+  # this cache never actually saves anything
+  class NilCache
+    def [] key
+      nil
+    end
+
+    def []= key, value
+      nil
+    end
+
+    def delete key
+      nil
+    end
+  end
+
+  # uses a local directory to store cache files
+  class FileCache
+    def initialize dir
+      @dir = dir
+    end
+
+    def to_file(key)
+      @dir + "/" + self.safe(key)
+    end
+
+    # turns a URL into a safe filename
+    def safe filename
+      filemd5 = MD5.hexdigest(filename)
+      filename = filename.sub(/^\w+:\/\//, '')
+      filename = filename.gsub(/[?\/:|]+/, ',')
+
+      filename + "," + filemd5
+    end
+
+    def [] key
+      File.read(self.to_file(key))
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def []= key, value
+      File.open(self.to_file(key), 'w') do |f|
+        f.write(value)
+      end
+    end
+
+    def delete key
+      File.delete(self.to_file(key))
+    end
+  end
+end

data/lib/atom/collection.rb

@@ -1,31 +1,102 @@
 require "atom/http"
 require "atom/feed"
 
-# so we can do some mimetype guessing
-require "webrick/httputils"
-
 module Atom
-  # represents an Atom Publishing Protocol Collection
-  class Collection < Feed
-    # comma separated string that contains a list of media types
-    # accepted by a collection.
-    #
-    # XXX I should parse this in some way, but I'm not sure what's useful 
-    attr_accessor :accepts
-
-    def initialize(uri, http = Atom::HTTP.new)
-      super uri, http
+  class Categories < Atom::Element
+    is_element PP_NS, 'categories'
+
+    atom_elements :category, :list, Atom::Category
+
+    attrb ['app', PP_NS], :scheme
+    attrb ['app', PP_NS], :href
+
+    def scheme= s
+      list.each do |cat|
+        unless cat.scheme
+          cat.scheme = s
+        end
+      end
+    end
+
+    # 'fixed' attribute parsing/building
+    attr_accessor :fixed
+
+    on_parse_attr [PP_NS, :fixed] do |e,x|
+      e.set(:fixed, x == 'yes')
+    end
+
+    on_build do |e,x|
+      if e.get(:fixed)
+        e.attributes['fixed'] = 'yes'
+      end
+    end
+  end
+
+  class Collection < Atom::Element
+    is_element PP_NS, 'collection'
+
+    strings ['app', PP_NS], :accept, :accepts
+    attrb ['app', PP_NS], :href
+
+    def_set :href do |href|
+      @href = href
+      @feed = Atom::Feed.new @href, @http
+    end
+
+    atom_element :title, Atom::Title
+
+    elements ['app', PP_NS], :categories, :categories, Atom::Categories
+
+    def title
+      @title or @feed.title
+    end
+
+    def accepts
+      if @accepts.empty?
+        ['application/atom+xml;type=entry']
+      else
+        @accepts
+      end
+    end
+
+    def accepts= array
+      @accepts = array
     end
 
-    # POST an entry to the collection, with a slug
+    attr_reader :http
+
+    attr_reader :feed
+
+    def initialize(href = nil, http = Atom::HTTP.new)
+      super()
+
+      @http = http
+
+      if href
+        self.href = href
+      end
+    end
+
+    def self.parse xml, base = ''
+      e = super
+
+      # URL absolutization
+      if !e.base.empty? and e.href
+        e.href = (e.base.to_uri + e.href).to_s
+      end
+
+      e
+    end
+
+    # POST an entry to the collection, with an optional slug
     def post!(entry, slug = nil)
       raise "Cowardly refusing to POST a non-Atom::Entry" unless entry.is_a? Atom::Entry
       headers = {"Content-Type" => "application/atom+xml" }
       headers["Slug"] = slug if slug
-      
-      @http.post(@uri, entry.to_s, headers)
+
+      @http.post(@href, entry.to_s, headers)
     end
-  
+
     # PUT an updated version of an entry to the collection
     def put!(entry, url = entry.edit_url)
       @http.put_atom_entry(entry, url)
@@ -40,8 +111,8 @@ module Atom
     def post_media!(data, content_type, slug = nil)
       headers = {"Content-Type" => content_type}
       headers["Slug"] = slug if slug
-      
-      @http.post(@uri, data, headers)
+
+      @http.post(@href, data, headers)
     end
 
     # PUT a media item to the collection
@@ -51,25 +122,4 @@ module Atom
       @http.put(url, data, headers)
     end
   end
-
-  class HTTP
-    # GET a URL and turn it into an Atom::Entry
-    def get_atom_entry(url)
-      res = get(url)
-
-      if res.code != "200" or res.content_type != "application/atom+xml"
-        raise Atom::HTTPException, "expected Atom::Entry, didn't get it"
-      end
-
-      Atom::Entry.parse(res.body, url)
-    end
-
-    # PUT an Atom::Entry to a URL
-    def put_atom_entry(entry, url = entry.edit_url)
-      raise "Cowardly refusing to PUT a non-Atom::Entry (#{entry.class})" unless entry.is_a? Atom::Entry
-      headers = {"Content-Type" => "application/atom+xml" }
-      
-      put(url, entry.to_s, headers)
-    end
-  end
 end