moved moogle
[wikirepo] / 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 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).