X-Git-Url: https://gitweb.fperrin.net/?p=atom.git;a=blobdiff_plain;f=atom.el;h=d159eed7029a85c69e9e33afe78739b0fb6fa599;hp=7b43065babb1527f1d63b195d349375ab44e9ad2;hb=2f1f8729baa9edb46b8b65b101fdfd81e0a8a59e;hpb=1e75e274945b36bc74eb4e605b023ee85b8a86c5

diff --git a/atom.el b/atom.el
index 7b43065..d159eed 100644
--- a/atom.el
+++ b/atom.el
@@ -20,51 +20,95 @@
 
 ;;; 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 self id author updated)
   "Create a new atom structure.
 
 TITLE is the title for the feed, a short, text-only, human
 readable string.
 
-AUTHOR is the author of the feed. See `atom-massage-author' for
-the possible ways to specify it.
-
 LINK is the URL of a page responible for the content of this
 feed.
 
-UPDATED is the date the feed was last updated. If not given,
-`(current-time)' is used.
+SELF is the canonical URL to 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))))
+defaults to SELF.
+
+AUTHOR is the author of the feed. See `atom-massage-author' for
+the possible ways to specify it.
+
+UPDATED is the date the feed was last updated. If not given,
+`(current-time)' is used."
+  (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 self 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.
 
@@ -81,9 +125,10 @@ If SUMMARY is not given, the entry will not contain any summary.
 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))
@@ -98,26 +143,22 @@ between successive generations of the atom feed."
 `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."
@@ -126,6 +167,12 @@ fragment. See `atom-add-entry' for additional details."
   (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)))
+
 
 (defun atom-format-time (&optional time)
   "Format a time according to RFC3339."
@@ -144,17 +191,18 @@ Atom feed. CONTENT must be a string."
 (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:
@@ -164,15 +212,24 @@ Atom feed."
 - 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