;;; Commentary:
-;; This is a library for creating an Atom file from a Lisp program.
+;; This is a library for creating an Atom feed from a Lisp program.
+;; The normal usage is to create a feed with `atom-create', giving it
+;; a title and a Web address. Once the feed has been created, entries
+;; may be added to the feed, by specifying (at the minimum) a title, a
+;; permanent link and the content of the entry. Text-only, HTML and
+;; XHTML entries are supported.
+
+;; A feed is really a Lisp structure as used by the `xml.el' package,
+;; without the parent `feed' element.
+
+;; A typical usage would look like this:
+
+;; (let ((my-atom-feed (atom-create "My feed" "http://example.org")))
+;; ; A simple, text-only entry
+;; (atom-add-text-entry
+;; my-atom-feed
+;; "Hello world"
+;; "http://example.org/hello"
+;; "Hello the world!")
+;;
+;; ; A text-only entry, with all the optional pieces of data
+;; (atom-add-text-entry
+;; my-atom-feed
+;; "Bonjour"
+;; "http://example.org/bonjour"
+;; "Bonjour à tout le monde !"
+;; ;; optional: the last modification time
+;; (date-to-time "2011-01-30 23:40:12")
+;; ;; optional: an identifier for this entry; a common way to generate it is
+;; ;; to use the domain name and the creation date of the entry.
+;; (atom-generate-id "http://example.org"
+;; (date-to-time "2011-01-30 10:01:05"))
+;; ;; optional: a summary for this entry
+;; "Bonjour, monde.")
+;;
+;; (atom-add-xhtml-entry
+;; my-atom-feed
+;; "An XHTML example"
+;; "http://example.org/html-example"
+;; "<p>One can also use <acronym>XHTML</acronym> in the entries.</p>")
+;; (atom-print my-atom-feed))
;;; Code:
-(defun atom-create (title author link &optional updated id)
+(require 'xml)
+
+(defun atom-create (title link &optional author self updated id)
"Create a new atom structure.
TITLE is the title for the feed, a short, text-only, human
AUTHOR is the author of the feed. See `atom-massage-author' for
the possible ways to specify it.
+SELF is the canonical URL to this feed.
+
LINK is the URL of a page responible for the content of this
feed.
ID is a unique identifier for this feed. If not given, it
defaults to LINK."
- `((title nil ,title)
- (link ((href . ,link)))
- ,(atom-massage-author author)
- (updated nil ,(atom-format-time updated))
- (id nil ,(or id link))))
+ (let ((atom-feed (list (list 'title nil title))))
+ (atom-modify-entry atom-feed 'link `(((href . ,link))))
+ (atom-modify-entry atom-feed 'author (atom-massage-author author))
+ (if self (atom-modify-entry atom-feed 'link
+ `(((href . ,self) (rel . "self")
+ (type . "application/atom+xml")))))
+ (atom-modify-entry atom-feed 'updated (atom-format-time updated))
+ (atom-modify-entry atom-feed 'id (or id link))
+ atom-feed))
(defun atom-push-entry (atom entry)
"Add the entry ENTRY to the feed ATOM."
- (nconc atom (list `(entry nil . ,entry))))
+ (nconc atom (list `(entry nil ,@entry))))
(defun atom-modify-entry (entry name val)
- "Set the NAME element of ENTRY to VAL."
- (let ((elem (assoc name entry)))
- (if elem
- (if (stringp val)
- (setcar (cddr elem) val)
- (setcdr elem val))
- (setq elem (if (stringp val)
- (list name nil val)
- (cons name val)))
- (nconc entry (list elem)))))
+ "Set the NAME element of ENTRY to VAL. A true MULTIPLE means
+to add a new element instead of updating it when it already exists."
+ (let ((elem (if (stringp val)
+ (list name nil val)
+ (cons name val))))
+ (nconc entry (list elem))))
(defun atom-add-entry (atom title link content
- &optional summary updated id)
+ &optional updated id summary)
"Add an entry to the atom flux ATOM. Return the newly added
entry.
UPDATED defaults to `(current-time)' if omitted, which is
probably not a very good default.
-ID defaults to LINK, which is not optimal; TODO give a way to
-easily generate IDs. For a given entry, it must not change
-between successive generations of the atom feed."
+ID defaults to LINK, which is not optimal; see `atom-generate-id'
+for a way to create good identifiers. For a given entry, it must
+not change between successive generations of the atom feed, even
+when the content of the entry ."
(let ((entry (list (list 'title nil title))))
(atom-modify-entry entry 'link (list (list (cons 'href link))))
(atom-modify-entry entry 'id (or id link))
`atom-add-entry' for details.")
(defun atom-add-html-entry (atom title link content
- &optional summary updated id)
+ &optional updated id summary)
"Add an entry to ATOM, with some HTML content. CONTENT should
be a string enconding a valid HTML fragment. See `atom-add-entry'
for additional details."
(atom-add-entry atom
- title link
- (atom-massage-html content)
- (and summary (atom-massage-html summary))
- updated id))
+ title link (atom-massage-html content)
+ updated id (and summary (atom-massage-html summary))))
(defun atom-add-xhtml-entry (atom title link content
- &optional summary updated id)
+ &optional updated id summary)
"Add an entry to ATOM, with some XHTML content. CONTENT may be
given either as a string, or as an XML tree, of a valid XHTML
fragment. See `atom-add-entry' for additional details."
(atom-add-entry atom
- title link
- (atom-massage-xhtml content)
- (and summary (atom-massage-xhtml summary))
- updated id))
+ title link (atom-massage-xhtml content)
+ updated id (and summary (atom-massage-xhtml summary))))
(defun atom-print (atom)
"Print the Atom feed ATOM in the current buffer."
(xml-print atom)
(insert "\n</feed>"))
+(defun atom-write-file (atom filename)
+ "Writes the feed ATOM to FILENAME."
+ (with-temp-buffer
+ (atom-print atom)
+ (write-region (point-min) (point-max) filename)))
+
\f
(defun atom-format-time (&optional time)
"Format a time according to RFC3339."
(defun atom-string-to-xml (string)
"Convert STRING into a Lisp structure as used by `xml.el'."
(with-temp-buffer
+ (insert "<div xmlns=\"http://www.w3.org/1999/xhtml\">")
(insert string)
+ (insert "</div>")
(xml-parse-region (point-min) (point-max))))
(defun atom-massage-xhtml (content)
"Massage CONTENT so it can be used as an XHTML fragment in an
Atom feed."
- (list '((type . "xhtml"))
- `(div ((xmlns . "http://www.w3.org/1999/xhtml"))
- . ,(or (and (stringp content)
- (atom-string-to-xml content))
- content))))
+ `(((type . "xhtml"))
+ ,@(or (and (stringp content)
+ (atom-string-to-xml content))
+ content)))
(defun atom-massage-author (author)
"Return an XML node representing the author. AUTHOR can be:
- a list with two elements, the full name and the email address
of the author;
- something else, assumed to be a complete `atomPersonConstruct'."
- (cond
- ((null author) `(author nil
- (name nil ,user-full-name)
- (email nil ,user-mail-address)))
- ((stringp author) `(author nil
- (name nil ,user-full-name)))
- ((= 2 (length author)) `(author nil (name nil ,(car author))
- (email nil ,(cadr author))))
- (t `(author nil ,author))))
+ `(nil ,@(cond
+ ((null author) `((name nil ,user-full-name)
+ (email nil ,user-mail-address)))
+ ((stringp author) `((name nil ,author)))
+ ((= 2 (length author)) `((name nil ,(car author))
+ (email nil ,(cadr author))))
+ (t `(author nil ,author)))))
+
+(require 'url-parse)
+
+(defun atom-generate-id (link creation-date)
+ "Generate a string suitable for use as an atom:id element. This
+implements Mark Pilgrom's tag: URI method, using the
+CREATION-DATE of the entry, and the domain part of LINK."
+ (format "tag:%s,%s:/%s"
+ (url-host (url-generic-parse-url link))
+ (format-time-string "%Y-%m-%d" creation-date)
+ (format-time-string "%Y%m%d%H%M%S" creation-date)))
(provide 'atom)
;;; atom.el ends here
projects / atom.el.git / blobdiff