{"id":13484476,"url":"https://github.com/seangeo/ratom","last_synced_at":"2025-03-27T16:30:54.564Z","repository":{"id":384850,"uuid":"2113","full_name":"seangeo/ratom","owner":"seangeo","description":"A fast, libxml based, Ruby Atom library supporting the Syndication Format and the Publishing Protocol. ","archived":true,"fork":false,"pushed_at":"2015-06-08T14:32:03.000Z","size":615,"stargazers_count":97,"open_issues_count":5,"forks_count":31,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-23T14:38:33.931Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rdoc.info/github/seangeo/ratom/frames","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seangeo.png","metadata":{"files":{"readme":"README.rdoc","changelog":"History.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2008-03-02T13:26:19.000Z","updated_at":"2024-02-29T17:54:27.000Z","dependencies_parsed_at":"2022-08-16T10:20:12.665Z","dependency_job_id":null,"html_url":"https://github.com/seangeo/ratom","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seangeo%2Fratom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seangeo%2Fratom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seangeo%2Fratom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seangeo%2Fratom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seangeo","download_url":"https://codeload.github.com/seangeo/ratom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245882287,"owners_count":20687860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:25.004Z","updated_at":"2025-03-27T16:30:54.135Z","avatar_url":"https://github.com/seangeo.png","language":"Ruby","readme":"= rAtom\n\nrAtom is a library for working with the Atom Syndication Format and\nthe Atom Publishing Protocol (APP).\n\n* Built using libxml so it is _much_ faster than a REXML based library.\n* Uses the libxml pull parser so it has much lighter memory usage.\n* Supports {RFC 5005}[http://www.ietf.org/rfc/rfc5005.txt] for feed pagination.\n\nrAtom was originally built to support the communication between a number of applications\nbuilt by Peerworks[http://peerworks.org], via the Atom Publishing protocol.  However, it \nsupports, or aims to support, all the Atom Syndication Format and Publication Protocol\nand can be used to access Atom feeds or to script publishing entries to a blog supporting APP.\n\n{\u003cimg src=\"https://secure.travis-ci.org/seangeo/ratom.png?branch=master\" alt=\"Build Status\" /\u003e}[http://travis-ci.org/seangeo/ratom]\n\nAPI docs are {here}[http://rdoc.info/github/seangeo/ratom/frames].\n\n== Prerequisites\n\n* libxml-ruby, \u003e= 1.1.2\n* rspec (Only required for tests)\n\nlibxml-ruby in turn requires the libxml2 library to be installed. libxml2 can be downloaded\nfrom http://xmlsoft.org/downloads.html or installed using whatever tools are provided by your\nplatform.  At least version 2.6.31 is required.\n\n=== Mac OSX\n\nMac OSX by default comes with an old version of libxml2 that will not work with rAtom. You\nwill need to install a more recent version.  If you are using Macports:\n\n  port install libxml2\n\nAlternatively, using Homebrew:\n\n  brew install libxml2\n\n== Installation\n\nYou can install via gem using:\n\n  gem install ratom\n  \n== Usage\n\nTo fetch a parse an Atom Feed you can simply:\n\n  require 'atom'\n\n  feed = Atom::Feed.load_feed(URI.parse(\"http://example.com/feed.atom\"))\n  \nAnd then iterate over the entries in the feed using:\n\n  feed.each_entry do |entry|\n    # do cool stuff\n  end\n  \nTo construct the following example Feed is from the Atom spec:\n\n  \u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n  \u003cfeed xmlns=\"http://www.w3.org/2005/Atom\"\u003e\n\n    \u003ctitle\u003eExample Feed\u003c/title\u003e \n    \u003clink href=\"http://example.org/\"/\u003e\n    \u003cupdated\u003e2003-12-13T18:30:02Z\u003c/updated\u003e\n    \u003cauthor\u003e \n      \u003cname\u003eJohn Doe\u003c/name\u003e\n    \u003c/author\u003e \n    \u003cid\u003eurn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6\u003c/id\u003e\n\n    \u003centry\u003e\n      \u003ctitle\u003eAtom-Powered Robots Run Amok\u003c/title\u003e\n      \u003clink href=\"http://example.org/2003/12/13/atom03\"/\u003e\n      \u003cid\u003eurn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a\u003c/id\u003e\n      \u003cupdated\u003e2003-12-13T18:30:02Z\u003c/updated\u003e\n      \u003csummary\u003eSome text.\u003c/summary\u003e\n    \u003c/entry\u003e\n\n  \u003c/feed\u003e\n  \nTo build this in rAtom we would do:\n\n  feed = Atom::Feed.new do |f|\n    f.title = \"Example Feed\"\n    f.links \u003c\u003c Atom::Link.new(:href =\u003e \"http://example.org/\")\n    f.updated = Time.parse('2003-12-13T18:30:02Z')\n    f.authors \u003c\u003c Atom::Person.new(:name =\u003e 'John Doe')\n    f.id = \"urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6\"\n    f.entries \u003c\u003c Atom::Entry.new do |e|\n      e.title = \"Atom-Powered Robots Run Amok\"\n      e.links \u003c\u003c Atom::Link.new(:href =\u003e \"http://example.org/2003/12/13/atom03\")\n      e.id = \"urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a\"\n      e.updated = Time.parse('2003-12-13T18:30:02Z')\n      e.summary = \"Some text.\"\n    end\n  end\n  \nTo output the Feed as XML use to_xml\n\n  \u003e puts feed.to_xml\n  \u003c?xml version=\"1.0\"?\u003e\n  \u003cfeed xmlns=\"http://www.w3.org/2005/Atom\"\u003e\n    \u003cid\u003eurn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6\u003c/id\u003e\n    \u003ctitle\u003eExample Feed\u003c/title\u003e\n    \u003cupdated\u003e2003-12-13T18:30:02Z\u003c/updated\u003e\n    \u003clink href=\"http://example.org/\"/\u003e\n    \u003cauthor\u003e\n      \u003cname\u003eJohn Doe\u003c/name\u003e\n    \u003c/author\u003e\n    \u003centry\u003e\n      \u003ctitle\u003eAtom-Powered Robots Run Amok\u003c/title\u003e\n      \u003cid\u003eurn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a\u003c/id\u003e\n      \u003csummary\u003eSome text.\u003c/summary\u003e\n      \u003cupdated\u003e2003-12-13T18:30:02Z\u003c/updated\u003e\n      \u003clink href=\"http://example.org/2003/12/13/atom03\"/\u003e\n    \u003c/entry\u003e\n  \u003c/feed\u003e\n  \n\nSee Feed and Entry for details on the methods and attributes of those classes.\n\n=== Publishing\n\nTo publish to a remote feed using the Atom Publishing Protocol, first you need to create a collection to publish to:\n\n  require 'atom/pub'\n  \n  collection = Atom::Pub::Collection.new(:href =\u003e 'http://example.org/myblog')\n  \nThen create a new entry\n\n  entry = Atom::Entry.new do |entry|\n    entry.title = \"I have discovered rAtom\"\n    entry.authors \u003c\u003c Atom::Person.new(:name =\u003e 'A happy developer')\n    entry.updated = Time.now\n    entry.id = \"http://example.org/myblog/newpost\"\n    entry.content = Atom::Content::Html.new(\"\u003cp\u003erAtom lets me post to my blog using Ruby, how cool!\u003c/p\u003e\")\n  end\n  \nAnd publish it to the Collection:\n\n  published_entry = collection.publish(entry)\n\nPublish returns an updated entry filled out with any attributes to server may have set, including information\nrequired to let us update to the entry.  For example, lets change the content and republished:\n\n  published_entry.content =  Atom::Content::Html.new(\"\u003cp\u003erAtom lets me post to and edit my blog using Ruby, how cool!\u003c/p\u003e\")\n  published_entry.updated = Time.now\n  published_entry.save!\n\nTo update an existing Entry:\n\n  existing_entry = Entry.load_entry(URI.parse(\"http://example.org/afeedentry.atom\"))\n\n  existing_entry.title = \"I have discovered rAtom\"\n  existing_entry.updated = Time.now\n  existing_entry.save!\n\nYou can also delete an entry using the \u003ctt\u003edestroy!\u003c/tt\u003e method, but we won't do that will we?.\n    \n=== Extension elements\n\nAs of version 0.3.0, rAtom support simple extension elements on feeds and entries.  As defined in the Atom Syndication Format,\nsimple extension elements consist of XML elements from a non-Atom namespace that have no attributes or child elements, i.e.\nthey are empty or only contain text content.  These elements are treated as a name value pair where the element namespace\nand local name make up the key and the content of the element is the value, empty elements will be treated as an empty string.\n\nTo access extension elements use the [] method on the Feed or Entry. For example, if we are parsing the follow Atom document\nwith extensions:\n\n  \u003c?xml version=\"1.0\"?\u003e\n  \u003cfeed xmlns=\"http://www.w3.org/2005/Atom\" xmlns:ex=\"http://example.org\"\u003e\n    \u003ctitle\u003eFeed with extensions\u003c/title\u003e\n    \u003cex:myelement\u003eSomething important\u003c/ex:myelement\u003e\n  \u003c/feed\u003e\n  \nWe could then access the extension element on the feed using:\n\n  \u003e feed[\"http://example.org\", \"myelement\"]\n  =\u003e [\"Something important\"]\n  \nNote that the return value is an array. This is because XML allows multiple instances of the element. \n\nTo set an extension element you append to the array:\n\n  \u003e feed['http://example.org', 'myelement'] \u003c\u003c 'Something less important'\n  =\u003e [\"Something important\", \"Something less important\"]\n  \nYou can then call to_xml and rAtom will serialize the extension elements into xml.\n\n  \u003e puts feed.to_xml\n  \u003c?xml version=\"1.0\"?\u003e\n  \u003cfeed xmlns=\"http://www.w3.org/2005/Atom\"\u003e\n    \u003cmyelement xmlns=\"http://example.org\"\u003eSomething important\u003c/myelement\u003e\n    \u003cmyelement xmlns=\"http://example.org\"\u003eSomething less important\u003c/myelement\u003e\n  \u003c/feed\u003e\n  \nNotice that the output repeats the xmlns attribute for each of the extensions, this is semantically the same the input XML, just a bit\nugly.  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).\n\n==== Custom Extension Classes \n\nAs of version 0.5.0 you can also define your own classes for a extension elements.  This is done by first creating an alias\nfor the namespace for the class and then using the +element+ method on the Atom::Feed or Atom::Entry class to tell rAtom\nto use your custom class when it encounters the extension element.\n\nFor example, say we have the following piece Atom XML with a structured extension element:\n\n  \u003c?xml version='1.0' encoding='UTF-8'?\u003e\n  \u003centry xmlns='http://www.w3.org/2005/Atom' xmlns:custom='http://custom.namespace'\u003e\n    \u003cid\u003ehttps://custom.namespace/id/1\u003c/id\u003e\n    \u003clink rel='self' type='application/atom+xml' href='https://custom.namespace/id/1'/\u003e\n    \u003ccustom:property name='foo' value='bar'/\u003e\n    \u003ccustom:property name='baz' value='bat'/\u003e\n  \u003c/entry\u003e\n\t\nAnd we want the +custom:property+ elements to be parsed as our own custom class called Custom::Property that is\ndefined like this:\n\n  class Custom::Property\n    attr_accessor :name, :value\n    def initialize(xml)\n      # Custom XML handling\n    end\n  end\n\t\nWe can tell rAtom about our custom namespace and custom class using the following method calls:\n\n  Atom::Entry.add_extension_namespace :custom, \"http://custom.namespace\"\n  Atom::Entry.elements \"custom:property\", :class =\u003e Custom::Property\n\t\nThe first method call registers an alias for the \"http://custom.namespace\" namespace and the second method call\ntell rAtom that when it encounters a custom:property element within a Feed it should create an instance of Custom::Property\nand pass the XML Reader to the constructor of the instance.  It is then up to the constructor to populate the objects attributes \nfrom the XML. Note that the alias you create using +add_extension_namespace+ can be anything you want, it doesn't need\nto match the alias in the actual XML itself.\n\nThe custom property will then be available as a method on the rAtom class.  In the above example:\n\n  @feed.custom_property.size == 2\n  @feed.custom_property.first.name == 'foo'\n  @feed.custom_property.first.value == 'bar'\n\t\nThere is one caveat to this.  By using this type of extension support you are permanently modifying the rAtom classes.\nSo if your application process one type of atom extension and you are happy with permanently modified rAtom classes,\nthe extra extensibility might work for you.  If on the other hand you process lots of different types of extension you might\nwant to stick with simpler extension mechanism using the [namespace, element] method described above.\n \n(Thanks to nachokb for this feature!!)\n\n=== Basic Authentication\n\nAll methods that involve HTTP requests now support HTTP Basic Authentication.  Authentication credentials are passed\nas :user and :pass parameters to the methods that invoke the request. For example you can load a feed with HTTP Basic Authentication using:\n\n  Atom::Feed.load_entry(URI.parse(\"http://example.org/feed.atom\"), :user =\u003e 'username', :pass =\u003e 'password')\n\nLikewise all the Atom Pub methods support similar parameters, for example you can publish an Entry to a Feed with authentication\nusing:\n\n  feed.publish(entry, :user =\u003e 'username', :pass =\u003e 'password')\n\nOr destroy an entry with:\n\n  entry.destroy!(:user =\u003e 'username', :pass =\u003e 'password')\n\nrAtom doesn't store these credentials anywhere within the object model so you will need to pass them as arguments to every\nmethod 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\nfor protecting your credentials, although if you are using HTTP Basic Authentication there is a good chance your credentials aren't\nvery well protected anyway.\n\n=== AuthHMAC authentication\n\nAs 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.\n\n=== SSL\n\nAs 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.\n\n== TODO\n\n* Support partial content responses from the server.\n* Support batching of protocol operations.\n* 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.\n* Handle all base uri tests.\n* Add slug support.\n\n== Source Code\n\nThe source repository is accessible via GitHub:\n\n  git clone git://github.com/seangeo/ratom.git\n\nThe project now uses Bundler for dependency management so, just do \n\n  bundle install\n\nto get going.\n\n== Contact Information\n\nThe project page is at http://github.com/seangeo/ratom. Please file any bugs or feedback\nusing the trackers and forums there.\n\n== Authors and Contributors\n\nrAtom was developed by Peerworks[http://peerworks.org] and written by Sean Geoghegan.\n\n","funding_links":[],"categories":["RSS"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseangeo%2Fratom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseangeo%2Fratom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseangeo%2Fratom/lists"}