README.md in ably-0.7.2 vs README.md in ably-0.7.4
- old
+ new
@@ -3,34 +3,72 @@
[](https://travis-ci.org/ably/ably-ruby)
[](http://badge.fury.io/rb/ably)
A Ruby client library for [ably.io](https://ably.io), the real-time messaging service.
+## Documentation
+
+Visit https://ably.io/documentation for a complete API reference and more examples.
+
## Installation
The client library is available as a [gem from RubyGems.org](https://rubygems.org/gems/ably).
Add this line to your application's Gemfile:
gem 'ably'
-And then execute:
+And then install this Bundler dependency:
$ bundle
Or install it yourself as:
$ gem install ably
## Using the Realtime API
+### Introduction
+
+All examples must be run within an [EventMachine](https://github.com/eventmachine/eventmachine) [reactor](https://github.com/eventmachine/eventmachine/wiki/General-Introduction) as follows:
+
+```ruby
+EventMachine.run do
+ # ...
+end
+```
+
+All examples assume a client has been created as follows:
+
+```ruby
+client = Ably::Realtime.new(api_key: "xxxxx")
+```
+
+### Connection
+
+Successful connection:
+
+```ruby
+client.connection.connect do
+ # successful connection
+end
+```
+
+Failed connection:
+
+```ruby
+connection_result = client.connection.connect
+connection_result.errback = Proc.new do
+ # failed connection
+end
+```
+
### Subscribing to a channel
Given:
```ruby
-client = Ably::Realtime.new(api_key: "xxxxx")
channel = client.channel("test")
```
Subscribe to all events:
@@ -51,72 +89,117 @@
```
### Publishing to a channel
```ruby
-client = Ably::Realtime.new(api_key: "xxxxx")
-channel = client.channel("test")
channel.publish("greeting", "Hello World!")
```
+### Querying the History
+
+```ruby
+channel.history do |messages|
+ messages # Ably::Models::PaginatedResource
+ messages.first # Ably::Models::Message
+ messages.length # number of messages in the retrieved history page
+ messages.next_page # Ably::Models::PaginatedResource
+end
+```
+
### Presence on a channel
```ruby
-client = Ably::Realtime.new(api_key: "xxxxx")
-channel = client.channel("test")
channel.presence.enter(data: 'john.doe') do |presence|
presence.get #=> [Array of members present]
end
```
+### Querying the Presence History
+
+```ruby
+channel.presence.history do |presence_messages|
+ presence_messages.first.action # Any of :enter, :update or :leave
+ presence_messages.first.client_id
+ presence_messages.first.data
+ presence_messages.next_page # Ably::Models::PaginatedResource
+end
+```
+
## Using the REST API
-### Publishing a message to a channel
+### Introduction
+Unlike the Realtime API, all calls are synchronous and are not run within an [EventMachine](https://github.com/eventmachine/eventmachine) [reactor](https://github.com/eventmachine/eventmachine/wiki/General-Introduction).
+
+All examples assume a client and/or channel has been created as follows:
+
```ruby
client = Ably::Rest.new(api_key: "xxxxx")
-channel = client.channel("test")
+channel = client.channel('test')
+```
+
+### Publishing a message to a channel
+
+```ruby
channel.publish("myEvent", "Hello!") #=> true
```
-### Fetching a channel's history
+### Querying the History
```ruby
-client = Ably::Rest.new(api_key: "xxxxx")
-channel = client.channel("test")
-channel.history #=> [{:name=>"test", :data=>"payload"}]
+channel.history #=> #<Ably::Models::PaginatedResource ...>
```
-### Authentication with a token
+### Presence on a channel
```ruby
-client = Ably::Rest.new(api_key: "xxxxx")
-client.auth.authorise # creates a token and will use token authentication moving forwards
-client.auth.current_token #=> #<Ably::Models::Token>
-channel.publish("myEvent", "Hello!") #=> true, sent using token authentication
+channel.presence.get # => #<Ably::Models::PaginatedResource ...>
```
-### Fetching your application's stats
+### Querying the Presence History
```ruby
-client = Ably::Rest.new(api_key: "xxxxx")
-client.stats #=> [{:channels=>..., :apiRequests=>..., ...}]
+channel.presence.history # => #<Ably::Models::PaginatedResource ...>
```
-### Fetching the Ably service time
+### Generate Token and Token Request
```ruby
-client = Ably::Rest.new(api_key: "xxxxx")
-client.time #=> 2013-12-12 14:23:34 +0000
+client.auth.request_token
+# => #<Ably::Models::Token ...>
+
+client.auth.create_token_request
+# => {"id"=>...,
+# "clientId"=>nil,
+# "ttl"=>3600,
+# "timestamp"=>...,
+# "capability"=>"{\"*\":[\"*\"]}",
+# "nonce"=>...,
+# "mac"=>...}
```
+### Fetching your application's stats
+
+```ruby
+client.stats #=> PaginatedResource [{:channels=>..., :apiRequests=>..., ...}]
+```
+
## Dependencies
If you only need to use the REST features of this library and do not want EventMachine as a dependency, then you should use the [Ably Ruby REST gem](https://rubygems.org/gems/ably-rest).
+## Support and feedback
+
+Please visit https://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
+
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Ensure you have added suitable tests and the test suite is passing(`bundle exec rspec`)
4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Create a new Pull Request
+
+## License
+
+Copyright (c) 2015 Ably, Licensed under an MIT license. Refer to [LICENSE.txt](LICENSE.txt) for the license terms.