vk_music 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ccf9ed379a89eda14ad649e19b7b5626045d6d348d4bdb0855155ab83cae752
-  data.tar.gz: de7cd8866f59df7bea26f5cffa29900361d70e3559704b26d93928b657172d66
+  metadata.gz: 0c6e2d05ccf44bc32534cc66a85c2495f799e247876495df962bd312b3cef644
+  data.tar.gz: acc2fab3d0f196536f195cecea4f5bd0c997a6e14566a9a8a574b444db98bf4e
 SHA512:
-  metadata.gz: 1d4ebee0fb3e0cd2a38fc077de818e167c6f154a3c065ce524359f1c2dd9e3813dfbeb53ebcedf68e91d401f0be90647a851a97a527ae6d985364105a41f363f
-  data.tar.gz: 41122b9abf3f900c5ea56b063368f1e902eefc7afa939f3ea2febd18fd5978394ac18f6ade0abd7446aa064d95ddc73859f1c15f3a9144a34c07a5ad7c280149
+  metadata.gz: 9f31a0049dc14a0ef0603f503733593a5bd8ffc2a26cae4ce4c6bb4ace98d175f86745ead97e2293d9157a2bf62b323c2f61254c01940b37505715c35454fdbc
+  data.tar.gz: 20fa21e9ee919f544664c20c149089ce594967bafa9809e7ab28ed68f53ab68d0147f5451fac66d83fe4453d1e3c388614fc543958f024d911ff24439cf94bb5

data/lib/vk_music/audio.rb

@@ -2,10 +2,38 @@ require "cgi"
 
 module VkMusic
 
+  # VK audio.
   class Audio
   
-    attr_reader :id, :owner_id, :secret_1, :secret_2, :artist, :title, :duration, :url, :url_encoded
+    # Id of audio.
+    attr_reader :id
+    # Id of audio owner.
+    attr_reader :owner_id
+    # Parts of secret hash which used when using +act=reload_audio+
+    attr_reader :secret_1, :secret_2
+    # Artist.
+    attr_reader :artist
+    # Title.
+    attr_reader :title
+    # Duration.
+    attr_reader :duration
+    # Download URL.
+    attr_reader :url
+    # Encoded URL.
+    attr_reader :url_encoded
 
+    # Update audio URLs.
+    #
+    # If +:url+ is provided - just save it.
+    # If +:url_encoded+ and +:client_id+ provided - unmask link first.
+    #
+    # ===== Parameters:
+    # * [+options+] (+Hash+)
+    #
+    # ===== Options:
+    # * +:url+
+    # * +:url_encoded+
+    # * +:client_id+
     def update_url(options)
       raise ArgumentError, "options hash must be provided", caller unless options.class == Hash
       if !options[:url].to_s.empty?
@@ -13,20 +41,37 @@ module VkMusic
         @url = options[:url].to_s
       elsif !options[:url].to_s.empty? && options[:client_id]
         @url_encoded = options[:url_encoded].to_s
-        @url = VkMusic.unmask_link(options[:url_encoded], options[:client_id])
+        @url = VkMusic::LinkDecoder.unmask_link(options[:url_encoded], options[:client_id])
       else
         raise ArgumentError, "You should either provide :url or :url_encoded and :client_id", caller
       end
     end
     
+    # Returns string with information about audio.
     def to_s
       "#{@artist} - #{@title} [#{Utility.format_seconds(@duration)}]"
     end
 
+    # Returns extended information about audio.
     def pp
       "#{to_s} (Got decoded URL: #{@url ? "yes" : "no"}, able to get URL from VK: #{@id && @owner_id && @secret_1 && @secret_2 ? "yes" : "no"})"
     end
   
+    # Initialize new audio.
+    #
+    # ===== Parameters:
+    # * [+options+] (+Hash+)
+    #
+    # ===== Options:
+    # * +:id+
+    # * +:owner_id+
+    # * +:secret_1+
+    # * +:secret_2+
+    # * +:artist+
+    # * +:title+
+    # * +:duration+
+    # * +:url_encoded+
+    # * +:url+
     def initialize(options)
       # Arguments check
       raise ArgumentError, "options hash must be provided", caller unless options.class == Hash
@@ -46,6 +91,11 @@ module VkMusic
       @url         = options[:url].to_s
     end
     
+    # Initialize new audio from Nokogiri HTML node.
+    #
+    # ===== Parameters:
+    # * [+node+] (+Nokogiri::XML::Node+)
+    # * [+client_id+] (+Integer+)
     def self.from_node(node, client_id)
       url_encoded = node.at_css("input").attribute("value").to_s
       url_encoded = nil if url_encoded == "https://m.vk.com/mp3/audio_api_unavailable.mp3"
@@ -58,10 +108,15 @@ module VkMusic
         :title => node.at_css(".ai_title").text.strip,
         :duration => node.at_css(".ai_dur").attribute("data-dur").to_s.to_i,
         :url_encoded => url_encoded,
-        :url => url_encoded ? VkMusic.unmask_link(url_encoded, client_id) : nil,
+        :url => url_encoded ? VkMusic::LinkDecoder.unmask_link(url_encoded, client_id) : nil,
       })
     end
     
+    # Initialize new audio from data array.
+    #
+    # ===== Parameters:
+    # * [+data+] (+Array+)
+    # * [+client_id+] (+Integer+)
     def self.from_data_array(data, client_id)
       url_encoded = data[2]
       url_encoded = nil if url_encoded == ""
@@ -77,7 +132,7 @@ module VkMusic
         :title => CGI.unescapeHTML(data[3]),
         :duration => data[5],
         :url_encoded => url_encoded,
-        :url => url_encoded ? VkMusic.unmask_link(url_encoded, client_id) : nil,
+        :url => url_encoded ? VkMusic::LinkDecoder.unmask_link(url_encoded, client_id) : nil,
       })
     end
   

data/lib/vk_music/client.rb

@@ -3,9 +3,13 @@ require "json"
 
 module VkMusic
 
+  # Main class with all the interface.
   class Client
   
-    attr_reader :id, :name
+    # ID of user
+    attr_reader :id
+    # Name of user
+    attr_reader :name
     
     # Mechanize agent
     @agent = nil
@@ -21,16 +25,31 @@ module VkMusic
       login(options[:username], options[:password])
     end
     
+    # Find Audio.
+    #
+    # ===== Parameters:
+    # * [+query+] (+String+) - string to search for.
+    #
+    # ===== Returns:
+    # * (+Array+) - array of Audio.
     def find_audio(query)
-      uri = URI(VK_URL[:audios])
+      uri = URI(Constants::VK_URL[:audios])
       uri.query = Utility.hash_to_params({ "act" => "search", "q" => query.to_s })
       load_audios_from_page(uri)
     end
     
+    # Get Playlist.
+    #
+    # ===== Parameters:
+    # * [+url+] (+String+) - url to playlist.
+    # * [+up_to+] (+Integer+) - maximum amount of Audio to load.
+    #
+    # ===== Returns:
+    # * (+Playlist+)
     def get_playlist(url, up_to = nil)
       # NOTICE: it is possible to use same type of requests as in get_audios method
       begin
-        url, owner_id, id, access_hash = url.to_s.match(PLAYLIST_URL_REGEX).to_a
+        url, owner_id, id, access_hash = url.to_s.match(Constants::PLAYLIST_URL_REGEX).to_a
       
         # Load first page and get info
         first_page = load_playlist_page(owner_id: owner_id, id: id, access_hash: access_hash, offset: 0)
@@ -47,7 +66,7 @@ module VkMusic
           playlist_size = 0
         end
       rescue Exception => error
-        raise PlaylistParseError, "unable to parse playlist page. Error: #{error.message}", caller
+        raise Exceptions::PlaylistParseError, "unable to parse playlist page. Error: #{error.message}", caller
       end
       # Now we can be sure we are on correct page
       
@@ -75,7 +94,15 @@ module VkMusic
       })
     end
     
-    def get_audios(obj, up_to = nil)
+    # Get user or group audios.
+    #
+    # ===== Parameters:
+    # * [+url+] (+String+) - URL to user or group.
+    # * [+up_to+] (+Integer+) - maximum amount of Audio to load.
+    #
+    # ===== Returns:
+    # * (+Playlist+)
+    def get_audios(url, up_to = nil)
       if up_to && up_to > 100
         Utility.warn("Current implementation of method VkMusic::Client#get_audios is only able to load first 100 audios from user page.")
       end
@@ -84,7 +111,7 @@ module VkMusic
       # NOTICE: it is possible to load up to 2000 audios **without url** if offset is negative
       
       # Firstly, we need to get numeric id
-      id = get_id(obj.to_s)      
+      id = get_id(url.to_s)      
       
       # Trying to parse out audios
       begin
@@ -92,7 +119,7 @@ module VkMusic
         first_data = first_json["data"][0]
         first_data_audios = load_audios_from_data(first_data["list"])
       rescue Exception => error
-        raise AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
+        raise Exceptions::AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
       end
       
       #total_count = first_data["totalCount"] # NOTICE: not used due to restrictions described above
@@ -113,6 +140,13 @@ module VkMusic
       })
     end
 
+    # Get audios by their ids and secrets.
+    #
+    # ===== Parameters:
+    # * [+arr+] (+Array+) - Array of objects, which can have different types: Audio or Array[owner_id, id, secret_1, secret_2].
+    #
+    # ===== Returns:
+    # * (+Array+) - array of audios with decoded URLs.
     def get_audios_by_id(*arr)
       if arr.size > 10
         Utility.warn("Current implementation of method VkMusic::Client#get_audios_by_id is only able to handle first 10 audios.")
@@ -131,18 +165,27 @@ module VkMusic
       end
       json = load_audios_json_by_id(arr)
       result = load_audios_from_data(json["data"][0].to_a)
-      raise ReloadAudiosParseError, "Result size don't match: excepected #{arr.size}, got #{result.size}", caller if result.size != arr.size
+      raise Exceptions::ReloadAudiosParseError, "Result size don't match: excepected #{arr.size}, got #{result.size}", caller if result.size != arr.size
 
       result
     end
 
+    # Get audios on wall of user or group starting with given post.
+    #
+    # ===== Parameters:
+    # * [+owner_id+] (+Integer+)
+    # * [+post_id+] (+Integer+)
+    # * [+up_to+] (+Integer+) - maximum amount of Audio to load.
+    #
+    # ===== Returns:
+    # * (+Array+) - array of audios with URLs.
     def get_audios_from_wall(owner_id, post_id, up_to = nil)
       begin
         json = load_audios_json_from_wall(owner_id, post_id)
         data = json["data"][0]
         no_url_audios = load_audios_from_data(data["list"])
       rescue Exception => error
-        raise WallParseError, "Failed to parse wall from #{@owner_id}_#{post_id}. Error: #{error.message}", caller
+        raise Exceptions::WallParseError, "Failed to parse wall from #{@owner_id}_#{post_id}. Error: #{error.message}", caller
       end
 
       up_to = no_url_audios.size if (up_to.nil? || up_to < 0 || up_to > no_url_audios.size)
@@ -159,54 +202,75 @@ module VkMusic
       })
     end
     
+    # Get audios attached to post.
+    #
+    # ===== Parameters:
+    # * [+url+] (+String+)
+    #
+    # ===== Returns:
+    # * (+Array+) - array of audios with URLs.
     def get_audios_from_post(url)
-      url, owner_id, post_id = url.match(POST_URL_REGEX).to_a
+      url, owner_id, post_id = url.match(Constants::POST_URL_REGEX).to_a
 
       amount = get_amount_of_audios_in_post(owner_id, post_id)
       get_audios_from_wall(owner_id, post_id, amount).to_a
     end
 
-
+    # Get user or group id.
+    #
+    # ===== Parameters:
+    # * [+str+] (+String+) - link, id with prefix or custom id.
+    #
+    # ===== Returns:
+    # * (+Integer+)
     def get_id(str)
       case str
-        when VK_URL_REGEX
-          path = str.match(VK_URL_REGEX)[1]
+        when Constants::VK_URL_REGEX
+          path = str.match(Constants::VK_URL_REGEX)[1]
           get_id(path) # Recursive call
-        when VK_ID_REGEX
+        when Constants::VK_ID_REGEX
           str
-        when VK_AUDIOS_REGEX
+        when Constants::VK_AUDIOS_REGEX
           str.match(/-?\d+/).to_s # Numbers with sigh
-        when VK_PREFIXED_ID_REGEX
+        when Constants::VK_PREFIXED_ID_REGEX
           id = str.match(/\d+/).to_s # Just numbers. Sign needed
           id = "-#{id}" unless str.start_with?("id")
           id
-        when VK_CUSTOM_ID_REGEX
+        when Constants::VK_CUSTOM_ID_REGEX
           begin
-            page = load_page("#{VK_URL[:home]}/#{str}")
+            page = load_page("#{Constants::VK_URL[:home]}/#{str}")
           rescue Exception => error
-            raise IdParseError, "unable to load page by id \"#{str}\". Error: #{error.message}"
+            raise Exceptions::IdParseError, "unable to load page by id \"#{str}\". Error: #{error.message}"
           end
           
           unless page.at_css(".PageBlock .owner_panel")
             # Ensure this isn't some random vk page
-            raise IdParseError, "page #{str} doesn't seem to be a group or user page"
+            raise Exceptions::IdParseError, "page #{str} doesn't seem to be a group or user page"
           end
           
-          id = page.link_with(href: VK_HREF_ID_CONTAINING_REGEX).href.slice(/-?\d+/) # Numbers with sign
+          id = page.link_with(href: Constants::VK_HREF_ID_CONTAINING_REGEX).href.slice(/-?\d+/) # Numbers with sign
           id
       else
-        raise IdParseError, "unable to convert \"#{str}\" into id"
+        raise Exceptions::IdParseError, "unable to convert \"#{str}\" into id"
       end
     end
 
+    # Get amount of audios attached to specified post.
+    #
+    # ===== Parameters:
+    # * [+owner_id+] (+Integer+)
+    # * [+post_id+] (+Integer+)
+    #
+    # ===== Returns:
+    # * (+Integer+)
     def get_amount_of_audios_in_post(owner_id, post_id)
       begin
-        page = load_page("#{VK_URL[:wall]}#{owner_id}_#{post_id}")
+        page = load_page("#{Constants::VK_URL[:wall]}#{owner_id}_#{post_id}")
         result = page.css(".wi_body > .pi_medias .medias_audio").size
       rescue Exception => error
-        raise PostParseError, "Unable to get amount of audios in post #{owner_id}_#{post_id}. Error: #{error.message}", caller
+        raise Exceptions::PostParseError, "Unable to get amount of audios in post #{owner_id}_#{post_id}. Error: #{error.message}", caller
       end
-      raise PostParseError, "Post not found: #{owner_id}_#{post_id}", caller if result == 0 && !page.css(".service_msg_error").empty?
+      raise Exceptions::PostParseError, "Post not found: #{owner_id}_#{post_id}", caller if result == 0 && !page.css(".service_msg_error").empty?
       result
     end
 
@@ -224,7 +288,7 @@ module VkMusic
     end
     
     def load_playlist_page(options)
-      uri = URI(VK_URL[:audios])
+      uri = URI(Constants::VK_URL[:audios])
       uri.query = Utility.hash_to_params({
         "act" => "audio_playlist#{options[:owner_id]}_#{options[:id]}",
         "access_hash" => options[:access_hash].to_s,
@@ -233,7 +297,7 @@ module VkMusic
       load_page(uri)
     end
     def load_playlist_json_section(owner_id, playlist_id, offset = 0)
-      uri = URI(VK_URL[:audios])
+      uri = URI(Constants::VK_URL[:audios])
       uri.query = Utility.hash_to_params({
         "act" => "load_section",
         "owner_id" => owner_id,
@@ -245,12 +309,12 @@ module VkMusic
       begin
         load_json(uri)
       rescue Exception => error
-        raise AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
+        raise Exceptions::AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
       end
     end
 
     def load_audios_json_by_id(ids)
-      uri = URI(VK_URL[:audios])
+      uri = URI(Constants::VK_URL[:audios])
       uri.query = Utility.hash_to_params({
         "act" => "reload_audio",
         "ids" => ids,
@@ -259,12 +323,12 @@ module VkMusic
       begin
         load_json(uri)
       rescue Exception => error
-        raise AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
+        raise Exceptions::AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
       end
     end
 
     def load_audios_json_from_wall(owner_id, post_id)
-      uri = URI(VK_URL[:audios])
+      uri = URI(Constants::VK_URL[:audios])
       uri.query = Utility.hash_to_params({
         "act" => "load_section",
         "owner_id" => owner_id,
@@ -276,7 +340,7 @@ module VkMusic
       begin
         load_json(uri)
       rescue Exception => error
-        raise AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
+        raise Exceptions::AudiosSectionParseError, "unable to load or parse audios section: #{error.message}", caller
       end
     end
     
@@ -294,24 +358,24 @@ module VkMusic
     # Login
     def login(username, password)
       # Loading login page
-      homepage = load_page(VK_URL[:home])
+      homepage = load_page(Constants::VK_URL[:home])
       # Submitting login form
-      login_form = homepage.forms.find { |form| form.action.start_with?(VK_URL[:login_action]) }
-      login_form[VK_LOGIN_FORM_NAMES[:username]] = username.to_s
-      login_form[VK_LOGIN_FORM_NAMES[:password]] = password.to_s
+      login_form = homepage.forms.find { |form| form.action.start_with?(Constants::VK_URL[:login_action]) }
+      login_form[Constants::VK_LOGIN_FORM_NAMES[:username]] = username.to_s
+      login_form[Constants::VK_LOGIN_FORM_NAMES[:password]] = password.to_s
       after_login = @agent.submit(login_form)
 
       # Checking whether logged in
-      raise LoginError, "unable to login. Redirected to #{after_login.uri.to_s}", caller unless after_login.uri.to_s == VK_URL[:feed]
+      raise Exceptions::LoginError, "unable to login. Redirected to #{after_login.uri.to_s}", caller unless after_login.uri.to_s == Constants::VK_URL[:feed]
       
       # Parsing information about this profile
-      profile = load_page(VK_URL[:profile])      
+      profile = load_page(Constants::VK_URL[:profile])      
       @name = profile.title
-      @id = profile.link_with(href: VK_HREF_ID_CONTAINING_REGEX).href.slice(/\d+/)
+      @id = profile.link_with(href: Constants::VK_HREF_ID_CONTAINING_REGEX).href.slice(/\d+/)
     end
     
     def unmask_link(link)
-      VkMusic.unmask_link(link, @id)
+      VkMusic::LinkDecoder.unmask_link(link, @id)
     end
     
   end

data/lib/vk_music/constants.rb

@@ -1,41 +1,46 @@
 module VkMusic
 
-  # Web
-  # DEFAULT_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1636.0 Safari/537.36"
+  # Constants
+  module Constants
+    # Web
+    # 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"
-  }
-  
-  VK_LOGIN_FORM_NAMES = {
-    :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]+))?/
+    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"
+    }
+    
+    VK_LOGIN_FORM_NAMES = {
+      :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+)/
+    
+    
+    # QUESTION: Should I move ALL the constants (string, regex etc) here? It would make code more flexible, but seems like overkill
+  end
+
+  include Constants
 
-  # Post
-  POST_URL_REGEX = /.*wall(-?\d+)_(\d+)/
-  
-  
-  # QUESTION: Should I move ALL the constants (string, regex etc) here? It would make code more flexible, but seems like overkill
-  
 end

data/lib/vk_music/exceptions.rb

@@ -1,30 +1,35 @@
 module VkMusic
 
-  # General class for all the errors
-  class VkMusicError < RuntimeError; end
+  # 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 login.
+    class LoginError < VkMusicError; end
+    
+    # Unable to parse audios from somewhere.
+    class AudiosParseError < VkMusicError; end
 
-  # Unable to load or parse audios section from json
-  class AudiosSectionParseError < AudiosParseError; end
+    # Unable to find playlist or got permission error.
+    class PlaylistParseError < AudiosParseError; end
 
-  # Unable to load or parse all of audios by ids
-  class ReloadAudiosParseError < AudiosParseError; end
-  
-  # Unable to convert string to id
-  class IdParseError < AudiosParseError; end
+    # Unable to load or parse audios section from json.
+    class AudiosSectionParseError < AudiosParseError; end
 
-  # Unable to parse audios from wall
-  class WallParseError < AudiosParseError; end
+    # Unable to load or parse all of audios by ids.
+    class ReloadAudiosParseError < AudiosParseError; end
     
-  # Unable to parse audios from post
-  class PostParseError < AudiosParseError; 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
   
 end

data/lib/vk_music/link_decoder.rb

@@ -2,92 +2,105 @@ require "execjs"
 
 module VkMusic
 
-  # Setting up decoding context
-  js_code = <<~HEREDOC
-  function vk_unmask_link(link, vk_id) {
+  # Module containing link decoding utilities.
+  module LinkDecoder
 
-    // Utility functions to unmask
+    # JS code which creates function to unmask audio URL.
+    js_code = <<~HEREDOC
+    function vk_unmask_link(link, vk_id) {
 
-    var audioUnmaskSource = function (encrypted) {
-      if (encrypted.indexOf('audio_api_unavailable') != -1) {
-        var parts = encrypted.split('?extra=')[1].split('#');
+      // Utility functions to unmask
 
-        var handled_anchor = '' === parts[1] ? '' : handler(parts[1]);
+      var audioUnmaskSource = function (encrypted) {
+        if (encrypted.indexOf('audio_api_unavailable') != -1) {
+          var parts = encrypted.split('?extra=')[1].split('#');
 
-        var handled_part = handler(parts[0]);
+          var handled_anchor = '' === parts[1] ? '' : handler(parts[1]);
 
-        if (typeof handled_anchor != 'string' || !handled_part) {
-          // if (typeof handled_anchor != 'string') console.warn('Handled_anchor type: ' + typeof handled_anchor);
-          // if (!handled_part) console.warn('Handled_part: ' + handled_part);
-          return encrypted;
-        }
-
-        handled_anchor = handled_anchor ? handled_anchor.split(String.fromCharCode(9)) : [];
+          var handled_part = handler(parts[0]);
 
-        for (var func_key, splited_anchor, l = handled_anchor.length; l--;) {
-          splited_anchor = handled_anchor[l].split(String.fromCharCode(11));
-          func_key = splited_anchor.splice(0, 1, handled_part)[0];
-          if (!utility_object[func_key]) {
-            // console.warn('Was unable to find key: ' + func_key);
+          if (typeof handled_anchor != 'string' || !handled_part) {
+            // if (typeof handled_anchor != 'string') console.warn('Handled_anchor type: ' + typeof handled_anchor);
+            // if (!handled_part) console.warn('Handled_part: ' + handled_part);
             return encrypted;
           }
-          handled_part = utility_object[func_key].apply(null, splited_anchor)
-        }
 
-        if (handled_part && 'http' === handled_part.substr(0, 4)) return handled_part;
-        // else console.warn('Failed unmasking: ' + handled_part);
-      } else {
-        // console.warn('Bad link: ' + encrypted);
+          handled_anchor = handled_anchor ? handled_anchor.split(String.fromCharCode(9)) : [];
+
+          for (var func_key, splited_anchor, l = handled_anchor.length; l--;) {
+            splited_anchor = handled_anchor[l].split(String.fromCharCode(11));
+            func_key = splited_anchor.splice(0, 1, handled_part)[0];
+            if (!utility_object[func_key]) {
+              // console.warn('Was unable to find key: ' + func_key);
+              return encrypted;
+            }
+            handled_part = utility_object[func_key].apply(null, splited_anchor)
+          }
+
+          if (handled_part && 'http' === handled_part.substr(0, 4)) return handled_part;
+          // else console.warn('Failed unmasking: ' + handled_part);
+        } else {
+          // console.warn('Bad link: ' + encrypted);
+        }
+        return encrypted;
       }
-      return encrypted;
-    }
 
-    var handler = function (part) {
-      if (!part || part.length % 4 == 1) return !1;
-      for (var t, i, o = 0, s = 0, a = ''; i = part.charAt(s++);) {
-        i = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN0PQRSTUVWXYZO123456789+/='.indexOf(i)
-        ~i && (t = o % 4 ? 64 * t + i : i, o++ % 4) && (a += String.fromCharCode(255 & t >> (-2 * o & 6)));
+      var handler = function (part) {
+        if (!part || part.length % 4 == 1) return !1;
+        for (var t, i, o = 0, s = 0, a = ''; i = part.charAt(s++);) {
+          i = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN0PQRSTUVWXYZO123456789+/='.indexOf(i)
+          ~i && (t = o % 4 ? 64 * t + i : i, o++ % 4) && (a += String.fromCharCode(255 & t >> (-2 * o & 6)));
+        }
+        return a;
       }
-      return a;
-    }
 
-    var utility_object = {
-      i: function(e, t) {
-        return utility_object.s(e, t ^ vk_id);
-      },
-      s: function(e, t) {
-        var n = e.length;
+      var utility_object = {
+        i: function(e, t) {
+          return utility_object.s(e, t ^ vk_id);
+        },
+        s: function(e, t) {
+          var n = e.length;
+          if (n) {
+            var i = r_func(e, t),
+              o = 0;
+            for (e = e.split(''); ++o < n;)
+              e[o] = e.splice(i[n - 1 - o], 1, e[o])[0];
+            e = e.join('')
+          }
+          return e;
+        }
+      };
+
+      var r_func = function (e, t) {
+        var n = e.length,
+          i = [];
         if (n) {
-          var i = r_func(e, t),
-            o = 0;
-          for (e = e.split(''); ++o < n;)
-            e[o] = e.splice(i[n - 1 - o], 1, e[o])[0];
-          e = e.join('')
+          var o = n;
+          for (t = Math.abs(t); o--;)
+            t = (n * (o + 1) ^ t + o) % n,
+            i[o] = t;
         }
-        return e;
-      }
-    };
-
-    var r_func = function (e, t) {
-      var n = e.length,
-        i = [];
-      if (n) {
-        var o = n;
-        for (t = Math.abs(t); o--;)
-          t = (n * (o + 1) ^ t + o) % n,
-          i[o] = t;
+        return i;
       }
-      return i;
+
+      return audioUnmaskSource(link);
     }
+    HEREDOC
 
-    return audioUnmaskSource(link);
-  }
-HEREDOC
+    @@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.
+    #
+    # ===== Returns:
+    # * (+String+) - audio download URL, which can be used from current IP.
+    def self.unmask_link(link, client_id)
+      @@js_context.call("vk_unmask_link", link.to_s, client_id.to_i)
+    end
 
-  @@js_context = ExecJS.compile(js_code)
-  
-  def self.unmask_link(link, client_id)
-    @@js_context.call("vk_unmask_link", link.to_s, client_id.to_i)
   end
   
-end
+end

data/lib/vk_music/playlist.rb

@@ -1,39 +1,74 @@
 module VkMusic
 
+  # VK playlist. Extended with Enumerable.
   class Playlist
     include Enumerable
     
-    attr_reader :id, :owner_id, :access_hash, :title, :subtitle
-    
-    def length
-      @list.length
-    end
-    alias size length
+    # Playlist id.
+    attr_reader :id
+    # Owner of playlist.
+    attr_reader :owner_id
+    # Access hash which should be part of link for some playlists.
+    attr_reader :access_hash
+    # Playlist title.
+    attr_reader :title
+    # Playlist subtitle. May be empty.
+    attr_reader :subtitle
     
+    # Return string describing playlist in Russian.
     def to_s
       (@subtitle.empty? ? "" : "#{@subtitle} - ") + "#{@title} (#{self.length} аудиозаписей)"
     end
 
+    # Same to +to_s+, but also outputs list of audios.
     def pp
       "#{to_s}:\n#{@list.map(&:to_s).join("\n")}"
     end
 
+    # Returns audios array.
     def to_a
       @list.dup
     end
     
+    # :nodoc:
     def each(&block)
       @list.each(&block)
     end
-    
-    def [](index)
-      @list[index]
+
+    # :stopdoc:
+    def length
+      @list.length
     end
-    
+    alias size length
+
     def empty?
       @list.empty?
     end
+    # :startdoc:
+    
+    # Access to audios from playlist.
+    #
+    # ===== Parameters:
+    # * [+index+] (+Integer+) - index of audio (starting from 0).
+    #
+    # ===== Returns:
+    # * (+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+)
+    #
+    # ===== Options:
+    # * [+:id+]
+    # * [+:owner_id+]
+    # * [+:access_hash+]
+    # * [+:title+]
+    # * [+:subtitle+]
     def initialize(list, options = {})
       # Arguments check
       raise ArgumentError, "array of audios must be provided", caller unless list.class == Array

data/lib/vk_music/utility.rb

@@ -2,27 +2,52 @@ require "cgi"
 
 module VkMusic
 
+  # Utility methods.
   module Utility
   
+    # Turn amount of seconds into string.
+    #
+    # ===== Parameters:
+    # * [+s+] (+Integer+) - amount of seconds.
+    #
+    # ===== Returns:
+    # * (+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:
+    # * +: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.
     def self.guess_request_type(str)
       # Guess what type of request is this. Returns Symbol: :find, :playlist, :audios
       case str
-        when PLAYLIST_URL_REGEX
+        when Constants::PLAYLIST_URL_REGEX
           :playlist
-        when POST_URL_REGEX
+        when Constants::POST_URL_REGEX
           :post
-        when VK_URL_REGEX
+        when Constants::VK_URL_REGEX
           :audios
       else
         :find
       end
     end
 
+    # Turn hash into URL query string.
+    #
+    # ===== Parameters:
+    # * [+hash+] (+Hash+)
+    #
+    # ===== Returns:
+    # * (+String+)
     def self.hash_to_params(hash = {})
       qs = ""
       hash.each_key do |key|
@@ -37,6 +62,7 @@ module VkMusic
       qs
     end
 
+    # Send warning.
     def self.warn(*args)
       if defined?(Warning.warn)
         Warning.warn args.join("\n")

data/vk_music.gemspec

@@ -2,7 +2,7 @@ Gem::Specification.new do |s|
   s.name           = "vk_music"
   s.summary        = "Provides interface to work with VK music via HTTP requests"
   s.description    = "Library to work with audios on popular Russian social network vk.com. VK disabled their public API for audios, so it is now necessary to use parsers instead."
-  s.version        = "1.1.0"
+  s.version        = "1.1.1"
   s.author         = "Kuznetsov Vladislav"
   s.email          = "fizvlad@mail.ru"
   s.homepage       = "https://github.com/fizvlad/vk-music-rb"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vk_music
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Kuznetsov Vladislav
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-29 00:00:00.000000000 Z
+date: 2019-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mechanize