ratom-instructure 0.6.9

data/History.txt

@@ -0,0 +1,135 @@
+== 0.6.9
+
+* SSL support [kossnocorp]
+
+== 0.6.8
+
+* Better auth-hmac detection.
+* Handles Ruby 1.9 arrays. [wilkie]
+
+== 0.6.7
+
+* Handle dashes in extension names.
+
+== 0.6.6
+
+* Added support for absoluting relative uris using xml:base. [Greg Campbell]
+
+== 0.6.5
+
+* Fixed missing version.rb, now loads version.yml. [Greg Campbell]
+
+== 0.6.4
+
+* Remove Hoe dependency and converted to a Jeweler based project build.
+* Fixed error when assigning nil to node['xml:lang'] [George Guimarães].
+* Handle link@title. [Brian Dewey]
+* SimpleExtensions#[] returns a namespace hash if localname is not given. [Daniel Vartanov]
+
+== 0.6.3 2009-11-19
+
+* Removed extraneous logging.
+
+== 0.6.2 2009-06-19
+
+* Handle href and fixed on service doc categories.
+* Use request_uri instead of path so that we get any query parameters too. [Wybo Wiersma]
+* Doc Patches.
+
+== 0.6.1 2009-03-27
+
+Some minor exception fixes.
+
+* Removed Atom::ParseError. Parse errors now will only throw ArgumentError.
+* ProtocolError has a to string method.
+
+== 0.6.0 2009-03-19
+
+* Now depends on libxml-ruby 1.1.2.
+* Added support for hreflang on links. (David Arango)
+* Update to work with latest version of libxml-ruby. (oortle & me)
+* Content::Text and Content::Xhtml can now be created with String's like Content::Html.
+* Make sure Atom::Generator outputs the generator name as the text of the element.
+
+== 0.5.2 2008-12-06
+
+* Remove whitespace modification in content. (dlisboa)
+
+== 0.5.1 2008-08-05
+
+* Added optional AuthHMAC support
+
+== 0.5.0 2008-07-28
+
+* Fix bug where processing instructions break parsing.
+* Added Custom extension element classes. (Ignacio Carrera)
+
+== 0.4.2 2008-07-09
+
+* Update to libxml-ruby version 0.8.x
+
+== 0.4.1 2008-07-09
+
+* Update to libxml-ruby version 0.6.0.
+
+== 0.4.0 2008-06-26
+
+* Support for HTTP Basic Authentication.
+
+== 0.3.7 2008-06-05
+
+* Support XML in extension elements. (Min Kim)
+
+== 0.3.6 2008-05-15
+
+* Added categories to feeds.
+* Make sure atom:content appears at the end of a atom:entry.
+* Don't use namespace prefixes on content unless we really have to.
+
+== 0.3.5 2008-05-03
+
+* Make sure atom:entries appears last.
+* Better examples in the documentation. Docs for Feed and Entry list attributes.
+* Gave Feeds authors and contributors.
+* Fixed a couple warnings.
+
+== 0.3.4 2008-04-21
+
+* Remove useless variable warning.  (Sam Roberts)
+* Support initialization of Atom::Source from Hash and block.
+* Support initialization of Atom::Generator from Hash and block.
+
+== 0.3.3 2008-04-09
+
+* Better serialization of namespaced elements. ratom will now generate prefixes for namespaces and write them as
+  attributes on the root element.
+* Extensions read as attributes are now written as attributes.
+* When programmatically setting an extension value you can tell ratom to write it as an attribute using:
+  
+  entry['http://example.org', 'extattr'].as_attribute = true  
+
+* Add support for atom:category.
+* Support extension attributes using the same mechanism as extension elements.
+
+== 0.3.1 2008-04-02
+
+* Bunch of fixes to the Atom::Pub classes to make them work like the Atom classes
+  with respect to initializers and to_xml.
+
+== 0.3.0 2008-04-02
+
+* Raise Atom::Serialization error when you try and serialize non-utf8 content.
+* Support reading simple extension elements, see README.txt.
+* Support writing simple extension elements, see README.txt.
+
+== 0.2.2 2008-02-10
+
+* Removed dependency on ActiveSupport.
+
+== 0.2.1 2008-03-03
+
+* Initial release to the public.
+
+== < 0.2.1
+
+* Internal releases.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Peerworks
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,293 @@
+= rAtom
+
+rAtom is a library for working with the Atom Syndication Format and
+the Atom Publishing Protocol (APP).
+
+* Built using libxml so it is _much_ faster than a REXML based library.
+* Uses the libxml pull parser so it has much lighter memory usage.
+* Supports {RFC 5005}[http://www.ietf.org/rfc/rfc5005.txt] for feed pagination.
+
+rAtom was originally built to support the communication between a number of applications
+built by Peerworks[http://peerworks.org], via the Atom Publishing protocol.  However, it 
+supports, or aims to support, all the Atom Syndication Format and Publication Protocol
+and can be used to access Atom feeds or to script publishing entries to a blog supporting APP.
+
+== Prerequisites
+
+* libxml-ruby, >= 1.1.2
+* rspec (Only required for tests)
+
+libxml-ruby in turn requires the libxml2 library to be installed. libxml2 can be downloaded
+from http://xmlsoft.org/downloads.html or installed using whatever tools are provided by your
+platform.  At least version 2.6.31 is required.
+
+=== Mac OSX
+
+Mac OSX by default comes with an old version of libxml2 that will not work with rAtom. You
+will need to install a more recent version.  If you are using Macports:
+
+  port install libxml2
+
+== Installation
+
+You can install via gem using:
+
+  gem install ratom
+  
+== Usage
+
+To fetch a parse an Atom Feed you can simply:
+
+  feed = Atom::Feed.load_feed(URI.parse("http://example.com/feed.atom"))
+  
+And then iterate over the entries in the feed using:
+
+  feed.each_entry do |entry|
+    # do cool stuff
+  end
+  
+To construct the following example Feed is from the Atom spec:
+
+  <?xml version="1.0" encoding="utf-8"?>
+  <feed xmlns="http://www.w3.org/2005/Atom">
+
+    <title>Example Feed</title> 
+    <link href="http://example.org/"/>
+    <updated>2003-12-13T18:30:02Z</updated>
+    <author> 
+      <name>John Doe</name>
+    </author> 
+    <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
+
+    <entry>
+      <title>Atom-Powered Robots Run Amok</title>
+      <link href="http://example.org/2003/12/13/atom03"/>
+      <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+      <updated>2003-12-13T18:30:02Z</updated>
+      <summary>Some text.</summary>
+    </entry>
+
+  </feed>
+  
+To build this in rAtom we would do:
+
+  feed = Atom::Feed.new do |f|
+    f.title = "Example Feed"
+    f.links << Atom::Link.new(:href => "http://example.org/")
+    f.updated = Time.parse('2003-12-13T18:30:02Z')
+    f.authors << Atom::Person.new(:name => 'John Doe')
+    f.id = "urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6"
+    f.entries << Atom::Entry.new do |e|
+      e.title = "Atom-Powered Robots Run Amok"
+      e.links << Atom::Link.new(:href => "http://example.org/2003/12/13/atom03")
+      e.id = "urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a"
+      e.updated = Time.parse('2003-12-13T18:30:02Z')
+      e.summary = "Some text."
+    end
+  end
+  
+To output the Feed as XML use to_xml
+
+  > puts feed.to_xml
+  <?xml version="1.0"?>
+  <feed xmlns="http://www.w3.org/2005/Atom">
+    <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
+    <title>Example Feed</title>
+    <updated>2003-12-13T18:30:02Z</updated>
+    <link href="http://example.org/"/>
+    <author>
+      <name>John Doe</name>
+    </author>
+    <entry>
+      <title>Atom-Powered Robots Run Amok</title>
+      <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+      <summary>Some text.</summary>
+      <updated>2003-12-13T18:30:02Z</updated>
+      <link href="http://example.org/2003/12/13/atom03"/>
+    </entry>
+  </feed>
+  
+
+See Feed and Entry for details on the methods and attributes of those classes.
+
+=== Publishing
+
+To publish to a remote feed using the Atom Publishing Protocol, first you need to create a collection to publish to:
+
+  require 'atom/pub'
+  
+  collection = Atom::Pub::Collection.new(:href => 'http://example.org/myblog')
+  
+Then create a new entry
+
+  entry = Atom::Entry.new do |entry|
+    entry.title = "I have discovered rAtom"
+    entry.authors << Atom::Person.new(:name => 'A happy developer')
+    entry.updated = Time.now
+    entry.id = "http://example.org/myblog/newpost"
+    entry.content = Atom::Content::Html.new("<p>rAtom lets me post to my blog using Ruby, how cool!</p>")
+  end
+  
+And publish it to the Collection:
+
+  published_entry = collection.publish(entry)
+
+Publish returns an updated entry filled out with any attributes to server may have set, including information
+required to let us update to the entry.  For example, lets change the content and republished:
+
+  published_entry.content =  Atom::Content::Html.new("<p>rAtom lets me post to and edit my blog using Ruby, how cool!</p>")
+  published_entry.updated = Time.now
+  published_entry.save!
+
+To update an existing Entry:
+
+  existing_entry = Entry.load_entry(URI.parse("http://example.org/afeedentry.atom"))
+
+  existing_entry.title = "I have discovered rAtom"
+  existing_entry.updated = Time.now
+  existing_entry.save!
+
+You can also delete an entry using the <tt>destroy!</tt> method, but we won't do that will we?.
+    
+=== Extension elements
+
+As of version 0.3.0, rAtom support simple extension elements on feeds and entries.  As defined in the Atom Syndication Format,
+simple extension elements consist of XML elements from a non-Atom namespace that have no attributes or child elements, i.e.
+they are empty or only contain text content.  These elements are treated as a name value pair where the element namespace
+and local name make up the key and the content of the element is the value, empty elements will be treated as an empty string.
+
+To access extension elements use the [] method on the Feed or Entry. For example, if we are parsing the follow Atom document
+with extensions:
+
+  <?xml version="1.0"?>
+  <feed xmlns="http://www.w3.org/2005/Atom" xmlns:ex="http://example.org">
+    <title>Feed with extensions</title>
+    <ex:myelement>Something important</ex:myelement>
+  </feed>
+  
+We could then access the extension element on the feed using:
+
+  > feed["http://example.org", "myelement"]
+  => ["Something important"]
+  
+Note that the return value is an array. This is because XML allows multiple instances of the element. 
+
+To set an extension element you append to the array:
+
+  > feed['http://example.org', 'myelement'] << 'Something less important'
+  => ["Something important", "Something less important"]
+  
+You can then call to_xml and rAtom will serialize the extension elements into xml.
+
+  > puts feed.to_xml
+  <?xml version="1.0"?>
+  <feed xmlns="http://www.w3.org/2005/Atom">
+    <myelement xmlns="http://example.org">Something important</myelement>
+    <myelement xmlns="http://example.org">Something less important</myelement>
+  </feed>
+  
+Notice that the output repeats the xmlns attribute for each of the extensions, this is semantically the same the input XML, just a bit
+ugly.  It seems to be a limitation of the libxml-Ruby API. But if anyone knows a work around I'd gladly accept a patch (or even advice).
+
+==== Custom Extension Classes 
+
+As of version 0.5.0 you can also define your own classes for a extension elements.  This is done by first creating an alias
+for the namespace for the class and then using the +element+ method on the Atom::Feed or Atom::Entry class to tell rAtom
+to use your custom class when it encounters the extension element.
+
+For example, say we have the following piece Atom XML with a structured extension element:
+
+  <?xml version='1.0' encoding='UTF-8'?>
+  <entry xmlns='http://www.w3.org/2005/Atom' xmlns:custom='http://custom.namespace'>
+    <id>https://custom.namespace/id/1</id>
+    <link rel='self' type='application/atom+xml' href='https://custom.namespace/id/1'/>
+    <custom:property name='foo' value='bar'/>
+    <custom:property name='baz' value='bat'/>
+  </entry>
+	
+And we want the +custom:property+ elements to be parsed as our own custom class called Custom::Property that is
+defined like this:
+
+  class Custom::Property
+    attr_accessor :name, :value
+    def initialize(xml)
+      # Custom XML handling
+    end
+  end
+	
+We can tell rAtom about our custom namespace and custom class using the following method calls:
+
+  Atom::Feed..add_extension_namespace :custom, "http://custom.namespace"
+  Atom::Entry.elements "custom:property", :class => Custom::Property
+	
+The first method call registers an alias for the "http://custom.namespace" namespace and the second method call
+tell rAtom that when it encounters a custom:property element within a Feed it should create an instance of Custom::Property
+and pass the XML Reader to the constructor of the instance.  It is then up to the constructor to populate the objects attributes 
+from the XML. Note that the alias you create using +add_extension_namespace+ can be anything you want, it doesn't need
+to match the alias in the actual XML itself.
+
+The custom property will then be available as a method on the rAtom class.  In the above example:
+
+  @feed.custom_property.size == 2
+  @feed.custom_property.first.name == 'foo'
+  @feed.custom_property.first.value == 'bar'
+	
+There is one caveat to this.  By using this type of extension support you are permanently modifying the rAtom classes.
+So if your application process one type of atom extension and you are happy with permanently modified rAtom classes,
+the extra extensibility might work for you.  If on the other hand you process lots of different types of extension you might
+want to stick with simpler extension mechanism using the [namespace, element] method described above.
+ 
+(Thanks to nachokb for this feature!!)
+
+=== Basic Authentication
+
+All methods that involve HTTP requests now support HTTP Basic Authentication.  Authentication credentials are passed
+as :user and :pass parameters to the methods that invoke the request. For example you can load a feed with HTTP Basic Authentication using:
+
+  Atom::Feed.load_entry(URI.parse("http://example.org/feed.atom"), :user => 'username', :pass => 'password')
+
+Likewise all the Atom Pub methods support similar parameters, for example you can publish an Entry to a Feed with authentication
+using:
+
+  feed.publish(entry, :user => 'username', :pass => 'password')
+
+Or destroy an entry with:
+
+  entry.destroy!(:user => 'username', :pass => 'password')
+
+rAtom doesn't store these credentials anywhere within the object model so you will need to pass them as arguments to every
+method call that requires them.  This might be a bit of a pain but it does make things simpler and it means that I'm not responsible
+for protecting your credentials, although if you are using HTTP Basic Authentication there is a good chance your credentials aren't
+very well protected anyway.
+
+=== AuthHMAC authentication
+
+As of version 0.5.1 rAtom also support authentication via HMAC request signing using the AuthHMAC[http://auth-hmac.rubyforge.org] gem.  This is made available using the :hmac_access_id and :hmac_secret_key parameters which can be passed to the same methods as the HTTP Basic credentials support.
+
+=== SSL
+
+As of version 0.6.9, rAtom supports fetching feeds via https. This is done by using URLs with the SSL protocol. Publishing support is still limited to http, but patches are welcome.
+
+== TODO
+
+* Support partial content responses from the server.
+* Support batching of protocol operations.
+* All my tests have been against internal systems, I'd really like feedback from those who have tried rAtom using existing blog software that supports APP.
+* Handle all base uri tests.
+* Add slug support.
+
+== Source Code
+
+The source repository is accessible via GitHub:
+
+  git clone git://github.com/seangeo/ratom.git
+
+== Contact Information
+
+The project page is at http://github.com/seangeo/ratom. Please file any bugs or feedback
+using the trackers and forums there.
+
+== Authors and Contributors
+
+rAtom was developed by Peerworks[http://peerworks.org] and written by Sean Geoghegan.
+

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ratom"
+    gem.summary = %Q{Atom Syndication and Publication API}
+    gem.description = %Q{A fast Atom Syndication and Publication API based on libxml}
+    gem.email = "seangeo@gmail.com"
+    gem.homepage = "http://github.com/seangeo/ratom"
+    gem.rubyforge_project = 'ratom'
+    gem.authors = ["Peerworks", "Sean Geoghegan"]
+    gem.add_development_dependency "rspec"
+    gem.add_dependency 'libxml-ruby', '>= 1.1.2'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+  Jeweler::RubyforgeTasks.new do |rf|
+    rf.doc_task = 'rdoc'
+    rf.remote_doc_path = ''
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ratom #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end