joe.milbourn.org.uk Git - wikirepo/blob - projects/moogle.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 readers\[[1][], [2][]\] and GUI rss readers which can sync to google reader\[[3][]\]
   8 and [Google Reader][] proper but no console reader which could sync to google
   9 reader: enter moogle.
  10
  11 [scratch an itch]: http://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar
  12 [Mutt]: http://www.mutt.org
  13
  14 [Google Reader]: http://google.com/reader
  15 [1]: http://kiza.kcore.de/software/snownews/
  16 [2]: http://www.newsbeuter.org/
  17 [3]: http://liferea.sourceforge.net/
  18
  19 ### Screenshot
  20 <img src="moogle.png" alt="Moogle Screenshot"/>
  21
  22 ### Features
  23
  24 Why should you use moogle?
  25
  26  * Google Reader synchronisation
  27  * Curses interface
  28  * Powerful limit expressions
  29  * Offline cache support
  30  * Configurable keybindings
  31
  32 ### Using Moogle
  33
  34 Using setting up moogle is simple: there are no configuration options, and only
  35 one configuration file, `~/.moogle/cred` which should contain your google reader credentials
  36 in the form:
  37
  38         username@google.com,password
  39
  40 Moogle is a work in progress - to get going try `python frontend.py` in the
  41 moogle directory, simple help is available by pressing "?".
  42
  43 Most commands are simple, and do exactly what you'd expect, "limit" accepts a
  44 python expression and uses it to [filter][] the feed items shown.  To only show
  45 items from the BBC try `Limit: "BBC" in item.feed` or to show only items
  46 labelled "comics" `Limit: "comics" in item.labels`.  A full list of item
  47 attributes can be seen in the [source][], or in the debug output (bound to
  48 "d").
  49
  50 [filter]: http://docs.python.org/library/functions.html#filter
  51 [source]: http://joesbox.vm.bytemark.co.uk/cgi-bin/viewvc.cgi/moogle/moogle.py?root=src&view=markup
  52
  53 #### Limit Expressions
  54
  55 Moogle supports python expressions to limit the items shown in the index.  The
  56 expression must return a boolean value, for example to show only unread items
  57 `'read' not in item.labels`.  The item properties available are:
  58
  59         item.feed
  60         item.body
  61         item.author
  62         item.title
  63         item.labels
  64         item.link
  65         item.date
  66         item.entry
  67
  68
  69 #### Commands
  70 <table>
  71 <tr><td><pre>Commands.add_label</pre></td>
  72         <td>Prompts for a label to add to the currently selected item.</td></tr>
  73 <tr><td><pre>Commands.command</pre></td>
  74         <td>Run a python expression with access to the internal state.</td></tr>
  75 <tr><td><pre>Commands.edit_labels</pre></td>
  76         <td>Edit the labels for the currently selected item.</td></tr>
  77 <tr><td><pre>Commands.help</pre></td>
  78         <td>Show help.</td></tr>
  79 <tr><td><pre>Commands.limit</pre></td>
  80         <td>Apply a limit expression to the items shown in the index.</td></tr>
  81 <tr><td><pre>Commands.next_message</pre></td>
  82         <td>Select the next message.</td></tr>
  83 <tr><td><pre>Commands.next_unread_message</pre></td>
  84         <td>Select the next unread message.</td></tr>
  85 <tr><td><pre>Commands.online</pre></td>
  86         <td>Toggle the online/offline state.</td></tr>
  87 <tr><td><pre>Commands.open_item</pre></td>
  88         <td>Open the selected item using `x-www-browser`.</td></tr>
  89 <tr><td><pre>Commands.previous_message</pre></td>
  90         <td>Select the previous message.</td></tr>
  91 <tr><td><pre>Commands.quit</pre></td>
  92         <td>Quit.</td></tr>
  93 <tr><td><pre>Commands.save_history</pre></td>
  94         <td>Save the current command histories to a named file.</td></tr>
  95 <tr><td><pre>Commands.scroll_down</pre></td>
  96         <td>Scroll the selected message body.</td></tr>
  97 <tr><td><pre>Commands.scroll_up</pre></td>
  98         <td>Scroll the selected message body.</td></tr>
  99 <tr><td><pre>Commands.star</pre></td>
 100         <td>Toggle the 'starred' status of the selected item.</td></tr>
 101 <tr><td><pre>Commands.toggle_label</pre></td>
 102         <td>Toggle the given item for the selected item.</td></tr>
 103 <tr><td><pre>Commands.update</pre></td>
 104         <td>Synchronise with google reader.</td></tr>
 105 </table>
 106
 107 #### Default Keybindings
 108 <table>
 109 <tr><td>Key</td><td>Action</td></tr>
 110 <tr><td><code>:</code></td><td>Execute python command in the context of this program.</td></tr>
 111 <tr><td><code>j</code></td><td>Scroll the current item down.</td></tr>
 112 <tr><td><code>J</code></td><td>Scroll the current item down.</td></tr>
 113 <tr><td><code>k</code></td><td>Scroll the current item up.</td></tr>
 114 <tr><td><code>K</code></td><td>Scroll the current item up.</td></tr>
 115 <tr><td><code>l</code></td><td>Limit the display of items according to an expression.</td></tr>
 116 <tr><td><code>n</code></td><td>Select the next message.</td></tr>
 117 <tr><td><code>N</code></td><td>Select the next message.</td></tr>
 118 <tr><td><code>o</code></td><td>Open the currently selected item</td></tr>
 119 <tr><td><code>O</code></td><td>Toggle the online state.</td></tr>
 120 <tr><td><code>p</code></td><td>Select the previous message.</td></tr>
 121 <tr><td><code>P</code></td><td>Select the previous message.</td></tr>
 122 <tr><td><code>q</code></td><td>Quit.</td></tr>
 123 <tr><td><code>?</code></td><td>Show help.</td></tr>
 124 <tr><td><code>space</code></td><td>Select the next unread item.</td></tr>
 125 <tr><td><code>T</code></td><td>Edit labels for the selected item.</td></tr>
 126 <tr><td><code>*</code></td><td>Toggle 'star' state of the selected item.</td></tr>
 127 <tr><td><code>x</code></td><td>Force an update.</td></tr>
 128 </table>
 129
 130 #### Config Save/Restore
 131
 132 Moogle now supports the saving and restoring of configuration to and from the
 133 file `~/.moogle/config` in [YaML][].  The default configuration looks like:
 134
 135         browser: x-www-browser
 136         headers:
 137         - labels
 138         - author
 139         - date
 140         - feed
 141         - title
 142         history_file: /home/joe/.moogle/history
 143         index_length: 5
 144         keybindings:
 145           '*': star
 146           ':': command
 147           <down>: scroll_down
 148           <space>: next_unread_message
 149           <up>: scroll_up
 150           '?': help
 151           J: scroll_down
 152           K: scroll_up
 153           N: next_message
 154           O: online
 155           P: previous_message
 156           R: read_tagged
 157           T: tag_set
 158           d: debug_dump_item
 159           j: scroll_down
 160           k: scroll_up
 161           l: limit
 162           n: next_message
 163           o: open_item
 164           p: previous_message
 165           q: quit
 166           s: save
 167           t: tag
 168           x: update
 169
 170 The keys `<up>`, `<down>`, and `<space>` are mapped to `curses.KEY_UP`,
 171 `curses.KEY_DOWN`, and `curses.KEY_SPACE` respectively.
 172
 173 [YaML]: http://www.yaml.org
 174
 175 ### Download
 176
 177 No packages yet - clone your own from [git](http://joe.milbourn.org.uk/git/projects/moogle).