turntabler 0.1.4 → 0.2.0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # master
 
+## 0.2.0 / 2013-02-16
+
+* Respect the keepalive update interval from API responses
+* Add official support for trigger custom events
+* Rename RoomDirectory#list to RoomDirectory#all
+* Add full support for playlists API
+* Fix Modlist example not sending messages to the room
+
 ## 0.1.4 / 2012-01-08
 
 * Fix Bop / ChatBot / Switch examples not working

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Aaron Pfeifer
+Copyright (c) 2013 Aaron Pfeifer
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -50,6 +50,7 @@ At a high level, this project features:
 * HTTP / Web Socket interface implementations
 * Room state / user list management
 * DSL syntax support
+* Custom events
 
 Turntable features include management of:
 
@@ -117,40 +118,47 @@ Turntabler.run do
   end
 
   # Authorized user interactions
-  user = client.user                                # => #<Turntabler::AuthorizedUser:0x95631b0 @email="ben.zelano@gmail.com" ...>
-  user.fan_of                                       # => [#<Turntabler::User:0x95ccb38 @id="d5616b31654e8b22a7a1eef0">, ...]
-  user.fans                                         # => [#<Turntabler::User:0x95dd1cc @id="d5616b31654e8b22a7a1eef0">, ...]
-  user.playlist.songs                               # => [#<Turntabler::Song:0x9610b44 @album="Abbey Road" ...>, ...]
-  user.blocks                                       # => [#<Turntabler::User:0x9792724 @id="19125d4da3b09562b2cf68b6">, ...]
-  user.buddies                                      # => [#<Turntabler::User:0x9792580 @id="efff38aeb7b9334164c1b630">, ...]
+  user = client.user                                # => #<Turntabler::AuthorizedUser @email="ben.zelano@gmail.com" ...>
+  user.fan_of                                       # => [#<Turntabler::User @id="d5616b31654e8b22a7a1eef0">, ...]
+  user.fans                                         # => [#<Turntabler::User @id="d5616b31654e8b22a7a1eef0">, ...]
+  user.playlist.songs                               # => [#<Turntabler::Song @album="Abbey Road" ...>, ...]
+  user.blocks                                       # => [#<Turntabler::User @id="19125d4da3b09562b2cf68b6">, ...]
+  user.buddies                                      # => [#<Turntabler::User @id="efff38aeb7b9334164c1b630">, ...]
   
   # Room Directory
-  client.rooms.list(:favorites => true)             # => []
-  client.rooms.list(:genre => :rock)                # => [#<Turntabler::Room:0x985d474 @id="4e4986bb14169c5f241318a6", ...>, ...]
-  client.rooms.list(:genre => :rock, :available_djs => true, :minimum_listeners => 5)
-  # => [#<Turntabler::Room:0x91c1d04 @id="4f4a5874a3f75128aa006c17", ...>, ...]
-  client.rooms.with_friends                         # => [#<Turntabler::Room:0x9674c98 @id="50b4c1e2df5bcf4af666f876", ...>, ...]
-  client.room('4dff1eac14169c565800892e').listeners # => #<Set: {#<Turntabler::User:0x96340bc @id="4e1341e2a3f75114d003c591" ...>, ...}>
+  client.rooms.all(:favorites => true)              # => []
+  client.rooms.all(:genre => :rock)                 # => [#<Turntabler::Room @id="4e4986bb14169c5f241318a6", ...>, ...]
+  client.rooms.all(:genre => :rock, :available_djs => true, :minimum_listeners => 5)
+  # => [#<Turntabler::Room @id="4f4a5874a3f75128aa006c17", ...>, ...]
+  client.rooms.with_friends                         # => [#<Turntabler::Room @id="50b4c1e2df5bcf4af666f876", ...>, ...]
+  client.room('4dff1eac14169c565800892e').listeners # => #<Set: {#<Turntabler::User @id="4e1341e2a3f75114d003c591" ...>, ...}>
   
   # Room interaction
   client.rooms.create("My Test Room #{rand}").enter # => true
-  room = client.room                                # => #<Turntabler::Room:0x99a16dc @name="My Test Room 0.24300857307298018" ...>
+  room = client.room                                # => #<Turntabler::Room @name="My Test Room 0.24300857307298018" ...>
   room.add_as_favorite                              # => true
   room.become_dj                                    # => true
   room.say "Hey guys!"                              # => true
   
   # User interaction
-  listeners = room.listeners                        # => #<Set: {#<Turntabler::User:0x95631b0 @id="309ba75b6385b83e110923bd" ..., ...}>
+  listeners = room.listeners                        # => #<Set: {#<Turntabler::User @id="309ba75b6385b83e110923bd" ..., ...}>
   listeners.each do |listener|
-    listener.messages                               # => [#<Turntabler::Message:0x99aa1ec @content="Hey man!" ...>, ...]
+    listener.messages                               # => [#<Turntabler::Message @content="Hey man!" ...>, ...]
     listener.website                                # => "http://mypersonalwebsite.com"
     listener.facebook_url                           # => "https://www.facebook.com/firstname.lastname"
-    listener.sticker_placements                     # => [#<Turntabler::StickerPlacement:0x9861024 @angle=0 ...>, ...]
+    listener.sticker_placements                     # => [#<Turntabler::StickerPlacement @angle=0 ...>, ...]
     listener.say "Welcome to the room!"             # => true
   end
   
+  # Playlist interaction
+  client.user.playlists.all                         # => [#<Turntabler::Playlist @id="default" ...>, ...]
+  client.user.playlists.create("rock")              # => #<Turntabler::Playlist @id="rock" ...>
+  client.user.playlist                              # => #<Turntabler::Playlist @id="default" ...>
+  client.user.playlist("rock").activate             # => true
+  client.user.playlist("rock").songs                # => []
+  
   # Songs
-  songs = client.search_song('Rolling Stones')      # => [#<Turntabler::Song:0x983c198 @album="Tattoo You (2009 Remaster)" ...>, ...]
+  songs = client.search_song('Rolling Stones')      # => [#<Turntabler::Song @album="Tattoo You (2009 Remaster)" ...>, ...]
   songs.each do
     song.enqueue                                    # => true
   end
@@ -171,6 +179,43 @@ can do with turntabler.  For a *complete* list, see the API documentation, espec
 For additional examples, see the [examples](https://github.com/obrie/turntabler/tree/master/examples)
 directory in the repository.
 
+### Custom events
+
+In addition to the default Turntable events supported out of the box, turntabler
+also allows you to define your own events.  This is particularly useful in cases
+where you may want to provide extensions on top of the turntabler library for
+others to use.  These extensions may be higher-order events, such as a user
+reaching their maximum play count for a turn or a user timing out.
+
+For example:
+
+```ruby
+require 'turntabler'
+
+EMAIL = ENV['EMAIL']
+PASSWORD = ENV['PASSWORD']
+
+# Register custom events
+Turntabler.events :user_greeted
+
+Turntabler.run do
+  client = Turntabler::Client.new(EMAIL, PASSWORD)
+  
+  # Events
+  client.on :user_spoke do |message|
+    if (message.content =~ /^\/hello$/)
+      # Trigger the custom event
+      client.trigger(:user_greeted, message.sender)
+    end
+  end
+
+  # Handle custom event
+  client.on :user_greeted do |user|
+    client.room.say "Hey! How are you #{message.sender.name}?"
+  end
+end
+```
+
 ## Additional Topics
 
 ### Differences with existing libraries
@@ -332,7 +377,7 @@ Notice that in this example the syntax is essentially the same except that we're
 one level out and need to interact directly with the `Turntabler::Client`
 instance itself.
 
-## Usage
+## Deployment
 
 ### Web Server Usage
 

data/examples/Gemfile.lock

@@ -17,7 +17,7 @@ GEM
     faye-websocket (0.4.6)
       eventmachine (>= 0.12.0)
     http_parser.rb (0.5.3)
-    turntabler (0.1.4)
+    turntabler (0.2.0)
       em-http-request
       em-synchrony
       faye-websocket

data/examples/modlist.rb

@@ -13,7 +13,7 @@ TT.run(EMAIL, PASSWORD, :room => ROOM) do
   on :user_spoke do |message|
     # Response to "/mod" command
     if moderator_ids.include?(message.sender.id) && message.content =~ /^\/mod$/
-      user.say("Yo #{message.sender.name}, it looks like you are a bot moderator!")
+      room.say("Yo #{message.sender.name}, it looks like you are a bot moderator!")
     end
   end
 end

data/lib/turntabler/authorized_user.rb

@@ -1,4 +1,4 @@
-require 'turntabler/playlist'
+require 'turntabler/playlist_directory'
 require 'turntabler/preferences'
 require 'turntabler/user'
 require 'turntabler/sticker_placement'
@@ -32,6 +32,10 @@ module Turntabler
     # @return [String]
     attribute :password
 
+    # The user's custom playlists
+    # @return [Turntabler::PlaylistDirectory]
+    attr_reader :playlists
+
     # The user's current Turntable preferences
     # @return [Turntabler::Preferences]
     attr_reader :preferences
@@ -39,7 +43,7 @@ module Turntabler
     # @api private
     def initialize(client, *)
       @status = 'available'
-      @playlists = {}
+      @playlists = PlaylistDirectory.new(client)
       @preferences = Preferences.new(client)
       super
     end
@@ -192,7 +196,7 @@ module Turntabler
     #   user.playlist             # => #<Turntabler::Playlist id="default" ...>
     #   user.playlist("rock")     # => #<Turntabler::Playlist id="rock" ...>
     def playlist(id = 'default')
-      @playlists[id] ||= Playlist.new(client, :_id => id)
+      playlists.build(:_id => id)
     end
 
     # Gets the stickers that have been purchased by this user.
@@ -245,8 +249,10 @@ module Turntabler
     def update_status(status = self.status)
       assert_valid_values(status, *%w(available unavailable away))
 
-      api('presence.update', :status => status)
+      result = api('presence.update', :status => status)
+      client.reset_keepalive(result['interval']) if result['interval']
       self.attributes = {'status' => status}
+
       true
     end
   end

data/lib/turntabler/client.rb

@@ -99,7 +99,7 @@ module Turntabler
 
         # Create a new connection to the given url
         @connection = Connection.new(url, :timeout => timeout, :params => {:clientid => id, :userid => user.id, :userauth => user.auth})
-        @connection.handler = lambda {|data| on_message(data)}
+        @connection.handler = lambda {|data| trigger(data.delete('command'), data)}
         @connection.start
 
         # Wait until the connection is authenticated
@@ -116,8 +116,8 @@ module Turntabler
     # @return [true]
     def close(allow_reconnect = false)
       if @connection
-        @update_timer.cancel if @update_timer
-        @update_timer = nil
+        @keepalive_timer.cancel if @keepalive_timer
+        @keepalive_timer = nil
         @connection.close
 
         wait do |&resume|
@@ -439,21 +439,64 @@ module Turntabler
       songs || raise(Error, 'Search failed to complete')
     end
 
-    # Callback when a message has been received from Turntable.  This will run
-    # any handlers registered for the event associated with the message.
+    # Triggers callback handlers for the given Turntable command.  This should
+    # either be invoked when responses are received for Turntable or when
+    # triggering custom events.
     # 
-    # @api private
-    # @param [Hash<String, Object>] data The message data received
-    # @return nil
-    def on_message(data)
-      if Event.command?(data['command'])
-        event = Event.new(self, data)
+    # @note If the command is unknown, it will simply get skipped and not raise an exception
+    # @param [Symbol] command The name of the command triggered.  This is typically the same name as the event.
+    # @param [Array] args The arguments to be processed by the event
+    # @return [true]
+    # 
+    # == Triggering custom events
+    # 
+    # After defining custom events, `trigger` can be used to invoke any handler
+    # that's been registered for that event.  The argument list passed into
+    # `trigger` will be passed, exactly as specified, to the registered
+    # handlers.
+    # 
+    # @example
+    #   # Define names of events
+    #   Turntabler.events(:no_args, :one_arg, :multiple_args)
+    #   
+    #   # ...
+    #   
+    #   # Register handlers
+    #   client.on(:no_args) { }
+    #   client.on(:one_arg) {|arg| }
+    #   client.on(:multiple_args) {|arg1, arg2| }
+    #   
+    #   # Trigger handlers registered for events
+    #   client.trigger(:no_args)              # => true
+    #   client.trigger(:one_arg, 1)           # => true
+    #   client.trigger(:multiple_args, 1, 2)  # => true
+    def trigger(command, *args)
+      command = command.to_sym if command
+
+      if Event.command?(command)
+        event = Event.new(self, command, args)
         handlers = @event_handlers[event.name] || []
         handlers.each do |handler|
           success = handler.run(event)
           handlers.delete(handler) if success && handler.once
         end
       end
+
+      true
+    end
+    
+    # Resets the keepalive timer to run at the given interval.
+    # 
+    # @param [Fixnum] interval The frequency with which keepalives get sent (in seconds)
+    # @api private
+    def reset_keepalive(interval = 10)
+      if !@keepalive_timer || @keepalive_interval != interval
+        @keepalive_interval = interval
+
+        # Periodically update the user's status to remain available
+        @keepalive_timer.cancel if @keepalive_timer
+        @keepalive_timer = EM::Synchrony.add_periodic_timer(interval) { user.update(:status => user.status) }
+      end
     end
     
     private
@@ -470,10 +513,7 @@ module Turntabler
       user.authenticate
       user.fan_of
       user.update(:status => user.status)
-      
-      # Periodically update the user's status to remain available
-      @update_timer.cancel if @update_timer
-      @update_timer = EM::Synchrony.add_periodic_timer(10) { user.update(:status => user.status) }
+      reset_keepalive
     end
     
     # Callback when the session has ended.  This will automatically reconnect if
@@ -488,7 +528,7 @@ module Turntabler
       if @reconnect && allow_reconnect
         EM::Synchrony.add_timer(@reconnect_wait) do
           room ? room.enter : connect(url)
-          on_message('command' => 'reconnected')
+          trigger(:reconnected)
         end
       end
     end

data/lib/turntabler/event.rb

@@ -35,7 +35,7 @@ module Turntabler
       # @param [String] command The command to check for the existence of
       # @return [Boolean] +true+ if the command exists, otherwise +false+
       def command?(command)
-        command && commands.include?(command.to_sym)
+        commands.include?(command)
       end
     end
 
@@ -79,7 +79,7 @@ module Turntabler
       data['user'].map do |attrs|
         user = room.build_user(attrs)
         room.listeners << user
-        user
+        [user]
       end
     end
 
@@ -88,7 +88,7 @@ module Turntabler
       data['user'].map do |attrs|
         user = room.build_user(attrs)
         room.listeners.delete(user)
-        user
+        [user]
       end
     end
 
@@ -122,7 +122,8 @@ module Turntabler
     handle :dj_added, :add_dj do
       new_djs = []
       data['user'].each_with_index do |attrs, index|
-        new_djs << user = room.build_user(attrs.merge('placements' => data['placements'][index]))
+        user = room.build_user(attrs.merge('placements' => data['placements'][index]))
+        new_djs << [user]
         room.djs << user
       end
       new_djs
@@ -133,7 +134,7 @@ module Turntabler
       data['user'].map do |attrs|
         user = room.build_user(attrs)
         room.djs.delete(user)
-        user
+        [user]
       end
     end
 
@@ -153,14 +154,14 @@ module Turntabler
 
     # There are no more songs to play in the room
     handle :song_unavailable, :nosong do
-      client.on_message('command' => 'song_ended') if room.current_song
+      client.trigger(:song_ended) if room.current_song
       room.attributes = data['room'].merge('current_song' => nil)
       nil
     end
 
     # A new song has started playing
     handle :song_started, :newsong do
-      client.on_message('command' => 'song_ended') if room.current_song
+      client.trigger(:song_ended) if room.current_song
       room.attributes = data['room']
       room.current_song
     end
@@ -190,13 +191,13 @@ module Turntabler
 
     # A song was skipped due to a copyright claim
     handle :song_blocked do
-      client.on_message('command' => 'song_ended') if room.current_song
+      client.trigger(:song_ended) if room.current_song
       Song.new(client, data)
     end
 
     # A song was skipped due to a limit on # of plays per hour
     handle :song_limited, :dmca_error do
-      client.on_message('command' => 'song_ended') if room.current_song
+      client.trigger(:song_ended) if room.current_song
       Song.new(client, data)
     end
 
@@ -207,7 +208,7 @@ module Turntabler
 
     # A song search has completed and the results are available
     handle :search_completed, :search_complete do
-      [data['docs'].map {|attrs| Song.new(client, attrs)}]
+      [[data['docs'].map {|attrs| Song.new(client, attrs)}]]
     end
 
     # A song search failed to complete
@@ -217,25 +218,29 @@ module Turntabler
     # @return [String]
     attr_reader :name
 
+    # The raw arguments list from the event
+    # @return [Array<Object>]
+    attr_reader :args
+
     # The raw hash of data parsed from the event
     # @return [Hash<String, Object>]
     attr_reader :data
 
-    # The typecasted results parsed from the data
-    # @return [Array]
+    # The typecasted results args parsed from the event
+    # @return [Array<Array<Object>>]
     attr_reader :results
 
     # Creates a new event triggered with the given data
     # 
     # @param [Turntabler::Client] client The client that this event is bound to
     # @param [Hash] data The response data from Turntable
-    def initialize(client, data)
+    def initialize(client, command, args)
       @client = client
-      @data = data
-      command = data['command'].to_sym
+      @args = args
+      @data = args[0]
       @name = self.class.commands[command]
       @results = __send__("typecast_#{command}_event")
-      @results = [@results] unless @results.is_a?(Array)
+      @results = [[@results].compact] unless @results.is_a?(Array)
     end
 
     private

data/lib/turntabler/handler.rb

@@ -46,9 +46,9 @@ module Turntabler
     def run(event)
       if conditions_match?(event.data)
         # Run the block for each individual result
-        event.results.each do |result|
+        event.results.each do |args|
           begin
-            @block.call(*[result].compact)
+            @block.call(*args)
           rescue StandardError => ex
             logger.error(([ex.message] + ex.backtrace) * "\n")
           end

data/lib/turntabler/playlist.rb

@@ -5,6 +5,14 @@ module Turntabler
   # Represents a collection of songs managed by the user and that can be played
   # within a room 
   class Playlist < Resource
+    # Allow the id to be set via the "name" attribute
+    # @return [String]
+    attribute :id, :name, :load => false
+
+    # Whether this is the currently active playlist
+    # @return [Boolean]
+    attribute :active, :load => false
+
     # The songs that have been added to this playlist
     # @return [Array<Turntabler::Song>]
     attribute :songs, :list do |songs|
@@ -30,6 +38,60 @@ module Turntabler
       super()
     end
 
+    # Updates this playlist's information.
+    # 
+    # @param [Hash] attributes The attributes to update
+    # @option attributes [String] :id
+    # @return [true]
+    # @raise [ArgumentError] if an invalid attribute or value is specified
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlist.update(:id => "rock")  # => true
+    def update(attributes = {})
+      assert_valid_keys(attributes, :id)
+
+      # Update id
+      id = attributes.delete(:id)
+      update_id(id) if id
+
+      true
+    end
+
+    # Whether this is the currently active playlist
+    # 
+    # @return [Boolean]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlist.active   # => true
+    def active
+      @active = client.user.playlists.all.any? {|playlist| playlist == self && playlist.active?} if @active.nil?
+      @active
+    end
+
+    # Changes this playlist to be used for queueing new songs with the room.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlist.switch   # => true
+    def activate
+      api('playlist.switch')
+      self.attributes = {'active' => true}
+      true
+    end
+
+    # Permanently deletes this playlist and the list of songs within it.  If this
+    # is the currently active playlist, the "default" playlist will become active.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlist.delete   # => true
+    def delete
+      api('playlist.delete')
+      true
+    end
+
     # Gets the song with the given id.
     # 
     # @param [String] song_id The id for the song
@@ -42,6 +104,13 @@ module Turntabler
     end
 
     private
+    # Updates the name used to identify this playlist
+    def update_id(id)
+      client.api('playlist.rename', :old_playlist_name => self.id, :new_playlist_name => id)
+      self.attributes = {'name' => id}
+      true
+    end
+
     def api(command, options = {})
       options[:playlist_name] = id
       super

data/lib/turntabler/playlist_directory.rb

@@ -0,0 +1,70 @@
+require 'turntabler/playlist'
+
+module Turntabler
+  # Provides a set of helper methods for interacting with a user's playlists.
+  class PlaylistDirectory
+    include Assertions
+
+    # @api private
+    def initialize(client)
+      @client = client
+      @playlists = {}
+    end
+
+    # Creates a new playlist with the given id.  This should only be used if
+    # the playlist doesn't already exist.
+    # 
+    # @note This will automatically enter the playlist when it is created
+    # @param [String] id The unique identifier of the playlist
+    # @return [Turntabler::Playlist]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlists.create("Rock")  # => #<Turntabler::Playlist ...>
+    def create(id)
+      api('playlist.create', :playlist_name => id)
+      build(:_id => id)
+    end
+
+    # Gets the list of playlists created.
+    # 
+    # @return [Array<Turntabler::Playlist>]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlists.all   # => [#<Turntabler::Playlist ...>, ...]
+    def all
+      data = api('playlist.list_all')
+      data['list'].map {|attrs| build(attrs)}
+    end
+
+    # Gets the playlist represented by the given attributes.
+    # 
+    # If the playlist hasn't been previously accessed, then a new Playlist
+    # instance will get created.
+    # 
+    # @api private
+    # @param [Hash] attrs The attributes representing the playlist
+    # @return [Turntabler::Playlist]
+    def build(attrs)
+      playlist = Playlist.new(client, attrs)
+
+      # Update existing in cache or cache a new playlist
+      if existing = @playlists[playlist.id]
+        playlist = existing
+        playlist.attributes = attrs
+      else
+        @playlists[playlist.id] = playlist
+      end
+
+      playlist
+    end
+
+    private
+    # The client that all APIs filter through
+    attr_reader :client
+
+    # Runs the given API command on the client.
+    def api(command, options = {})
+      client.api(command, options)
+    end
+  end
+end

data/lib/turntabler/room_directory.rb

@@ -54,11 +54,11 @@ module Turntabler
     # @raise [ArgumentError] if an invalid option or value is specified
     # @raise [Turntabler::Error] if the command fails
     # @example
-    #   rooms.list                                          # => [#<Turntabler::Room ...>, ...]
-    #   rooms.list(:favorites => true)                      # => [#<Turntabler::Room ...>, ...]
-    #   rooms.list(:available_djs => true, :genre => :rock) # => [#<Turntabler::Room ...>, ...]
-    #   rooms.list(:sort => :random)                        # => [#<Turntabler::Room ...>, ...]
-    def list(options = {})
+    #   rooms.all                                           # => [#<Turntabler::Room ...>, ...]
+    #   rooms.all(:favorites => true)                       # => [#<Turntabler::Room ...>, ...]
+    #   rooms.all(:available_djs => true, :genre => :rock)  # => [#<Turntabler::Room ...>, ...]
+    #   rooms.all(:sort => :random)                         # => [#<Turntabler::Room ...>, ...]
+    def all(options = {})
       assert_valid_keys(options, :limit, :skip, :favorites, :available_djs, :genre, :minimum_listeners, :sort)
       assert_valid_values(options[:genre], :rock, :electronic, :indie, :hiphop, :pop, :dubstep) if options[:genre]
       assert_valid_values(options[:sort], :created, :listeners, :random) if options[:sort]

data/lib/turntabler/version.rb

@@ -2,8 +2,8 @@ module Turntabler
   # The current version of the library
   module Version
     MAJOR = 0
-    MINOR = 1
-    PATCH = 4
+    MINOR = 2
+    PATCH = 0
     STRING = [MAJOR, MINOR, PATCH].join(".")
   end
 end

data/lib/turntabler.rb

@@ -4,6 +4,7 @@ require 'em-synchrony'
 # Turntable.FM API for Ruby
 module Turntabler
   autoload :Client, 'turntabler/client'
+  autoload :Event, 'turntabler/event'
 
   class << self
     # The logger to use for all Turntable messages.  By default, everything is
@@ -97,6 +98,25 @@ module Turntabler
         EM.synchrony { run(*args, &block) }
       end
     end
+
+    # Defines one or more custom events for which handlers can be registered
+    # and triggered via Turntabler::Client#on and Turntabler::Client#trigger,
+    # respectively.
+    # 
+    # @note Events must be defined before handlers can be registered for them
+    # @param [Array<String>] names The names of the events to define
+    # @raise [ArgumentError] if the event has already been defined
+    # @example
+    #   Turntabler::Client.events :custom_event1, :custom_event2
+    def events(*names)
+      names.each do |name|
+        if Event.command?(name)
+          raise ArgumentError, "Event :#{name} is already defined"
+        else
+          Event.handle(name) { [args] }
+        end
+      end
+    end
   end
 
   @logger = Logger.new(STDOUT)

metadata

@@ -1,121 +1,94 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: turntabler
-version: !ruby/object:Gem::Version
-  version: 0.1.4
+version: !ruby/object:Gem::Version 
   prerelease: 
+  version: 0.2.0
 platform: ruby
-authors:
+authors: 
 - Aaron Pfeifer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-08 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2013-02-16 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: em-synchrony
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: em-http-request
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: em-http-request
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: faye-websocket
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: faye-websocket
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
   name: rake
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '2.11'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
-        version: '2.11'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+      - !ruby/object:Gem::Version 
+        version: "2.11"
   type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: simplecov
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id006
 description: Turntable.FM API for Ruby
 email: aaron.pfeifer@gmail.com
 executables: []
+
 extensions: []
-extra_rdoc_files:
+
+extra_rdoc_files: 
 - README.md
 - CHANGELOG.md
 - LICENSE
-files:
+files: 
 - .gitignore
 - .rspec
 - .yardopts
@@ -149,6 +122,7 @@ files:
 - lib/turntabler/loggable.rb
 - lib/turntabler/message.rb
 - lib/turntabler/playlist.rb
+- lib/turntabler/playlist_directory.rb
 - lib/turntabler/preferences.rb
 - lib/turntabler/resource.rb
 - lib/turntabler/room.rb
@@ -165,33 +139,36 @@ files:
 - turntabler.gemspec
 homepage: http://github.com/obrie/turntabler
 licenses: []
+
 post_install_message: 
-rdoc_options:
+rdoc_options: 
 - --line-numbers
 - --inline-source
 - --title
 - turntabler
 - --main
 - README.md
-require_paths:
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
 requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Turntable.FM API for Ruby
 test_files: []
+
 has_rdoc: