vk_music 1.1.1 → 2.0.0

data/lib/vk_music/constants.rb

@@ -1,46 +1,91 @@
 module VkMusic
 
-  # Constants
+  ##
+  # Constants.
   module Constants
-    # Web
+    
+    ##
+    # Web user agent.
     # DEFAULT_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1636.0 Safari/537.36"
 
-    VK_URL = {
-      :scheme => "https",
-      :host => "m.vk.com",
-      :home => "https://m.vk.com",
-      :profile => "https://m.vk.com/id0",
-      :feed => "https://m.vk.com/feed",
-      :audios => "https://m.vk.com/audio",
-      :login  => "https://m.vk.com/login",
-      :login_action => "https://login.vk.com",
-      :wall => "https://m.vk.com/wall"
-    }
+    ##
+    # Different URLs
+    module URL
+
+      ##
+      # Hash with URLs to VK pages which are used by library.
+      VK = {
+        scheme: "https",
+        host: "m.vk.com",
+        home: "https://m.vk.com",
+        profile: "https://m.vk.com/id0",
+        feed: "https://m.vk.com/feed",
+        audios: "https://m.vk.com/audio",
+        login: "https://m.vk.com/login",
+        login_action: "https://login.vk.com",
+        wall: "https://m.vk.com/wall",
+        audio_unavailable: "https://m.vk.com/mp3/audio_api_unavailable.mp3"
+      }
+
+    end
+
+    ##
+    # Regular expressions
+    module Regex
+
+      ##
+      # VK user or group ID.
+      VK_ID_STR = /^-?\d+$/
+
+      ##
+      # VK user or group ID.
+      VK_ID = /-?\d+/
+
+      ##
+      # VK prefixed user or group ID.
+      VK_PREFIXED_ID_STR = /^(?:id|club|group|public|event)(\d+)$/
+
+      ##
+      # VK custom ID regular expression.
+      VK_CUSTOM_ID = /^\w+$/
+
+      ##
+      # VK URL regular expression.
+      VK_URL = /(?:https?:\/\/)?(?:m\.|www\.)?vk\.com\/([\w\-]+)/
+
+      ##
+      # +href+ attribute with VK ID regular expression.
+      VK_HREF_ID_CONTAINING = /(?:audios|photo|write|owner_id=|friends\?id=)(-?\d+)/
+      
+      ##
+      # VK audios page regular expression.
+      VK_AUDIOS_URL_POSTFIX = /^audios(-?\d+)$/
+      
+      ##
+      # Playlist URL regular expression.
+      VK_PLAYLIST_URL_POSTFIX = /.*audio_playlist(-?\d+)_(\d+)(?:(?:(?:&access_hash=)|\/|%2F)([\da-z]+))?/
+
+      ##
+      # Post URL regular expression #1.
+      VK_POST_URL_POSTFIX = /.*post(-?\d+)_(\d+)/
+
+      ##
+      # Post URL regular expression #2.
+      VK_WALL_URL_POSTFIX = /.*wall(-?\d+)_(\d+)/
+
+    end
     
+    ##
+    # Names used in VK login form.
     VK_LOGIN_FORM_NAMES = {
-      :username => "email",
-      :password => "pass",
+      username: "email",
+      password: "pass"
     }
-    
-    
-    VK_ID_REGEX = /^-?\d+$/
-    VK_AUDIOS_REGEX = /^audios-?\d+$/
-    VK_PREFIXED_ID_REGEX = /^(?:id|club|group|public|event)\d+$/ # TODO: Rework. This one is REALLY dirty. Not quite sure every page can return correct id with this regex
-    VK_CUSTOM_ID_REGEX = /^\w+$/
-    VK_URL_REGEX = /(?:https?:\/\/)?(?:m\.|www\.)?vk\.com\/([\w\-]+)/
-    
-    VK_HREF_ID_CONTAINING_REGEX = /(?:audios|photo|write|owner_id=|friends\?id=)-?\d+/
-    
-    # Playlist
-    PLAYLIST_URL_REGEX = /.*audio_playlist(-?\d+)_(\d+)(?:(?:(?:&access_hash=)|\/|%2F)([\da-z]+))?/
 
-    # Post
-    POST_URL_REGEX = /.*wall(-?\d+)_(\d+)/
+    ##
+    # Maximum amount of audios in VK playlist.
+    MAXIMUM_PLAYLIST_SIZE = 10000
     
-    
-    # QUESTION: Should I move ALL the constants (string, regex etc) here? It would make code more flexible, but seems like overkill
   end
 
-  include Constants
-
 end

data/lib/vk_music/exceptions.rb

@@ -1,33 +1,30 @@
 module VkMusic
 
+  ##
   # Exceptions.
   module Exceptions
+
+    ##
     # General class for all the errors.
     class VkMusicError < RuntimeError; end
 
+    ##
     # Failed to login.
     class LoginError < VkMusicError; end
-    
-    # Unable to parse audios from somewhere.
-    class AudiosParseError < VkMusicError; end
 
-    # Unable to find playlist or got permission error.
-    class PlaylistParseError < AudiosParseError; end
+    ##
+    # Failed to get request. _Only_ thron when Mechanize failed to load page
+    class RequestError < VkMusicError; end
 
-    # Unable to load or parse audios section from json.
-    class AudiosSectionParseError < AudiosParseError; end
+    ##
+    # Parse error. Request is OK, but something went wrong while parsing reply.
+    #   It might be missing playlist/post as well.
+    class ParseError < VkMusicError; end
 
-    # Unable to load or parse all of audios by ids.
-    class ReloadAudiosParseError < AudiosParseError; end
+    ##
+    # Unable to login.
+    class LoginError < VkMusicError; end
     
-    # Unable to convert string to id.
-    class IdParseError < AudiosParseError; end
-
-    # Unable to parse audios from wall.
-    class WallParseError < AudiosParseError; end
-      
-    # Unable to parse audios from post.
-    class PostParseError < AudiosParseError; end
   end
 
   include Exceptions

data/lib/vk_music/link_decoder.rb

@@ -2,9 +2,11 @@ require "execjs"
 
 module VkMusic
 
+  ##
   # Module containing link decoding utilities.
   module LinkDecoder
 
+    ##
     # JS code which creates function to unmask audio URL.
     js_code = <<~HEREDOC
     function vk_unmask_link(link, vk_id) {
@@ -87,17 +89,19 @@ module VkMusic
     }
     HEREDOC
 
+    ##
+    # JS context with unmasking link.
     @@js_context = ExecJS.compile(js_code)
     
+    ##
     # Unmask audio download URL.
     #
-    # ===== Parameters:
-    # * [+link+] (+String+) - encoded link to audio. Usually looks like "https://m.vk.​com/mp3/audio_api_unavailable.mp3?extra=...".
-    # * [+client_id+] (+Integer+) - ID of user which got this link. ID is required for decoding.
+    # @param link [String] encoded link to audio. Usually looks like "https://m.vk.​com/mp3/audio_api_unavailable.mp3?extra=...".
+    # @param client_id [Integer] ID of user which got this link. ID is required for decoding.
     #
-    # ===== Returns:
-    # * (+String+) - audio download URL, which can be used from current IP.
+    # @return [String] audio download URL, which can be used only from current IP.
     def self.unmask_link(link, client_id)
+      Utility.debug("Unmasking link.")
       @@js_context.call("vk_unmask_link", link.to_s, client_id.to_i)
     end
 

data/lib/vk_music/playlist.rb

@@ -1,87 +1,98 @@
 module VkMusic
 
-  # VK playlist. Extended with Enumerable.
+  ##
+  # VK playlist.
   class Playlist
     include Enumerable
     
-    # Playlist id.
+    ##
+    # @return [Integer, nil] playlist ID.
     attr_reader :id
-    # Owner of playlist.
+
+    ##
+    # @return [Integer, nil] owner of playlist ID.
     attr_reader :owner_id
-    # Access hash which should be part of link for some playlists.
+
+    ##
+    # @return [String, nil] access hash which should be part of link for some playlists.
     attr_reader :access_hash
-    # Playlist title.
+
+    ##
+    # @return [String] playlist title.
     attr_reader :title
-    # Playlist subtitle. May be empty.
+
+    ##
+    # @return [String, nil] playlist subtitle. May be empty.
     attr_reader :subtitle
     
-    # Return string describing playlist in Russian.
+    ##
+    # @return [String] playlist description in Russian.
     def to_s
-      (@subtitle.empty? ? "" : "#{@subtitle} - ") + "#{@title} (#{self.length} аудиозаписей)"
+      (@subtitle ? "#{@subtitle} - " : "") + "#{@title} (#{self.length} аудиозаписей)"
     end
 
-    # Same to +to_s+, but also outputs list of audios.
+    ##
+    # @return [String] Same to {#to_s}, but also outputs list of audios.
     def pp
-      "#{to_s}:\n#{@list.map(&:to_s).join("\n")}"
+      "#{to_s}:\n#{@list.map(&:pp).join("\n")}"
     end
 
-    # Returns audios array.
+    ##
+    # @return [Array<Audio>] Returns duplicate of array of playlist audios.
     def to_a
       @list.dup
     end
     
-    # :nodoc:
+    ##
+    # @see Array#each
     def each(&block)
       @list.each(&block)
     end
 
-    # :stopdoc:
+    ##
+    # @see Array#length
     def length
       @list.length
     end
     alias size length
 
+    ##
+    # @see Array#empty?
     def empty?
       @list.empty?
     end
-    # :startdoc:
     
-    # Access to audios from playlist.
-    #
-    # ===== Parameters:
-    # * [+index+] (+Integer+) - index of audio (starting from 0).
+    ##
+    # Access audios from playlist.
     #
-    # ===== Returns:
-    # * (+Audio+, +nil+) - audio or +nil+ if out of range.
+    # @param index [Integer] index of audio (starting from 0).
+    # 
+    # @return [Audio, nil] audio or +nil+ if out of range.
     def [](index)
       @list[index]
     end
   
+    ##
     # Initialize new playlist.
     #
-    # ===== Parameters:
-    # * [+list+] (+Array+) - list of audios in album.
-    # * [+options+] (+Hash+)
+    # @param list [Array] list of audios in playlist.
     #
-    # ===== Options:
-    # * [+:id+]
-    # * [+:owner_id+]
-    # * [+:access_hash+]
-    # * [+:title+]
-    # * [+:subtitle+]
+    # @option options [Integer] :id
+    # @option options [Integer] :owner_id
+    # @option options [String] :access_hash
+    # @option options [String] :title
+    # @option options [String] :subtitle
     def initialize(list, options = {})
-      # Arguments check
-      raise ArgumentError, "array of audios must be provided", caller unless list.class == Array
-      
+      raise ArgumentError, "Bad arguments", caller unless list.class == Array      
       # Saving list
       @list = list.dup
       
       # Setting up attributes
-      @id          = options[:id].to_s
-      @owner_id    = options[:owner_id].to_s
-      @access_hash = options[:access_hash].to_s
+      @id          = Utility.unless_nil_to Integer, options[:id]
+      @owner_id    = Utility.unless_nil_to Integer, options[:owner_id]
+      @access_hash = Utility.unless_nil_to String, options[:access_hash]
       @title       = options[:title].to_s
-      @subtitle    = options[:subtitle].to_s
+      @subtitle    = Utility.unless_nil_to String, options[:subtitle]
     end
   
   end

data/lib/vk_music/utility.rb

@@ -1,53 +1,55 @@
 require "cgi"
+require "logger"
 
 module VkMusic
 
+  ##
   # Utility methods.
   module Utility
   
+    ##
     # Turn amount of seconds into string.
     #
-    # ===== Parameters:
-    # * [+s+] (+Integer+) - amount of seconds.
+    # @param s [Integer] amount of seconds.
     #
-    # ===== Returns:
-    # * (+String+) - formatted string.
+    # @return [String] formatted string.
     def self.format_seconds(s)
       s = s.to_i # Require integer      
       "#{(s / 60).to_s.rjust(2, "0")}:#{(s % 60).to_s.rjust(2, "0")}";
     end
     
+    ##
     # Guess type of request by from string.
     #
-    # ===== Parameters:
-    # * [+str+] (+String+) - request from user for some audios.
-    #
-    # ===== Returns:
+    # Possible results:
     # * +:playlist+ - if string match playlist URL.
     # * +:post+ - if string match post URL.
     # * +:audios+ - if string match user or group URL.
     # * +:find+ - in rest of cases.
+    #
+    # @param str [String] request from user for some audios.
+    #
+    # @return [Symbol]
     def self.guess_request_type(str)
       # Guess what type of request is this. Returns Symbol: :find, :playlist, :audios
       case str
-        when Constants::PLAYLIST_URL_REGEX
+        when Constants::Regex::VK_PLAYLIST_URL_POSTFIX
           :playlist
-        when Constants::POST_URL_REGEX
+        when Constants::Regex::VK_WALL_URL_POSTFIX, Constants::Regex::VK_POST_URL_POSTFIX
           :post
-        when Constants::VK_URL_REGEX
+        when Constants::Regex::VK_URL
           :audios
       else
         :find
       end
     end
 
+    ##
     # Turn hash into URL query string.
     #
-    # ===== Parameters:
-    # * [+hash+] (+Hash+)
+    # @param hash [Hash]
     #
-    # ===== Returns:
-    # * (+String+)
+    # @return [String]
     def self.hash_to_params(hash = {})
       qs = ""
       hash.each_key do |key|
@@ -62,12 +64,48 @@ module VkMusic
       qs
     end
 
+    ##
+    # Utility loggers
+    @@loggers = {
+      debug: Logger.new(STDOUT),
+      warn: Logger.new(STDERR)
+    }
+    @@loggers[:debug].level = Logger::DEBUG
+    @@loggers[:warn].level = Logger::WARN
+
+    ##
     # Send warning.
     def self.warn(*args)
-      if defined?(Warning.warn)
-        Warning.warn args.join("\n")
-      else
-        STDERR.puts "Warning:", *args
+      @@loggers[:warn].warn(args.join("\n"))
+    end
+
+    ##
+    # Send debug message.
+    def self.debug(*args)
+      @@loggers[:debug].debug(args.join("\n")) if $DEBUG
+    end
+
+    ##
+    # Function to turn values into given class unless nil provided
+    #
+    # Supported types:
+    # * +String+
+    # * +Integer+
+    #
+    # @param new_class [Class] class to transform to.
+    # @param obj [Object] object to check.
+    #
+    # @return object transformed to given class or +nil+ if object was +nil+ already.
+    def self.unless_nil_to(new_class, obj)
+      case
+        when obj.nil?
+          nil
+        when String <= new_class
+          obj.to_s
+        when Integer <= new_class
+          obj.to_i
+        else
+          raise ArgumentError, "Bad arguments", caller
       end
     end