rbpod 0.0.2 → 0.0.3

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/README.md

@@ -18,47 +18,93 @@ Or install it yourself as:
 
 ## Usage
 
-Functional for most read-only purposes.
+Functional for most read-only purposes. To get started, add `require 'rbpod'` to your script.
 
-    #!/usr/bin/env ruby
+### RbPod::Database
 
-    require 'rbpod'
+To load a database from the filesystem:
 
-    # Explicitly load a database from the filesystem -- can be a mount point to an iPod.
-    database = RbPod::Database.new('/mnt/ipod/') # => #<RbPod::Database:0x8733fa4>
+    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
 
-    # Device information, including model name, number, and capacity.
-    database.device.capacity     # => 4.0
-    database.device.generation   # => "Nano Video (3rd Gen.)"
-    database.device.model_name   # => "Nano (Silver)"
-    database.device.model_number # => "A978"
-
-    # Device feature support detection.
-    database.device.supports_photos?         # => true
-    database.device.supports_videos?         # => true
-    database.device.supports_artwork?        # => true
-    database.device.supports_podcasts?       # => true
-    database.device.supports_chapter_images? # => true
-
-    # Device SysInfo read/write.
-    database.device['ModelNumStr'] # => "xA978"
-    database.device['PotsdamConf45'] = "Kilroy Was Here"
-    database.device.save!
-
-    # Playlists (includes enumerable)
+If you'd like to create a blank database, you can do that too:
+
+    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>
+
+    # 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
+
+    # 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>
+
+    # For a list of all the names of playlists on the iPod:
     database.playlists.map(&:name) # => ["iPod", "Podcasts", "Recently Added"]
 
-    # Track Listing (also enumerable)
-    database.tracks.length       # => 400
-    database.tracks.first.artist # => "Steppenwolf"
-    database.tracks.first.title  # => "Born To Be Wild"
+    # 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>
+
+### RbPod::Playlist
+
+All playlists support a variety of methods:
+
+    playlist = database.playlists.master
+
+    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.tracks # => #<RbPod::Collection:0xdeadbeef>
+
+### RbPod::Track
+
+Tracks also can do a lot, but not complete:
+
+    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
+
+### RbPod::Error
 
-It's alpha quality -- many pieces still need to be implemented. Patches welcome.
+If anything goes belly up at run time, an `RbPod::Error` exception should be thrown with a detailed message.
 
 ## Contributing
 

data/Rakefile

@@ -9,6 +9,9 @@ require 'bundler/gem_tasks'
 # Bring in RSpec's built-in rake task.
 require 'rspec/core/rake_task'
 
+# Bring in RDoc's built-in rake task.
+require 'rdoc/task'
+
 # By default, clean, compile and then test.
 task :default => [ :compile, :test ]
 
@@ -30,6 +33,15 @@ RSpec::Core::RakeTask.new(:test) do |task|
   task.ruby_opts = '-w'
 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'
+end
+
 desc "Open a console with rbpod preloaded."
 task :console => [ :compile ] do
   sh 'bundle console'

data/ext/rbpod/collection.c

@@ -3,53 +3,72 @@
 #include "rbpod.h"
 #include "collection.h"
 
-VALUE cRbPodCollection;
+struct collection {
+    VALUE klass;
+    GList *list;
+};
 
-struct collection { VALUE klass; GList *list; };
-
-inline VALUE rbpod_collection_create(GList *list, VALUE type) {
+inline VALUE rbpod_collection_create(GList *list, VALUE type)
+{
     struct collection *collection = ALLOC(struct collection);
     collection->list  = list;
     collection->klass = type;
     return Data_Wrap_Struct(cRbPodCollection, NULL, NULL, (void *) collection);
 }
 
-static VALUE rbpod_collection_get(VALUE self, VALUE key) {
+static VALUE rbpod_collection_get(VALUE self, VALUE key)
+{
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
     GList *current = NULL;
 
-    if (FIXNUM_P(key) == FALSE)
+    if (FIXNUM_P(key) == FALSE) {
         return Qnil;
+    }
 
     current = g_list_nth(collection->list, FIX2INT(key));
 
     return Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
 }
 
-static VALUE rbpod_collection_last(VALUE self) {
+static VALUE rbpod_collection_last(VALUE self)
+{
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
     GList *current = g_list_last(collection->list);
+
+    if (current == NULL) {
+        return Qnil;
+    }
+
     return Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
 }
 
-static VALUE rbpod_collection_first(VALUE self) {
+static VALUE rbpod_collection_first(VALUE self)
+{
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
     GList *current = g_list_first(collection->list);
+
+    if (current == NULL) {
+        return Qnil;
+    }
+
     return Data_Wrap_Struct(collection->klass, NULL, NULL, (void *) current->data);
 }
 
-static VALUE rbpod_collection_length(VALUE self) {
+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) {
+static VALUE rbpod_collection_each(VALUE self)
+{
     struct collection *collection = TYPED_DATA_PTR(self, struct collection);
     GList *current = NULL;
     VALUE item;
 
-    if (rb_block_given_p() == FALSE)
+    if (rb_block_given_p() == FALSE) {
         return rb_funcall(self, rb_intern("enum_for"), 1, ID2SYM(rb_intern("each")));
+    }
 
     /* If we were supplied a block, enumerate the entire list. */
     for (current = collection->list; current != NULL; current = current->next) {
@@ -60,35 +79,43 @@ static VALUE rbpod_collection_each(VALUE self) {
     return Qnil;
 }
 
-static VALUE rbpod_collection_initialize(VALUE self) {
+static VALUE rbpod_collection_initialize(VALUE self)
+{
     return self;
 }
 
-static void rbpod_collection_deallocate(void *handle) {
+static void rbpod_collection_deallocate(void *handle)
+{
     struct collection *collection = (struct collection *) handle;
 
-    if (collection->list != NULL)
+    if (collection->list != NULL) {
         g_list_free(collection->list);
+    }
 
     xfree(handle);
     return;
 }
 
-static VALUE rbpod_collection_allocate(VALUE self) {
+static VALUE rbpod_collection_allocate(VALUE self)
+{
     struct collection *collection = ALLOC(struct collection);
     collection->list = NULL;
     collection->klass = Qnil;
     return Data_Wrap_Struct(cRbPodCollection, NULL, rbpod_collection_deallocate, (void *) collection);
 }
 
-void Init_rbpod_collection(void) {
+void Init_rbpod_collection(void)
+{
+#if RDOC_CAN_PARSE_DOCUMENTATION
+    mRbPod = rb_define_module("RbPod");
+#endif
     cRbPodCollection = rb_define_class_under(mRbPod, "Collection", rb_cObject);
 
     rb_define_alloc_func(cRbPodCollection, rbpod_collection_allocate);
 
     rb_include_module(cRbPodCollection, rb_mEnumerable);
 
-    rb_define_method(cRbPodCollection, "initialize", rbpod_collection_initialize, 0);
+    rb_define_private_method(cRbPodCollection, "initialize", rbpod_collection_initialize, 0);
 
     rb_define_method(cRbPodCollection, "each", rbpod_collection_each, 0);
 

data/ext/rbpod/collection.h

@@ -3,7 +3,7 @@
 #ifndef RBPOD_COLLECTION_H
 #define RBPOD_COLLECTION_H
 
-extern VALUE cRbPodCollection;
+RUBY_EXTERN VALUE cRbPodCollection;
 
 void Init_rbpod_collection(void);
 

data/ext/rbpod/database.c

@@ -1,32 +1,38 @@
 /* database.c */
 
 #include "rbpod.h"
-#include "track.h"
 #include "device.h"
-#include "playlist.h"
 #include "database.h"
-#include "collection.h"
+#include "track_collection.h"
+#include "playlist_collection.h"
 
-VALUE cRbPodDatabase;
-
-static VALUE rbpod_database_write(VALUE self) {
+static VALUE rbpod_database_save(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
-    gboolean success = itdb_write(database, NULL); /* TODO: Improve error handling. */
-    return BooleanValue(success);
+    GError *error = NULL;
+
+    if (itdb_write(database, &error) == FALSE) {
+        return rbpod_raise_error(error);
+    }
+
+    return self;
 }
 
-static VALUE rbpod_database_is_synchronized(VALUE self) {
+static VALUE rbpod_database_synchronized_p(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     guint32 nontransferred = itdb_tracks_number_nontransferred(database);
     return BooleanValue(nontransferred == 0);
 }
 
-static VALUE rbpod_database_playlists_get(VALUE self) {
+static VALUE rbpod_database_playlists_get(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     return rbpod_playlist_collection_create(self, database->playlists);
 }
 
-static VALUE rbpod_database_tracks_get(VALUE self) {
+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. */
@@ -34,103 +40,152 @@ static VALUE rbpod_database_tracks_get(VALUE self) {
     return rbpod_track_collection_create(parent, database->tracks);
 }
 
-static VALUE rbpod_database_device_get(VALUE self) {
+static VALUE rbpod_database_device_get(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     return rbpod_device_create(database->device);
 }
 
-static VALUE rbpod_database_filename_get(VALUE self) {
+static VALUE rbpod_database_filename_get(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     return rb_str_new2(database->filename);
 }
 
-static VALUE rbpod_database_version_get(VALUE self) {
+static VALUE rbpod_database_version_get(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     return INT2NUM(database->version);
 }
 
-static VALUE rbpod_database_id_get(VALUE self) {
+static VALUE rbpod_database_id_get(VALUE self)
+{
     Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
     return INT2NUM(database->id);
 }
 
-static VALUE rbpod_database_mountpoint_get(VALUE self) {
+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));
 }
 
-static VALUE rbpod_database_mountpoint_set(VALUE self, VALUE path) {
+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);
 }
 
-static void rbpod_database_deallocate(void *handle) {
+static void rbpod_database_deallocate(void *handle)
+{
     itdb_free((Itdb_iTunesDB *) handle);
     return;
 }
 
-static VALUE rbpod_database_create(VALUE self, VALUE device_name, VALUE mount_point, VALUE model_number) {
-    gchar *_mount_point, *_model_number, *_device_name;
-    Itdb_iTunesDB *database = NULL;
-
-    _device_name  = StringValueCStr(device_name);
-    _mount_point  = StringValueCStr(mount_point);
+static VALUE rbpod_database_initialize(VALUE self, VALUE mount_point)
+{
+    Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
+    Itdb_iTunesDB *previous = database;
+    GError *error = NULL;
 
-    /* GPod can function with a NULL model number, however, artwork will not function. */
-    _model_number = !NIL_P(model_number) ? StringValueCStr(model_number) : NULL;
+    /* Try to parse the database from the given mount point. */
+    database = itdb_parse(StringValueCStr(mount_point), &error);
 
-    /* Initialize the iPod at this mount point, with this device name and model number. */
-    /* TODO: Improve error handling. */
-    if (itdb_init_ipod(_mount_point, _model_number, _device_name, NULL) == FALSE) {
-        rb_raise(eRbPodError, "Unable to format this iPod.");
-        return Qfalse;
+    if (database == NULL) {
+        return rbpod_raise_error(error);
     }
 
-    /* Parse the newly created database. */
-    /* TODO: Improve error handling. */
-    database = itdb_parse(_mount_point, NULL);
+    /* Overwrite our old database with the new one. */
+    DATA_PTR(self) = database;
 
-    if (database == NULL) {
-        rb_raise(eRbPodError, "Not an iPod mount point.");
-        return Qnil;
-    }
+    /* Free the old one. */
+    itdb_free(previous);
 
-    /* Return an instance of this class using the newly created database. */
+    return self;
+}
+
+static VALUE rbpod_database_allocate(VALUE self)
+{
+    Itdb_iTunesDB *database = itdb_new();
     return Data_Wrap_Struct(cRbPodDatabase, NULL, rbpod_database_deallocate, (void *) database);
 }
 
-static VALUE rbpod_database_initialize(VALUE self, VALUE mount_point) {
-    Itdb_iTunesDB *database = TYPED_DATA_PTR(self, Itdb_iTunesDB);
+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;
+    GError *error = NULL;
 
-    /* Try to parse the database from the given mount point. */
-    /* TODO: Improve error handling. */
-    database = itdb_parse(StringValueCStr(mount_point), NULL);
+    if (rb_scan_args(argc, argv, "12", &mount_point, &device_name, &model_number) < 1) {
+        rb_raise(eRbPodError, "Invalid arguments.");
+        return Qnil;
+    }
 
-    /* The given mount point was not an iPod mount point. */
-    if (database == NULL) {
-        rb_raise(eRbPodError, "This is not an iPod mount point.");
+    /* 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.");
         return Qnil;
     }
 
-    DATA_PTR(self) = database;
+    /* If we didn't specify a device name, default to 'iPod'. */
+    if (NIL_P(device_name) == TRUE) {
+        device_name = rb_str_new2("iPod");
+    }
 
-    return self;
-}
+    /* 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) {
+        rb_raise(eRbPodError, "Device name should be a string of at least three characters.");
+        return Qnil;
+    }
 
-static VALUE rbpod_database_allocate(VALUE self) {
-    Itdb_iTunesDB *database = itdb_new();
-    return Data_Wrap_Struct(cRbPodDatabase, NULL, rbpod_database_deallocate, (void *) database);
+    /* If the specified model number is specified but isn't a string, bail now. TODO: Use a regexp, stupid. */
+    if (NIL_P(model_number) == FALSE && (TYPE(model_number) != T_STRING || RSTRING_LEN(model_number) < 4)) {
+        rb_raise(eRbPodError, "Model number should be a string of at least four characters.");
+        return Qnil;
+    }
+
+    /* Extract pointers for glib use. */
+    _mount_point  = StringValueCStr(mount_point);
+    _device_name  = StringValueCStr(device_name);
+
+    /* 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);
 }
 
-void Init_rbpod_database(void) {
+void Init_rbpod_database(void)
+{
+#if RDOC_CAN_PARSE_DOCUMENTATION
+    mRbPod = rb_define_module("RbPod");
+#endif
     cRbPodDatabase = rb_define_class_under(mRbPod, "Database", rb_cObject);
 
     rb_define_alloc_func(cRbPodDatabase, rbpod_database_allocate);
 
     rb_define_method(cRbPodDatabase, "initialize", rbpod_database_initialize, 1);
 
-    rb_define_singleton_method(cRbPodDatabase, "create!", rbpod_database_create, 3);
+    rb_define_singleton_method(cRbPodDatabase, "create!", rbpod_database_create, -1);
 
     rb_define_method(cRbPodDatabase, "mountpoint", rbpod_database_mountpoint_get, 0);
     rb_define_method(cRbPodDatabase, "mountpoint=", rbpod_database_mountpoint_set, 1);
@@ -143,8 +198,8 @@ void Init_rbpod_database(void) {
     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_is_synchronized, 0);
+    rb_define_method(cRbPodDatabase, "synchronized?", rbpod_database_synchronized_p, 0);
 
-    rb_define_method(cRbPodDatabase, "write!", rbpod_database_write, 0);
+    rb_define_method(cRbPodDatabase, "save!", rbpod_database_save, 0);
 }
 

data/ext/rbpod/database.h

@@ -3,7 +3,7 @@
 #ifndef RBPOD_DATABASE_H
 #define RBPOD_DATABASE_H
 
-extern VALUE cRbPodDatabase;
+RUBY_EXTERN VALUE cRbPodDatabase;
 
 void Init_rbpod_database(void);