claudiob-yesradio 0.0.1 → 0.0.2

data/.gitignore

@@ -1 +1,3 @@
 .DS_Store
+doc/*
+pkg/**/*

data/README.md

@@ -5,18 +5,63 @@ Ruby gem to access Yes.com API
 <a name="rubygem_install" />
 ## Installation ##
 
-    sudo gem install yesradio -s http://gems.github.com
+    sudo gem install claudiob-yesradio -s http://gems.github.com
+
+## Documentation ##
+
+http://rdoc.info/projects/claudiob/yesradio
 
 ## Examples ##
 
 ### To show a list of 'Rock' stations ###
 
     require 'yesradio'
-    query = Yesradio::StationsSearchCriteria.new
-    query.match = "KWOF"
-    result = Yesradio::search_stations query  
+    Yesradio::search_stations :match => "Rock"
 
 ### To show details of 'WFNX' radio ###
 
     require 'yesradio'
-    Yesradio::match_station "WFNX"
+    Yesradio::get_station "WFNX"
+
+### To show log of tracks played on 'WFNX' radio ###
+
+    require 'yesradio'
+    Yesradio::get_log "WFNX"
+
+### To show recent tracks played on 'WFNX' radio ###
+
+    require 'yesradio'
+    Yesradio::get_recent "WFNX"
+
+### To show a chart of popular Rock songs ###
+
+    require 'yesradio'
+    Yesradio::get_chart :genre => "Rock"
+
+### To show a list of songs by artist Rihanna ###
+
+    require 'yesradio'
+    Yesradio::get_media :aid => 610471
+
+### To show a list of songs related to Umbrella (Rihanna) ###
+
+    require 'yesradio'
+    Yesradio::get_related :mid => 11586843
+
+
+## History ##
+
+v0.0.2  2009/09/15
+        Added support for actions: chart, media, related.
+        Added documentation through RDoc.
+        Added cucumber features for listing stations.
+
+v0.0.1  2009/09/15
+        Added support for actions: log, recent.
+
+v0.0.0  2009/09/14
+        Added support for actions: station, stations
+
+## Copyright ##
+
+Copyright (c) 2009 Claudio Baccigalupo. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/features/step_definitions/yesradio_steps.rb

@@ -0,0 +1,17 @@
+Given /^nothing$/ do
+  
+end
+
+When /^I look for ([0-9]+) stations called "([^\"]*)"$/ do |max, match|
+  @stations = Yesradio::search_stations :match => match, :max => max
+end
+
+Then /^I should see a radio with name "([^\"]*)" and market "([^\"]*)"$/ do |name, market|
+  @stations.collect do |station| 
+    station.name == name && station.market == market
+  end.inject{ |sum, el| sum || el }.should be_true
+end
+
+Then /^I should see nothing$/ do
+  @stations.should be_nil
+end

data/features/yesradio.feature

@@ -1,9 +1,14 @@
-Feature: something something
-  In order to something something
-  A user something something
-  something something something
+Feature: Call Yes.com API using Ruby
+  In order to retrieve Yes.com data in Ruby code
+  programmers
+  want a Ruby interface to Yes.com API
 
-  Scenario: something something
-    Given inspiration
-    When I create a sweet new gem
-    Then everyone should see how awesome I am
+  Scenario: List Stations
+    Given nothing
+    When I look for 10 stations called "KEXP"
+    Then I should see a radio with name "KEXP" and market "Seattle - Tacoma, WA"
+
+  Scenario: List Stations Empty
+    Given nothing
+    When I look for 10 stations called "ABCDEFGH"
+    Then I should see nothing

data/lib/item.rb

@@ -0,0 +1,36 @@
+# Author::    Claudio Baccigalupo
+# Copyright:: Copyright (c) 2009 - see LICENSE file
+
+require 'date'
+
+module Yesradio
+  class Item
+    class << self
+      attr_accessor :elements 
+    end
+    
+    def initialize(element = nil)
+      self.class.elements.each do |name, type|
+        new_value = get_element_child element, name.gsub('_', '/'), type
+        self.instance_variable_set("@#{name}", new_value) unless new_value.nil?
+      end
+    end
+
+    private
+
+    def get_element_child(element, child, type = :text)
+      return if element.nil? || element.elements[child].nil?
+      child = element.elements[child][0].to_s
+      return case type
+        when :int then child.to_i
+        when :float then child.to_f 
+        when :datetime then DateTime.parse(child)
+        else child
+      end
+
+    end
+
+  end
+end
+
+

data/lib/main.rb

@@ -1,24 +1,7 @@
-#=============================================================================
-#
-# 2009 Claudio Baccigalupo
-#
-# Licensed under the Ruby License
-#
-#=============================================================================
+# Author::    Claudio Baccigalupo
+# Copyright:: Copyright (c) 2009 - see LICENSE file
 
 require 'yesradio'
 
-# get the list of radio stations
-query = Yesradio::StationsSearchCriteria.new
-query.match = "KWOF"
-stations = Yesradio::search_stations query  
-p stations
-
-# get the details of a radio station
-Yesradio::match_station "WFNX"
-
-# get the log of songs played on a radio
-Yesradio::get_log "KEXP"
-
-# get the recent songs played on a radio
-Yesradio::get_recent "KEXP"
+# TODO: a file that prompts the user for the action to take
+# and the parameters, and returns the result (as a shell command)

data/lib/song.rb

@@ -1,20 +1,14 @@
-#=============================================================================
-#
-# 2009 Claudio Baccigalupo
-#
-# Licensed under the Ruby License
-#
-#=============================================================================
+# Author::    Claudio Baccigalupo
+# Copyright:: Copyright (c) 2009 - see LICENSE file
 
+require 'item'
 module Yesradio
-  class Song
-    @@elements = {'at' => :datetime, 'by' => :text, 'title' => :text, 
+  class Song < Item
+    @elements = {'at' => :datetime, 'by' => :text, 'title' => :text, 
                   'id' => :int, 'type' => :text, 'rank' => :int, 
-                  'cover' => :text, 'video' => :text, 'ago' => :int}
-    attr_accessor *@@elements.keys
-    def elements
-      @@elements
-    end  
+                  'cover' => :text, 'video' => :text, 'link' => :text,
+                  'ago' => :int}
+    attr_accessor *@elements.keys
   end
 end
 

data/lib/station.rb

@@ -1,22 +1,15 @@
-#=============================================================================
-#
-# 2009 Claudio Baccigalupo
-#
-# Licensed under the Ruby License
-#
-#=============================================================================
+# Author::    Claudio Baccigalupo
+# Copyright:: Copyright (c) 2009 - see LICENSE file
 
+require 'item'
 module Yesradio
-  class Station
-    @@elements = {'name' => :text, 'desc' => :text, 'genre' => :text, 
+  class Station < Item
+    @elements = {'name' => :text, 'desc' => :text, 'genre' => :text, 
                   'market' => :text, 'type' => :text, 'id' => :int, 
                   'tz' => :text, 'stream' => :text, 'yes' => :text, 
                   'relay' => :text, 'audiostream' => :text, 'array_id' => :int,
                   'array_song' => :text, 'array_artist' => :text}
-    attr_accessor *@@elements.keys
-    def elements
-      @@elements
-    end  
+    attr_accessor *@elements.keys
   end
 end
 

data/lib/yesradio.rb

@@ -1,15 +1,9 @@
-#=============================================================================
-#
-# 2009 Claudio Baccigalupo
-#
-# Licensed under the Ruby License
-#
-#=============================================================================
+# Author::    Claudio Baccigalupo
+# Copyright:: Copyright (c) 2009 - see LICENSE file
 
 require 'cgi'
 require 'net/http'
 require 'rexml/document'
-require 'date'
 
 require 'station'
 require 'stations_search_criteria'
@@ -20,103 +14,136 @@ module Yesradio
   YESRADIO_VERSION = 1
   YESRADIO_SERVER = "http://api.yes.com/#{YESRADIO_VERSION}"
 
-  def self.element_to_station(element)
-    station = Station.new
-    station.elements.each do |name, type|
-      new_value = get_element_child element, name.gsub('_', '/'), type
-      station.instance_variable_set("@#{name}", new_value) unless new_value.nil?
-    end
-    station
+  # Get current information about a single station including now playing song, 
+  # slogan, frequency, market, and links to any known webcast stream or site.
+  #
+  # == Parameters
+  # [+name+] The station name (for AM/FM it is just the call letters).
+  #
+  # == Examples
+  #     get_station :name => "KEXP"
+  #--
+  def self.get_station(query_hash)
+    array = self.search('Station', "station", "//api", query_hash)
+    array[0] unless array.nil? || array[0].name.nil?
   end
 
-  # TO DO, dry with the previous function
-  def self.element_to_song(element)
-    song = Song.new
-    song.elements.each do |name, type|
-      new_value = get_element_child element, name.gsub('_', '/'), type
-      song.instance_variable_set("@#{name}", new_value) unless new_value.nil?
-    end
-    song
+  # Search and find a list of stations by name, frequency, genre, artist, 
+  # or location.
+  #
+  # == Parameters
+  # [+match+] [optional] Used to search station names, call letters, slogans, frequency, or cities/states.
+  # [+freq+] [optional] Also match an exact AM/FM frequency.
+  # [+mid+] [optional] Also match only stations that have this media id (see #media call) in their top 100 charts.
+  # [+genre+] [optional] Also match any genre keywords like pop, rock, etc.
+  # [+loc+] [optional] Also match stations within 60 miles of the given zip code, "lat,lon", or city/state names.
+  # [+max+] [optional] Defaults to 10 stations returned.
+  #
+  # == Examples
+  #     search_stations :match => "KEX"
+  #--
+  def self.search_stations(query_hash)
+    self.search('Station', "stations", "//api/array/stations", query_hash)
   end
 
-  def self.search_stations(search_criteria)
-    stations = Array.new
+  # Get the log of all the songs played on the given station in a selected day 
+  # within the last week. 
+  #
+  # == Parameters
+  # [+name+] The station name.
+  # [+ago+] [optional] The days ago from now for the given date you want, an integer from 0-6 and defaults to 0 (the log today so far).
+  #
+  # == Examples
+  #     get_log :name => "KEXP", :ago => 3
+  #--
+  def self.get_log(query_hash)
+    self.search('Song', "log", "//api/array/songs", query_hash)
+  end
 
-    url = Yesradio::YESRADIO_SERVER + "/stations?type=xml"
-    url = url + search_criteria.to_query_params_string
-    uri = URI.parse(url)
-    req = Net::HTTP::Get.new(uri.path + '?' + uri.query)
-    res = Net::HTTP.start(uri.host, uri.port) { |http|
-      http.request(req)
-    }
-    doc = REXML::Document.new res.body
-    doc.elements.each("//api/array/stations") do |element|
-      stations << element_to_station(element)
-    end
-    stations
+  # Get the most recent songs played on any station.
+  #
+  # == Parameters
+  # [+name+] The station name.
+  # [+max+] How many recent songs to return (default is 10).
+  #
+  # == Examples
+  #     get_recent :name => "KEXP", :max => 3
+  #--
+  def self.get_recent(query_hash)
+    self.search('Song', "recent", "//api/array/songs", query_hash)
   end
 
-  def self.get_station(station_name)
-    url = Yesradio::YESRADIO_SERVER + "/station?type=xml"
-    url = url + "&name=" + CGI::escape(station_name)
-    uri = URI.parse(url)
-    req = Net::HTTP::Get.new(uri.path + '?' + uri.query)
-    res = Net::HTTP.start(uri.host, uri.port) { |http|
-      http.request(req)
-    }
-    doc = REXML::Document.new res.body
-    element_to_station(doc.elements["//api"])
+  # Get the current top 100 songs for any station based on number of times 
+  # played and user voting (calculated daily).
+  #
+  # == Parameters
+  # [+name+] [optional] The station name, defaults to US national top 100 if none given.
+  # [+date+] [optional] Return just the charts from a specific date in the format year-mm-dd (April 2008 and newer).
+  # [+genre+] [optional] Filter any request to a specific Genre ( Americana Blues Christian Classical Country Electronica Hip-Hop Jazz Latin Metal New Age Pop Punk R&B/Soul Rock Smooth Jazz World ).
+  # [+hot+] [optional] Alternative sorting, must be either "fresh" (by most increase in charts day-to-day, not supported in combination with date field) or "vote" (most votes via yes.com).
+  # [+max+] How many songs to return (default is 10).
+  #
+  # == Examples
+  #     get_chart :genre => "Rock"
+  #--
+  def self.get_chart(query_hash)
+    self.search('Song', "chart", "//api/array/songs", query_hash)
   end
 
-  def self.get_log(station_name, ago = nil)
-    songs = Array.new
-    
-    url = Yesradio::YESRADIO_SERVER + "/log?type=xml"
-    url = url + "&name=" + CGI::escape(station_name)
-    url = url + "&ago=" + CGI::escape(ago.to_s) unless ago.nil?
-    uri = URI.parse(url)
-    req = Net::HTTP::Get.new(uri.path + '?' + uri.query)
-    res = Net::HTTP.start(uri.host, uri.port) { |http|
-      http.request(req)
-    }
-    doc = REXML::Document.new res.body
-    doc.elements.each("//api/array/songs") do |element|
-      songs << element_to_song(element)
-    end
-    songs
+  # Get a list of any matching artist names or song titles based on airtime 
+  # popularity.
+  #
+  # == Parameters
+  # [+q+] The string to search with, can be partial (used for autocomplete) or full names.
+  # [+aid+] [optional] Instead of a general query, a known Artist ID can be passed to return just media from that artist.
+  # [+mid+] [optional] Instead of a general query, a known Media ID can be passed to return extra information (lyrics from Lyric Wiki and matching videos from YouTube and MTV) about just that song.
+  # [+max+] How many songs to return (default is 10, max is 50).  
+  #
+  # == Examples
+  #     get_media :aid => 610471
+  #--
+  # Run test with http://api.yes.com/1/media?mid=12812281&type=xml
+  # which returns an XML error (Yes.com's fault)
+  def self.get_media(query_hash)
+    self.search('Song', "media", "//api/array/songs", query_hash)
+  end
+
+  # Given a song, return a list of related songs based on airtime in the last 
+  # week.
+  #
+  # == Parameters
+  # [+mid+] The media ID (use media call to search for IDs).
+  # [+max+] Maximum number of related songs to return (default is 20).
+  #
+  # == Examples
+  #     get_related :mid => 11586843
+  #--
+  def self.get_related(query_hash)
+    self.search('Song', "related", "//api/array/songs", query_hash)
   end
 
-  def self.get_recent(station_name, max = nil)
-    songs = Array.new
-    
-    url = Yesradio::YESRADIO_SERVER + "/recent?type=xml"
-    url = url + "&name=" + CGI::escape(station_name)
-    url = url + "&max=" + CGI::escape(max.to_s) unless max.nil?
+  protected
+  
+  def self.search(item_class, action, xml_element, query_hash)
+    url = create_url(action, query_hash)
     uri = URI.parse(url)
     req = Net::HTTP::Get.new(uri.path + '?' + uri.query)
     res = Net::HTTP.start(uri.host, uri.port) { |http|
       http.request(req)
     }
     doc = REXML::Document.new res.body
-    doc.elements.each("//api/array/songs") do |element|
-      songs << element_to_song(element)
+    return if doc.elements[xml_element].nil?
+    doc.elements.collect(xml_element) do |element|
+      eval "#{item_class}.new(element)"
     end
-    songs
   end
-
-  protected
-
-  def self.get_element_child(element, child, type = :text)
-    return if element.elements[child].nil?
-    child = element.elements[child][0].to_s
-    return case type
-      when :int then child.to_i
-      when :float then child.to_f 
-      when :datetime then DateTime.parse(child)
-      else child
+  
+  def self.create_url(action, query_hash)
+    url = Yesradio::YESRADIO_SERVER + "/#{action}?type=xml"
+    query_hash.each do |name, value|
+      url = url + "&#{name}=" + CGI::escape(value.to_s) unless value.nil?  
     end
-
+    url
   end
   
 end
-

data/yesradio.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yesradio}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Claudio Baccigalupo"]
@@ -25,10 +25,10 @@ Gem::Specification.new do |s|
      "features/step_definitions/yesradio_steps.rb",
      "features/support/env.rb",
      "features/yesradio.feature",
+     "lib/item.rb",
      "lib/main.rb",
      "lib/song.rb",
      "lib/station.rb",
-     "lib/stations_search_criteria.rb",
      "lib/yesradio.rb",
      "test/test_helper.rb",
      "test/yesradio_test.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: claudiob-yesradio
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Claudio Baccigalupo
@@ -40,10 +40,10 @@ files:
 - features/step_definitions/yesradio_steps.rb
 - features/support/env.rb
 - features/yesradio.feature
+- lib/item.rb
 - lib/main.rb
 - lib/song.rb
 - lib/station.rb
-- lib/stations_search_criteria.rb
 - lib/yesradio.rb
 - test/test_helper.rb
 - test/yesradio_test.rb

data/lib/stations_search_criteria.rb

@@ -1,33 +0,0 @@
-#=============================================================================
-#
-# 2009 Claudio Baccigalupo
-#
-# Licensed under the Ruby License
-#
-#=============================================================================
-
-module Yesradio
-  class StationsSearchCriteria
-
-    attr_accessor :match, :freq, :mid, :genre, :loc, :max
-  
-    def initialize(options = {})
-      options.each do |key, value|
-        eval("@#{key} = '#{value.to_s}'")
-      end
-    end
-
-    def to_query_params_string
-      url = ''
-      url = url + "&match=" + CGI::escape(@match) if !@match.nil?
-      url = url + "&freq=" + CGI::escape(@freq) if !@freq.nil? 
-      url = url + "&mid=" + CGI::escape(@mid.to_s) if !@mid.nil?
-      url = url + "&genre=" + CGI::escape(@genre) if !@genre.nil?
-      url = url + "&loc=" + CGI::escape(@loc) if !@loc.nil?
-      url = url + "&max=" + CGI::escape(@max.to_s) if !@max.nil? 
-      url
-    end
-  end
-end
-
-