esnek 0.2.1 → 0.2.4

data/CHANGES

@@ -6,6 +6,7 @@
 * tests with elasticsearch API
 * Authentication mechanisms
 * proxy
+* Based on return value a hash or an array of OpenStruct is formed
 
 == 0.1.x
 * first working version

data/README.rdoc

@@ -1,16 +1,20 @@
 = Esnek
-_UNDER HEAVY DEVELOPMENT IN APRIL 2011_
 
-_Esnek_ provides a quick Ruby interface for JSON  APIs, such as _ElasticSearch_ (http://www.elasticsearch.org); a scalable, fast, distributed, 
-highly-available, real time search RESTful search engine communicating by JSON over HTTP, based on _Lucene_ (http://lucene.apache.org). 
+_Esnek_ provides a minimalistic Ruby interface for JSON  APIs, such as ElasticSearch, Google APIs, Facebook Graph API.. 
+
+Esnek is mainly developed for _ElasticSearch_ in mind.  ElasticSearch (http://www.elasticsearch.org) 
+is a scalable, fast, distributed, highly-available, real time search RESTful search engine communicating 
+by JSON over HTTP, based on _Lucene_ (http://lucene.apache.org). 
 
 == Installation:
 
   gem install esnek
 
+Esnek is under heavy development in april 2011, so use "gem update" frequently.
+
 For the installation of elasticsearch please follow the guides at http://www.elasticsearch.org
   
-== Usage 
+== Quick Start
 
 === ElasticSearch
 
@@ -18,8 +22,7 @@ To use esnek just instantiate Esnek with the base API URL.
   require 'esnek'  
   es = Esnek.new('http://localhost:9200')
 
-Make a chained method call where each method is a directory in the URL for the JSON API.Your method chain must end with get, post, put or delete.
-For example assuming elastic search is running at port 9200 on your localhost, the following code gets the state of the cluster.
+For example assuming elastic search is running at port 9200 on your localhost, the following code gets the state of the cluster for Elastic Search
 
   #curl -XGET 'http://localhost:9200/_cluster/state'
   es._cluster.state.get
@@ -56,19 +59,64 @@ In order to post a JSON data simply pass a block (do...end)
   require 'esnek'  
   fb = Esnek.new('http://graph.facebook.com')
   res = fb.send(:"http://www.wsirussia.ru").get
+Notice that since "http://www.wsirussia.ru" is an invalid ruby method name, we use "send" to call it
   puts res.shares
 
-== Proxy
+== Advanced
+With esnek just make a chained method call where each method is a directory in the URL 
+for your specific JSON API and end append a final method for HTTP verb; get, post, put or delete.
+
+=== General Usage 
+  require 'esnek'  
+Choose any JSON over HTTP API and identify the base url such as https://www.googleapis.com
+
+  gapi = Esnek.new('https://www.googleapis.com')
+  
+Form a chained method call where each directory in the URL becomes a method and dont forget that 
+your method chain must end with get, post, put or delete.
+
+  gapi.language.translate.v2.get :q => "hello world", :source => :en, :target => :tr, :key => INSERT_YOUR_KEY
+  
+Any query string should be given as a hash to any method in the method call, the following is valid too.
+
+  gapi.language.translate.v2(:key => INSERT_YOUR_KEY).get(:q => "hello world", :source => :en, :target => :tr)
+  
+If you face any portion of the URL which cannot be a valid Ruby method name use send(:'!1invalid_method')
+
+  res = fb.send(:"http://www.wsirussia.ru").get
+  
+Alternatively you may prefix digits with double underscore __
+
+  es.twitter.tweet.__1.get
+
+If you append a block and pass a hash, the hash is converted into a JSON and posted as data.
+
+  es.twitter.tweet.__2.put do
+    {"user" => "alper", "post_date" => "2011-11-15T14:12:12", "message" => "For esnek"}
+  end
+
+=== Return Values
+Esnek simply converts the returned JSON into an Ostruct ruby object.
+  
+  res.my_field
+  res.table[:my_field]  # alternative form for field names such as .id which already exist in the base object
+
+Notice that Ostruct converts only the first level hash keys into object attributes. 
+The deeper hashes are intact and should be accessed as Hash.
+
+Consult your specific API documentation on how the return value is structured
 
+=== Proxy
+Esnek is based on restclient and some of the settings from Restclient apply to esnek to.
 Esnek will use the proxy specified by RestClient.proxy:
 
   RestClient.proxy = "http://proxy.example.com/"
 or the proxy url is set in an environment variable   
   RestClient.proxy = ENV['http_proxy']
 
-== Logging
+=== Logging
 
-To enable logging you can
+To enable logging the calls made to the API, you may
 
 * set RestClient.log with a ruby Logger
 * or set an environment variable to avoid modifying the code (in this case you can use a file name, "stdout" or "stderr"):

data/lib/esnek/base.rb

@@ -11,6 +11,19 @@ class Esnek
     @chain = []
   end
 
+  def parse_json(resp)
+    j = JSON.parse resp
+    case
+    when j.is_a?(Hash)
+      r=OpenStruct.new(j)
+      class << r;def table;@table;end;end
+      r
+    when j.is_a?(Array)
+      j.map{|e| r=OpenStruct.new(e);class << r;def table;@table;end;end;r}
+    else
+      j
+    end
+  end
   def method_missing(method_sym, *args, &block)
     if [:get, :put, :post, :delete].include?(method_sym)
       @chain << {:method => nil, :arg => (args.empty? ? {} : args[0]) }
@@ -19,22 +32,11 @@ class Esnek
       if block_given?
         data = block.call.to_json rescue nil
       end
-      @chain = []
-      
+      @chain = []      
       resp = block_given? ? RestClient.send(method_sym, url, data,:params => params,:content_type => :json, :accept => :json) :
             RestClient.send(method_sym, url,:params => params,:content_type => :json, :accept => :json)
             
-      if resp.headers[:content_type].include?('application/json')
-        r = OpenStruct.new JSON.parse resp
-        class << r
-          def table
-            @table
-          end
-        end
-        r
-      else
-        resp
-      end
+      resp.headers[:content_type].include?('application/json') ? parse_json(resp) : resp
     else      
       @chain << {:method => method_sym.to_s.gsub(/^__/,''), :arg => (args.empty? ? {} : args[0]) }
       self

data/lib/esnek/version.rb

@@ -1 +1 @@
-ESNEK_VERSION='0.2.1'
+ESNEK_VERSION='0.2.4'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: esnek
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 4
+  version: 0.2.4
 platform: ruby
 authors: 
 - Alper Akgun
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-20 00:00:00 Z
+date: 2011-04-23 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
@@ -49,7 +49,7 @@ dependencies:
         version: 1.6.1
   type: :runtime
   version_requirements: *id002
-description: Esnek provides a quick Ruby interface for JSON  APIs, such as ElasticSearch
+description: Esnek provides a minimalistic Ruby interface for JSON  APIs, such as ElasticSearch
 email: esnek@sayarus.com
 executables: []
 
@@ -101,6 +101,6 @@ rubyforge_project:
 rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
-summary: Esnek provides a quick Ruby interface for JSON  APIs, such as ElasticSearch
+summary: Esnek provides a minimalistic Ruby interface for JSON  APIs, such as ElasticSearch
 test_files: []