joe.milbourn.org.uk Git - wikirepo/blob - projects/moogle/index.mdwn

   1 ## Moogle - A curses based google reader client
   2
   3 Moogle is a curses client for google reader, influenced by the best MUA ever,
   4 [Mutt][].  Like mutt moogle has keybindings for everything, and supports limit
   5 expressions to restrict what you're shown.
   6
   7 Moogle was written to [scratch an itch][] - there were console rss
   8 readers\[[1][], [2][]\] and GUI rss readers which can sync to google
   9 reader\[[3][]\] and [Google Reader][] proper but no console reader which could
  10 sync to google reader: enter moogle.
  11
  12 Moogle's not for everyone, as [Zed said][] (though he was talking about [newsbeuter][]):
  13
  14 > Now, I’m sure tons of people will scoff at the idea of not having graphics in
  15 > their feed.  They’ve gotta have that curvy candy coated interface with the
  16 > flash video about Steampunk Buttplugs posted by BoingBoing blaring right in
  17 > their fucking face or else they don’t feel alive.  They don’t feel young.
  18 > Dammit, they want to augment that Nerd ADD with a feed reader that goes to
  19 > eleven!
  20
  21 If that sounds like you, maybe you won't like moogle.
  22
  23 [scratch an itch]: http://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar
  24 [Mutt]: http://www.mutt.org
  25 [Zed said]: http://www.zedshaw.com/essays/i_want_the_mutt_of_feed_readers.html
  26
  27 [Google Reader]: http://google.com/reader
  28 [1]: http://kiza.kcore.de/software/snownews/
  29 [2]: http://www.newsbeuter.org/
  30 [newsbeuter]: http://www.newsbeuter.org/
  31 [3]: http://liferea.sourceforge.net/
  32
  33 ### Screenshot
  34 <img src="moogle.png" alt="Moogle Screenshot"/>
  35
  36 ### Features
  37
  38 Why should you use moogle?
  39
  40  * Google Reader synchronisation
  41  * Curses interface
  42  * Powerful limit expressions
  43  * Offline cache support
  44  * Configurable keybindings
  45  * Built in python command line
  46  * Mutt-like tagging of items
  47
  48 ### Getting Started
  49
  50 Using setting up moogle is simple: there are no configuration options, and only
  51 one required configuration file, `~/.moogle/cred` which should contain your
  52 google reader credentials in the form:
  53
  54         username@google.com,password
  55
  56 Moogle is a work in progress - to get going try `python frontend.py` in the
  57 moogle directory, simple help is available by pressing "?".
  58
  59 ### Commands
  60
  61 The default set of commands is:
  62
  63         <space>:  Select the next unread item.
  64         *:  Toggle 'star' state of the selected item.
  65         ::  Execute python command in the context of this program.  DANGEROUS
  66         ?:  Show help.
  67         J:  Scroll the current item down.
  68         K:  Scroll the current item up.
  69         N:  Select the next message.
  70         O:  Toggle the online state.
  71         P:  Select the previous message.
  72         R:  Mark all tagged items as read.
  73         T:  Toggle the 'tagged' state for all items matching expr.
  74         d:  Print a debug summary of the selected item.
  75         j:  Scroll the current item down.
  76         k:  Scroll the current item up.
  77         l:  Limit the display of items according to an expression.
  78         n:  Select the next message.
  79         o:  Open the currently selected item
  80         p:  Select the previous message.
  81         q:  Quit.
  82         s:  Save the current items for offline reading.
  83         t:  Toggle 'tagged' state of an item.
  84         x:  Force an update.
  85
  86 Most commands are simple, and do exactly what you'd expect.  Keybindings can be
  87 created and modified at run time by using `Config.bind(key, function)`.
  88
  89 ### The Limit Command
  90 Limit accepts a python expression and uses it to [filter][] the feed items
  91 shown.  To only show items from the BBC try `Limit: "BBC" in item.feed` or to
  92 show only items labelled "comics" `Limit: "comics" in item.labels`.  A full
  93 list of item attributes can be seen in the [source][], or in the debug output
  94 (bound to "d" by default).
  95
  96 [filter]: http://docs.python.org/library/functions.html#filter
  97 [source]: http://joe.milbourn.org.uk/git?p=moogle;a=blob_plain;f=moogle.py;hb=HEAD
  98
  99 Any python expression returning a boolean can be used as a limit expression,
 100 but probably you'll want to limit based on some property of the each item.  Common attributes for an item are:
 101
 102  * `item.feed`:  The feed source
 103  * `item.body`:  The body of the item, formatted as markdown
 104  * `item.author`:  The author of the item
 105  * `item.title`:  The item title
 106  * `item.labels`:  A list of this item's labels
 107  * `item.link`:  The link to the full version of this item
 108  * `item.date`:  A [datetime][] object representing the time this item was written
 109  * `item.entry`:  A [feedparser][] object representing this object
 110
 111 [datetime]: http://docs.python.org/library/datetime.html
 112 [feedparser]: http://www.feedparser.org/
 113
 114 ### Config Save/Restore
 115
 116 Moogle now supports the saving and restoring of configuration to and from the
 117 file `~/.moogle/config` in [YaML][].  Moogle will load an existing config file
 118 during initialisation, to create a config file run
 119 `Config.save(filename="~/.moogle/config")`, and to run a new config run
 120 `Config.restore(filename="~/.moogle/config")`.  The default configuration looks
 121  like:
 122
 123         browser: x-www-browser
 124         headers:
 125         - labels
 126         - author
 127         - date
 128         - feed
 129         - title
 130         history_file: /home/joe/.moogle/history
 131         index_length: 5
 132         keybindings:
 133           '*': star
 134           ':': command
 135           <down>: scroll_down
 136           <space>: next_unread_message
 137           <up>: scroll_up
 138           '?': help
 139           J: scroll_down
 140           K: scroll_up
 141           N: next_message
 142           O: online
 143           P: previous_message
 144           R: read_tagged
 145           T: tag_set
 146           d: debug_dump_item
 147           j: scroll_down
 148           k: scroll_up
 149           l: limit
 150           n: next_message
 151           o: open_item
 152           p: previous_message
 153           q: quit
 154           s: save
 155           t: tag
 156           x: update
 157
 158 The keys `<up>`, `<down>`, and `<space>` are mapped to `curses.KEY_UP`,
 159 `curses.KEY_DOWN`, and `curses.KEY_SPACE` respectively.
 160
 161 [YaML]: http://www.yaml.org
 162
 163 ### Download
 164
 165 No packages yet - clone your own from [git](http://joe.milbourn.org.uk/git/projects/moogle).