msp-youtube-g 0.4.7 → 0.4.8.1

data/lib/youtube_g.rb

@@ -1,3 +1,10 @@
+require 'logger'
+require 'open-uri'
+require 'net/https'
+require 'digest/md5'
+require 'rexml/document'
+require 'cgi'
+
 require File.dirname(__FILE__) + '/youtube_g/client'
 require File.dirname(__FILE__) + '/youtube_g/record'
 require File.dirname(__FILE__) + '/youtube_g/parser'
@@ -9,12 +16,15 @@ require File.dirname(__FILE__) + '/youtube_g/model/playlist'
 require File.dirname(__FILE__) + '/youtube_g/model/rating'
 require File.dirname(__FILE__) + '/youtube_g/model/thumbnail'
 require File.dirname(__FILE__) + '/youtube_g/model/user'
-require File.dirname(__FILE__) + '/youtube_g/model/video' 
+require File.dirname(__FILE__) + '/youtube_g/model/video'
 require File.dirname(__FILE__) + '/youtube_g/model/upload_error' 
+require File.dirname(__FILE__) + '/youtube_g/request/base_search'
+require File.dirname(__FILE__) + '/youtube_g/request/user_search'
+require File.dirname(__FILE__) + '/youtube_g/request/standard_search'
 require File.dirname(__FILE__) + '/youtube_g/request/video_upload'
 require File.dirname(__FILE__) + '/youtube_g/request/video_search'
 require File.dirname(__FILE__) + '/youtube_g/response/video_search'
 
-class YouTubeG
-  VERSION = '0.4.7'
+class YouTubeG #:nodoc:
+  VERSION = '0.4.8.1'
 end

data/lib/youtube_g/client.rb

@@ -1,36 +1,81 @@
-require 'logger'
-
 class YouTubeG
   class Client
     attr_accessor :logger
     
-    def initialize(logger=Logger.new(STDOUT))
-      @logger = logger
+    def initialize(logger=false)
+      @logger = Logger.new(STDOUT) if logger
     end
-
-    # Params can be one of :most_viewed, :top_rated, :recently_featured, :watch_on_mobile
-    # Or :tags, :categories, :query, :user
+    
+    # Retrieves an array of standard feed, custom query, or user videos.
+    # 
+    # === Parameters
+    # If fetching videos for a standard feed:
+    #   params<Symbol>:: Accepts a symbol of :top_rated, :top_favorites, :most_viewed, 
+    #                    :most_popular, :most_recent, :most_discussed, :most_linked, 
+    #                    :most_responded, :recently_featured, and :watch_on_mobile.
+    #  
+    #   You can find out more specific information about what each standard feed provides
+    #   by visiting: http://code.google.com/apis/youtube/reference.html#Standard_feeds                 
+    #   
+    #   options<Hash> (optional)::  Accepts the options of :time, :page (default is 1), 
+    #                               and :per_page (default is 25). :offset and :max_results
+    #                               can also be passed for a custom offset.
+    #  
+    # If fetching videos by tags, categories, query:
+    #   params<Hash>:: Accepts the keys :tags, :categories, :query, :order_by, 
+    #                  :author, :racy, :response_format, :video_format, :page (default is 1), 
+    #                  and :per_page(default is 25)
+    #                  
+    #   options<Hash>:: Not used. (Optional)
+    # 
+    # If fetching videos for a particular user:
+    #   params<Hash>:: Key of :user with a value of the username.
+    #   options<Hash>:: Not used. (Optional)
+    # === Returns
+    # YouTubeG::Response::VideoSearch
     def videos_by(params, options={})
+      request_params = params.respond_to?(:to_hash) ? params : options
+      request_params[:page] ||= 1
+      
+      unless request_params[:max_results]
+        request_params[:max_results] = request_params[:per_page] || 25
+      end
+      
+      unless request_params[:offset]
+        request_params[:offset] = calculate_offset(request_params[:page], request_params[:max_results] )
+      end
+      
       if params.respond_to?(:to_hash) and not params[:user]
-        request = YouTubeG::Request::VideoSearch.new(params)
-
+        request = YouTubeG::Request::VideoSearch.new(request_params)
       elsif (params.respond_to?(:to_hash) && params[:user]) || (params == :favorites)
-        request = YouTubeG::Request::UserSearch.new(params, options)
-
+        request = YouTubeG::Request::UserSearch.new(request_params, options)
       else
-        request = YouTubeG::Request::StandardSearch.new(params, options)
+        request = YouTubeG::Request::StandardSearch.new(params, request_params)
       end
       
-      logger.debug "Submitting request [url=#{request.url}]."
+      logger.debug "Submitting request [url=#{request.url}]." if logger
       parser = YouTubeG::Parser::VideosFeedParser.new(request.url)
       parser.parse
     end
     
+    # Retrieves a single YouTube video.
+    #
+    # === Parameters
+    #   vid<String>:: The ID or URL of the video that you'd like to retrieve.
+    # 
+    # === Returns
+    # YouTubeG::Model::Video
     def video_by(vid)
       video_id = vid =~ /^http/ ? vid : "http://gdata.youtube.com/feeds/videos/#{vid}"
       parser = YouTubeG::Parser::VideoFeedParser.new(video_id)
       parser.parse
     end
     
+    private
+    
+    def calculate_offset(page, per_page)
+      page == 1 ? 1 : ((per_page * page) - per_page + 1)
+    end
+    
   end
 end

data/lib/youtube_g/logger.rb

@@ -1,5 +1,3 @@
-require 'logger'
-
 class YouTubeG
   
   # TODO: Why is this needed? Does this happen if running standalone w/o Rails?

data/lib/youtube_g/model/author.rb

@@ -1,7 +1,10 @@
 class YouTubeG
   module Model
     class Author < YouTubeG::Record
+      # *String*: Author's YouTube username.
       attr_reader :name
+      
+      # *String*: Feed URL of the author.
       attr_reader :uri
     end
   end

data/lib/youtube_g/model/category.rb

@@ -1,7 +1,10 @@
 class YouTubeG
   module Model
     class Category < YouTubeG::Record
-      attr_reader :label
+      # *String*:: Name of the YouTube category
+      attr_reader :label 
+      
+      # *String*:: Identifies the type of item described.
       attr_reader :term
     end
   end

data/lib/youtube_g/model/contact.rb

@@ -1,7 +1,15 @@
 class YouTubeG
   module Model
     class Contact < YouTubeG::Record
+      # *String*:: Identifies the status of a contact.
+      #
+      # * The tag's value will be accepted if the authenticated user and the contact have marked each other as friends.
+      # * The tag's value will be requested if the contact has asked to be added to the authenticated user's contact list, but the request has not yet been accepted (or rejected).
+      # * The tag's value will be pending if the authenticated user has asked to be added to the contact's contact list, but the request has not yet been accepted or rejected.
+      #
       attr_reader :status
+      
+      # *String*:: The Youtube username of the contact.
       attr_reader :username
     end
   end

data/lib/youtube_g/model/content.rb

@@ -1,10 +1,15 @@
 class YouTubeG
   module Model
     class Content < YouTubeG::Record
+      # *Boolean*:: Description of the video.
       attr_reader :default
+      # *Fixnum*:: Length of the video in seconds.
       attr_reader :duration
+      # YouTubeG::Model::Video::Format:: Specifies the video format of the video object
       attr_reader :format
+      # *String*:: Specifies the MIME type of the media object.
       attr_reader :mime_type
+      # *String*:: Specifies the URL for the media object.
       attr_reader :url
       
       alias :is_default? :default

data/lib/youtube_g/model/playlist.rb

@@ -1,6 +1,7 @@
 class YouTubeG
   module Model
     class Playlist < YouTubeG::Record
+      # *String*:: User entered description for the playlist.
       attr_reader :description
     end
   end

data/lib/youtube_g/model/rating.rb

@@ -1,9 +1,16 @@
 class YouTubeG
   module Model
     class Rating < YouTubeG::Record
+      # *Float*:: Average rating given to the video
       attr_reader :average
+      
+      # *Fixnum*:: Maximum rating that can be assigned to the video
       attr_reader :max
+      
+      # *Fixnum*:: Minimum rating that can be assigned to the video
       attr_reader :min
+      
+      # *Fixnum*:: Indicates how many people have rated the video
       attr_reader :rater_count
     end
   end

data/lib/youtube_g/model/thumbnail.rb

@@ -1,9 +1,16 @@
 class YouTubeG
   module Model
     class Thumbnail < YouTubeG::Record
+      # *String*:: URL for the thumbnail image.
       attr_reader :url
+      
+      # *Fixnum*:: Height of the thumbnail image.
       attr_reader :height
+      
+      # *Fixnum*:: Width of the thumbnail image.
       attr_reader :width
+      
+      # *String*:: Specifies the time offset at which the frame shown in the thumbnail image appears in the video.
       attr_reader :time
     end
   end

data/lib/youtube_g/model/upload_error.rb

@@ -0,0 +1,13 @@
+class YouTubeG
+  module Model
+    class UploadError < YouTubeG::Record
+      attr_reader :domain
+      attr_reader :code
+      attr_reader :location     
+      
+      def to_s
+        "location: [#{location}] domain: [#{domain}] code: [#{code}]"
+      end  
+    end
+  end
+end

data/lib/youtube_g/model/video.rb

@@ -1,38 +1,57 @@
+# TODO
+#  * self atom feed
+#  * alternate youtube watch url
+#  * comments feedLink
+
 class YouTubeG
   module Model
     class Video < YouTubeG::Record
       # Describes the various file formats in which a Youtube video may be
       # made available and allows looking them up by format code number.
-      #
       class Format
         @@formats = Hash.new
 
+        # Instantiates a new video format object.
+        #
+        # == Parameters
+        #   :format_code<Fixnum>:: The Youtube Format code of the object. 
+        #   :name<Symbol>:: The name of the format
+        #   
+        # == Returns
+        #   YouTubeG::Model::Video::Format: Video format object
         def initialize(format_code, name)
           @format_code = format_code
           @name = name
 
           @@formats[format_code] = self          
         end
-
+        
+        # Allows you to get the video format for a specific format code.
+        # 
+        # A full list of format codes is available at:
+        # 
+        # http://code.google.com/apis/youtube/reference.html#youtube_data_api_tag_media:content
+        #
+        # == Parameters
+        #   :format_code<Fixnum>:: The Youtube Format code of the object. 
+        #   
+        # == Returns
+        #   YouTubeG::Model::Video::Format: Video format object
         def self.by_code(format_code)
           @@formats[format_code]
         end
 
-        # Flash format on YouTube site. All videos are available in this
-        # format.
-        #
+        # Flash format on YouTube site. All videos are available in this format.
         FLASH = YouTubeG::Model::Video::Format.new(0, :flash)
 
-        # RTSP streaming URL for mobile video playback. H.263 video (176x144)
-        # and AMR audio.
-        #
+        # RTSP streaming URL for mobile video playback. H.263 video (176x144) and AMR audio.
         RTSP = YouTubeG::Model::Video::Format.new(1, :rtsp)
 
         # HTTP URL to the embeddable player (SWF) for this video. This format
         # is not available for a video that is not embeddable.
-        #
         SWF = YouTubeG::Model::Video::Format.new(5, :swf)
         
+        # RTSP streaming URL for mobile video playback. MPEG-4 SP video (up to 176x144) and AAC audio.
         THREE_GPP = YouTubeG::Model::Video::Format.new(6, :three_gpp)
       end 
        
@@ -43,58 +62,114 @@ class YouTubeG
          attr_reader :state
       end
             
+      # *Fixnum*:: Duration of a video in seconds.
       attr_reader :duration
+      
+      # *Boolean*:: Specifies that a video may or may not be embedded on other websites.
       attr_reader :noembed
+      
+      # *Fixnum*:: Specifies the order in which the video appears in a playlist.
       attr_reader :position
+      
+      # *Boolean*:: Specifies that a video is flagged as adult or not.
       attr_reader :racy
-      attr_reader :statistics
       
+      # YouTubeG::Model::Video::AppControl The state of this video if post upload
       attr_reader :app_control
-      
+
+      # *String*: Specifies a URI that uniquely and permanently identifies the video.
       attr_reader :video_id
+      
+      # *Time*:: When the video was published on Youtube.
       attr_reader :published_at
+      
+      # *Time*:: When the video's data was last updated.
       attr_reader :updated_at
+      
+      # *Array*:: A array of YouTubeG::Model::Category objects that describe the videos categories. 
       attr_reader :categories
+      
+      # *Array*:: An array of words associated with the video.
       attr_reader :keywords
+      
+      # *String*:: Description of the video.
       attr_reader :description
+      
+      # *String*:: Title for the video.
       attr_reader :title
+      
+      # *String*:: Description of the video.
       attr_reader :html_content
+      
+      # YouTubeG::Model::Author:: Information about the YouTube user who owns a piece of video content.
       attr_reader :author
-
-      # YouTubeG::Model::Content records describing the individual media content
-      # data available for this video.  Most, but not all, videos offer this.
+      
+      # *Array*:: An array of YouTubeG::Model::Content objects describing the individual media content data available for this video.  Most, but not all, videos offer this.
       attr_reader :media_content
-
-      attr_reader :thumbnails         # YouTubeG::Model::Thumbnail records
+      
+      # *Array*:: An array of YouTubeG::Model::Thumbnail objects that contain information regarding the videos thumbnail images. 
+      attr_reader :thumbnails
+      
+      # *String*:: The link to watch the URL on YouTubes website.
       attr_reader :player_url
+      
+      # YouTubeG::Model::Rating:: Information about the videos rating.
       attr_reader :rating
+      
+      # *Fixnum*:: Number of times that the video has been viewed
       attr_reader :view_count
-
-      # TODO:
-      # self atom feed
-      # alternate youtube watch url
-      # responses feed
-      # comments feedLink
-
+      
+      attr_reader :statistics
+      
+      # Videos related to the current video.
+      #
+      # === Returns
+      #   YouTubeG::Response::VideoSearch
       def related
         YouTubeG::Parser::VideosFeedParser.new("http://gdata.youtube.com/feeds/api/videos/#{unique_id}/related").parse
       end
       
-      # For convenience, the video_id with the URL stripped out, useful for searching for the video again
-      # without having to store it anywhere. A regular query search, with this id will return the same video.
-      # http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o
+      # Video responses to the current video.
+      #
+      # === Returns
+      #   YouTubeG::Response::VideoSearch   
+      def responses
+        YouTubeG::Parser::VideosFeedParser.new("http://gdata.youtube.com/feeds/api/videos/#{unique_id}/responses").parse
+      end
+      
+      # The ID of the video, useful for searching for the video again without having to store it anywhere. 
+      # A regular query search, with this id will return the same video.
+      # 
+      # === Example
+      #   >> video.unique_id
+      #   => "ZTUVgYoeN_o"
+      #   
+      # === Returns
+      #   String: The Youtube video id.
       def unique_id
         video_id[/videos\/([^<]+)/, 1]
       end
       
-      def can_embed?
+      # Allows you to check whether the video can be embedded on a webpage.
+      #
+      # === Returns
+      #   Boolean: True if the video can be embedded, false if not.
+      def embeddable?
         not @noembed
       end
       
+      # Provides a URL and various other types of information about a video.
+      # 
+      # === Returns
+      #   YouTubeG::Model::Content: Data about the embeddable video.
       def default_media_content
         @media_content.find { |c| c.is_default? }
       end
       
+      # Gives you the HTML to embed the video on your website.
+      #
+      # === Returns
+      #   String: The HTML for embedding the video on your website.
       def embed_html(width = 425, height = 350)
         <<EDOC
 <object width="#{width}" height="#{height}">
@@ -106,6 +181,10 @@ class YouTubeG
 EDOC
       end
 
+      # The URL needed for embedding the video in a page.
+      #
+      # === Returns
+      #   String: Absolute URL for embedding video
       def embed_url
         @player_url.sub('watch?', '').sub('=', '/')          
       end