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