README.md

   1 # Twitter4R
   2
   3 * Project Website - http://twitter4r.rubyforge.org
   4 * Mailing List - http://groups.google.com/group/twitter4r-users
   5 * Issues - http://github.com/twitter4r/twitter4r-core/issues
   6
   7 ## Description
   8
   9 Twitter4R provides an object based API to query or update your Twitter account via pure Ruby.  It hides the ugly HTTP/REST code from your code.
  10
  11 ## Installation
  12
  13 <code>gem install twitter4r</code>
  14
  15 ## Getting Started
  16
  17 Add the <code>twitter4r</code> dependency to your <code>Gemfile</code>:
  18
  19 <pre><code>
  20 gem 'twitter4r', :require => 'twitter'
  21 </code></pre>
  22
  23 Set your OAuth consumer key and token like so:
  24
  25 <pre><code>
  26 Twitter.configure do |config|
  27   config.oauth_consumer_token = CONSUMER_KEY_HERE
  28   config.oauth_consumer_secret = CONSUME_SECRET_HERE
  29 end
  30 </code></pre>
  31
  32 To create a client object with access tokens:
  33
  34 <pre><code>
  35   client = Twitter::Client.new(:oauth_access => {
  36       :key => ACCESS\_KEY, :secret => ACCESS\_SECRET
  37     }
  38   client.status(:post, "Your awesome less than 140 characters tweet goes here!!! #with #hashtag #goodness")
  39 </code></pre>
  40
  41
  42 ## Usage Examples
  43
  44 Twitter4R starting with version 0.1.1 and above is organized into seven parts:
  45
  46 * [Configuration API](link:examples/configure_rb.html)
  47 * [Friendship API](link:examples/friendship_rb.html)
  48 * [Messaging API](link:examples/messaging_rb.html)
  49 * [Model API](link:examples/model_rb.html)
  50 * [Status API](link:examples/status_rb.html)
  51 * [Timeline API](link:examples/timeline_rb.html)
  52 * [User API](link:examples/user_rb.html)
  53
  54 ## Features
  55
  56 Library supports:
  57
  58 * OAuth support for authentication with the Twitter.com REST and Search APIs
  59 * identi.ca API access
  60 * Customizability of API endpoints such that any Twitter.com compliant API can be accessed (not just Twitter.com and identi.ca's)
  61 * Uses lightweight native JSON under the hood as opposed to heavyweight XML parsing (which is what other Ruby Twitter client libraries use)
  62
  63 Twitter.com REST API coverage includes:
  64
  65 * Status posting and retrieving
  66 * User information
  67 * Profile updates and retrieval
  68 * Favorites add, remove, retrieve
  69 * Direct messaging post, remove, read
  70 * Friendship adding, removing, blocking
  71 * Geolocation embedding inside of statuses and reading from statuses
  72 * Rate limit status access
  73 * Trends retrieval and trend location querying
  74
  75 Twitter.com Search API coverage includes:
  76
  77 * Searching with various options
  78
  79 ## Developers
  80
  81 * [Susan Potter](http://SusanPotter.NET) <me at susanpotter dot net>
  82
  83 ## Contributors
  84
  85 Code:
  86
  87 * Kaiichi Matsunaga <ma2 at lifemedia dot co dot jp> - proxy code suggestion
  88 * Sergio Santos <> - message paging code suggestion
  89 * Adam Stiles <adam at stilesoft dot com> - URI.encode => CGI.escape fix
  90 * Carl Crawley <cwcrawley at gmail dot com> - Friendship get => post fix
  91 * Christian Johansen <christian at cjohansen dot no> - in_reply_to attributes in Twitter::Status
  92 * Harry Love <harrylove at gmail dot com> - added attributes to Twitter::Status
  93 * Filipe Giusti <filipegiusti at gmail dot com> - fixed users/show issue that Twitter.com changed from under us, also inspired the v0.5.2 bugfix release by submitting great issue example code.
  94 * Seth Cousins <seth.cousins at gmail dot com> - added HTTP timeout option and provided a patch that inspired the OAuth support for Twitter4R
  95 * John McKerrell <@mcknut on twitter> - added geo attribute to Twitter::Message.
  96
  97 Design Suggestions:
  98
  99 * Bosco So <rubymeetup at boscoso dot com> - making Twitter::Error a RuntimeError instead of an Exception to prevent irb from crashing out.
 100
 101 ## External Dependencies
 102
 103 * Ruby 1.8 (tested with 1.8.6)
 104 * RSpec gem 1.0.0+ (tested with 1.1.3)
 105 * JSON gem 0.4.3+ (tested with versions: 1.1.1 and 1.1.2)
 106 * jcode (for unicode support)