dropcaster 0.0.1 → 0.0.2

data/Gemfile

@@ -7,4 +7,5 @@ group :development do
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.6.4"
   gem 'libxml-ruby'
+  gem 'rdoc'
 end

data/Gemfile.lock

@@ -8,15 +8,19 @@ GEM
       git (>= 1.2.5)
       rake
     libxml-ruby (2.2.1)
+    libxml-ruby (2.2.1-x86-mingw32)
     rake (0.9.2)
+    rdoc (3.9.3)
     ruby-mp3info (0.6.15)
 
 PLATFORMS
   ruby
+  x86-mingw32
 
 DEPENDENCIES
   activesupport
   bundler (~> 1.0.0)
   jeweler (~> 1.6.4)
   libxml-ruby
+  rdoc
   ruby-mp3info

data/README.md

@@ -1,36 +1,60 @@
 Dropcaster - Simple Podcast Publishing with Dropbox
 ===================================================
-
-Dropcaster is a podcast feed generator for the command line. It is most simple to use with Dropbox, but works equally well with any other hoster.
+[Dropcaster](http://nerab.github.com/dropcaster) is a podcast feed generator for the command line. It is most simple to use with Dropbox, but works equally well with any other hoster.
 
 Author: Nicolas E. Rabenau <nerab@gmx.at>
 
 What is the problem Dropcaster is trying to solve?
 ==================================================
-
 You have a number of podcast episodes that you would like to publish as a feed. Nothing else - no fancy website, no stats, nothing but the pure podcast.
 
-With Dropcaster, you simply put the mp3 files into the Public folder of your [Dropbox](http://www.dropbox.com/). Then run the Dropcaster script that generates the feed, writing it to a file in your Dropbox, e.g. index.rss. All mp3 files in the Public folder of your Dropbox are already accessible via HTTP, and so will the RSS file. You can then take the RSS file's URL and publish it (again, this is because any file in the Public folder of my Dropbox automatically gets a public, HTTP-accessible URL).
+With Dropcaster, you simply put the mp3 files into the Public folder of your [Dropbox](http://www.dropbox.com/). Then run the Dropcaster script that generates the feed, writing it to a file in your Dropbox, e.g. index.rss. All mp3 files in the Public folder of your Dropbox are already accessible via HTTP, and so will the RSS file. You can then take the RSS file's URL and publish it (again, this is because any file in the Public folder of a Dropbox automatically gets a public, HTTP-accessible URL).
 
-The feed URL can be consumed my any podcatcher, e.g. [iTunes](http://www.apple.com/itunes/) or [Juice](http://juicereceiver.sourceforge.net/).
+The feed URL can be consumed by any podcatcher, e.g. [iTunes](http://www.apple.com/itunes/) or [Juice](http://juicereceiver.sourceforge.net/).
 
-Meta Data
-=========
+Installation
+============
+To get started, use RubyGems to install Dropcaster:
+
+    $ gem install dropcaster
+
+With Dropcaster installed, you can use the `dropcaster` command to generate a new podcast feed document.
+
+Basic Usage
+===========
+Once Dropcaster is installed, the only two other things you will need are a channel definition and one or more mp3 files to publish.
+
+Let's start with the channel definition. It is a simple [YAML](http://yaml.org/) file that holds the general information about your podcast channel. According to the [RSS 2.0 spec](http://feedvalidator.org/docs/rss2.html#requiredChannelElements), the only mandatory information that your channel absolutely needs are a title, a description and a link to a web site where the channel belongs to.
+
+The simplest channel file looks like this:
+
+		:title: 'All About Everything'
+		:subtitle: 'A show about everything'
+		:url: 'http://www.example.com/podcasts/everything/index.html'
 
-The meta data for your channel is provided in a YAML file. It is expected to be present in the current working directory as channel.yml. This can be overridden using a command line switch.
+Store this file as channel.yml in the same directory where the mp3 files of your podcast reside. The channel definition is expected to be present in the same directory as your mp3 files, but this can be overridden using a command line switch. You can find a [more elaborate example](http://github.com/nerab/dropcaster/blob/master/doc/sample-channel.yml) for the channel definition in the doc folder of the Dropcaster gem. You can find it by running `gem open dropcaster`. Instead of writing these title, subtitle, etc. to the channel.yml, you may also spedify them on the command line. For details, just run
 
-For the podcast episodes, the mp3 files are the authoritative meta data source. Dropcaster reads the metadata from the mp3 files and fills the RSS feed from it. 
+    $ dropcaster --help
 
-You may override the meta data for any episode by providing a YAML file with the same name as the mp3 file, but with an extension of yml or yaml (ususally refered to as <a href="http://en.wikipedia.org/wiki/Sidecar_file">sidecar file</a>). Any attributes specified in this file override the ID tags in the mp3 file.
+Now that we have the podcast channel defined, we need at least one episode (an audio file) in it. From Dropcaster's perspective, it does not matter how the episode was produced, but the critical information is the meta data in the mp3 file, because that is the authoritative source for the episode information. Almost all audio editors can write metadata, usually called ID3 tags. Dropcaster reads these tags from the mp3 files and fills the item element in the feed (that's how an episode is defined, technically) from it.
 
-Please note that Dropcaster will only write the sidecar file if the appropriate option was passed, and it will use the information in it only for generating new files like the index.rss. It will not write back to mp3 files.
+With all required pieces in place, we could generate the podcast feed. Just before we do that, we will inspect the feed by running the following commands:
+
+    $ cd ~/Dropbox/Public
+    $ dropcaster
+
+(The above lines assume that you are using Dropbox, and that there is at least one mp3 file in ~/Dropbox/Public).
+
+Dropcaster will print the feed to standard-out, without writing it to disk. When you are happy with the results, call Dropcaster again, but redirect the output to a file, this time:
+
+    $ dropcaster > index.rss
+
+If all went well, you will now have a valid podcast feed in your Dropbox, listing all mp3 files as podcast episodes. Please see the section [Publish Your Feed] for details on how to find the public URL of your feed.
 
 Use Cases
 =========
-
 Publish a New Episode
 ---------------------
-
 1. Drop the mp3 file into the Dropbox Public folder (e.g. ~/Dropbox/Public), and then run the following command in the directory where the mp3 files reside:
 
         $ dropcaster > index.rss
@@ -39,28 +63,33 @@ Publish a New Episode
 
 Delete an Episode
 -----------------
-
 Remove the mp3 you want to delete from the Dropbox Public folder, and then run the following command in the directory where the remaining mp3 files reside:
 
 	  $ dropcaster > index.rss
 
 Replace an Episode With an Updated File
 ---------------------------------------
-
 In the Dropbox Public folder, replace the mp3 you want to update with a new version, and then run the following command in the directory where the mp3 files reside:
 
 	  $ dropcaster > index.rss
 
 Publish Your Feed
 -----------------
-
 1. Re-generate the feed to make sure the it is up to date (see above):
 
         $ dropcaster > index.rss
-	
+
 1. In your Dropbox Public folder, right-click the index.rss and select "Dropbox / Copy public link". This copies the public, HTTP-addressable link to your podcast into the clipboard.
 1. Publish this link and tell people to subscribe to it.
 
+Generate a Podcast Feed for a Subset of the Available MP3 Files
+---------------------------------------------------------------
+Dropcaster accepts any number of files or directories as episodes. For directories, all files ending in .mp3 will be included. For advanced filtering, you can use regular shell patterns to further specify which files will be included. These patterns will be resolved by the shell itself (e.g. bash), and not by Dropcaster.
+
+For example, in order to generate a feed that only publishes MP3 files where the name starts with 'A', call Dropcaster like this:
+
+    $ dropcaster A*.mp3 > index.rss
+
 Publish More than One Feed
 --------------------------
 
@@ -79,26 +108,32 @@ Include Episodes From Two Subdirectories Into a Single Feed
 
 	  $ dropcaster project1 project2 > index.rss
 
-Episode Identifier (uuid)
-=========================
-
-Dropcaster uses a rather simple approach to uniquely identify the episodes. It simply generates a SHA1 hash of the mp3 file. If it changes, for whatever reason (even if only a tag was changes), the episode will get a new UUID, and any podcatcher will fetch the episode again (which is what you want, in most cases).
+Advanced features
+=================
+Sidecar files
+-------------
+You may override the meta data for any episode by providing a YAML file with the same name as the mp3 file, but with an extension of yml or yaml (ususally refered to as [sidecar file](http://en.wikipedia.org/wiki/Sidecar_file)). Any attributes specified in this file override the ID tags in the mp3 file.
 
-Modifying the sidecar file does not change the UUID, because it only affects the feed and not the episode itself.
+Dropcaster will only write the sidecar file if the appropriate command line option was passed, and it will use the information in it only for generating new files like the index.rss. It will not write back to mp3 files.
 
 A Note on iTunes
-================
-
+----------------
 The generated XML file contains all elements required for iTunes. However, Dropcaster will not notify the iTunes store about new episodes.
 
 Using Dropcaster Without Dropbox
-================================
-
+--------------------------------
 The whole concept of Dropcaster works perfectly fine without Dropbox. Just run the Dropcaster script in a directory of mp3 files and upload the files as well as the generated index.rss to a web server. Leave the relative position of the index and mp3 files as is, otherwise the path to the mp3 files in index.rss will become invalid.
 
+Episode Identifier (uuid)
+-------------------------
+Dropcaster uses a rather simple approach to uniquely identify the episodes. It simply generates a SHA1 hash of the mp3 file. If it changes, for whatever reason (even if only a tag was changes), the episode will get a new UUID, and any podcatcher will fetch the episode again (which is what you want, in most cases).
+
+Modifying the sidecar file does not change the UUID, because it only affects the feed and not the episode itself.
+
 Contributing to Dropcaster
 ==========================
- 
+Dropcaster is hosted at [Github](http://github.com/nerab/dropcaster):
+
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
 * Fork the project
@@ -109,5 +144,4 @@ Contributing to Dropcaster
 
 Copyright
 =========
-
 Copyright (c) 2011 Nicolas E. Rabenau. See LICENSE.txt for further details.

data/Rakefile

@@ -36,8 +36,8 @@ end
 
 task :default => :test
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'

data/TODO

@@ -1,3 +1,5 @@
+* Take the the channel's URL as enclosure_url and make enclosure_url an optional parameter
+* In verbose mode, log warnings to STDERR for all the opinionated decisions and fallbacks that Dropcaster takes
 * Allow overriding the path to the ERB template (and document the available template variables)
 * Support a tree of iTunes categories: <itunes:category text="Technology"><itunes:category text="Gadgets"/></itunes:category>
 * If an index.html.erb is present, generate an index.html from it
@@ -5,7 +7,7 @@
 * Print warnings when one of the specs from http://www.apple.com/itunes/podcasts/specs.html is violated
 * Allow muting of the iTunes warnings (see above) using a commandline switch
 * Implement sidecar files
-* Support other file types than mp3
+* Support other file types than mp3 (e.g. ogg or pdf)
 * Treat lyrics as plain text for the episode page, and with an optional command line switch we could also support markdown etc.
 * Potential optimization for large numbers of mp3 files: If there is an existing index.rss file, do not re-read the information from those files that are still there and still have the same hash value.
 * It feels pretty awkward to refer to the ID3v2 frame names all the time. After all, this is an implementation detail. Maybe we can wrap the frames with a nicer name, but still allow access to the underlying mp3info library? Maybe all we need is some aliasing and / or delegation?

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/bin/dropcaster

@@ -8,20 +8,17 @@ require 'yaml'
 help = <<HELP
 Dropcaster is a podcast feed generator for the command line.
 
+Author: Nicolas E. Rabenau nerab@gmx.at
+Homepage: http://nerab.github.com/dropcaster/
+
 Basic Usage:
-  dropcaster                   Prints a podcast feed document for the mp3 files
-                               in the current directory. The channel definition
-                               is read from the current directory.
-                               
-  dropcaster [<file>...]       Prints a podcast feed documentfor the files
-                               specified as argument. The channel definition
-                               is read from the current directory.
-
-  dropcaster [<dir>...]        Prints a podcast feed document for the files in
-                               the directory specified as argument. The channel
-                               definition is read from the current directory.
-
-Options:                               
+
+  dropcaster            Prints a podcast feed document for the mp3 files in the current directory.
+  dropcaster [FILE]...  Prints a podcast feed document for FILES
+  dropcaster [DIR]...   Prints a podcast feed document for the mp3 files in DIR
+
+Options:
+
 HELP
 
 def usage
@@ -31,18 +28,51 @@ end
 require 'optparse'
 require 'dropcaster'
 
-channel_file = 'channel.yml'
+options = Hash.new
+options[:verbose] = false
+options[:auto_detect_channel_file] = true
 
-options = {}
 opts = OptionParser.new do |opts|
   opts.banner = help
 
-  opts.on("--channel FILE", "Read the channel information from FILE") do |file|
-    channel_file = file
+  opts.on("--verbose", "Verbose mode - displays additional diagnostic information") do |file|
+    options[:verbose] = true
+  end
+
+  opts.on("--channel FILE", "Read the channel definition from FILE instead of channel.yml in the current directory.") do |file|
+    begin
+      STDERR.puts "Reading channel definition from #{file}" if options[:verbose]
+      options = YAML.load_file(file).merge(options)
+      options[:auto_detect_channel_file] = false
+    rescue
+      STDERR.puts "Error loading channel definition: #{$!.message}"
+      STDERR.puts $!.backtrace if options[:verbose]
+      exit(1)
+    end
+  end
+
+  opts.on("--title STRING", "Use STRING as the channel's title. Overrides settings read from channel definition file.") do |title|
+    STDERR.puts "Setting channel title to '#{title}' via command line" if options[:verbose]
+    options[:title] = title
+  end
+
+  opts.on("--url URL", "Use URL as the channel's url. Overrides settings read from channel definition file.") do |url|
+    STDERR.puts "Setting channel URL to '#{url}' via command line" if options[:verbose]
+    options[:url] = url
   end
 
-  opts.on("--channel-template FILE", "Use FILE as template for the channel") do |file|
-    options[:channel_template] = file
+  opts.on("--description STRING", "Use STRING as the channel's description. Overrides settings read from channel definition file.") do |description|
+    STDERR.puts "Setting channel description to '#{description}' via command line" if options[:verbose]
+    options[:description] = description
+  end
+
+  opts.on("--enclosure_base URL", "Use URL as base URL for the channel's enclosures. Overrides settings read from channel definition file.") do |enclosure_base|
+    STDERR.puts "Setting enclosure base to '#{enclosure_base}' via command line" if options[:verbose]
+    options[:enclosure_base] = enclosure_base
+  end
+
+  opts.on("--channel-template FILE", "Use FILE as template for generating the channel feed. Overrides the default that comes with Dropcaster.") do |file|
+    options[:template] = file
   end
 
   opts.on("--version", "Display current version") do
@@ -52,25 +82,30 @@ opts = OptionParser.new do |opts|
 end
 
 opts.parse!
-
-begin
-  options.merge! YAML.load_file(channel_file)
-rescue
-  STDERR.puts "Error: Could not find channel definition."
-  puts usage
-  exit 1
+sources = ARGV.blank? ? '.' : ARGV
+
+if options[:auto_detect_channel_file]
+  # There was no channel file specified, so we try to load channel.yml from sources dir
+  channel_file = Dropcaster::ChannelFileLocator.locate(sources)
+
+  if File.exists?(channel_file)
+    STDERR.puts "Auto-detected channel file at #{channel_file}" if options[:verbose]
+    options_from_yaml = YAML.load_file(channel_file)
+    options = options_from_yaml.merge(options)
+  else
+    STDERR.puts "No #{channel_file} found."
+    STDERR.puts usage
+    exit(1) # No way to continue without a channel definition
+  end
 end
 
-if ARGV.empty?
-  src_dir = '.'
-else
-  src_dir = ARGV
-end
+STDERR.puts "Generating the channel with these options: #{options.inspect}" if options[:verbose]
 
 begin
-  puts Dropcaster::Channel.new(src_dir, options).to_rss
+  puts Dropcaster::Channel.new(sources, options).to_rss
 rescue
-  puts "Error: #{$!.message}"
-  puts usage
+  STDERR.puts "Error generating the channel feed: #{$!.message}"
+  STDERR.puts usage
+  STDERR.puts $!.backtrace if options[:verbose]
   exit(1)
 end

data/doc/sample-channel.yml

@@ -0,0 +1,77 @@
+#
+# A sample RSS channel definition
+#
+# This file is read by Dropcaster
+# http://github.com/nerab/dropcaster
+#
+# It defines the properties of your podcast channel.
+#
+
+#
+# Title (name) of the podcast
+#
+:title: 'All About Everything'
+
+#
+# Short description of the podcast (a few words)
+#
+:subtitle: 'A show about everything'
+
+#
+# URL to the podcast. 
+#
+:url: 'http://www.example.com/podcasts/everything/index.html'
+
+#
+# Base URL for enclosure links
+#
+:enclosure_base: 'http://www.example.com/podcasts/everything'
+
+#
+# Language of the podcast - ISO 639-1 Alpha-2 list (two-letter language codes, some with possible modifiers, such as "en-us").
+#
+:language: 'en-us'
+
+#
+# Not visible in iTunes, but useful as a statement in the feed
+#
+:copyright: '© 2011 John Doe & Family'
+
+#
+# Author / creator of the podcast. In iTunes, it is displayed in the artist column.
+#
+:author: 'John Doe'
+
+#
+# Longer description of the podcast
+#
+:description: 'All About Everything is a show about everything. Each week we dive into any subject known to man and talk about it as much as we can. Look for our Podcast in the iTunes Store!'
+
+#
+# Contact information of the owner of the podcast. Not be publicly displayed in iTunes.
+#
+:owner:
+  :name: 'John Doe'
+  :email: 'john.doe@example.com'
+
+#
+# iTunes prefers square .jpg images that are at least 600 x 600 pixels
+#
+:image_url: 'http://example.com/podcasts/everything/AllAboutEverything.jpg'
+
+#
+# Category / categories of the podcast
+#
+# For iTunes, see http://www.apple.com/itunes/podcasts/specs.html#categories for applicable values
+#
+# Examples:
+#   :categories: 'Technology'
+#   :categories: ['Technology', 'Gadgets']
+#   :categories: ['TV & Film', ['Technology', 'Gadgets']]
+
+:categories: ['Technology', 'Gadgets']
+
+#
+# Yes, No or Clean, see http://www.apple.com/itunes/podcasts/specs.html#explicit
+#
+:explicit: 'No'

data/doc/sample-sidecar.yml

@@ -0,0 +1,19 @@
+#
+# Sample sidecar file
+#
+# If this file is present side-by-side with an mp3 file, and if it has the same name as the mp3 (but with
+# an extension of yml or yaml), then any setting made in this file will be used instead of the value from the mp3.
+#
+:title: 'Title of the episode'
+:author: 'Author of the episode'
+:subtitle: 'Subtitle of the episode'
+:description: 'Desciption and summary of the episode'
+:image_url: 'URL to an image specific for this episode'
+:enclosure:
+  :url: 'URL where this episode can be downloaded'
+  :length: 42 # length of the episode in milliseconds
+  :type: 'usually audio/mp3'
+:guid: 'Globally unique id of the episode'
+:pubDate: 'Date as per RFC 2822; e.g. Wed, 15 Jun 2005 19:00:00 GMT'
+:duration: 'Either HH:MM:SS, H:MM:SS, MM:SS, M:SS, or SS'
+:keywords: ['ruby', 'rails', 'podcast'] # up to 12 text keywords

data/dropcaster.gemspec

@@ -0,0 +1,87 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dropcaster}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{nerab}]
+  s.date = %q{2011-10-05}
+  s.description = %q{Dropcaster is a podcast feed generator for the command line. It is most simple to use with Dropbox, but works equally well with any other hoster.}
+  s.email = %q{nerab@gmx.at}
+  s.executables = [%q{lstags}, %q{dropcaster}, %q{dropcaster}, %q{lstags}]
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md",
+    "TODO"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "TODO",
+    "VERSION",
+    "bin/dropcaster",
+    "bin/lstags",
+    "doc/infoPane.png",
+    "doc/lyricsPane.png",
+    "doc/sample-channel.yml",
+    "doc/sample-sidecar.yml",
+    "doc/videoPane.png",
+    "dropcaster.gemspec",
+    "lib/dropcaster.rb",
+    "lib/dropcaster/channel.rb",
+    "lib/dropcaster/channel_file_locator.rb",
+    "lib/dropcaster/errors.rb",
+    "lib/dropcaster/hashkeys.rb",
+    "lib/dropcaster/item.rb",
+    "templates/channel.rss.erb",
+    "test/fixtures/channel.yml",
+    "test/fixtures/iTunes.mp3",
+    "test/helper.rb",
+    "test/unit/test_app.rb",
+    "test/unit/test_channel.rb",
+    "test/unit/test_channel_locator.rb",
+    "test/unit/test_channel_xml.rb",
+    "test/unit/test_item.rb"
+  ]
+  s.homepage = %q{http://github.com/nerab/dropcaster}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.9}
+  s.summary = %q{Simple Podcast Publishing with Dropbox}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ruby-mp3info>, [">= 0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<libxml-ruby>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, [">= 0"])
+    else
+      s.add_dependency(%q<ruby-mp3info>, [">= 0"])
+      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<libxml-ruby>, [">= 0"])
+      s.add_dependency(%q<rdoc>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<ruby-mp3info>, [">= 0"])
+    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<libxml-ruby>, [">= 0"])
+    s.add_dependency(%q<rdoc>, [">= 0"])
+  end
+end
+

data/lib/dropcaster/channel.rb

@@ -2,14 +2,28 @@ require 'erb'
 require 'uri'
 
 module Dropcaster
+  #
+  # Represents a podcast feed in the RSS 2.0 format
+  #
   class Channel < DelegateClass(Hash)
     include HashKeys
 
+    # Instantiate a new Channel object. +sources+ must be present and can be a String or Array
+    # of Strings, pointing to a one or more directories or MP3 files.
+    #
+    # +options+ is a hash with all attributes for the channel. The following attributes are 
+    # mandatory when a new channel is created:
+    # 
+    # * <tt>:title</tt> - Title (name) of the podcast
+    # * <tt>:url</tt> - URL to the podcast
+    # * <tt>:description</tt> - Short description of the podcast (a few words)
+    # * <tt>:enclosure_base</tt> - Base URL for enclosure links
+    #
     def initialize(sources, options)
       super(Hash.new)
 
-      # Assert mantadory options
-      [:title, :url, :description].each{|attr|
+      # Assert mandatory options
+      [:title, :url, :description, :enclosure_base].each{|attr|
         raise MissingAttributeError.new(attr) if options[attr].blank?
       }
       
@@ -29,10 +43,18 @@ module Dropcaster
       @index_template = ERB.new(File.new(File.join(File.dirname(__FILE__), '..', '..', 'templates', 'channel.rss.erb')), 0, "%<>")
     end
 
+    #
+    # Returns this channel as an RSS representation. The actual rendering is done with the help
+    # of an ERB template. By default, it is expected as ../../templates/channel.rss.erb (relative)
+    # to channel.rb.
+    #
     def to_rss
       @index_template.result(binding)
     end
 
+    #
+    # Returns all items (episodes) of this channel, ordered by newest-first.
+    #
     def items
       all_items = Array.new
       @source_files.each{|src|
@@ -42,10 +64,9 @@ module Dropcaster
         item.tag.artist = self.author if item.artist.blank?
         item.image_url = self.image_url if item.image_url.blank?
         
-        # Construct absolute URL, based on the channel's enclosure_base attribute
-        item.url = enclosure_base || ''
-        item.url << '/' unless item.url =~ /\/$/
-        item.url += URI.escape(item.file_name, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+        # construct absolute URL, based on the channel's enclosure_base attribute
+        enclosure_base << '/' unless enclosure_base =~ /\/$/
+        item.url = URI.join(URI.escape(enclosure_base), URI.escape(item.file_name))
         
         all_items << item
       }

data/lib/dropcaster/channel_file_locator.rb

@@ -0,0 +1,48 @@
+module Dropcaster
+  #
+  # Encapsulates the strategy how to find the channel definition file
+  #
+  class ChannelFileLocator
+    class << self
+      #
+      # Locates the channel definition file based on the <tt>sources</tt> directory.
+      #
+      # * If <tt>sources</tt> is a single file name, the channel definition file is expected
+      # as channel.yml in the same directory.
+      #
+      # * If <tt>sources</tt> is a single directory name, the channel definition file is
+      # expected as channel.yml in that directory.
+      #
+      # * If <tt>sources</tt> is an array of file names, the channel definition file is
+      # expected as channel.yml in the directory common to all files. If the files are
+      # located in more than one directory, an AmbiguousSourcesError is raised. In that
+      # case, the caller should specify the channel.yml as command line parameter.
+      #
+      # * If <tt>sources</tt> is an array with more than a single directory name, an
+      # AmbiguousSourcesError is raised. In that case, the caller should specify the
+      # channel.yml as command line parameter.
+      #
+      def locate(sources)
+        channel_source_dir = nil
+
+        if sources.respond_to?(:at)
+          # More than one source given. Check that they are all in the same directory.
+          distinct_dirs = sources.collect{|source| File.dirname(source)}.uniq
+
+          if 1 == distinct_dirs.size
+            # If all are the in same directory, use that as source directory where channel.yml is expected.
+            channel_source_dir = distinct_dirs.first
+          else
+            # Since no channel_file was specified at the command line, throw and quit
+            raise AmbiguousSourcesError.new(sources)
+          end
+        else
+          # If a single file or directory is given, use that as source directory where channel.yml is expected.
+          channel_source_dir = File.dirname(sources)
+        end
+
+        File.join(channel_source_dir, CHANNEL_YML)
+      end
+    end
+  end
+end

data/lib/dropcaster/errors.rb

@@ -1,11 +1,19 @@
-class ConfigurationError < StandardError
-  def initialize(msg)
-    super(msg)
+module Dropcaster
+  class ConfigurationError < StandardError
+    def initialize(msg)
+      super(msg)
+    end
+  end
+
+  class MissingAttributeError < ConfigurationError
+    def initialize(missingAttribute)
+      super("#{missingAttribute} is a mandatory attribute, but it is missing.")
+    end
   end
-end
 
-class MissingAttributeError < ConfigurationError
-  def initialize(missingAttribute)
-    super("#{missingAttribute} is a mantadory attribute, but it is missing.")
+  class AmbiguousSourcesError < ConfigurationError
+    def initialize(ambiguousSources)
+      super("The list of sources is ambiguous. Can't derive common directory from these: #{ambiguousSources.inspect}")
+    end
   end
 end

data/lib/dropcaster/item.rb

@@ -9,7 +9,7 @@ module Dropcaster
       super(Hash.new)
 
       Mp3Info.open(file_path){|mp3info|
-        self[:file_name] = Pathname.new(file_path).cleanpath.to_s
+        self[:file_name] = Pathname.new(File.expand_path(file_path)).relative_path_from(Pathname.new(Dir.pwd)).cleanpath.to_s
         self[:tag] = mp3info.tag
         self[:tag2] = mp3info.tag2
         self[:duration] = mp3info.length

data/lib/dropcaster.rb

@@ -10,7 +10,9 @@ require 'dropcaster/errors'
 require 'dropcaster/hashkeys'
 require 'dropcaster/channel'
 require 'dropcaster/item'
+require 'dropcaster/channel_file_locator'
 
 module Dropcaster
   VERSION = File.read(File.join(File.dirname(__FILE__), *%w[.. VERSION]))
+  CHANNEL_YML = 'channel.yml'
 end

data/test/helper.rb

@@ -1,3 +1,10 @@
 require 'rubygems'
 require 'test/unit'
 require 'dropcaster'
+
+$:.unshift File.join(File.dirname(__FILE__), *%w[.. test unit])
+
+module DropcasterTest
+  FIXTURES_DIR = File.join(File.dirname(__FILE__), 'fixtures')
+  NS_ITUNES = "itunes:http://www.itunes.com/dtds/podcast-1.0.dtd"
+end

data/test/unit/test_app.rb

@@ -0,0 +1,59 @@
+require 'helper'
+require 'test_channel_xml'
+require 'xml/libxml'
+require 'open3'
+
+#
+# End-to-end test
+#
+# Same as TestChannelXML, but with the XML generated by calling the bin script
+#
+class TestApp < TestChannelXML
+  include DropcasterTest
+  
+  def setup
+    @options = YAML.load_file(File.join(FIXTURES_DIR, Dropcaster::CHANNEL_YML))
+    @channel = XML::Document.string(%x[bin/dropcaster test/fixtures/iTunes.mp3]).find("//rss/channel").first
+  end
+  
+  def test_overwrite_title
+    test_title = 'Alice and Bob in Wonderland'
+    channel = XML::Document.string(%x[bin/dropcaster test/fixtures/iTunes.mp3 --title '#{test_title}']).find("//rss/channel").first
+    assert_equal(test_title, channel.find('title').first.content)
+  end
+  
+  def test_overwrite_link
+    test_link = 'http://www.example.com/foo/bar'
+    channel = XML::Document.string(%x[bin/dropcaster test/fixtures/iTunes.mp3 --url '#{test_link}']).find("//rss/channel").first
+    assert_equal(test_link, channel.find('link').first.content)
+  end
+  
+  def test_overwrite_description
+    test_description = 'Testing commandline apps is not that hard.'
+    channel = XML::Document.string(%x[bin/dropcaster test/fixtures/iTunes.mp3 --description '#{test_description}']).find("//rss/channel").first
+    assert_equal(test_description, channel.find('description').first.content)
+    assert_equal(test_description, channel.find('itunes:summary', NS_ITUNES).first.content)
+  end
+  
+  def test_no_channel_file
+    Open3.popen3('bin/dropcaster'){|stdin, stdout, stderr|
+      assert(stderr.read =~ /No \.\/channel.yml found/)
+    }
+  end
+
+  def test_overwrite_all
+      test_title = 'Bob and Alice in Wonderland'
+      test_link = 'http://www.example.com/bar/foot'
+      test_description = 'Testing commandline apps is really not that hard.'
+
+      channel = XML::Document.string(%x[bin/dropcaster test/fixtures/iTunes.mp3 --title '#{test_title}' --url '#{test_link}' --description '#{test_description}']).find("//rss/channel").first
+
+      assert_equal(test_title, channel.find('title').first.content)
+      assert_equal(test_link, channel.find('link').first.content)
+      assert_equal(test_description, channel.find('description').first.content)
+      assert_equal(test_description, channel.find('itunes:summary', NS_ITUNES).first.content)
+  end
+
+  # TODO --enclosure_base
+  # TODO --channel
+end

data/test/unit/test_channel.rb

@@ -1,43 +1,32 @@
 require 'helper'
-require 'xml/libxml'
 
 class TestChannel < Test::Unit::TestCase
-  FIXTURES_DIR = File.join(File.dirname(__FILE__), '..', 'fixtures')
-  NS_ITUNES = "itunes:http://www.itunes.com/dtds/podcast-1.0.dtd"
-  
+  include DropcasterTest
+
   def setup
-    @channel = Dropcaster::Channel.new(FIXTURES_DIR, {:title => 'Test Channel', :url => 'http://www.example.com/podcast.rss', :description => 'A test channel'})
+    @options = YAML.load_file(File.join(FIXTURES_DIR, Dropcaster::CHANNEL_YML))
+    @channel = Dropcaster::Channel.new(FIXTURES_DIR, @options)
   end
-  
-  def test_items
+
+  def test_item_count
     assert_equal(1, @channel.items.size)
-    assert_equal('77bf84447c0f69ce4a33a18b0ae1e030b82010de', @channel.items.first.uuid)
   end
+
+  def test_channel
+    assert_equal(@options[:title], @channel.title)
+    assert_equal(@options[:url], @channel.url)
+    assert_equal(@options[:description], @channel.description)
+    assert_equal(@options[:subtitle], @channel.subtitle)
+    assert_equal(@options[:language], @channel.language)
+    assert_equal(@options[:copyright], @channel.copyright)
+    assert_equal(@options[:author], @channel.author)
   
-  def test_attributes_mantadory
-    channel = XML::Document.string(@channel.to_rss).find("//rss/channel").first
-    assert_equal('Test Channel', channel.find('title').first.content)
-    assert_equal('http://www.example.com/podcast.rss', channel.find('link').first.content)
-    assert_equal('A test channel', channel.find('description').first.content)
-  end
+    owner = @channel.owner
+    assert_equal(@options[:owner][:name], owner[:name])
+    assert_equal(@options[:owner][:email], owner[:email])
   
-  def test_attributes_complete
-    options = YAML.load_file(File.join(FIXTURES_DIR, 'test_channel.yml'))
-    channel = XML::Document.string(Dropcaster::Channel.new(FIXTURES_DIR, options).to_rss).find("//rss/channel").first
-    assert_equal(options[:title], channel.find('title').first.content)
-    assert_equal(options[:url], channel.find('link').first.content)
-    assert_equal(options[:description], channel.find('description').first.content)
-    assert_equal(options[:subtitle], channel.find('itunes:subtitle', NS_ITUNES).first.content)
-    assert_equal(options[:language], channel.find('language').first.content)
-    assert_equal(options[:copyright], channel.find('copyright').first.content)
-    assert_equal(options[:author], channel.find('itunes:author', NS_ITUNES).first.content)
-    
-    owner = channel.find('itunes:owner', NS_ITUNES).first
-    assert_equal(options[:owner][:name], owner.find('itunes:name', NS_ITUNES).first.content)
-    assert_equal(options[:owner][:email], owner.find('itunes:email', NS_ITUNES).first.content)
-    
-    assert_equal(options[:image_url], channel.find('itunes:image', NS_ITUNES).first['href'])
+    assert_equal(@options[:image_url], @channel.image_url)
     # TODO :categories: ['Technology', 'Gadgets']
-    assert_equal(options[:explicit], channel.find('itunes:explicit', NS_ITUNES).first.content)
+    assert_equal(@options[:explicit], @channel.explicit)
   end
 end

data/test/unit/test_channel_locator.rb

@@ -0,0 +1,91 @@
+require 'helper'
+require 'tmpdir'
+
+class TestChannelLocator < Test::Unit::TestCase
+  include DropcasterTest
+
+  class << self
+    attr_reader :temp_dir
+
+    def startup
+      @temp_dir = Dir.mktmpdir
+    end
+
+    def shutdown
+      FileUtils.remove_entry_secure(@temp_dir)
+    end
+
+    def suite
+      # from http://stackoverflow.com/questions/255969#778701
+      _suite = super
+
+      def _suite.run(*args)
+        TestChannelLocator.startup()
+        super
+        TestChannelLocator.shutdown()
+      end
+
+      _suite
+    end
+  end
+
+  def test_single_file
+    sources = File.join(TestChannelLocator.temp_dir, 'single_file.mp3')
+    assert_location(sources)
+  end
+
+  def test_current_directory
+    sources = File.join(TestChannelLocator.temp_dir, '.')
+    assert_location(sources)
+  end
+
+  def test_single_directory
+    sources = File.join(TestChannelLocator.temp_dir, 'single_dir')
+    assert_location(sources)
+  end
+
+  def test_array_of_files_same_dir
+    sources = Array.new
+    sources << File.join(TestChannelLocator.temp_dir, 'file1.mp3')
+    sources << File.join(TestChannelLocator.temp_dir, 'file2.mp3')
+    sources << File.join(TestChannelLocator.temp_dir, 'file3.mp3')
+
+    assert_location(sources)
+  end
+
+  def test_array_of_files_different_dir
+    sources = Array.new
+    sources << File.join(TestChannelLocator.temp_dir, 'foo', 'file1.mp3')
+    sources << File.join(TestChannelLocator.temp_dir, 'bar', 'file1.mp3')
+    sources << File.join(TestChannelLocator.temp_dir, 'baz', 'file1.mp3')
+
+    assert_raises Dropcaster::AmbiguousSourcesError do
+      Dropcaster::ChannelFileLocator.locate(sources)
+    end
+  end
+
+  def test_array_with_one_directory
+    assert_location(File.join(TestChannelLocator.temp_dir, ['single_dir']))
+  end
+
+  def test_array_with_more_than_a_single_directory
+    Dir.mktmpdir{|tmp_dir1|
+      Dir.mktmpdir{|tmp_dir2|
+        sources = Array.new
+        sources << File.join(tmp_dir1, 'another_dir')
+        sources << File.join(tmp_dir2, 'another_dir')
+
+        assert_raises Dropcaster::AmbiguousSourcesError do
+          Dropcaster::ChannelFileLocator.locate(sources)
+        end
+      }
+    }
+  end
+
+  private
+
+  def assert_location(sources)
+    channel_file = Dropcaster::ChannelFileLocator.locate(sources)
+    assert_equal(File.join(TestChannelLocator.temp_dir, Dropcaster::CHANNEL_YML), channel_file)
+  end
+end

data/test/unit/test_channel_xml.rb

@@ -0,0 +1,69 @@
+require 'helper'
+require 'xml/libxml'
+
+class TestChannelXML < Test::Unit::TestCase
+  include DropcasterTest
+
+  def setup
+    @options = YAML.load_file(File.join(FIXTURES_DIR, Dropcaster::CHANNEL_YML))
+    @channel = XML::Document.string(Dropcaster::Channel.new(FIXTURES_DIR, @options).to_rss).find("//rss/channel").first
+  end
+
+  def test_item
+    item = @channel.find("item").first
+    assert(item)
+
+    assert_equal('iTunes Name', item.find('title').first.content)
+    assert_equal('iTunes Artist', item.find('itunes:author', NS_ITUNES).first.content)
+    assert_equal('iTunes Description (Video Pane)', item.find('itunes:summary', NS_ITUNES).first.content)
+    assert_equal('http://example.com/podcasts/everything/AllAboutEverything.jpg', item.find('itunes:image', NS_ITUNES).first['href'])
+
+    enclosure = item.find('enclosure').first
+    assert(enclosure)
+    assert_equal('http://www.example.com/podcasts/everything/test/fixtures/iTunes.mp3', enclosure['url'])
+    assert_equal('58119', enclosure['length'])
+    assert_equal('audio/mp3', enclosure['type'])
+
+    guid = item.find('guid').first
+    assert(guid)
+    assert_equal('false', guid['isPermaLink'])
+    assert_equal('77bf84447c0f69ce4a33a18b0ae1e030b82010de', guid.content)
+
+    assert_equal('Sat, 01 Oct 2011 14:08:20 +0200', item.find('pubDate').first.content)
+    assert_equal('3', item.find('itunes:duration', NS_ITUNES).first.content)
+
+    # Not used in our fixture yet
+    # assert_equal('', item.find('itunes:subtitle', NS_ITUNES).first.content)
+    # assert_equal('', item.find('itunes:keywords', NS_ITUNES).first.content)
+  end
+
+  def test_attributes_mandatory
+    options = {:title => 'Test Channel',
+               :url => 'http://www.example.com/',
+               :description => 'A test channel',
+               :enclosure_base => 'http://www.example.com/foo/bar',
+              }
+    @channel = XML::Document.string(Dropcaster::Channel.new(FIXTURES_DIR, options).to_rss).find("//rss/channel").first    
+    assert_equal('Test Channel', @channel.find('title').first.content)
+    assert_equal('http://www.example.com/', @channel.find('link').first.content)
+    assert_equal('A test channel', @channel.find('description').first.content)
+  end
+
+  def test_attributes_complete
+    assert_equal(@options[:title], @channel.find('title').first.content)
+    assert_equal(@options[:url], @channel.find('link').first.content)
+    assert_equal(@options[:description], @channel.find('description').first.content)
+    assert_equal(@options[:subtitle], @channel.find('itunes:subtitle', NS_ITUNES).first.content)
+    assert_equal(@options[:language], @channel.find('language').first.content)
+    assert_equal(@options[:copyright], @channel.find('copyright').first.content)
+    assert_equal(@options[:author], @channel.find('itunes:author', NS_ITUNES).first.content)
+
+    owner = @channel.find('itunes:owner', NS_ITUNES).first
+    assert_equal(@options[:owner][:name], owner.find('itunes:name', NS_ITUNES).first.content)
+    assert_equal(@options[:owner][:email], owner.find('itunes:email', NS_ITUNES).first.content)
+
+    assert_equal(@options[:image_url], @channel.find('itunes:image', NS_ITUNES).first['href'])
+    # TODO :categories: ['Technology', 'Gadgets']
+    assert_equal(@options[:explicit], @channel.find('itunes:explicit', NS_ITUNES).first.content)
+  end
+end

data/test/unit/test_item.rb

@@ -10,7 +10,7 @@ class TestItem < Test::Unit::TestCase
     assert_equal(58119, @item.file_size)
     assert_equal('77bf84447c0f69ce4a33a18b0ae1e030b82010de', @item.uuid)
     assert_equal(1317470900, @item.pub_date.to_i)
-    assert_equal(Pathname.new('../../fixtures/iTunes.mp3'), Pathname.new(@item.file_name).relative_path_from(Pathname.new(__FILE__)))
+    assert_equal('test/fixtures/iTunes.mp3', @item.file_name)
   end
   
   def test_tag

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: dropcaster
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - nerab
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-03 00:00:00 Z
+date: 2011-10-05 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   requirement: &id001 !ruby/object:Gem::Requirement 
@@ -91,6 +91,20 @@ dependencies:
   name: libxml-ruby
   prerelease: false
   type: :development
+- !ruby/object:Gem::Dependency 
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id006
+  name: rdoc
+  prerelease: false
+  type: :development
 description: Dropcaster is a podcast feed generator for the command line. It is most simple to use with Dropbox, but works equally well with any other hoster.
 email: nerab@gmx.at
 executables: 
@@ -113,19 +127,26 @@ files:
 - VERSION
 - bin/dropcaster
 - bin/lstags
+- doc/infoPane.png
+- doc/lyricsPane.png
+- doc/sample-channel.yml
+- doc/sample-sidecar.yml
+- doc/videoPane.png
+- dropcaster.gemspec
 - lib/dropcaster.rb
 - lib/dropcaster/channel.rb
+- lib/dropcaster/channel_file_locator.rb
 - lib/dropcaster/errors.rb
 - lib/dropcaster/hashkeys.rb
 - lib/dropcaster/item.rb
 - templates/channel.rss.erb
+- test/fixtures/channel.yml
 - test/fixtures/iTunes.mp3
-- test/fixtures/infoPane.png
-- test/fixtures/lyricsPane.png
-- test/fixtures/test_channel.yml
-- test/fixtures/videoPane.png
 - test/helper.rb
+- test/unit/test_app.rb
 - test/unit/test_channel.rb
+- test/unit/test_channel_locator.rb
+- test/unit/test_channel_xml.rb
 - test/unit/test_item.rb
 homepage: http://github.com/nerab/dropcaster
 licenses: