turntabler 0.0.1

data/lib/turntabler/event.rb

@@ -0,0 +1,239 @@
+require 'turntabler/boot'
+require 'turntabler/message'
+require 'turntabler/snag'
+require 'turntabler/song'
+
+module Turntabler
+  # Provides access to all of the events that get triggered by incoming messages
+  # from the Turntable API
+  # @api private
+  class Event
+    class << self
+      # Maps Turntable command => event name
+      # @return [Hash<String, String>]
+      attr_reader :commands
+
+      # Defines a new event that maps to the given Turntable command.  The
+      # block defines how to typecast the data that is received from Turntable.
+      # 
+      # @param [String] name The name of the event exposed to the rest of the library
+      # @param [String] command The Turntable command that this event name maps to
+      # @yield [data] Gives the data to typecast to the block
+      # @yieldparam [Hash] data The data received from Turntable
+      # @yieldreturn The typecasted data that should be passed into any handlers bound to the event
+      # @return [nil]
+      def handle(name, command = name, &block)
+        block ||= lambda {}
+        commands[command] = name
+
+        define_method("typecast_#{command}_event", &block)
+        protected :"typecast_#{command}_event"
+      end
+      
+      # Determines whether the given command is handled
+      # 
+      # @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)
+      end
+    end
+
+    @commands = {}
+
+    # An authenticated session is missing
+    handle :session_missing, :no_session
+
+    # The client is being asked to disconnect
+    handle :session_end_requested, :killdashnine do
+      room_id = data['roomid']
+      if !room_id || room && room.id == room_id
+        client.close(true)
+        data['msg'] || 'Unknown reason'
+      end
+    end
+
+    # The client's connection has closed
+    handle :session_ended
+
+    # A heartbeat was received from Turntable to ensure the client's connection
+    # is still valid
+    handle :heartbeat
+
+    # A response was receivied from a prior command sent to Turntable
+    handle :response_received do
+      data
+    end
+
+    # Information about the room was updated
+    handle :room_updated, :update_room do
+      room.attributes = data
+      room
+    end
+
+    # One or more users have entered the room
+    handle :user_entered, :registered do
+      data['user'].map do |attrs|
+        user = room.build_user(attrs)
+        room.listeners << user
+        user
+      end
+    end
+
+    # One or more users have left the room
+    handle :user_left, :deregistered do
+      data['user'].map do |attrs|
+        user = room.build_user(attrs)
+        room.listeners.delete(user)
+        user
+      end
+    end
+
+    # A user has been booted from the room
+    handle :user_booted, :booted_user do
+      boot = Boot.new(client, data)
+      client.room = nil if boot.user == client.user
+      boot
+    end
+
+    # A user's name / profile has been updated
+    handle :user_updated, :update_user do
+      fans_change = data.delete('fans')
+      user = room.build_user(data)
+      user.attributes = {'fans' => user.fans_count + fans_change} if fans_change
+      user
+    end
+
+    # A user's stickers have been updated
+    handle :user_updated, :update_sticker_placements do
+      room.build_user(data)
+    end
+
+    # A user spoke in the chat room
+    handle :user_spoke, :speak do
+      Message.new(client, data)
+    end
+
+    # A new dj was added to the room
+    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]))
+        room.listeners << user
+        room.djs << user
+      end
+      new_djs
+    end
+
+    # A dj was removed from the room
+    handle :dj_removed, :rem_dj do
+      data['user'].map do |attrs|
+        user = room.build_user(attrs)
+        room.listeners << user
+        room.djs.delete(user)
+        user
+      end
+    end
+
+    # A new moderator was added to the room
+    handle :moderator_added, :new_moderator do
+      user = room.build_user(data)
+      room.listeners << user
+      room.moderators << user
+      user
+    end
+
+    # A moderator was removed from the room
+    handle :moderator_removed, :rem_moderator do
+      user = room.build_user(data)
+      room.moderators.delete(user)
+      user
+    end
+
+    # There are no more songs to play in the room
+    handle :song_unavailable, :nosong do
+      room.attributes = data['room'].merge('current_song' => nil)
+      nil
+    end
+
+    # A new song has started playing
+    handle :song_started, :newsong do
+      room.attributes = data['room']
+      room.current_song
+    end
+
+    # The current song has ended
+    handle :song_ended, :endsong do
+      room.attributes = data['room']
+      room.current_song
+    end
+
+    # A vote was cast for the song
+    handle :song_voted, :update_votes do
+      room.attributes = data['room']
+      room.current_song
+    end
+
+    # A user in the room has queued the current song onto their playlist
+    handle :song_snagged, :snagged do
+      Snag.new(client, data.merge(:song => room.current_song))
+    end
+
+    # A song was skipped due to a copyright claim
+    handle :song_blocked do
+      Song.new(client, data)
+    end
+
+    # A song was skipped due to a limit on # of plays per hour
+    handle :song_limited, :dmca_error do
+      Song.new(client, data)
+    end
+
+    # A private message was received from another user in the room
+    handle :message_received, :pmmed do
+      Message.new(client, data)
+    end
+
+    # A song search has completed and the results are available
+    handle :search_completed, :search_complete do
+      [data['docs'].map {|attrs| Song.new(client, attrs)}]
+    end
+
+    # A song search failed to complete
+    handle :search_failed
+    
+    # The name of the event that was triggered
+    # @return [String]
+    attr_reader :name
+    
+    # The raw hash of data parsed from the event
+    # @return [Hash]
+    attr_reader :data
+    
+    # The typecasted results parsed from the data
+    # @return [Array]
+    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)
+      @client = client
+      @data = data
+      command = data['command'].to_sym
+      @name = self.class.commands[command]
+      @results = __send__("typecast_#{command}_event")
+      @results = [@results] unless @results.is_a?(Array)
+    end
+    
+    private
+    # The client that all APIs filter through
+    attr_reader :client
+    
+    # Gets the current room the user is in
+    def room
+      client.room
+    end
+  end
+end

data/lib/turntabler/handler.rb

@@ -0,0 +1,67 @@
+require 'turntabler/event'
+
+module Turntabler
+  # Represents a callback that's been bound to a particular event
+  # @api private
+  class Handler
+    include Assertions
+
+    # The event this handler is bound to
+    # @return [String]
+    attr_reader :event
+    
+    # Whether to only call the handler once and then never again
+    # @return [Boolean] +true+ if only called once, otherwise +false+
+    attr_reader :once
+    
+    # The data that must be matched in order for the handler to run
+    # @return [Hash<String, Object>]
+    attr_reader :conditions
+    
+    # Builds a new handler bound to the given event.
+    # 
+    # @param [String] event The name of the event to bind to
+    # @param [Hash] options The configuration options
+    # @option options [Boolean] :once (false) Whether to only call the handler once
+    # @option options [Hash] :if (nil) Data that must be matched to run
+    # @raise [ArgumentError] if an invalid option is specified
+    def initialize(event, options = {}, &block)
+      assert_valid_values(event, *Event.commands.values)
+      assert_valid_keys(options, :once, :if)
+      options = {:once => false, :if => nil}.merge(options)
+
+      @event = event
+      @once = options[:once]
+      @conditions = options[:if]
+      @block = block
+    end
+    
+    # Runs this handler with results from the given event.
+    # 
+    # @param [Array] event The event being triggered
+    # @return [Boolean] +true+ if conditions were matcher to run the handler, otherwise +false+
+    def run(event)
+      if conditions_match?(event.data)
+        # Run the block for each individual result
+        event.results.each do |result|
+          @block.call(*[result].compact)
+        end
+        
+        true
+      else
+        false
+      end
+    end
+
+    private
+    # Determines whether the conditions configured for this handler match the
+    # event data
+    def conditions_match?(data)
+      if conditions
+        conditions.all? {|(key, value)| data[key] == value}
+      else
+        true
+      end
+    end
+  end
+end

data/lib/turntabler/loggable.rb

@@ -0,0 +1,11 @@
+module Turntabler
+  # Provides a set of helper methods for logging
+  # @api private
+  module Loggable
+    private
+    # Delegates access to the logger to Turntabler.logger
+    def logger
+      Turntabler.logger
+    end
+  end
+end

data/lib/turntabler/message.rb

@@ -0,0 +1,24 @@
+require 'turntabler/resource'
+require 'turntabler/user'
+
+module Turntabler
+  # Represents a message that was sent to or from the current user.  This can
+  # either be within the context of a room or a private conversation.
+  class Message < Resource
+    # The user who sent the message
+    # @return [Turntabler::User]
+    attribute :sender, :senderid do |id|
+      room? ? room.build_user(:_id => id) : User.new(client, :_id => id)
+    end
+
+    # The text of the message
+    # @return [String]
+    attribute :content, :text
+
+    # The time at which the message was created
+    # @return [Time]
+    attribute :created_at, :time do |value|
+      Time.at(value)
+    end
+  end
+end

data/lib/turntabler/playlist.rb

@@ -0,0 +1,50 @@
+require 'turntabler/resource'
+require 'turntabler/song'
+
+module Turntabler
+  # Represents a collection of songs managed by the user and that can be played
+  # within a room 
+  class Playlist < Resource
+    # The songs that have been added to this playlist
+    # @return [Array<Turntabler::Song>]
+    attribute :songs, :list do |songs|
+      songs.map {|attrs| Song.new(client, attrs)}
+    end
+
+    # Loads the attributes for this playlist.  Attributes will automatically load
+    # when accessed, but this allows data to be forcefully loaded upfront.
+    # 
+    # @param [Hash] options The configuration options
+    # @option options [Boolean] minimal (false) Whether to only include the identifiers for songs and not the entire metadata
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   playlist.load   # => true
+    #   playlist.songs  # => [#<Turntabler::Song ...>, ...]
+    def load(options = {})
+      assert_valid_keys(options, :minimal)
+      options = {:minimal => false}.merge(options)
+
+      data = api('playlist.all', options)
+      self.attributes = data
+      super()
+    end
+    
+    # Gets the song with the given id.
+    # 
+    # @param [String] song_id The id for the song
+    # @return [Turntabler::Song]
+    # @raise [Turntabler::Error] if the list of songs fail to load
+    # @example
+    #   playlist.song('4fd8...')    # => #<Turntabler::Song ...>
+    def song(song_id)
+      songs.detect {|song| song.id == song_id}
+    end
+
+    private
+    def api(command, options = {})
+      options[:playlist_name] = id
+      super
+    end
+  end
+end

data/lib/turntabler/preferences.rb

@@ -0,0 +1,70 @@
+require 'turntabler/resource'
+
+module Turntabler
+  # Represents the site preferences for the authorized user
+  class Preferences < Resource
+    # Send e-mails if a fan starts DJing
+    # @return [Boolean]
+    attribute :notify_dj
+    
+    # Send e-mails when someone becomes a fan
+    # @return [Boolean]
+    attribute :notify_fan
+    
+    # Sends infrequent e-mails about news
+    # @return [Boolean]
+    attribute :notify_news
+    
+    # Sends e-mails at random times with a different subsection of the digits of pi
+    # @return [Boolean]
+    attribute :notify_random
+    
+    # Publishes to facebook songs awesomed in public rooms
+    # @return [Boolean]
+    attribute :facebook_awesome
+    
+    # Publishes to facebook when a public room is joined
+    # @return [Boolean]
+    attribute :facebook_join
+    
+    # Publishes to facebook when DJing in a public room
+    # @return [Boolean]
+    attribute :facebook_dj
+    
+    # Loads the user's current Turntable preferences.
+    # 
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   preferences.load    # => true
+    def load
+      data = api('user.get_prefs')
+      self.attributes = data['result'].inject({}) do |result, (preference, value, id, description)|
+        result[preference] = value
+        result
+      end
+      super
+    end
+
+    # Updates the preferences.
+    # 
+    # @param [Hash] attributes The attributes to update
+    # @option attributes [Boolean] :notify_dj
+    # @option attributes [Boolean] :notify_fan
+    # @option attributes [Boolean] :notify_news
+    # @option attributes [Boolean] :notify_random
+    # @option attributes [Boolean] :facbeook_awesome
+    # @option attributes [Boolean] :facebook_join
+    # @option attributes [Boolean] :facebook_dj
+    # @return [true]
+    # @raise [Turntabler::Error] if the command fails
+    # @example
+    #   preferences.update(:notify_dj => false)   # => true
+    def update(attributes = {})
+      assert_valid_values(attributes, :notify_dj, :notify_fan, :notify_news, :notify_random, :facebook_awesome, :facebook_join, :facebook_dj)
+      api('user.edit_prefs', attributes)
+      self.attributes = attributes
+      true
+    end
+  end
+end

data/lib/turntabler/resource.rb

@@ -0,0 +1,194 @@
+require 'pp'
+require 'digest/sha1'
+require 'turntabler/assertions'
+require 'turntabler/digest_helpers'
+
+module Turntabler
+  # Represents an object that's been created using content from Turntable. This
+  # encapsulates responsibilities such as reading and writing attributes.
+  # 
+  # By default all Turntable resources have a +:id+ attribute defined.
+  class Resource
+    include Assertions
+    include DigestHelpers
+
+    class << self
+      include Assertions
+      
+      # Defines a new Turntable attribute on this class.  By default, the name
+      # of the attribute is assumed to be the same name that Turntable specifies
+      # in its API.  If the names are different, this can be overridden on a
+      # per-attribute basis.
+      # 
+      # Configuration options:
+      # * +:load+ - Whether the resource should be loaded remotely from
+      #   Turntable in order to access the attribute.  Default is true.
+      # 
+      # == Examples
+      # 
+      #   # Define a "name" attribute that maps to a Turntable "name" attribute
+      #   attribute :name
+      #   
+      #   # Define an "id" attribute that maps to a Turntable "_id" attribute
+      #   attribute :id, :_id
+      #   
+      #   # Define an "user_id" attribute that maps to both a Turntable "user_id" and "userid" attribute
+      #   attribute :user_id, :user_id, :userid
+      #   
+      #   # Define a "time" attribute that maps to a Turntable "time" attribute
+      #   # and converts the value to a Time object
+      #   attribute :time do |value|
+      #     Time.at(value)
+      #   end
+      #   
+      #   # Define a "created_at" attribute that maps to a Turntable "time" attribute
+      #   # and converts the value to a Time object
+      #   attribute :created_at, :time do |value|
+      #     Time.at(value)
+      #   end
+      #   
+      #   # Define a "friends" attribute that does *not* get loaded from Turntable
+      #   # when accessed
+      #   attribute :friends, :load => false
+      # 
+      # @api private
+      # @!macro [attach] attribute
+      #   @!attribute [r] $1
+      def attribute(name, *turntable_names, &block)
+        options = turntable_names.last.is_a?(Hash) ? turntable_names.pop : {}
+        assert_valid_keys(options, :load)
+        options = {:load => true}.merge(options)
+
+        # Reader
+        define_method(name) do
+          load if instance_variable_get("@#{name}").nil? && !loaded? && options[:load]
+          instance_variable_get("@#{name}")
+        end
+        
+        # Query
+        define_method("#{name}?") do
+          !!__send__(name)
+        end
+        
+        # Typecasting
+        block ||= lambda {|value| value}
+        define_method("typecast_#{name}", &block)
+        protected :"typecast_#{name}"
+
+        # Attribute name conversion
+        turntable_names = [name] if turntable_names.empty?
+        turntable_names.each do |turntable_name|
+          define_method("#{turntable_name}=") do |value|
+            instance_variable_set("@#{name}", value.nil? ? nil : __send__("typecast_#{name}", value))
+          end
+          protected :"#{turntable_name}="
+        end
+      end
+    end
+
+    # The unique identifier for this resource
+    # @return [String, Fixnum]
+    attribute :id, :_id, :load => false
+
+    # Initializes this resources with the given attributes.  This will continue
+    # to call the superclass's constructor with any additional arguments that
+    # get specified.
+    # 
+    # @api private
+    def initialize(client, attributes = {}, *args)
+      @loaded = false
+      @client = client
+      self.attributes = attributes
+      super(*args)
+    end
+
+    # Loads the attributes for this resource from Turntable.  By default this is
+    # a no-op and just marks the resource as loaded.
+    # 
+    # @return [true]
+    def load
+      @loaded = true
+    end
+    alias :reload :load
+
+    # Determines whether the current resource has been loaded from Turntable.
+    # 
+    # @return [Boolean] +true+ if the resource has been loaded, otherwise +false+
+    def loaded?
+      @loaded
+    end
+
+    # Attempts to set attributes on the object only if they've been explicitly
+    # defined by the class.  Note that this will also attempt to interpret any
+    # "metadata" properties as additional attributes.
+    # 
+    # @api private
+    def attributes=(attributes)
+      if attributes
+        attributes.each do |attribute, value|
+          attribute = attribute.to_s
+          if attribute == 'metadata'
+            self.attributes = value
+          else
+            __send__("#{attribute}=", value) if respond_to?("#{attribute}=")
+          end
+        end
+      end
+    end
+    
+    # Forces this object to use PP's implementation of inspection.
+    # 
+    # @api private
+    def pretty_print(q)
+      q.pp_object(self)
+    end
+    alias inspect pretty_print_inspect
+
+    # Defines the instance variables that should be printed when inspecting this
+    # object.  This ignores the +client+ and +loaded+ attributes.
+    # 
+    # @api private
+    def pretty_print_instance_variables
+      (instance_variables - [:'@client', :'@loaded']).sort
+    end
+
+    # Determines whether this resource is equal to another based on their
+    # unique identifiers.
+    # 
+    # @return [Boolean] +true+ if the resource ids are equal, otherwise +false+
+    def ==(other)
+      if other && other.respond_to?(:id) && other.id
+        other.id == id
+      else
+        false
+      end
+    end
+    alias :eql? :==
+
+    # Generates a hash for this resource based on the unique identifier
+    # 
+    # @return [Fixnum]
+    def hash
+      id.hash
+    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
+
+    # Gets the current room the user is in
+    def room
+      client.room || raise(Turntabler::Error, 'User is not currently in a room')
+    end
+    
+    # Determines whether the user is currently in a room
+    def room?
+      !client.room.nil?
+    end
+  end
+end