curt-wren 0.0.0

data/README.rdoc

@@ -0,0 +1,143 @@
+= Wren
+
+A very lightweight Ruby wrapper for the Twitter REST API
+
+== Author
+
+Curt Gilman, Reductive Reason LLC
+
+curt.gilman [at] reductivereason.com
+
+- http://twitter.com/curtg72 - Twitter ego
+- http://reductivereason.com - Corporate identity
+- http://pearlsofnonsense.com - Personal soapbox
+- http://w8track.com - Online weight tracking
+
+== Description
+
+Wren is a very lightweight Ruby wrapper for the Twitter REST API.
+It implements only basic authentication and JSON parsing. SSL is
+used automatically whenever credentials are sent and for all post
+requests. OAuth authentication, search API, and XML parsing are
+not implemented. PUT and DELETE methods are also not implemented.
+
+== Installation
+
+Add GitHub to your gem sources, if you haven't already:
+ gem sources -a http://gems.github.com
+
+Install the gem.
+ sudo gem install curt-wren
+
+== Usage
+
+The first thing you'll need to do is require Wren.
+ require 'wren'
+
+=== Configuration
+
+Before you make any Twitter API calls, you'll want to set up
+the configuration.
+
+==== Using no authentication
+
+If you're not using any parts of the Twitter API requiring
+authentication, you can use the default configuration. Congratulations,
+you're done!
+
+==== Using basic authentication
+
+The simplest configuration for basic authentication is just your 
+Twitter username and password.
+ config = Wren::Configuration.new do |c|
+   c.user = 't123'
+   c.pwd = 'fido' # <= not recommended
+ end
+
+You could also do this as a one-liner.
+
+ config = Wren::Configuration(:user => 't123', :pwd => 'fido')
+
+==== Other settings
+
+If you've created a configuration, you can change the logger, which
+is STDOUT by default.
+ config.logger = my_logger
+
+=== Calling the API
+
+You'll first need to "new" up an instance of Client.
+ client = Wren::Client.new(config)
+
+If you call the initializer with a hash, it'll create a Configuration
+object for you.
+ client = Wren::Client.new(:user => 't123', :pwd => 'fido')
+
+If you're just using the default configuration, that's fine too.
+ client = Wren::Client.new
+
+==== GET requests
+
+To call the GET method on a resource, simply chain method calls together
+like they were parts of the URI. The request will replace the periods
+with slashes. At the end of the chain, call the "get" method.
+ client.account.rate_limit_status.get
+   # => returns a Hash object 
+
+If your request requires authentication, call the "auth" method as part of
+the chain.
+ client.direct_messages.auth.get
+   # => returns an Array object
+
+If your request requires query parameters, pass them in as a hash using the
+"options" method as part of the query chain.
+ client.friends.ids.options(:screen_name => 't123').get
+   # => returns an Array object
+
+And, of course, you can use both "auth" and "options" methods.
+ client.favorites.auth.options(:id => 't123', :page => 3)
+   # => returns an Array object
+
+==== POST requests
+
+Calling a POST method on a resource behaves much like a GET resource, except
+that you call the "post" method. The "post" method takes a hash of data to
+send. Authentication is assumed, so you don't need to call the "auth" method.
+ client.statuses.update.post(:status => 'Is this thing on?')
+   # => returns a Hash object
+
+Some POST methods require query parameters, and that's fine.
+ client.friendships.destroy.options(:screen_name => 't123').post
+   # => returns a Hash object
+
+==== One-liner?
+
+It's certainly possible to combine much of this into a one-liner, if you
+have a screen that's wide enough.
+ Wren::Client.new(:user => 't123', :pwd => 'fido').statuses.update.post(:status => 'Wow!')
+   # => returns a Hash object
+   
+== License
+
+(MIT License)
+
+Copyright (c) 2009 Reductive Reason LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/wren.rb

@@ -0,0 +1,151 @@
+require 'uri'
+require 'logger'
+require 'rubygems'
+require 'net/http'
+require 'net/https'
+require 'json'
+require 'cgi'
+
+module Wren
+  class HTTP < Net::HTTP
+    alias_method :old_wren_initialize, :initialize
+
+    def initialize(*args)
+      old_wren_initialize(*args)
+      @ssl_context = OpenSSL::SSL::SSLContext.new
+      @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    end
+  end
+
+  class Configuration
+    attr_accessor :user, :pwd, :logger, :transport
+
+    def initialize(params = nil)
+      if params.is_a?(Hash)
+        params.each{ |k, v| self.send("#{k.to_sym}=", v) }
+      end
+      
+      @logger = Logger.new(STDOUT)
+      @logger.level = Logger::DEBUG
+      @transport = Wren::HTTP
+
+      yield self if block_given?
+    end
+  end
+
+  class TwitterError < StandardError
+    attr_accessor :method, :request_uri, :status, :response_body, :response_object
+
+    def initialize(method, request_uri, status, response_body, msg = nil)
+      self.method = method
+      self.request_uri = request_uri
+      self.status = status
+      self.response_body = response_body
+      super(msg || "#{self.method} #{self.request_uri} => #{self.status}: #{self.response_body}")
+    end
+  end
+
+  class Client
+    attr_accessor :config
+
+    def initialize(arg = Configuration.new)
+      if arg.is_a?(Hash)
+        @config = Configuration.new
+        arg.each{ |k, v| @config.send("#{k.to_sym}=", v) }
+      elsif arg.is_a?(Configuration)
+        @config = arg
+      end
+    end
+    
+    private
+
+    def method_missing(name, *args)
+      req = Request.new(self)
+      req.send(name, *args)
+      req
+    end
+
+    class Request
+      TWITTER_ROOT_URL = "http://twitter.com"
+
+      def initialize(client)
+        @client = client
+        @auth = false
+        @options = {}
+        @data = {}
+        @path = ''
+      end
+
+      def auth
+        @auth = true
+        self
+      end
+
+      def options(params)
+        @options.merge!(params)
+        self
+      end
+
+      def get
+        get_json
+      end
+
+      def post(params = nil)
+        if params.is_a?(Hash)
+          @data.merge!(params)
+        end
+        post_json
+      end
+
+      private
+
+      def method_missing(name, *args)
+        @path << "/#{name}"
+        self
+      end
+      
+      def url_with_options
+        "#{TWITTER_ROOT_URL}#{@path}.json#{query_string}"
+      end
+
+      def query_string
+        @options.empty? ? '' : '?' + @options.collect{ |k, v| "#{CGI::escape(k.to_s)}=#{CGI::escape(v.to_s)}" }.join('&')
+      end
+
+      def get_json
+        request_json(Net::HTTP::Get)
+      end
+
+      def post_json
+        @auth = true
+        request_json(Net::HTTP::Post)
+      end
+
+      def request_json(method)
+        begin
+          url = URI.parse(url_with_options)
+          method_name = method.class_eval('METHOD').downcase
+          url.scheme = @auth ? 'https' : 'http'
+          req = method.new(url.request_uri)
+          if @auth; req.basic_auth(@client.config.user, @client.config.pwd); end
+          if @data; req.set_form_data(@data); end
+          http = @client.config.transport.new(url.host, url.scheme == 'https' ? 443 : 80)
+          http.use_ssl = (url.scheme == 'https')
+          res = http.request(req)
+          case res
+          when Net::HTTPSuccess
+            JSON.parse(res.body)
+          else
+            raise TwitterError.new(method_name, url.request_uri, res.status, res.body)
+          end
+        rescue TwitterError => e
+          raise e
+        rescue JSON::ParserError => e
+          raise TwitterError.new(method_name, url.request_uri, res.status, res.body, "Unable to parse JSON: #{e}")
+        rescue Timeout::Error
+          raise "Timeout while #{method_name}ing to #{url.to_s}"
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: curt-wren
+version: !ruby/object:Gem::Version 
+  version: 0.0.0
+platform: ruby
+authors: 
+- Curt Gilman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-23 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.6
+    version: 
+description: Wren is a very lightweight Ruby wrapper for the Twitter REST API.
+email: curt.gilman@reductivereason.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/wren.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/curt/wren
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Wren is a very lightweight Ruby wrapper for the Twitter REST API.
+test_files: []
+