rbpod 0.0.3 → 0.0.4

data/ext/rbpod/device.c

@@ -2,42 +2,74 @@
 
 #include "rbpod.h"
 #include "device.h"
-
-inline VALUE rbpod_device_create(Itdb_Device *device)
-{
-    return Data_Wrap_Struct(cRbPodDevice, NULL, NULL, (void *) device);
-}
-
+#include "database.h"
+
+/*
+ * call-seq:
+ *     supports_chapter_images?() -> Boolean
+ *
+ * Returns true of false if the device supports chapter images.
+ */
 static VALUE rbpod_device_chapter_image_support_p(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
     return BooleanValue(itdb_device_supports_chapter_image(device));
 }
 
+/*
+ * call-seq:
+ *     supports_podcasts?() -> Boolean
+ *
+ * Returns true of false if the device supports podcasts.
+ */
 static VALUE rbpod_device_podcast_support_p(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
     return BooleanValue(itdb_device_supports_podcast(device));
 }
 
+/*
+ * call-seq:
+ *     supports_artwork?() -> Boolean
+ *
+ * Returns true of false if the device supports artwork.
+ */
 static VALUE rbpod_device_artwork_support_p(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
     return BooleanValue(itdb_device_supports_artwork(device));
 }
 
+/*
+ * call-seq:
+ *     supports_videos?() -> Boolean
+ *
+ * Returns true of false if the device supports videos.
+ */
 static VALUE rbpod_device_video_support_p(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
     return BooleanValue(itdb_device_supports_video(device));
 }
 
+/*
+ * call-seq:
+ *     supports_photos?() -> Boolean
+ *
+ * Returns true of false if the device supports photos.
+ */
 static VALUE rbpod_device_photo_support_p(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
     return BooleanValue(itdb_device_supports_photo(device));
 }
 
+/*
+ * call-seq:
+ *     model_name() -> String
+ *
+ * Returns the model name of the device.
+ */
 static VALUE rbpod_device_model_name_get(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -45,6 +77,12 @@ static VALUE rbpod_device_model_name_get(VALUE self)
     return rb_str_new2(itdb_info_get_ipod_model_name_string(info->ipod_model));
 }
 
+/*
+ * call-seq:
+ *     model_number() -> String
+ *
+ * Returns the model number of the device.
+ */
 static VALUE rbpod_device_model_number_get(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -52,6 +90,12 @@ static VALUE rbpod_device_model_number_get(VALUE self)
     return rb_str_new2(info->model_number);
 }
 
+/*
+ * call-seq:
+ *     generation() -> String
+ *
+ * Returns the generation of the device.
+ */
 static VALUE rbpod_device_generation_get(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -59,6 +103,12 @@ static VALUE rbpod_device_generation_get(VALUE self)
     return rb_str_new2(itdb_info_get_ipod_generation_string(info->ipod_generation));
 }
 
+/*
+ * call-seq:
+ *     capacity() -> Float
+ *
+ * Returns the capacity of the device in gigabytes (GB).
+ */
 static VALUE rbpod_device_capacity_get(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -66,6 +116,12 @@ static VALUE rbpod_device_capacity_get(VALUE self)
     return DBL2NUM(info->capacity);
 }
 
+/*
+ * call-seq:
+ *     uuid() -> String
+ *
+ * Returns the UUID of the device.
+ */
 static VALUE rbpod_device_uuid_get(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -73,6 +129,12 @@ static VALUE rbpod_device_uuid_get(VALUE self)
     return (uuid == NULL) ? Qnil : rb_str_new2(uuid);
 }
 
+/*
+ * call-seq:
+ *     [](key) -> String
+ *
+ * Returns the SysInfo entry for the given key, or nil.
+ */
 static VALUE rbpod_device_sysinfo_get(VALUE self, VALUE key)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -87,6 +149,12 @@ static VALUE rbpod_device_sysinfo_get(VALUE self, VALUE key)
 
 }
 
+/*
+ * call-seq:
+ *     []=(key, value) -> nil
+ *
+ * Sets the given SysInfo entry to a value and returns nil.
+ */
 static VALUE rbpod_device_sysinfo_set(VALUE self, VALUE key, VALUE value)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -100,6 +168,12 @@ static VALUE rbpod_device_sysinfo_set(VALUE self, VALUE key, VALUE value)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *     save!() -> nil
+ *
+ * Writes the SysInfo data back to the device. Call this if you change any entries.
+ */
 static VALUE rbpod_device_sysinfo_save(VALUE self)
 {
     Itdb_Device *device = TYPED_DATA_PTR(self, Itdb_Device);
@@ -112,20 +186,32 @@ static VALUE rbpod_device_sysinfo_save(VALUE self)
     return Qnil;
 }
 
-static VALUE rbpod_device_initialize(VALUE self)
+/*
+ * call-seq:
+ *     initialize(database) -> RbPod::Device
+ *
+ * Creates an RbPod::Device for a given RbPod::Database. You shouldn't have to call this.
+ */
+static VALUE rbpod_device_initialize(VALUE self, VALUE database)
 {
-    /* Private method, no setup required yet. */
-    return self;
-}
+    Itdb_iTunesDB *_database = TYPED_DATA_PTR(database, Itdb_iTunesDB);
 
-static void rbpod_device_deallocate(void *handle)
-{
-    itdb_device_free((Itdb_Device *) handle);
-}
+    /* Make sure we were given an instance of a RbPod::Database. */
+    if (rb_class_of(database) != cRbPodDatabase) {
+        rb_raise(eRbPodError, "Given database must be an instance of RbPod::Database: %s", StringValueCStr(database));
+        return Qnil;
+    }
 
-static VALUE rbpod_device_allocate(VALUE self)
-{
-    return Data_Wrap_Struct(cRbPodDevice, NULL, rbpod_device_deallocate, (void *) itdb_device_new());
+    /* The database pointer and it's device should both be non-NULL. */
+    if (_database == NULL || _database->device == NULL) {
+        rb_raise(eRbPodError, "Given database and/or device was NULL.");
+        return Qnil;
+    }
+
+    /* Attach our data pointer to this database's backing device. */
+    DATA_PTR(self) = _database->device;
+
+    return self;
 }
 
 void Init_rbpod_device(void)
@@ -135,10 +221,7 @@ void Init_rbpod_device(void)
 #endif
     cRbPodDevice = rb_define_class_under(mRbPod, "Device", rb_cObject);
 
-    rb_define_alloc_func(cRbPodDevice, rbpod_device_allocate);
-
-    /* We don't want to explicitly create these, so mark the constructor as private. */
-    rb_define_private_method(cRbPodDevice, "initialize", rbpod_device_initialize, 0);
+    rb_define_method(cRbPodDevice, "initialize", rbpod_device_initialize, 1);
 
     rb_define_method(cRbPodDevice, "[]", rbpod_device_sysinfo_get, 1);
     rb_define_method(cRbPodDevice, "[]=", rbpod_device_sysinfo_set, 2);

data/ext/rbpod/device.h

@@ -7,6 +7,4 @@ RUBY_EXTERN VALUE cRbPodDevice;
 
 void Init_rbpod_device(void);
 
-inline VALUE rbpod_device_create(Itdb_Device *device);
-
 #endif /* RBPOD_DEVICE_H */

data/ext/rbpod/playlist.c

@@ -4,73 +4,152 @@
 #include "playlist.h"
 #include "track_collection.h"
 
+/*
+ * call-seq:
+ *     is_podcast_playlist?() -> Boolean
+ *
+ * Returns true or false if this playlist is the podcast-only playlist.
+ */
 static VALUE rbpod_playlist_podcast_p(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return BooleanValue(itdb_playlist_is_podcasts(playlist));
 }
 
+/*
+ * call-seq:
+ *     is_master_playlist?() -> Boolean
+ *
+ * Returns true or false if this playlist is the master playlist.
+ */
 static VALUE rbpod_playlist_master_p(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return BooleanValue(itdb_playlist_is_mpl(playlist));
 }
 
+/*
+ * call-seq:
+ *     is_smart_playlist?() -> Boolean
+ *
+ * Returns true or false if this playlist is a smart playlist.
+ */
 static VALUE rbpod_playlist_smart_p(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return BooleanValue(playlist->is_spl);
 }
 
+/*
+ * call-seq:
+ *     timestamp() -> Time
+ *     created_on() -> Time
+ *
+ * Returns a Time object representing the time that this playlist was created.
+ */
 static VALUE rbpod_playlist_timestamp_get(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return rb_funcall(rb_cTime, rb_intern("at"), 1, INT2NUM(playlist->timestamp));
 }
 
-static VALUE rbpod_playlist_shuffle(VALUE self)
+/*
+ * call-seq:
+ *     shuffle!() -> nil
+ *
+ * Shuffles the tracks in this playlist in place.
+ */
+static VALUE rbpod_playlist_shuffle_bang(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     itdb_playlist_randomize(playlist);
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *     tracks() -> RbPod::Collection
+ *
+ * Returns a collection of the tracks in this playlist.
+ */
 static VALUE rbpod_playlist_tracks_get(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return rbpod_track_collection_create(self, playlist->members);
 }
 
+/*
+ * call-seq:
+ *     length() -> Integer
+ *
+ * Returns the total number of tracks in this playlist.
+ */
 static VALUE rbpod_playlist_length_get(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return INT2NUM(itdb_playlist_tracks_number(playlist));
 }
 
+/*
+ * call-seq:
+ *     name() -> String
+ *
+ * Returns the name of this playlist.
+ */
 static VALUE rbpod_playlist_name_get(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return rb_str_new2(playlist->name);
 }
 
+/*
+ * call-seq:
+ *     <=>(other) -> Integer
+ *
+ * Compares two playlists based on their names.
+ */
+static VALUE rbpod_playlist_compare(VALUE self, VALUE other)
+{
+    VALUE this_playlist_name, other_playlist_name;
+
+    if (rb_class_of(other) != cRbPodPlaylist) {
+        rb_raise(eRbPodError, "Can't compare a Playlist with %s", StringValueCStr(other));
+        return Qnil;
+    }
+
+    this_playlist_name  = rbpod_playlist_name_get(self);
+    other_playlist_name = rbpod_playlist_name_get(other);
+
+    return rb_str_cmp(this_playlist_name, other_playlist_name);
+}
+
+/*
+ * call-seq:
+ *     id() -> Fixnum
+ *
+ * Returns the internal ID number for this playlist. Do not use this method.
+ */
 static VALUE rbpod_playlist_id_get(VALUE self)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     return INT2NUM(playlist->id);
 }
 
+/*
+ * call-seq:
+ *     initialize(name, is_smart_playlist) -> RbPod::Playlist
+ *
+ * Creates a detached playlist. (Not managed by the database.)
+ */
 static VALUE rbpod_playlist_initialize(VALUE self, VALUE playlist_name, VALUE smart_playlist)
 {
     Itdb_Playlist *playlist = TYPED_DATA_PTR(self, Itdb_Playlist);
     gchar *_playlist_name = StringValueCStr(playlist_name);
 
-    /* Kill off the dummy playlist. */
     itdb_playlist_free(playlist);
 
-    /* Create a new playlist based on the values provided. */
     playlist = itdb_playlist_new(_playlist_name, (smart_playlist == Qtrue) ? TRUE : FALSE);
 
-    /* Store the new playlist. */
     DATA_PTR(self) = playlist;
 
     return self;
@@ -97,7 +176,7 @@ static VALUE rbpod_playlist_allocate(VALUE self)
 void Init_rbpod_playlist(void)
 {
 #if RDOC_CAN_PARSE_DOCUMENTATION
-     mRbPod = rb_define_module("RbPod");
+    mRbPod = rb_define_module("RbPod");
 #endif
     cRbPodPlaylist = rb_define_class_under(mRbPod, "Playlist", rb_cObject);
 
@@ -105,16 +184,21 @@ void Init_rbpod_playlist(void)
 
     rb_define_method(cRbPodPlaylist, "initialize", rbpod_playlist_initialize, 2);
 
-    rb_define_method(cRbPodPlaylist, "id", rbpod_playlist_id_get, 0);
+    rb_define_private_method(cRbPodPlaylist, "id", rbpod_playlist_id_get, 0);
+
+    rb_define_method(cRbPodPlaylist, "<=>", rbpod_playlist_compare, 1);
+
     rb_define_method(cRbPodPlaylist, "name", rbpod_playlist_name_get, 0);
     rb_define_method(cRbPodPlaylist, "length", rbpod_playlist_length_get, 0);
     rb_define_method(cRbPodPlaylist, "tracks", rbpod_playlist_tracks_get, 0);
-    rb_define_method(cRbPodPlaylist, "shuffle!", rbpod_playlist_shuffle, 0);
-    rb_define_method(cRbPodPlaylist, "created_on", rbpod_playlist_timestamp_get, 0);
+    rb_define_method(cRbPodPlaylist, "shuffle!", rbpod_playlist_shuffle_bang, 0);
+    rb_define_method(cRbPodPlaylist, "timestamp", rbpod_playlist_timestamp_get, 0);
+
+    rb_define_alias(cRbPodPlaylist, "created_on", "timestamp");
 
-    rb_define_method(cRbPodPlaylist, "smart_playlist?", rbpod_playlist_smart_p, 0);
-    rb_define_method(cRbPodPlaylist, "master_playlist?", rbpod_playlist_master_p, 0);
-    rb_define_method(cRbPodPlaylist, "podcast_playlist?", rbpod_playlist_podcast_p, 0);
+    rb_define_method(cRbPodPlaylist, "is_smart_playlist?", rbpod_playlist_smart_p, 0);
+    rb_define_method(cRbPodPlaylist, "is_master_playlist?", rbpod_playlist_master_p, 0);
+    rb_define_method(cRbPodPlaylist, "is_podcast_playlist?", rbpod_playlist_podcast_p, 0);
 
     return;
 }

data/ext/rbpod/playlist_collection.c

@@ -5,56 +5,77 @@
 #include "collection.h"
 #include "playlist_collection.h"
 
-static VALUE rbpod_playlist_collection_parent(VALUE self)
+/*
+ * call-seq:
+ *     database() -> RbPod::Database
+ *
+ * The database from which this collection of playlists is attached to.
+ */
+static VALUE rbpod_playlist_collection_database(VALUE self)
 {
-    return rb_iv_get(self, "@parent");
+    return rb_iv_get(self, "@database");
 }
 
+/*
+ * call-seq:
+ *     [](index) -> RbPod::Playlist
+ *     [](name) -> RbPod::Playlist
+ *
+ * Returns a playlist by either position or name in the collection, or nil if it wasn't found.
+ */
 static VALUE rbpod_playlist_collection_get(VALUE self, VALUE key)
 {
-    VALUE parent = rbpod_playlist_collection_parent(self);
+    VALUE parent = rbpod_playlist_collection_database(self);
     Itdb_iTunesDB *database = TYPED_DATA_PTR(parent, Itdb_iTunesDB);
     Itdb_Playlist *playlist = NULL;
+    int key_type = TYPE(key);
 
-    switch (TYPE(key)) {
-    case T_SYMBOL:
-    case T_STRING:
+    if (key_type == T_SYMBOL || key_type == T_STRING) {
         playlist = itdb_playlist_by_name(database, StringValueCStr(key));
-        break;
-    case T_FIXNUM:
-        playlist = itdb_playlist_by_nr(database, FIX2INT(key));
-        break;
+        return Data_Wrap_Struct(cRbPodPlaylist, NULL, NULL, (void *) playlist);
     }
 
-    if (playlist == NULL) {
-        return Qnil;
+    if (key_type == T_FIXNUM) {
+        playlist = itdb_playlist_by_nr(database, FIX2INT(key));
+        return Data_Wrap_Struct(cRbPodPlaylist, NULL, NULL, (void *) playlist);
     }
 
-    return Data_Wrap_Struct(cRbPodPlaylist, NULL, NULL, (void *) playlist);
+    return Qnil;
 }
 
-static VALUE rbpod_playlist_collection_podcasts_get(VALUE self)
+/*
+ * call-seq:
+ *     podcast() -> RbPod::Playlist
+ *
+ * Returns the podcast playlist in this collection.
+ */
+static VALUE rbpod_playlist_collection_podcast_get(VALUE self)
 {
-    VALUE parent = rbpod_playlist_collection_parent(self);
+    VALUE parent = rbpod_playlist_collection_database(self);
     Itdb_iTunesDB *database = TYPED_DATA_PTR(parent, Itdb_iTunesDB);
     Itdb_Playlist *podcasts = itdb_playlist_podcasts(database);
     return Data_Wrap_Struct(cRbPodPlaylist, NULL, NULL, (void *) podcasts);
 }
 
+/*
+ * call-seq:
+ *     master() -> RbPod::Playlist
+ *
+ * Returns the master playlist in this collection.
+ */
 static VALUE rbpod_playlist_collection_master_get(VALUE self)
 {
-    VALUE parent = rbpod_playlist_collection_parent(self);
+    VALUE parent = rbpod_playlist_collection_database(self);
     Itdb_iTunesDB *database = TYPED_DATA_PTR(parent, Itdb_iTunesDB);
     Itdb_Playlist *master = itdb_playlist_mpl(database);
     return Data_Wrap_Struct(cRbPodPlaylist, NULL, NULL, (void *) master);
 }
 
-inline VALUE rbpod_playlist_collection_create(VALUE parent, GList *items)
+inline VALUE rbpod_playlist_collection_create(VALUE database, GList *items)
 {
     VALUE collection = rbpod_collection_create(items, cRbPodPlaylist);
     rb_extend_object(collection, mRbPodPlaylistCollection);
-    rb_extend_object(collection, rb_mComparable);
-    rb_iv_set(collection, "@parent", parent);
+    rb_iv_set(collection, "@database", database);
     return collection;
 }
 
@@ -63,12 +84,13 @@ void Init_rbpod_playlist_collection(void)
 #if RDOC_CAN_PARSE_DOCUMENTATION
     mRbPod = rb_define_module("RbPod");
 #endif
+    /* This module extends any collection of playlists at runtime. */
     mRbPodPlaylistCollection = rb_define_module_under(mRbPod, "PlaylistCollection");
 
-    rb_define_private_method(mRbPodPlaylistCollection, "parent", rbpod_playlist_collection_parent, 0);
+    rb_define_method(mRbPodPlaylistCollection, "database", rbpod_playlist_collection_database, 0);
 
     rb_define_method(mRbPodPlaylistCollection, "master", rbpod_playlist_collection_master_get, 0);
-    rb_define_method(mRbPodPlaylistCollection, "podcasts", rbpod_playlist_collection_podcasts_get, 0);
+    rb_define_method(mRbPodPlaylistCollection, "podcast", rbpod_playlist_collection_podcast_get, 0);
 
     rb_define_method(mRbPodPlaylistCollection, "[]", rbpod_playlist_collection_get, 1);
 

data/ext/rbpod/rbpod.c

@@ -23,6 +23,7 @@ VALUE mRbPodPlaylistCollection;
 VALUE cRbPodTrack;
 VALUE mRbPodTrackCollection;
 
+VALUE rb_cPathname;
 
 inline VALUE rbpod_raise_error(GError *error)
 {
@@ -37,12 +38,28 @@ inline VALUE rbpod_raise_error(GError *error)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *     RbPod(mount_point) -> RbPod::Database
+ *
+ * A shortcut for creating an RbPod::Database instance from a mount point.
+ *
+ */
+static VALUE rbpod_load_database(VALUE self, VALUE mount_point)
+{
+    return rb_class_new_instance(1, &mount_point, cRbPodDatabase);
+}
+
 void Init_rbpod(void)
 {
+    /* This is the wrapper for all RbPod related classes. */
     mRbPod = rb_define_module("RbPod");
 
+    /* This is a generic subclass of RuntimeError for RbPod-specific errors.*/
     eRbPodError = rb_define_class_under(mRbPod, "Error", rb_eRuntimeError);
 
+    rb_cPathname = rb_const_get(rb_cObject, rb_intern("Pathname"));
+
     Init_rbpod_database();
     Init_rbpod_device();
     Init_rbpod_collection();
@@ -51,6 +68,8 @@ void Init_rbpod(void)
     Init_rbpod_track();
     Init_rbpod_track_collection();
 
+    rb_define_global_function("RbPod", rbpod_load_database, 1);
+
     return;
 }
 

data/ext/rbpod/rbpod.h

@@ -13,6 +13,8 @@
 RUBY_EXTERN VALUE mRbPod;
 RUBY_EXTERN VALUE eRbPodError;
 
+RUBY_EXTERN VALUE rb_cPathname;
+
 inline VALUE rbpod_raise_error(GError *error);
 
 #endif /* RBPOD_H */