Skip to content
This repository has been archived by the owner. It is now read-only.
An elisp implementation of the Atom Syndication Format (RFC4287)
Emacs Lisp
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE
README
atom-syndication.el
atom-syndication.rnc

README

* About

=atom-syndication.el= is an elisp implementation of the Atom
Syndication Format ([[http://www.ietf.org/rfc/rfc4287.txt][RFC4287]]).  It provides a set of functions to
create an Atom feed based on a lisp structure.

=atom-syndication.el= is Copyright (C) 2010 by David Maus and released
under the terms of the [[http://www.gnu.org/licenses/gpl.html][GNU General Public License]], version 3.

* Installation

=atom-syndication.el= is developed in a public git repository on
[[http://github.com/dmj/atom-syndication/][Github]].  You can clone the repository using git

=git clone git://github.com/dmj/atom-syndication.git=

The repository ships with a copy of the [[http://www.relaxng.org][RELAX NG Compact Scheme]] of the
Atom Syndication Format that can be used to check the validity of a
feed with [[http://www.thaiopensource.com/nxml-mode/][nxml-mode]].[fn:: M-x rng-set-schema-file-and-validate RET
/path/to/atom-syndication.rnc RET]

* Concept

Atom feed documents are XML documents, consisting of probably nested
Atom elements.  An Atom element is represented by a list of the
following format:

=(ELEMENT ATTR VAR [VAR VAR ...])=

Where ELEMENT is the symbol of the element name, ATTR is a list of
cons with XML attributes and VAR are values of the element.  The
distinction between XML attributes and XML container data is handled
transparently: Atom element values that are, at the end, XML
attributes can either represented in ATTR, a list of cons, or optional
values of the element.  Thus, the list representing the
=atom:generator= element

#+begin_src emacs-lisp
(generator nil "Example Generator" "1.0" "http://example.tld/")
#+end_src

is equivalent to

#+begin_src emacs-lisp
(generator ((version . "1.0") (uri . "http://example.tld/")) "Example Generator")
#+end_src

For Atom container elements, that is: Atom elements that contain one
or more other elements, the first value is expected to be a list with
the child elements.

To achieve compliance with the Atom specification, this library
implements a set of rules to check for the presence of mandatory
elements in a container element as well as the validity of Atom
element values.  If you want to add Atom extensions or modify the
rules in other ways you can customize the variables
=atom-syndication-attribute-xtra-alist=,
=atom-syndication-element-xtra-alist=, and
=atom-syndication-container-xtra-alist=.

* Usage

The most convenient function to create an Atom feed is
=atom-syndication-syndicate= that accepts a list representation of an
Atom container element as argument and returns a string with the XML
markup of this element.

For example calling this function with a simple feed that is
represented in this lisp structure:

#+begin_src emacs-lisp
  `(feed nil
         ((title nil "This is an example feed")
          (updated nil ,(current-time))
          (id nil "376c73f3-8483-44d8-9d3e-8da7cba0ebf1")
          (entry nil
                 ((title nil "This is an entry")
                  (id nil "d11e07e2-127f-4789-ab17-1bc2d6c80e28")
                  (updated nil ,(current-time))))))
#+end_src

Will return a string with a proper markup for an Atom feed.

#+begin_src nxml
  <feed xmlns=\"http://www.w3.org/2005/Atom\">
    <title>This is an example feed</title>
    <updated>2010-04-19T16:28:10+02:00</updated>
    <id>376c73f3-8483-44d8-9d3e-8da7cba0ebf1</id>
    <entry>
      <title>This is an entry</title>
      <id>d11e07e2-127f-4789-ab17-1bc2d6c80e28</id>
      <updated>2010-04-19T16:28:10+02:00</updated>
    </entry>
  </feed>
#+end_src

Besides =atom-syndication-syndicate= there is a function for each Atom
element that is called with the element values as arguments,
e.g. =atom-syndication-element-entry= which returns XML markup for a
single feed entry element.

* Appendix

** Revision history of this document

#+BEGIN_EXAMPLE
$Log: atom-syndication.org,v $
Revision 1.1  2010/06/06 14:13:20  dmaus
Initial revision

#+END_EXAMPLE
You can’t perform that action at this time.