vkontakte_api 0.1 → 0.2

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc/*

data/.travis.yml

@@ -0,0 +1,4 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/.yardopts

@@ -0,0 +1,3 @@
+--files README.md,README.ru.md
+--markup markdown
+--markup-provider redcarpet

data/README.md

@@ -1,4 +1,4 @@
-# vkontakte_api
+# vkontakte_api [![Build Status](https://secure.travis-ci.org/7even/vkontakte_api.png)](http://travis-ci.org/7even/vkontakte_api)
 
 `vkontakte_api` is a Ruby wrapper for VKontakte API. It allows you to call all API methods in the simplest possible way.
 
@@ -20,7 +20,13 @@ VkontakteApi.configure do |config|
 end
 ```
 
-All requests are sent via `VkontakteApi::Client` instance. To create one you just pass an access token.
+All requests are sent via `VkontakteApi::Client` instance.
+
+``` ruby
+@app = VkontakteApi::Client.new
+```
+
+To create a client able to perform authorized requests you need to pass an access token.
 
 ``` ruby
 @app = VkontakteApi::Client.new('my_access_token')
@@ -47,18 +53,25 @@ Now for parameters. All method parameters are named, and you can pass them in a
 
 ``` ruby
 @app.friends.get(fields: 'uid,first_name,last_name')
-# => [
-  {
-    :uid          => "1",
-    :first_name   => "Павел",
-    :last_name    => "Дуров"
-  },
-  {
-    :uid          => "6492",
-    :first_name   => "Andrew",
-    :last_name    => "Rogozov"
-  }
-]
+# =>  [
+#       {
+#         :uid          => "1",
+#         :first_name   => "Павел",
+#         :last_name    => "Дуров"
+#       },
+#       {
+#         :uid          => "6492",
+#         :first_name   => "Andrew",
+#         :last_name    => "Rogozov"
+#       }
+#     ]
+```
+
+If the parameter value is a comma-separated list, you can pass it as an array - it will be properly handled before the request:
+
+``` ruby
+users_ids = [1, 6492]
+@app.users.get(uids: users_ids) # => same output as above
 ```
 
 It's also worth noting that all returned hashes have symbolized keys.
@@ -83,10 +96,15 @@ If VKontakte returns an error in response, you get a `VkontakteApi::Error` excep
 # => VkontakteApi::Error: VKontakte returned an error 1: 'Unknown error occured' after calling method 'audio.getById' with parameters {}.
 ```
 
+## Changelog
+
+* 0.1 Initial stable version
+* 0.2 Array arguments support, cleaned up non-authorized requests, updated namespaces list, code documentation
+
 ## Roadmap
 
 * Authentication (getting the access_token from VK)
-* RDoc coverage
+* Maybe Struct-like objects in result (instead of Hashes)
 
 ## Contributing
 

data/README.ru.md

@@ -1,4 +1,4 @@
-# vkontakte_api
+# vkontakte_api [![Build Status](https://secure.travis-ci.org/7even/vkontakte_api.png)](http://travis-ci.org/7even/vkontakte_api)
 
 `vkontakte_api` - ruby-обертка для API ВКонтакте. Она позволяет вызывать методы API настолько просто, насколько это возможно.
 
@@ -20,7 +20,13 @@ VkontakteApi.configure do |config|
 end
 ```
 
-Все запросы к API отправляются через объект класса `VkontakteApi::Client`. Чтобы создать его, нужно просто передать в конструктор токен доступа.
+Все запросы к API отправляются через объект класса `VkontakteApi::Client`.
+
+``` ruby
+@app = VkontakteApi::Client.new
+```
+
+Чтобы создать клиент для отправки авторизованных запросов, нужно просто передать в конструктор токен доступа.
 
 ``` ruby
 @app = VkontakteApi::Client.new('my_access_token')
@@ -47,18 +53,25 @@ end
 
 ``` ruby
 @app.friends.get(fields: 'uid,first_name,last_name')
-# => [
-  {
-    :uid          => "1",
-    :first_name   => "Павел",
-    :last_name    => "Дуров"
-  },
-  {
-    :uid          => "6492",
-    :first_name   => "Andrew",
-    :last_name    => "Rogozov"
-  }
-]
+# =>  [
+#       {
+#         :uid          => "1",
+#         :first_name   => "Павел",
+#         :last_name    => "Дуров"
+#       },
+#       {
+#         :uid          => "6492",
+#         :first_name   => "Andrew",
+#         :last_name    => "Rogozov"
+#       }
+#     ]
+```
+
+Если значение параметра - список, разделенный запятыми, то его можно передать в виде массива; он будет корректно обработан перед отправкой запроса:
+
+``` ruby
+users_ids = [1, 6492]
+@app.users.get(uids: users_ids) # => тот же вывод, что и выше
 ```
 
 Также следует заметить, что все возвращаемые хэши имеют символьные ключи.
@@ -83,10 +96,15 @@ end
 # => VkontakteApi::Error: VKontakte returned an error 1: 'Unknown error occured' after calling method 'audio.getById' with parameters {}.
 ```
 
+## Changelog
+
+* 0.1 Первая стабильная версия
+* 0.2 Поддержка аргументов-массивов, подчищенные неавторизованные запросы, обновленный список пространств имен, документация кода
+
 ## Планы
 
 * Авторизация (получение токена доступа с ВКонтакте)
-* Документация RDoc
+* Возможно, Struct-подобные объекты в результатах запросов (вместо Hash)
 
 ## Участие в разработке
 

data/lib/vkontakte_api.rb

@@ -11,6 +11,7 @@ require 'vkontakte_api/api'
 require 'vkontakte_api/resolver'
 require 'vkontakte_api/client'
 
+# Main module.
 module VkontakteApi
   extend VkontakteApi::Configuration
 end

data/lib/vkontakte_api/api.rb

@@ -1,9 +1,17 @@
 module VkontakteApi
+  # A low-level module which handles the requests to VKontakte and returns their results as hashes with symbolized keys.
+  # 
+  # It uses Faraday underneath the hood.
   module API
     BASE_HOST = 'https://api.vkontakte.ru'
     BASE_URL  = '/method/'
     
     class << self
+      # Main interface method.
+      # @param [String] method_name A full name of the method.
+      # @param [Hash] args Method arguments including the access token.
+      # @return [Hash] The result of the method call.
+      # @raise [VkontakteApi::Error] raised when VKontakte returns an error.
       def call(method_name, args = {}, &block)
         connection = Faraday.new(:url => BASE_HOST) do |builder|
           builder.adapter(VkontakteApi.adapter)
@@ -19,9 +27,25 @@ module VkontakteApi
           response[:response]
         end
       end
+      
     private
-      def url_for(method_name, args)
-        "#{BASE_URL}#{method_name}?#{args.to_param}"
+      def url_for(method_name, arguments)
+        flat_arguments = flatten_arguments(arguments)
+        "#{BASE_URL}#{method_name}?#{flat_arguments.to_param}"
+      end
+      
+      def flatten_arguments(arguments)
+        arguments.inject({}) do |flat_args, (arg_name, arg_value)|
+          flat_args[arg_name] = if arg_value.respond_to?(:join)
+            # if value is an array, we join it with a comma
+            arg_value.join(',')
+          else
+            # otherwise leave it untouched
+            arg_value
+          end
+          
+          flat_args
+        end
       end
     end
   end

data/lib/vkontakte_api/client.rb

@@ -1,15 +1,21 @@
 module VkontakteApi
+  # A class representing a connection to VK. It holds an access token.
   class Client
+    # An access token needed by authorized requests.
     attr_reader :access_token
     
+    # A new API client.
+    # @param [String] access_token An access token.
     def initialize(access_token = nil)
       @access_token = access_token
     end
     
+    # Is a `VkontakteApi::Client` instance authorized.
     def authorized?
       !@access_token.nil?
     end
     
+    # All unknown methods are delegated to a `VkontakteApi::Resolver` instance.
     def method_missing(method_name, *args, &block)
       args = args.first || {}
       VkontakteApi::Resolver.new(:access_token => @access_token).send(method_name, args, &block)

data/lib/vkontakte_api/configuration.rb

@@ -1,20 +1,32 @@
 module VkontakteApi
+  # General configuration module.
+  # 
+  # It extends `VkontakteApi` so it's methods should be called from there.
   module Configuration
+    # Available options.
     OPTION_NAMES = [:app_id, :app_secret, :adapter]
     
     attr_accessor *OPTION_NAMES
     
+    # Default HTTP adapter.
     DEFAULT_ADAPTER = :net_http
     
+    # A global configuration set via the block.
+    # @example
+    #   VkontakteApi.configure do |config|
+    #     config.adapter = :net_http
+    #   end
     def configure
       yield self if block_given?
       self
     end
     
+    # Reset all configuration options to defaults.
     def reset
       @adapter = DEFAULT_ADAPTER
     end
     
+    # When this module is extended, set all configuration options to their default values.
     def self.extended(base)
       base.reset
     end

data/lib/vkontakte_api/error.rb

@@ -1,5 +1,12 @@
 module VkontakteApi
+  # An exception raised by `VkontakteApi::API` when VKontakte returns an error.
   class Error < StandardError
+    # An error code.
+    # @return [Fixnum]
+    attr_reader :error_code
+    
+    # An exception is initialized by the data from response hash.
+    # @param [Hash] data Error data.
     def initialize(data)
       @error_code = data.delete(:error_code)
       @error_msg  = data.delete(:error_msg)
@@ -13,9 +20,12 @@ module VkontakteApi
       @params       = request_params
     end
     
+    # A full description of the error.
+    # @return [String]
     def message
-      "VKontakte returned an error #{@error_code}: \'#{@error_msg}\' after calling method \'#{@method_name}\' with parameters #{@params.inspect}."
+      "VKontakte returned an error #{@error_code}: '#{@error_msg}' after calling method '#{@method_name}' with parameters #{@params.inspect}."
     end
+    
   private
     def parse_params(params)
       params.inject({}) do |memo, pair|

data/lib/vkontakte_api/namespaces.yml

@@ -1,3 +1,4 @@
+- users
 - friends
 - groups
 - photos
@@ -20,3 +21,5 @@
 - likes
 - status
 - polls
+- account
+- auth

data/lib/vkontakte_api/resolver.rb

@@ -1,27 +1,49 @@
 module VkontakteApi
+  # A class for resolving namespaced methods like `friends.get`.
+  # 
+  # Methods are dispatched the following way:
+  # 
+  # 1. API client gets an unknown method, creates a `VkontakteApi::Resolver` instance and sends it the method
+  # 2. if the method is a namespace (like `friends`), it creates another `VkontakteApi::Resolver` instance, namespaced this time; else go to 3
+  # 3. the `VkontakteApi::Resolver` instance gets the last method, inserts an access token into params and sends it to `VkontakteApi::API`
+  # 4. the result is typecasted and/or yielded (mapped) to a block depending on it's type
   class Resolver
+    # A pattern for names of methods with a boolean result.
     PREDICATE_NAMES = /^(is.*)\?$/
     
+    # A namespace of the current instance (if present).
     attr_reader :namespace
     
+    # A new resolver.
+    # @option options [String] :namespace A namespace.
+    # @option options [String] :access_token An access token.
     def initialize(options = {})
       @namespace    = options.delete(:namespace)
       @access_token = options.delete(:access_token)
     end
     
+    # Main methods dispatch.
+    # 
+    # If the called method is a namespace, it creates and returns a new `VkontakteApi::Resolver` instance.
+    # Otherwise it determines the full method name and result type, and sends everything to `VkontakteApi::API`.
+    # 
+    # If the result is enumerable, each element is yielded to the block (or returned as is if called without a block).
+    # Non-enumerable results are typecasted (and yielded if the block is present).
+    # 
+    # Called with a block, it returns the result of the block; called without a block it returns just the result.
+    # @todo Break this crap into several small methods.
     def method_missing(method_name, *args, &block)
       method_name = method_name.to_s
       
       if Resolver.namespaces.include?(method_name)
-        # method with a two-level name called
+        # first level of method with a two-level name called
         Resolver.new(:namespace => method_name, :access_token => @access_token)
       else
-        # method with a one-level name called
+        # method with a one-level name called (or second level of a two-level method)
         name, type = Resolver.vk_method_name(method_name, @namespace)
         
-        # adding access_token to the args hash
         args = args.first || {}
-        args.update(:access_token => @access_token)
+        args[:access_token] = @access_token unless @access_token.nil?
         
         result = API.call(name, args, &block)
         
@@ -37,6 +59,7 @@ module VkontakteApi
         end
       end
     end
+    
   private
     def typecast(parameter, type)
       case type
@@ -49,17 +72,27 @@ module VkontakteApi
     end
     
     class << self
+      # An array of method namespaces.
+      # @return [Array]
       attr_reader :namespaces
       
-      # load namespaces array from namespaces.yml
+      # Loading namespaces array from `namespaces.yml`.
+      # This method is called automatically at startup time.
       def load_namespaces
         filename    = File.expand_path('../namespaces.yml', __FILE__)
         file        = File.read(filename)
         @namespaces = YAML.load(file)
       end
       
-      # vk_method_name('get_country_by_id', 'places')
-      # => 'places.getCountryById'
+      # A complete method name needed by VKontakte.
+      # 
+      # Returns a full name and the result type (:boolean or :anything).
+      # @example
+      #   vk_method_name('is_app_user?')
+      #   # => 'isAppUser'
+      #   vk_method_name('get_country_by_id', 'places')
+      #   # => 'places.getCountryById'
+      # @return [Array] full method name and type
       def vk_method_name(method_name, namespace = nil)
         method_name = method_name.to_s
         
@@ -78,6 +111,7 @@ module VkontakteApi
         
         [full_name, type]
       end
+      
     private
       # convert('get_profiles')
       # => 'getProfiles'

data/lib/vkontakte_api/version.rb

@@ -1,3 +1,3 @@
 module VkontakteApi
-  VERSION = '0.1'
+  VERSION = '0.2'
 end

data/spec/vkontakte_api/api_spec.rb

@@ -22,13 +22,7 @@ describe VkontakteApi::API do
       @connection.stub(:get).and_return(response)
       
       @result = stub("Result")
-      @result.stub(:has_key?) do |key|
-        if key == 'response'
-          true
-        else
-          false
-        end
-      end
+      @result.stub(:has_key?) { |key| key == 'response' }
       
       @result_response  = stub("Result[response]")
       @result_error     = stub("Result[error]").as_null_object
@@ -57,13 +51,7 @@ describe VkontakteApi::API do
     
     context "with an error response" do
       before(:each) do
-        @result.stub(:has_key?) do |key|
-          if key == 'response'
-            false
-          else
-            true
-          end
-        end
+        @result.stub(:has_key?) { |key| key != 'response' }
       end
       
       it "raises a VkontakteApi::Error" do
@@ -79,5 +67,16 @@ describe VkontakteApi::API do
       url = VkontakteApi::API.send(:url_for, @method_name, @args)
       url.should == '/method/apiMethod?access_token=some_token&field=value'
     end
+    
+    context "with an array argument" do
+      before(:each) do
+        @args_with_array = @args.merge(:array_arg => [1, 2, 3])
+      end
+      
+      it "concats it with a comma" do
+        url = VkontakteApi::API.send(:url_for, @method_name, @args_with_array)
+        url.should == "/method/apiMethod?access_token=some_token&array_arg=#{CGI.escape('1,2,3')}&field=value"
+      end
+    end
   end
 end

data/spec/vkontakte_api/resolver_spec.rb

@@ -13,33 +13,42 @@ describe VkontakteApi::Resolver do
     
     context "with a nil @namespace" do
       before(:each) do
+        VkontakteApi::Resolver.stub(:vk_method_name).and_return(['apiMethod', :anything])
         @resolver = VkontakteApi::Resolver.new(:access_token => @token)
       end
       
-      context "with method_name not from NAMESPACES" do
-        before(:each) do
-          VkontakteApi::Resolver.stub(:vk_method_name).and_return(['apiMethod', :anything])
-        end
-        
+      context "with method_name not from namespaces" do
         it "calls #vk_method_name with method name and nil namespace" do
           VkontakteApi::Resolver.should_receive(:vk_method_name).with('api_method', nil)
           @resolver.api_method
         end
         
-        it "calls #api_call with full VK method name" do
-          full_args = @args.merge(:access_token => @token)
-          VkontakteApi::API.should_receive(:call).with('apiMethod', full_args)
+        it "calls #api_call with full VK method name and access_token" do
+          @args.should_receive(:[]=).with(:access_token, @token)
+          VkontakteApi::API.should_receive(:call).with('apiMethod', @args)
           @resolver.api_method(@args).should == @result
         end
       end
       
-      context "with method_name from NAMESPACES" do
+      context "with method_name from namespaces" do
         it "return a new resolver with the corresponding @namespace" do
           new_resolver = @resolver.friends
           new_resolver.should be_a(VkontakteApi::Resolver)
           new_resolver.namespace.should == 'friends'
         end
       end
+      
+      context "without a token" do
+        before(:each) do
+          @resolver = VkontakteApi::Resolver.new
+        end
+        
+        it "calls #api_call with full VK method name but without a token" do
+          @args.should_not_receive(:[]=).with(:access_token, anything)
+          VkontakteApi::API.should_receive(:call).with('apiMethod', @args)
+          @resolver.api_method(@args).should == @result
+        end
+      end
     end
     
     context "with a non-nil @namespace" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vkontakte_api
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-31 00:00:00.000000000 Z
+date: 2012-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70258037639260 !ruby/object:Gem::Requirement
+  requirement: &70235030424180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70258037639260
+  version_requirements: *70235030424180
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70258037638480 !ruby/object:Gem::Requirement
+  requirement: &70235030421960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '0.6'
   type: :runtime
   prerelease: false
-  version_requirements: *70258037638480
+  version_requirements: *70235030421960
 - !ruby/object:Gem::Dependency
   name: faraday
-  requirement: &70258037637640 !ruby/object:Gem::Requirement
+  requirement: &70235030420280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 0.7.6
   type: :runtime
   prerelease: false
-  version_requirements: *70258037637640
+  version_requirements: *70235030420280
 - !ruby/object:Gem::Dependency
   name: yajl-ruby
-  requirement: &70258037636920 !ruby/object:Gem::Requirement
+  requirement: &70235030434380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70258037636920
+  version_requirements: *70235030434380
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70258037656820 !ruby/object:Gem::Requirement
+  requirement: &70235030433320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70258037656820
+  version_requirements: *70235030433320
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70258037656180 !ruby/object:Gem::Requirement
+  requirement: &70235030432180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70258037656180
+  version_requirements: *70235030432180
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70258037655480 !ruby/object:Gem::Requirement
+  requirement: &70235030431540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70258037655480
+  version_requirements: *70235030431540
 - !ruby/object:Gem::Dependency
   name: awesome_print
-  requirement: &70258037654980 !ruby/object:Gem::Requirement
+  requirement: &70235030430680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,7 +98,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70258037654980
+  version_requirements: *70235030430680
 description: A transparent wrapper for API of vk.com social network called VKontakte.
   Supports ruby-way method naming (without any method lists inside), result typecasting
   and any faraday-supported http adapter of your choice (no hardcoded Net::HTTP).
@@ -109,6 +109,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
+- .yardopts
 - Gemfile
 - MIT-LICENSE
 - README.md
@@ -144,7 +146,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2826215231838222847
+      hash: 4524106874123629909
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -153,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2826215231838222847
+      hash: 4524106874123629909
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10