poddb_client 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.markdown CHANGED
@@ -1,15 +1,11 @@
1
1
  # poddb
2
2
 
3
- Poddb lets you find, track, and download podcasts from the Unix command line and Vim.
4
-
5
- [screenshots]
3
+ _Podcatching for nerds, Zen minimalists, and unix fanatics_.
6
4
 
5
+ Poddb lets you browse, search, and download podcasts from the Unix command line
6
+ and Vim.
7
7
 
8
- ## Benefits
9
-
10
- * Search for podcasts from the command line
11
- * Lean Vim interface to navigate, favorite, and download podcasts
12
- * Handle podcasts directly as files; use any tool to play them
8
+ [screenshots]
13
9
 
14
10
 
15
11
  ## Prerequisites
@@ -29,6 +25,9 @@ Poddb assumes a Unix (POSIX) environment.
29
25
 
30
26
  ## Install
31
27
 
28
+ Poddb can be installed as a Ruby gem. Please note that while the tool is called
29
+ **poddb**, the gem is called **poddb_client**.
30
+
32
31
  gem install poddb_client
33
32
 
34
33
  Test your installation by typing `poddb -h`. You should see poddb's help.
@@ -36,87 +35,192 @@ Test your installation by typing `poddb -h`. You should see poddb's help.
36
35
  On some systems you may run into a PATH issue, where the system can't find the
37
36
  `poddb` command after installation. You might want to try
38
37
 
39
- sudo gem install poddb
38
+ sudo gem install poddb_client
40
39
 
41
40
  to see if that puts `poddb` on your PATH.
42
41
 
43
42
  If you ever want to uninstall Poddb from your system, just execute this command:
44
43
 
45
- gem uninstall poddb
44
+ gem uninstall poddb_client
46
45
 
47
- and all traces of Poddb will removed, except the application-specific files it
48
- creates during execution. These files are created in a directory called `~/.poddb`.
46
+ This will remove all traces of Poddb, except for the application-specific files
47
+ it creates in a directory called `~/.poddb`. These you'll have to remove
48
+ manually.
49
49
 
50
50
 
51
51
  ## How to use it
52
52
 
53
- Invoke `poddb` from command line interface, passing it flags and search terms.
54
- After you press `ENTER`, Poddb will send the query over the internet to the poddb
55
- server. The server will send back data, and poddb will launch Vim to let you
56
- navigate and interact with the results.
53
+ You invoke `poddb` from command line interface, passing it flags and search
54
+ terms. Poddb will send the query over the internet to the poddb server. (So you
55
+ must be online to use Poddb, though once you've downloaded some podcast audio
56
+ or video files you can play them entirely offline.) The server will send back
57
+ data, and poddb will launch Vim to let you navigate and interact with the query
58
+ results.
57
59
 
58
- The command line interface is as follows:
60
+ Here is a partial synopsis of the command line interface. A more detailed guide
61
+ to using Poddb follows.
59
62
 
60
63
  Usage: poddb [options] [query]
61
64
 
62
- -f, --from-favorites Show all recent items from favorite podcasts
65
+ -f, --from-favorites Show all recent episodes from favorite podcasts
63
66
  -a, --add PODCAST_URL Add podcast with PODCAST_URL to the poddb database
64
67
  -l, --list [QUERY] List all podcasts in the poddb database
65
68
  (If QUERY is supplied, will return matching podcasts)
66
69
  -F, --favorite-podcasts Show favorite podcasts
67
70
  -o, --order ORDER Sort results by ORDER
68
71
  The only option right now is 'popular'. Default order is pubdate.
69
- -d, --days DAYS Limit results to items published since DAYS days ago
70
- -t, --type MEDIA_TYPE Return items of MEDIA_TYPE only (audio,video)
71
- --download-and-play ITEM_ID Download item and play with PODDB_MEDIA_PLAYER
72
- --key-mappings Show key mappings for Vim navigation interface
73
- -h, --help Show this message
74
- -v, --version Show version number
72
+ -d, --days DAYS Limit results to episodes published since DAYS days ago
73
+ -t, --type MEDIA_TYPE Return episodes of MEDIA_TYPE only (audio,video)
74
+
75
+ ## Browse and search for podcasts
76
+
77
+ To see all the podcasts in the poddb database:
75
78
 
79
+ poddb -l
80
+
81
+ Type `poddb -l QUERY` to see if any podcasts matching the QUERY string are in
82
+ the database. E.g.
76
83
 
77
- ## Podcast list
84
+ poddb -l music
78
85
 
79
- To see all the podcasts in the poddb database, type `poddb -l`. Type `poddb -l
80
- QUERY` to see if any podcasts matching the QUERY string are in the database. If
81
- you don't see a favorite feed of yours in the list, you can add the feed to the
82
- Poddb database with this command:
86
+ will return all the podcasts in the Poddb database with the word "music" in the
87
+ title or podcast description.
88
+
89
+ Press `ENTER` on a podcast to see its episodes. See **Navigate and download
90
+ podcast episodes** below for instruction on how to view and download episodes.
91
+
92
+
93
+ ## Add podcasts to the database
94
+
95
+ If you don't see a favorite feed of yours in the list returned by `poddb -l`,
96
+ you can add the feed to the Poddb database with this command:
83
97
 
84
98
  poddb -a PODCAST_URL
85
99
 
86
- This command will also add the podcast to your favorites.
100
+ E.g.,
101
+
102
+ poddb -a http://www.philosophybites.libsyn.com/rss
103
+
104
+ The `-a` command will also add the podcast to your favorites.
105
+
106
+
107
+ ## Favorite podcasts
108
+
109
+ When viewing a list of podcasts returned by `poddb -l`, you can add a podcast
110
+ to your favorites by putting the cursor over it and pressing `f`. Press `f`
111
+ again to remove the podcast from your favorite podcasts. Favorite podcasts
112
+ have a `@` sign in the left margin.
113
+
114
+ Once you have a few favorite podcasts, you can list and navigate them with
115
+ the command
116
+
117
+ poddb -F
118
+
119
+ You can also aggregate all the most recent episodes from your favorite episodes by
120
+ launching Poddb with the command
121
+
122
+ poddb -f
123
+
124
+ Your favorite podcasts are stored in `~/.poddb/favorites` as a simple list of
125
+ podcast ids. The ids are internal to Poddb's PostgreSQL database.
126
+
127
+ ## Search for podcast episodes
128
+
129
+ With Poddb, you search for podcast episodes from the command line. If there are
130
+ matches, Poddb will launch the Vim navigation interface. If not, you'll just
131
+ see a message saying no matches were found.
132
+
133
+ A basic search like
134
+
135
+ poddb music oud
136
+
137
+ will return all podcast episodes that match the query words "music" and "oud."
87
138
 
88
- When you're viewing a list of podcasts, you can add a podcast to your favorites
89
- by putting the cursor over it and pressing `f`. Press `f` again to remove the
90
- podcast from your favorite podcasts. Your favorite podcasts are stored in
91
- `~/.poddb/favorites` as a simple list of podcast ids.
139
+ You can also limit the scope of the search by media type:
92
140
 
93
- Press `ENTER` on a podcast to see its items.
141
+ poddb -t video ruby
94
142
 
143
+ will return all podcast episodes that match the words "food" and "recipe" that
144
+ are video downloads. You can use `-t audio` to limit search results to audio
145
+ downloads.
95
146
 
96
- ## Item list
147
+ Two other command flags that are useful are `-o` and `-d`. `-d n` lets you
148
+ limit the scope of the search to episodes published in the last _n_ days. So
97
149
 
98
- If you see a list of items (i.e. downloadable podcast episodes), the following
99
- key commands apply:
150
+ poddb -d 7 libya
100
151
 
101
- * `l` or `ENTER` show item detail
102
- * `d` mark item for download
103
- * `D` start downloading item and play with mplayer or `PODDB_MEDIA_PLAYER`
104
- * `p` show all items for this podcast
105
- * `CTRL-j` show next item
106
- * `CTRL-k` show previous item
152
+ will return all podcast episodes that match the query "libya" published over
153
+ the last week.
107
154
 
108
- If you mark items for downloading, Poddb will download them as soon as you quit
109
- the Vim interface with `:qa` or some similar command.
155
+ To sort the search results by most popular episodes first, use the `-o popular`
156
+ flag. So
157
+
158
+ poddb -d 30 -o popular tiny desk concert
159
+
160
+ will show the most popular Tiny Desk Concert episodes in the last month
161
+
162
+ Invoking Poddb with no query words will show you all the most recent
163
+ episodes from all the podcasts in the Poddb database. So to see the most
164
+ popular downloads in the last week, you can use
165
+
166
+ poddb -d 7 -o popular
167
+
168
+
169
+
170
+ ## Navigate and download podcast episodes
171
+
172
+ When you see a list of episodes, you can use the following key commands, in
173
+ addition to Vim's standard cursor commands:
174
+
175
+ * `l` or `ENTER` show episode detail
176
+ * `d` mark episode for download
177
+ * `D` start downloading episode immediately and play with `mplayer` or `PODDB_MEDIA_PLAYER`
178
+ * `p` show all episodes for this podcast
179
+ * `CTRL-j` show next episode
180
+ * `CTRL-k` show previous episode
181
+
182
+ If you press `p` to show all the episodes for the podcast, you can navigate back to the
183
+ previous screen with `CTRL-o` and return forward again with `CTRL-i`. In other words,
184
+ feel free to use Vim's jump-list navigation commands.
185
+
186
+ When you press `l` or `ENTER`, more information about the episode will appear in a split
187
+ window below the list.
188
+
189
+ If you mark episodes for downloading, Poddb will place a `*` in their left
190
+ margin and download them as soon as you quit the Vim interface with `:qa` or
191
+ some similar command.
192
+
193
+ Poddb uses `wget` to download episodes. The current version downloads all
194
+ marked episodes serially. A future version may implement parallel downloading.
195
+
196
+ Poddb downloads episodes into the current directory and saves them with
197
+ filenames that follow the format,
198
+
199
+ {title of podcast}.{title of episode}.{poddb internal identifier}.{filetype extension}
200
+
201
+ Examples:
202
+
203
+ The-Loh-Life.Wisconsin-Wasp-Nest-part-2.poddb42329.mp3
204
+ Philosophy-Bites.Michael-Sandel-on-Justice.poddb_711_56523.mp3
205
+ NPR-Tiny-Desk-Concerts-Podcast.Diego-Garcia.poddb_312_48461.m4v
110
206
 
111
207
  If you press `D`, Poddb will quit the Vim interface immediately and begin
112
- downloading the item that was under the cursor. After the download is complete,
113
- Poddb will start playing the item with `mplayer` or whatever command you
114
- specify using the `PODDB_MEDIA_PLAYER` environment variable.
208
+ downloading the episode that was under the cursor. After the download is complete,
209
+ Poddb will automatically start playing the episode with `mplayer`.
210
+
211
+ If you don't want to use `mplayer` or don't have it installed. You can make
212
+ Poddb launch a different media player by setting the `PODDB_MEDIA_PLAYER`
213
+ environment variable and exporting it. For example, to make Poddb use `totem`:
214
+
215
+ export PODDB_MEDIA_PLAYER=totem
216
+ poddb
115
217
 
116
- If you see a `D` on the left margin of an item in the item list, that means
117
- that you already downloaded that podcast item into the current directory.
218
+ Put the `export` command in your `.bash_profile` if you don't want to keep
219
+ typing it.
118
220
 
119
- Poddb uses `wget` to download items.
221
+ If you see a `D` on the left margin of an episode while you're looking at a
222
+ list of episodes, that means that you've already downloaded that episode into
223
+ the current directory.
120
224
 
121
225
 
122
226
  ## Bug reports and feature requests
@@ -126,6 +230,20 @@ Please submit them here:
126
230
  * <https://github.com/danchoi/poddb_client/issues>
127
231
 
128
232
 
233
+ ## About the app
234
+
235
+ Poddb has two parts, a client and a server. The client is a hybrid
236
+ Ruby/VimScript program packaged as a Ruby gem. The server is a Ruby
237
+ [Sinatra][sinatra] app sitting in front of a [PostgreSQL][postgres] database.
238
+ Podcast feeds are fetched with [curb][curb] and parsed with
239
+ [nokogiri][nokogiri].
240
+
241
+ [sinatra]:http://www.sinatrarb.com/
242
+ [postgres]:http://www.google.com/search?aq=f&sourceid=chrome&ie=UTF-8&q=postgresql
243
+ [curb]:http://curb.rubyforge.org/
244
+ [nokogiri]:http://nokogiri.org/
245
+
246
+
129
247
  ## About the developer
130
248
 
131
249
  My name is Daniel Choi. I make software with Ruby, Rails, MySQL, PostgreSQL,
@@ -141,5 +259,3 @@ Software](http://kajasoftware.com).
141
259
  [twitter]:http://twitter.com/#!/danchoi
142
260
 
143
261
 
144
-
145
-
data/Rakefile CHANGED
@@ -39,8 +39,9 @@ desc "build webpage"
39
39
  task :build_webpage do
40
40
  `cp README.markdown ../project-webpages/src/poddb_client.README.markdown`
41
41
  `cp coverage.markdown ../project-webpages/src/poddb_client.coverage.markdown`
42
+ `cp links.markdown ../project-webpages/src/poddb_client.links.markdown`
42
43
  Dir.chdir "../project-webpages" do
43
- puts `ruby gen.rb poddb_client #{ViTunes::VERSION}`
44
+ puts `ruby gen.rb poddb_client #{PoddbClient::VERSION}`
44
45
  `open out/poddb_client.html`
45
46
  end
46
47
  end
data/coverage.markdown ADDED
File without changes
data/lib/interactive.vim CHANGED
@@ -221,7 +221,7 @@ endfunction
221
221
 
222
222
  function! s:help()
223
223
  " This just displays the README
224
- let res = system(s:client_cmd." --key-mappings")
224
+ let res = system(s:client_cmd." --readme")
225
225
  echo res
226
226
  endfunction
227
227
 
data/lib/poddb_client.rb CHANGED
@@ -6,7 +6,13 @@ require 'net/http'
6
6
 
7
7
  class PoddbClient
8
8
 
9
- # TODO: set for production
9
+ # checks
10
+ %w( curl wget ).each do |x|
11
+ if `which #{x}` == ''
12
+ abort("Missing `#{x}`. Please install it before you start poddb.")
13
+ end
14
+ end
15
+
10
16
  SERVER = ENV['PODDB_SERVER'] || "http://poddb.com"
11
17
 
12
18
  PODDB_DIR = "%s/.poddb" % ENV['HOME']
@@ -70,12 +76,15 @@ class PoddbClient
70
76
  opts.on("--download-and-play ITEM_ID", "Download item and play with PODDB_MEDIA_PLAYER") do |item_id|
71
77
  puts "Download and play #{item_id}"
72
78
  end
73
- opts.on("--key-mappings", "Show key mappings for Vim navigation interface") do
74
- puts "KEYMAPPINGS"
79
+ opts.on("--readme", "Show README") do
80
+ readme_file = File.expand_path("../../README.markdown", __FILE__)
81
+ system("less #{readme_file}")
75
82
  exit
76
83
  end
77
84
  opts.on_tail("-h", "--help", "Show this message") do
78
85
  puts opts
86
+ puts
87
+ puts "For more detailed help, use `poddb --readme` or visit http://danielchoi.com/software/poddb.html"
79
88
  exit
80
89
  end
81
90
  opts.on_tail("-v", "--version", "Show version number") do
@@ -6,7 +6,7 @@ class PoddbClient
6
6
 
7
7
 
8
8
  def titleize(s, maxlength=20)
9
- s.gsub(/\W+/, '-')[0,maxlength].sub(/-$/, '')
9
+ s.gsub(/\W+/, '-')[0,maxlength].sub(/-$/, '').sub(/^-/, '')
10
10
  end
11
11
 
12
12
  def download(item_id)
@@ -1,3 +1,3 @@
1
1
  class PoddbClient
2
- VERSION = '0.1.4'
2
+ VERSION = '0.1.5'
3
3
  end
data/links.markdown ADDED
@@ -0,0 +1,4 @@
1
+ * [github repo](https://github.com/danchoi/poddb_client)
2
+ * [rubygems page](https://rubygems.org/gems/poddb_client)
3
+ * [commit history](https://github.com/danchoi/poddb_client/commits/master)
4
+ * [issue tracker](https://github.com/danchoi/poddb_client/issues)
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: poddb_client
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.1.5
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2011-09-15 00:00:00.000000000Z
12
+ date: 2011-09-16 00:00:00.000000000Z
13
13
  dependencies: []
14
14
  description: Podcast aggregation from the command line
15
15
  email:
@@ -24,10 +24,12 @@ files:
24
24
  - README.markdown
25
25
  - Rakefile
26
26
  - bin/poddb
27
+ - coverage.markdown
27
28
  - lib/interactive.vim
28
29
  - lib/poddb_client.rb
29
30
  - lib/poddb_client/downloading.rb
30
31
  - lib/poddb_client/version.rb
32
+ - links.markdown
31
33
  - poddb_client.gemspec
32
34
  homepage: http://danielchoi.com/software/poddb.html
33
35
  licenses: []