org-contrib/org-feed.org

   1 #+TITLE:     org-feed.el -- add RSS feed items to Org files
   2 #+OPTIONS:   ^:{} author:nil
   3 #+STARTUP: odd
   4
   5 This module allows to create and change entries in an Org-mode
   6 file triggered by items in an RSS feed.  The basic functionality is
   7 geared toward simply adding new items found in a feed as outline nodes
   8 to an Org file.  Using hooks, arbitrary actions can be triggered for
   9 new or changed items.
  10
  11 * Example
  12
  13 This module is configured through a single variable, =org-feed-alist=.
  14 Here is an example, using a notes/tasks feed from reQall.com.
  15 #+begin_src emacs-lisp
  16 (setq org-feed-alist
  17       '(("ReQall"
  18          "http://www.reqall.com/user/feeds/rss/a1b2c3....."
  19          "~/org/feeds.org" "ReQall Entries")
  20 #+end_src
  21
  22 With this setup, the command =M-x org-feed-update-all= will
  23 collect new entries in the feed at the given URL and create
  24 entries as subheadings under the "ReQall Entries" heading in the
  25 file "~/org-feeds.org".  Each feed needs to have its own heading.
  26
  27 Besides these standard elements that need to be specified for each
  28 feed,, keyword-value pairs can set additional options.  For example,
  29 to de-select transitional entries with a title containing /reQall is
  30 typing what you said/ you could use the =:filter= argument:
  31
  32 #+begin_src emacs-lisp
  33 (setq org-feed-alist
  34       '(("ReQall"
  35          "http://www.reqall.com/user/feeds/rss/a1b2c3....."
  36          "~/org/feeds.org" "ReQall Entries"
  37          :filter my-reqall-filter)))
  38
  39 (defun my-reqall-filter (e)
  40   (if (string-match "reQall is typing what you said"
  41                     (plist-get e :title))
  42       nil
  43     e))
  44 #+end_src
  45
  46 See the docstring for =org-feed-alist= for more details.
  47
  48 * Keeping track of previously added entries
  49
  50 Since Org allows you to delete, archive, or move outline nodes,
  51 org-feed.el needs to keep track of which feed items have been handled
  52 before, so that they will not be handled again.  For this, org-feed.el
  53 stores information in a special drawer, FEEDSTATUS, under the heading
  54 that received the input of the feed.  You should add FEEDSTATUS
  55 to your list of drawers in the files that receive feed input:
  56
  57 #+begin_src org
  58 ,#+DRAWERS: PROPERTIES LOGBOOK FEEDSTATUS
  59 #+end_src
  60
  61
  62 * Detailed description of =org-feed-alist=
  63
  64 Alist specifying RSS feeds that should create inputs for Org.
  65 Each entry in this list specified an RSS feed tat should be queried
  66 to create inbox items in Org.  Each entry is a list with the following items:
  67
  68
  69 - name     :: a custom name for this feed
  70 - URL      :: the Feed URL
  71 - file     :: the target Org file where entries should be listed
  72 - headline :: the headline under which entries should be listed
  73
  74 Additional arguments can be given using keyword-value pairs.  Many of
  75 these specify functions that receive one or a list of "entries" as
  76 their single argument.  An entry is a property list that describes a
  77 feed item.  The property list has properties for each field in the
  78 item, for example =:title= for the =<title>= field and =:pubDate= for
  79 the publication date.  In addition, it contains the following
  80 properties:
  81
  82 - =:item-full-text= :: the full text in the =<item>= tag
  83 - =:guid-permalink= :: t when the guid property is a permalink
  84
  85 Here are the keyword-value elements that can be configured
  86
  87 - :drawer drawer-name :: The name of the drawer for storing feed
  88      information.  The default is "FEEDSTATUS".  Using different
  89      drawers for different feeds allows several feeds to target the
  90      same inbox heading.
  91
  92 - :filter filter-function :: A function to select interesting entries
  93      in the feed.  It gets a single entry as parameter.  It should
  94      return the entry if it is relevant, or nil if it is not.
  95
  96 - :template template-string :: The default action on new items in the
  97      feed is to add them as children under the headline for the feed.
  98      The template describes how the entry should be formatted.  If not
  99      given, it defaults to =org-feed-default-template=.
 100
 101 - :formatter formatter-function :: Instead of relying on a template,
 102      you may specify a function to format the outline node to be
 103      inserted as a child.  This function gets passed a property list
 104      describing a single feed item, and it should return a string that
 105      is a properly formatted Org outline node of level 1.
 106
 107 - :new-handler function :: If adding new items as children to the
 108      outline is not what you want to do with new items, define a
 109      handler function that is called with a list of all new items in
 110      the feed, each one represented as a property list.  The handler
 111      should do what needs to be done, and org-feed will mark all items
 112      given to this handler as \"handled\", i.e. they will not be
 113      passed to this handler again in future readings of the feed.
 114      When the handler is called, point will be at the feed headline.
 115
 116 - :changed-handler function :: This function gets passed a list of all
 117      entries that have been handled before, but are now still in the
 118      feed and have *changed* since last handled (as evidenced by a
 119      different sha1 hash).  When the handler is called, point will be
 120      at the feed headline.
 121
 122 * Acknowledgments
 123
 124 /org-feed.el/ is based on ideas by Brad Bozarth who implemented a
 125 similar mechanism using shell and awk scripts.
 126
 127