rbpod 0.0.3 → 0.0.4

data/README.md

@@ -24,88 +24,110 @@ Functional for most read-only purposes. To get started, add `require 'rbpod'` to
 
 To load a database from the filesystem:
 
-    database = RbPod::Database.new('/mnt/ipod/') # => #<RbPod::Database:0xdeadbeef>
+```ruby
+database = RbPod::Database.new('/mnt/ipod/') # => #<RbPod::Database:0xdeadbeef>
 
-    database.version       # => 42
-    database.mountpoint    # => "/mnt/ipod/"
-    database.filename      # => "/mnt/ipod/iPod_Control/iTunes/iTunesDB"
-    database.synchronized? # => true
+database.version       # => 42
+database.mountpoint    # => "/mnt/ipod/"
+database.filename      # => "/mnt/ipod/iPod_Control/iTunes/iTunesDB"
+database.synchronized? # => true
+```
+Loading a database is common, so you can also use a shortcut:
 
-If you'd like to create a blank database, you can do that too:
+```ruby
+database = RbPod('/mnt/ipod/')
+```
 
-    database = RbPod::Database.create!('/tmp/ipod-blank') # => #<RbPod::Database:0xdeadbeef>
+If you'd like to create a new, blank database you can do that too:
+
+```ruby
+database = RbPod::Database.create!('/tmp/ipod-blank') # => #<RbPod::Database:0xdeadbeef>
+```
 
 ### RbPod::Device
 
 The device (if any) that backs the database can be interrogated:
 
-    device = database.device # => #<RbPod::Device:0xdeadbeef>
+```ruby
+device = database.device # => #<RbPod::Device:0xdeadbeef>
 
-    # Model name, number, and capacity.
-    device.capacity     # => 4.0
-    device.generation   # => "Nano Video (3rd Gen.)"
-    device.model_name   # => "Nano (Silver)"
-    device.model_number # => "A978"
+# Model name, number, and capacity.
+device.capacity     # => 4.0
+device.generation   # => "Nano Video (3rd Gen.)"
+device.model_name   # => "Nano (Silver)"
+device.model_number # => "A978"
 
-    # Feature support.
-    device.supports_photos?         # => true
-    device.supports_videos?         # => true
-    device.supports_artwork?        # => true
-    device.supports_podcasts?       # => true
-    device.supports_chapter_images? # => true
+# Feature support.
+device.supports_photos?         # => true
+device.supports_videos?         # => true
+device.supports_artwork?        # => true
+device.supports_podcasts?       # => true
+device.supports_chapter_images? # => true
 
-    # Reading/writing SysInfo. Set a key to nil to erase it.
-    device['ModelNumStr'] # => "xA978"
-    device['PotsdamConf45'] = "Kilroy Was Here"
-    device.save!
+# Reading/writing SysInfo. Set a key to nil to erase it.
+device['ModelNumStr'] # => "xA978"
+device['PotsdamConf45'] = "Kilroy Was Here"
+device.save!
+```
 
 ### RbPod::Collection
 
 All methods that return lists return a `Collection` enumerator decorated depending on it's contents:
 
-    database.playlists # => #<RbPod::Collection:0xdeadbeef>
+```ruby
+database.playlists # => #<RbPod::Collection:0xdeadbeef>
 
-    # For a list of all the names of playlists on the iPod:
-    database.playlists.map(&:name) # => ["iPod", "Podcasts", "Recently Added"]
+# For a list of all the names of playlists on the iPod:
+database.playlists.map(&:name) # => ["iPod", "Podcasts", "Recently Added"]
 
-    # For direct access to the master playlist:
-    database.playlists.master # => #<RbPod::Playlist:0xdeadbeef>
+# For direct access to the master playlist:
+database.playlists.master # => #<RbPod::Playlist:0xdeadbeef>
 
-    # For direct access to the podcasts playlist:
-    database.playlists.podcasts # => #<RbPod::Playlist:0xdeadbeef>
+# For direct access to the podcasts playlist:
+database.playlists.podcasts # => #<RbPod::Playlist:0xdeadbeef>
+```
 
 ### RbPod::Playlist
 
 All playlists support a variety of methods:
 
-    playlist = database.playlists.master
+```ruby
+playlist = database.playlists.master
 
-    playlist.name       # => "iPod"
-    playlist.length     # => 400
-    playlist.created_on # => 2008-04-05 08:47:46 -0700
+playlist.name       # => "iPod"
+playlist.length     # => 400
+playlist.created_on # => 2008-04-05 08:47:46 -0700
 
-    playlist.master_playlist?  # => true
-    playlist.smart_playlist?   # => false
-    playlist.podcast_playlist? # => false
+playlist.master_playlist?  # => true
+playlist.smart_playlist?   # => false
+playlist.podcast_playlist? # => false
 
-    playlist.tracks # => #<RbPod::Collection:0xdeadbeef>
+playlist.tracks # => #<RbPod::Collection:0xdeadbeef>
+```
 
 ### RbPod::Track
 
 Tracks also can do a lot, but not complete:
 
-    track = database.playlists.master.tracks.first
+```ruby
+track = database.playlists.master.tracks.first
 
-    track.artist       # => "Steppenwolf"
-    track.title        # => "Born To Be Wild"
-    track.album        # => "All Time Greatest Hits Remastered"
-    track.file_type    # => "MPEG audio file"
-    track.transferred? # => true
+track.artist       # => "Steppenwolf"
+track.title        # => "Born To Be Wild"
+track.album        # => "All Time Greatest Hits Remastered"
+track.file_type    # => "MPEG audio file"
+track.transferred? # => true
+````
 
 ### RbPod::Error
 
 If anything goes belly up at run time, an `RbPod::Error` exception should be thrown with a detailed message.
 
+## Todo
+
+ * The RSpec tests need a lot of work and significantly more coverage, especially for integration.
+ * The documentation could be spiced up a bit. It's dry and doesn't provide too much useful information.
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,5 +1,6 @@
 # Bring in rake with rake-compiler's support.
 require 'rake'
+require 'rake/clean'
 require 'rake/extensiontask'
 
 # Bring in bundler and it's gem tasks.
@@ -15,6 +16,9 @@ require 'rdoc/task'
 # By default, clean, compile and then test.
 task :default => [ :compile, :test ]
 
+# Let Rake know what is safe to remove.
+CLEAN.include [ 'pkg/*', 'doc/*' ]
+
 desc "Compile the native extension."
 Rake::ExtensionTask.new do |extension|
   # Some basic configuration.
@@ -35,11 +39,11 @@ end
 
 desc "Build all RDoc documentation."
 RDoc::Task.new(:rdoc) do |task|
- task.main = 'README.md'
- task.markup = 'markdown'
- task.rdoc_files.include("README.md", 'lib/**/*.rb', 'ext/**/*.[ch]')
- task.options << "--all"
- task.rdoc_dir = 'doc'
+ task.rdoc_dir = 'doc/rdoc'
+ task.markup   = 'markdown'
+ task.main     = 'README.md'
+ task.title    = 'RbPod: Lightweight Ruby bindings to libgpod'
+ task.rdoc_files.include('README.md', 'lib/**/*.rb', 'ext/**/*.[ch]')
 end
 
 desc "Open a console with rbpod preloaded."

data/ext/rbpod/collection.c

@@ -16,6 +16,12 @@ inline VALUE rbpod_collection_create(GList *list, VALUE type)
     return Data_Wrap_Struct(cRbPodCollection, NULL, NULL, (void *) collection);
 }
 
+/*
+ * call-seq:
+ *     [](index) -> Object or nil
+ *
+ * Return the item located at the given position in the list.
+ */
 static VALUE rbpod_collection_get(VALUE self, VALUE key)
 {
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
@@ -30,6 +36,12 @@ static VALUE rbpod_collection_get(VALUE self, VALUE key)
     return Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
 }
 
+/*
+ * call-seq:
+ *     last() -> Object
+ *
+ * Return the last item of the collection.
+ */
 static VALUE rbpod_collection_last(VALUE self)
 {
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
@@ -42,6 +54,12 @@ static VALUE rbpod_collection_last(VALUE self)
     return Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
 }
 
+/*
+ * call-seq:
+ *     first() -> Object
+ *
+ * Return the first item of the collection.
+ */
 static VALUE rbpod_collection_first(VALUE self)
 {
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
@@ -54,33 +72,46 @@ static VALUE rbpod_collection_first(VALUE self)
     return Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
 }
 
+/*
+ * call-seq:
+ *     length() -> Integer
+ *
+ * Return the total length of all items in the collection.
+ */
 static VALUE rbpod_collection_length(VALUE self)
 {
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
     return INT2NUM(g_list_length(collection->list));
 }
 
-static VALUE rbpod_collection_each(VALUE self)
+/*
+ * call-seq:
+ *     each(*args) -> Enumerator
+ *     each(*args) { |item| block } -> Enumerator
+ *
+ * Iterate over the collection, passing each item to a given block.
+ * If no block was supplied, return an enumerator for the collection.
+ *
+ */
+static VALUE rbpod_collection_each(VALUE self, VALUE argv)
 {
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
+    VALUE item = Qnil, arguments = rb_ary_dup(argv);
     GList *current = NULL;
-    VALUE item;
 
-    if (rb_block_given_p() == FALSE) {
-        return rb_funcall(self, rb_intern("enum_for"), 1, ID2SYM(rb_intern("each")));
-    }
+    /* Return an enumerator if a block was not supplied. */
+    RETURN_ENUMERATOR(self, 0, 0);
+
+    /* Prepend an empty element as a placeholder. */
+    rb_ary_unshift(arguments, Qnil);
 
     /* If we were supplied a block, enumerate the entire list. */
     for (current = collection->list; current != NULL; current = current->next) {
         item = Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
-        rb_yield(item);
+        rb_ary_store(arguments, 0, item);
+        rb_yield_splat(arguments);
     }
 
-    return Qnil;
-}
-
-static VALUE rbpod_collection_initialize(VALUE self)
-{
     return self;
 }
 
@@ -114,14 +145,14 @@ void Init_rbpod_collection(void)
     rb_define_alloc_func(cRbPodCollection, rbpod_collection_allocate);
 
     rb_include_module(cRbPodCollection, rb_mEnumerable);
+    rb_include_module(cRbPodCollection, rb_mComparable);
 
-    rb_define_private_method(cRbPodCollection, "initialize", rbpod_collection_initialize, 0);
-
-    rb_define_method(cRbPodCollection, "each", rbpod_collection_each, 0);
+    rb_define_method(cRbPodCollection, "each", rbpod_collection_each, -2);
 
     rb_define_method(cRbPodCollection, "length", rbpod_collection_length, 0);
 
     rb_define_alias(cRbPodCollection,  "size", "length");
+    rb_define_alias(cRbPodCollection,  "count", "length");
 
     rb_define_method(cRbPodCollection, "first", rbpod_collection_first, 0);
     rb_define_method(cRbPodCollection, "last", rbpod_collection_last, 0);

data/ext/rbpod/database.c

@@ -6,6 +6,12 @@
 #include "track_collection.h"
 #include "playlist_collection.h"
 
+/*
+ * call-seq:
+ *     save!() -> nil
+ *
+ * Saves any changes made to the database.
+ */
 static VALUE rbpod_database_save(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
@@ -15,9 +21,15 @@ static VALUE rbpod_database_save(VALUE self)
         return rbpod_raise_error(error);
     }
 
-    return self;
+    return Qnil;
 }
 
+/*
+ * call-seq:
+ *     synchronized?() -> Boolean
+ *
+ * Returns true or false depending if any changes have been made, but not saved.
+ */
 static VALUE rbpod_database_synchronized_p(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
@@ -25,6 +37,12 @@ static VALUE rbpod_database_synchronized_p(VALUE self)
     return BooleanValue(nontransferred == 0);
 }
 
+/*
+ * call-seq:
+ *     playlists() -> RbPod::Collection
+ *
+ * Returns a collection of all playlists added to this database.
+ */
 static VALUE rbpod_database_playlists_get(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
@@ -35,23 +53,40 @@ static VALUE rbpod_database_tracks_get(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     Itdb_Playlist *playlist = itdb_playlist_mpl(database);
-    /* Use the master playlist as the parent for the master track list. */
     VALUE parent = Data_Wrap_Struct(cRbPodPlaylist, NULL, NULL, (void *) playlist);
     return rbpod_track_collection_create(parent, database->tracks);
 }
 
+/*
+ * call-seq:
+ *     device() -> RbPod::Device
+ *
+ * Returns the device backing this database.
+ */
 static VALUE rbpod_database_device_get(VALUE self)
 {
-    Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
-    return rbpod_device_create(database->device);
+    return rb_class_new_instance(1, &self, cRbPodDevice);
 }
 
+/*
+ * call-seq:
+ *     filename() -> String
+ *
+ * Returns the path on the file system to the database.
+ */
 static VALUE rbpod_database_filename_get(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
-    return rb_str_new2(database->filename);
+    VALUE file_path = rb_str_new2(database->filename);
+    return rb_class_new_instance(1, &file_path, rb_cPathname);
 }
 
+/*
+ * call-seq:
+ *     version() -> Fixnum
+ *
+ * Returns the version number of the database.
+ */
 static VALUE rbpod_database_version_get(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
@@ -64,17 +99,24 @@ static VALUE rbpod_database_id_get(VALUE self)
     return INT2NUM(database->id);
 }
 
+/*
+ * call-seq:
+ *     mountpoint() -> String
+ *
+ * Returns the location of the mount point this database was parsed from.
+ */
 static VALUE rbpod_database_mountpoint_get(VALUE self)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
-    return rb_str_new2(itdb_get_mountpoint(database));
+    VALUE mount_point = rb_str_new2(itdb_get_mountpoint(database));
+    return rb_class_new_instance(1, &mount_point, rb_cPathname);
 }
 
 static VALUE rbpod_database_mountpoint_set(VALUE self, VALUE path)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     itdb_set_mountpoint(database, StringValueCStr(path));
-    return rbpod_database_mountpoint_get(self);
+    return Qnil;
 }
 
 static void rbpod_database_deallocate(void *handle)
@@ -83,6 +125,12 @@ static void rbpod_database_deallocate(void *handle)
     return;
 }
 
+/*
+ * call-seq:
+ *     initialize(mount_point) -> RbPod::Database
+ *
+ * Loads a new database parsed from the given mount point.
+ */
 static VALUE rbpod_database_initialize(VALUE self, VALUE mount_point)
 {
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
@@ -111,11 +159,18 @@ static VALUE rbpod_database_allocate(VALUE self)
     return Data_Wrap_Struct(cRbPodDatabase, NULL, rbpod_database_deallocate, (void *) database);
 }
 
+/*
+ * call-seq:
+ *     create!(mount_point) -> RbPod::Database
+ *     create!(mount_point, device_name) -> RbPod::Database
+ *     create!(mount_point, device_name, model_number) -> RbPod::Database
+ *
+ * Creates a new database on the file system and loads it.
+ */
 static VALUE rbpod_database_create(int argc, VALUE *argv, VALUE self)
 {
-    VALUE mount_point, device_name, model_number, instance;
     gchar *_mount_point, *_device_name, *_model_number;
-    GDir *directory = NULL;
+    VALUE mount_point, device_name, model_number;
     GError *error = NULL;
 
     if (rb_scan_args(argc, argv, "12", &mount_point, &device_name, &model_number) < 1) {
@@ -123,21 +178,18 @@ static VALUE rbpod_database_create(int argc, VALUE *argv, VALUE self)
         return Qnil;
     }
 
-    /* Reject the mount point immediately if it isn't a string. */
-    if (TYPE(mount_point) != T_STRING && RSTRING_LEN(mount_point) > 0) {
-        rb_raise(eRbPodError, "Mount point must be a non-empty string.");
+    /* Check if the mount point is a directory. */
+    if (rb_file_directory_p(rb_cFile, mount_point) != Qtrue) {
+        rb_raise(eRbPodError, "The mount point must be a directory!");
         return Qnil;
     }
 
     /* If we didn't specify a device name, default to 'iPod'. */
-    if (NIL_P(device_name) == TRUE) {
-        device_name = rb_str_new2("iPod");
-    }
-
-    /* If the specified device name isn't a string of at least three characters, bail now. */
-    if (TYPE(device_name) != T_STRING || RSTRING_LEN(device_name) < 3) {
+    if (RTEST(device_name) && (TYPE(device_name) != T_STRING || RSTRING_LEN(device_name) < 4)) {
         rb_raise(eRbPodError, "Device name should be a string of at least three characters.");
         return Qnil;
+    } else {
+        device_name = rb_str_new2("iPod");
     }
 
     /* If the specified model number is specified but isn't a string, bail now. TODO: Use a regexp, stupid. */
@@ -153,25 +205,13 @@ static VALUE rbpod_database_create(int argc, VALUE *argv, VALUE self)
     /* GPod can function with a NULL model number, however, artwork may not function properly. */
     _model_number = !NIL_P(model_number) ? StringValueCStr(model_number) : NULL;
 
-    /* Check if the mount point is a directory. */
-    directory = g_dir_open(_mount_point, 0, &error);
-
-    if (directory == NULL) {
-        return rbpod_raise_error(error);
-    }
-
-    /* Glib seems to think so... */
-    g_dir_close(directory);
-
     /* Initialize the iPod at this mount point, with this device name and model number. */
     if (itdb_init_ipod(_mount_point, _model_number, _device_name, &error) == FALSE) {
         return rbpod_raise_error(error);
     }
 
-    instance = rbpod_database_allocate(cRbPodDatabase);
-
     /* Return an instance of this class using the newly created database. */
-    return rbpod_database_initialize(instance, mount_point);
+    return rb_class_new_instance(1, &mount_point, cRbPodDatabase);
 }
 
 void Init_rbpod_database(void)
@@ -187,15 +227,16 @@ void Init_rbpod_database(void)
 
     rb_define_singleton_method(cRbPodDatabase, "create!", rbpod_database_create, -1);
 
+    rb_define_private_method(cRbPodDatabase, "id", rbpod_database_id_get, 0);
+    rb_define_private_method(cRbPodDatabase, "tracks", rbpod_database_tracks_get, 0);
+    rb_define_private_method(cRbPodDatabase, "mountpoint=", rbpod_database_mountpoint_set, 1);
+
     rb_define_method(cRbPodDatabase, "mountpoint", rbpod_database_mountpoint_get, 0);
-    rb_define_method(cRbPodDatabase, "mountpoint=", rbpod_database_mountpoint_set, 1);
 
-    rb_define_method(cRbPodDatabase, "id", rbpod_database_id_get, 0);
     rb_define_method(cRbPodDatabase, "version", rbpod_database_version_get, 0);
     rb_define_method(cRbPodDatabase, "filename", rbpod_database_filename_get, 0);
 
     rb_define_method(cRbPodDatabase, "device", rbpod_database_device_get, 0);
-    rb_define_method(cRbPodDatabase, "tracks", rbpod_database_tracks_get, 0);
     rb_define_method(cRbPodDatabase, "playlists", rbpod_database_playlists_get, 0);
 
     rb_define_method(cRbPodDatabase, "synchronized?", rbpod_database_synchronized_p, 0);