plex-ruby 0.1.0 → 0.2.0

data/.gitignore

@@ -1,4 +1,5 @@
 *.gem
 .bundle
 Gemfile.lock
+.rake_tasks~
 pkg/*

data/CHANGELOG.md

@@ -3,3 +3,14 @@
 * Initial Release
 * Browsing a library works
 * Sending commands to a clients works intermittently, needs lots of work
+
+## 0.1.0
+
+* Gem released of RubyGems
+
+## 0.2.0
+
+* Added documentation
+* Added bang methods that clears caches
+* Fix naming of 'libary' to 'library'
+* Moved static content into Constants (Wow!\s)

data/README.md

@@ -13,6 +13,14 @@ Add to your `Gemfile` and run the `bundle` command
 gem 'plex-ruby'
 ```
 
+Or
+
+```ruby
+gem install plex-ruby
+
+require 'plex-ruby'
+```
+
 I developed this using Ruby 1.9.2 so no guaranties that it will work with
 lesser versions of Ruby.
 

data/lib/plex-ruby.rb

@@ -4,6 +4,11 @@ require 'cgi'
 
 module Plex
 
+  # Converts camel case names that are commonly found in the Plex APIs into
+  # ruby friendly names.  I.E. playMedia -> play_media
+  #
+  # @param [String] camel case name to be converted
+  # @return [String] snake case form
   def self.snake_case(string)
     string.gsub(/::/, '/').
     gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -12,6 +17,10 @@ module Plex
     downcase
   end
 
+  # The base url of the Plex Media Server, I.E. 'http://localhost:32400'
+  # !WARNING! This method will most likely be replaced in future versions
+  #
+  # @return [String] bases url of the Plex Media Server
   def self.url
     @@base_url
   end
@@ -25,7 +34,7 @@ end
 require 'plex-ruby/parser'
 require 'plex-ruby/server'
 require 'plex-ruby/client'
-require 'plex-ruby/libary'
+require 'plex-ruby/library'
 require 'plex-ruby/section'
 require 'plex-ruby/video'
 require 'plex-ruby/media'

data/lib/plex-ruby/client.rb

@@ -1,6 +1,12 @@
 module Plex
   class Client
 
+    NAV_METHODS = %w(moveUp moveDown moveLeft moveRight pageUp pageDown nextLetter 
+                     previousLetter select back contextMenu toggleOSD) 
+
+    PLAYBACK_METHODS = %w(play pause stop rewind fastForward stepForward 
+                          bigStepForward stepBack bigStepBack skipNext skipPrevious)
+
     attr_reader :name, :host, :address, :port, :machine_identifier, :version
 
     def initialize(node)
@@ -12,8 +18,12 @@ module Plex
       @version = node.attr('version')
     end
 
-    %w(moveUp moveDown moveLeft moveRight pageUp pageDown nextLetter previousLetter 
-       select back contextMenu toggleOSD).each { |nav|
+    # Navigation methods
+    # Sends a movement command to the client to move around menus and such
+    #
+    # @return [True, nil] true if it worked, nil if something went wrong check
+    #   the console for the error message
+    NAV_METHODS.each { |nav|
       class_eval %(
         def #{Plex.snake_case(nav)}
           ping player_url+'/navigation/#{nav}'
@@ -21,8 +31,12 @@ module Plex
       )
     }
 
-    %w(play pause stop rewind fastForward stepForward bigStepForward stepBack 
-       bigStepBack skipNext skipPrevious).each { |playback|
+    # Playback methods
+    # Sends a playback command to the client to play / pause videos and such
+    #
+    # @return [True, nil] true if it worked, nil if something went wrong check
+    #   the console for the error message
+    PLAYBACK_METHODS.each { |playback|
       class_eval %(
         def #{Plex.snake_case(playback)}
           ping player_url+'/playback/#{playback}'
@@ -34,6 +48,15 @@ module Plex
       ping player_url+"/application/playFile"
     end
 
+    # Plays a video that is in the library
+    #
+    # @param [String] the key of the video that we want to play.  (see
+    #   Episode#key) (see Movie#key)
+    # @param [String] no clue what this does, its the Plex Remote Command API though
+    # @param [String] no clue what this does, its the Plex Remote Command API though
+    # @param [String] no clue what this does, its the Plex Remote Command API though
+    # @return [True, nil] true if it worked, nil if something went wrong check
+    #   the console for the error message
     def play_media(key, user_agent = nil, http_cookies = nil, view_offset = nil)
       url = player_url+'/application/playMedia?'
       url += "path=#{CGI::escape(Plex.url+key)}"
@@ -45,22 +68,47 @@ module Plex
       ping url
     end
 
+    # Take a screenshot of whats on the Plex Client
+    #
+    # @param [String, Fixnum] width of the screenshot
+    # @param [String, Fixnum] height of the screenshot
+    # @param [String, Fixnum] quality of the screenshot
+    # @return [True, nil] true if it worked, nil if something went wrong check
+    #   the console for the error message
     def screenshot(width, height, quality)
       url = player_url+'/application/screenshot?'
       url += "width=#{width}"
       url += "&height=#{height}"
+      url += "&quality=#{quality}"
+
+      ping url
     end
 
+    # Sends a string message to the Plex Client
+    #
+    # @param [String] message to send
+    # @return [True, nil] true if it worked, nil if something went wrong check
+    #   the console for the error message
     def send_string(text)
-      ping player_url+"/application/sendString?text=#{CGI::escape(text)}"
+      ping player_url+"/application/sendString?text=#{CGI::escape(text.to_s)}"
     end
 
+    # Sends a key code to the Plex Client.  Key codes represent key presses on
+    # a keyboard. Codes are the ASCII value of the letter one wants pressed.
+    # It should be noted that the Plex devs have told people to try and avoid
+    # using this method when writing plugins, as different users can have
+    # different key mappings.
+    #
+    # @param [String, Fixnum] key code to send
+    # @return [True, nil] true if it worked, nil if something went wrong check
+    #   the console for the error message
     def send_key(code)
-      ping player_url+"/application/sendKey?code=#{CGI::escape(code)}"
+      ping player_url+"/application/sendKey?code=#{CGI::escape(code.to_s)}"
     end
 
+    # (see #send_key)
     def send_virtual_key(code)
-      ping player_url+"/application/sendVirtualKey?code=#{CGI::escape(code)}"
+      ping player_url+"/application/sendVirtualKey?code=#{CGI::escape(code.to_s)}"
     end
 
     private

data/lib/plex-ruby/episode.rb

@@ -7,6 +7,8 @@ module Plex
       @key = key
     end
     
+    # Delegates all method calls to the video object that represents this
+    # episode, if that video object responds to the method.
     def method_missing(method, *args, &block)
       if video.respond_to? method
         video.send(method, *args, &block)

data/lib/plex-ruby/library.rb

@@ -0,0 +1,54 @@
+module Plex
+  class Library
+
+    # Grab a specific section
+    #
+    # @param [String, Fixnum] key of the section we want
+    # @return [Section] section with that key
+    def section(id)
+      search_sections(xml_doc, id).first
+    end
+
+    # Cache busting version of #section
+    def section!(id)
+      search_sections(xml_doc!, id).first
+    end
+
+    # A list of sections that are located in this library
+    #
+    # @return [Array] list of sections
+    def sections
+      @sections ||= search_sections(xml_doc)
+    end
+
+    # Cache busting version of #sections
+    def sections!
+      @sections = search_sections(xml_doc!)
+    end
+
+    def key
+      "/library/sections"
+    end
+
+    private
+
+    def search_sections(doc, key = nil)
+      term = key ? "Directory[@key='#{key}']" : 'Directory'
+      doc.search(term).map { |m| Plex::Section.new(m.attributes) }
+    end
+
+    def xml_doc
+      @xml_doc ||= base_doc
+    end
+
+    def xml_doc!
+      @xml_doc = base_doc
+    end
+
+    def base_doc
+      Nokogiri::XML( open(Plex.url+key) )
+    end
+
+
+  end
+end

data/lib/plex-ruby/movie.rb

@@ -7,6 +7,8 @@ module Plex
       @key = key
     end
 
+    # Delegates all method calls to the video object that represents this
+    # movie, if that video object responds to the method.
     def method_missing(method, *args, &block)
       if video.respond_to? method
         video.send(method, *args, &block)

data/lib/plex-ruby/parser.rb

@@ -7,6 +7,13 @@ module Plex
       @node = node
     end
 
+    # Parses a XML node and returns the structure it represents. This is
+    # currently used to parse Sections as we don't know whether a Section holds
+    # a list of Shows or a list of Movies.  The parsing is done recursively.
+    #
+    # @return [Array, Movie, Episode, Show] depending on what node it is given,
+    #   will return an Array of Movies or Shows, a single Movie, and single
+    #   Episode, or a single Show
     def parse
       case node.name
       when 'document'

data/lib/plex-ruby/season.rb

@@ -1,38 +1,78 @@
 module Plex
-  # Found at /libary/metadata/:key
+  # Found at /library/metadata/:key
   class Season
 
+    ATTRIBUTES = %w(ratingKey guid type title summary index thumb leafCount 
+                    viewedLeafCount addedAt updatedAt) 
+
     attr_reader :key
 
     def initialize(key)
       @key = key
     end
 
-    %w(ratingKey guid type title summary index thumb leafCount viewedLeafCount 
-       addedAt updatedAt).each { |method|
+    # A Season has a key, which allows us to do lazy loading.  A season will
+    # not be fully loaded unless one of its attributes is called.  Then the
+    # Season will load itself from its key. Once loaded it caches its self.
+    # For every attribute there is a cache busting version wich is just the
+    # name of the attribute followed by '!'. For exsample <tt>season.type</tt>
+    # and <tt>season.type!</tt>
+    ATTRIBUTES.each { |method|
       class_eval %(
         def #{Plex.snake_case(method)}; directory.attr('#{method}') end
+        def #{Plex.snake_case(method)}!; directory!.attr('#{method}') end
       )
     }
 
+    # Returns the list of episodes in the library that are a part of this Season
+    #
+    # @return [Array] list of episodes in this season that are on the server
     def episodes
-      @episodes ||=
-        children.search("Video").map { |m| Plex::Episode.new(m.attr('key')) }
+      @episodes ||= episodes_from_video(children)
+    end
+
+    # Cache busting version of #episodes
+    def episodes!
+      @episodes = episodes_from_video(children!)
     end
 
     private
 
+    def base_doc
+      Nokogiri::XML( open(Plex.url+key) )
+    end
+
+    def base_children_doc
+      Nokogiri::XML( open(Plex.url+key+'/children') )
+    end
+
     def xml_doc
-      @xml_doc ||= Nokogiri::XML( open(Plex.url+key) )
+      @xml_doc ||= base_doc
+    end
+
+    def xml_doc!
+      @xml_doc = base_doc
     end
 
     def children 
-      @children ||= Nokogiri::XML( open(Plex.url+key+'/children') )
+      @children ||= base_children_doc
+    end
+
+    def children!
+      @children = base_children_doc 
+    end
+
+    def episodes_from_video(node)
+      node.search("Video").map { |m| Plex::Episode.new(m.attr('key')) }
     end
 
     def directory
       @directory ||= xml_doc.search("Directory").first
     end
 
+    def directory!
+      @directory = xml_doc!.search("Directory").first
+    end
+
   end
 end

data/lib/plex-ruby/section.rb

@@ -1,6 +1,8 @@
 module Plex
   class Section
 
+    GROUPS = %w(all unwatched newest recentlyAdded recentlyViewed onDeck)
+
     attr_reader :refreshing, :type, :title, :art, :agent, :scanner, :language, 
       :updated_at
 
@@ -16,11 +18,22 @@ module Plex
       @updated_at = options['updatedAt'].value
     end
 
+    # NOT IMPLEMENTED
     def refresh(deep = false, force = false)
     end
 
 
-    %w(all unwatched newest recentlyAdded recentlyViewed onDeck).each { |method|
+    # Returns a list of shows or movies that are in this Section. 
+    #
+    # all - all videos in this Section
+    # unwatched - videos unwatched in this Section
+    # newest - most recent videos in this Section
+    # recently_added - recently added videos in this Section
+    # recently_viewed - recently viewed videos in this Section
+    # on_deck - videos that are "on deck" in this Section
+    #
+    # @return [Array] list of Shows or Movies in that group
+    GROUPS.each { |method|
       class_eval %(
         def #{Plex.snake_case(method)}
           Plex::Parser.new( Nokogiri::XML(open(Plex.url+key+'/#{method}')) ).parse

data/lib/plex-ruby/server.rb

@@ -9,21 +9,41 @@ module Plex
       Plex.url = "http://#{host}:#{port}"
     end
 
-    def system
+    # The library of this server
+    #
+    # @return [Library] this Servers library
+    def library
+      @library ||= Plex::Libary.new
     end
 
-    def libary
-      @libary ||= Plex::Libary.new
+    # The Plex clients that are connected to this Server
+    # 
+    # @return [Array] list of Clients connected to this server
+    def clients
+      @clients ||= search_clients clients_doc
     end
 
-    def clients
-      @clients ||= clients_doc.search('Server').map { |m| Plex::Client.new(m) }
+    # Cache busting version of #clients
+    def clients!
+      @clients = search_clients clients_doc!
     end
 
     private
 
+    def clients_base
+      Nokogiri::XML( open(Plex.url+'/clients') )
+    end
+
     def clients_doc
-      @clients_doc ||= Nokogiri::XML( open(Plex.url+'/clients') )
+      @clients_doc ||= clients_base
+    end
+
+    def clients_doc!
+      @clients_doc = clients_base
+    end
+
+    def search_clients(node)
+      node.search('Server').map { |m| Plex::Client.new(m) }
     end
 
   end

data/lib/plex-ruby/show.rb

@@ -1,40 +1,76 @@
 module Plex
-  # Found at /libary/metadata/:key
+  # Found at /library/metadata/:key
   class Show
 
+    ATTRIBUTES = %w(guid studio title contentRating summary index rating year thumb 
+                    art banner theme duration originallyAvailableAt leafCount 
+                    viewedLeafCount addedAt updatedAt)
+
     attr_reader :key
 
     def initialize(key)
       @key = key
     end
 
-    %w(guid studio title contentRating summary index rating year thumb art banner
-       theme duration originallyAvailableAt leafCount viewedLeafCount addedAt
-       updatedAt).each { |method|
+    # A Show has a key, which allows us to do lazy loading.  A Show will
+    # not be fully loaded unless one of its attributes is called.  Then the
+    # Show will load itself from its key. Once loaded it caches its self.
+    ATTRIBUTES.each { |method|
       class_eval %(
         def #{Plex.snake_case(method)}; @#{method} ||= directory.attr('#{method}') end
+        def #{Plex.snake_case(method)}!; @#{method} = directory!.attr('#{method}') end
       )
     }
 
+    # The list of seasons in the library that belong to this Show
+    #
+    # @return [Array] list of Seasons that are a part of this Show
     def seasons
-      @seasons ||=
-        children.search('Directory').map do |season|
-          Plex::Season.new(season.attr('key')[0..-10]) # Remove /children
-        end.compact
+      @seasons ||= search_children children
+    end
+
+    def seasons!
+      @seasons = search_children children!
     end
 
     private
 
+    def base_doc
+      Nokogiri::XML( open(Plex.url+key) )
+    end
+
+    def children_base
+      Nokogiri::XML( open(Plex.url+key+'/children') )
+    end
+
+    def xml_doc
+      @xml_doc ||= base_doc
+    end
+    
+    def xml_doc!
+      @xml_doc = base_doc
+    end
+
     def children
-      @children ||= Nokogiri::XML( open(Plex.url+key+'/children') )
+      @children ||= children_base
+    end
+
+    def children!
+      @children = children_base
     end
 
     def directory
       @directory ||= xml_doc.search('Directory').first
     end
-    
-    def xml_doc
-      @xml_doc ||= Nokogiri::XML( open(Plex.url+key) )
+
+    def directory!
+      @directory = xml_doc!.search('Directory').first
+    end
+
+    def search_children(node)
+      node.search('Directory').map do |season|
+        Plex::Season.new(season.attr('key')[0..-10]) # Remove /children
+      end
     end
 
   end

data/lib/plex-ruby/version.rb

@@ -1,3 +1,3 @@
 module Plex
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -2,7 +2,7 @@
 name: plex-ruby
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Eric Koslow
@@ -65,7 +65,7 @@ files:
 - lib/plex-ruby.rb
 - lib/plex-ruby/client.rb
 - lib/plex-ruby/episode.rb
-- lib/plex-ruby/libary.rb
+- lib/plex-ruby/library.rb
 - lib/plex-ruby/media.rb
 - lib/plex-ruby/movie.rb
 - lib/plex-ruby/null.rb

data/lib/plex-ruby/libary.rb

@@ -1,25 +0,0 @@
-module Plex
-  class Libary
-
-    def section(id)
-      xml_doc.search("Directory[@key='#{id}']").map do |m| 
-        Plex::Section.new(m.attributes) 
-      end.first
-    end
-
-    def sections
-      xml_doc.search('Directory').map { |m| Plex::Section.new(m.attributes) }
-    end
-
-    def key
-      "/library/sections"
-    end
-
-    private
-
-    def xml_doc
-      @xml_doc ||= Nokogiri::XML( open(Plex.url+key) )
-    end
-
-  end
-end