etherpad-lite 0.1.0 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,8 @@
+** RELEASE 0.2.0 (?) **
+
+* Adds support for multiple API versions
+* Use rest_client
+
 ** RELEASE 0.1.0 (07/07/2012) **
 
 * Requires Etherpad Lite 1.1+

data/README.rdoc

@@ -7,13 +7,13 @@ See {github.com/Pita/etherpad-lite}[https://github.com/Pita/etherpad-lite] for i
 == Installation
     gem install etherpad-lite
 
-*NOTE* Support for Ruby 1.8.x is deprecated and will be removed in future versions. Upgrade to Ruby 1.9.x and stop being an old fuddie-duddie. It's the IE6 of Ruby.
+*NOTE* Nobody likes you, Ruby 1.8. Now go away.
 
 == Basic usage
     require 'etherpad-lite'
 
     # Connect to your Etherpad Lite instance
-    ether = EtherpadLite.connect('http://etherpad-lite.example.com', 'the api key')
+    ether = EtherpadLite.connect('http://etherpad-lite.example.com', 'the api key', 1.1)
 
     # Get a Pad (or create one if it doesn't exist)
     pad = ether.pad('my first etherpad lite pad')
@@ -55,14 +55,14 @@ Some example controller actions:
   class EtherpadController < ApplicationController
     # /etherpad
     def index
-      # The idea is that your users are probably members of some kind of groups.
+      # Your users are probably members of some kind of groups.
       # These groups can be mapped to EtherpadLite Groups. List all the user's groups.
       @app_groups = current_user.groups
     end
 
     # /etherpad/groups/:id
     def group
-      ether = EtherpadLite.connect(:local, File.new('/var/www/etherpad-lite/APIKEY.txt'))
+      ether = EtherpadLite.connect(9001, File.new('/srv/www/etherpad-lite/APIKEY.txt'))
       @app_group = YourAppGroup.find(params[:id])
       # Map your app's group to an EtherpadLite Group, and list all its pads
       group = ether.group("my_app_group_#{@app_group.id}")
@@ -71,7 +71,7 @@ Some example controller actions:
 
     # /etherpad/pads/:ep_group_id/:ep_pad_name
     def pad
-      ether = EtherpadLite.connect(:local, File.new('/var/www/etherpad-lite/APIKEY.txt'))
+      ether = EtherpadLite.connect(9001, File.new('/srv/www/etherpad-lite/APIKEY.txt'))
       # Get the EtherpadLite Group and Pad by id
       @group = ether.get_group(params[:ep_group_id])
       @pad = @group.pad(params[:ep_pad_name])
@@ -89,24 +89,19 @@ Some example controller actions:
     end
   end
 
-== Why is the Ruby client so different from the others? What gives you the right?!?
-Most of the EPL clients are extremely thin wrappers around the HTTP API. The Ruby client offers a slightly higher level of abstraction,
-with the goal of making it as simple, powerful, and dare I say fun, as possible. That said, there are times when a bare-bones client may be 
-preferable. In a hopefully not misguided attempt to please everyone, the Ruby client is written in two layers:
-- A high-level "models" interface starting with EtherpadLite::Instance (above)
-- A low-level client matching the HTTP API (EtherpadLite::Client, below)
+== Low-level client
 
-In the examples above, the low-level client is accessible from the high-level interface:
+There is an optional low-level client, which is a paper-thin wrapper around Etherpad Lite's HTTP JSON API. In the examples above, the low-level client is accessible from the high-level interface:
     client = ether.client
-    client.getText('my first etherpad lite pad')
+    client.getText(padID: 'my first etherpad lite pad')
     => {:text => "What hath God wrought?"}
 
 or you can explicitly load just the low-level client:
     require 'etherpad-lite/client'
-    client = EtherpadLite::Client.new('http://beta.etherpad.org/api', 'api key')
+    client = EtherpadLite.client('http://beta.etherpad.org/api', 'api key', 1.1)
+    client.setText(padID: 'my first etherpad lite pad', text: "lots of new text and stuff")
 
-The methods available to the low-level client should precisely match the HTTP API. In general, it behaves identically to the other
-clients, particularly PHP's and Python's.
+The methods and parameters exactly match the HTTP API. For a full list of them, see {github.com/Pita/etherpad-lite/wiki/HTTP-API}[https://github.com/Pita/etherpad-lite/wiki/HTTP-API].
 
 == Testing
 Testing this library is fairly simple. It requires:

data/lib/etherpad-lite/client.rb

@@ -1,344 +1,77 @@
 require 'uri'
-require 'net/http'
-require 'net/https'
 require 'json'
-
-# Ruby 1.8.x may not work, and I don't care
-BAD_RUBY = RUBY_VERSION < '1.9.0' # :nodoc:
-
+require 'rest_client'
+
+# A client library for Etherpad Lite's JSON API. 
+# 
+# A thin wrapper around the HTTP API. See the API documentation at https://github.com/Pita/etherpad-lite/wiki/HTTP-API.
+# 
+#  client = EtherpadLite.client('http://localhost:9001', 'api key', '1.1')
+#  client.getText(:padID => 'foo')
+#  => {:text => "Pad text"}
+#  client.setText(:padID => 'padID', :text => 'new pad text')
+# 
+# A higher-level interface to the API:
+# 
+#  ether = EtherpadLite.connect('http://localhost:9001', 'api key', '1.1')
+#  pad = ether.pad('padID')
+#  puts pad.text
+#  => 'Pad text'
+#  pad.text = 'new pad text'
 module EtherpadLite
   # An error returned by the server
-  class APIError < StandardError
-    MESSAGE = "Error while talking to the API (%s). Make sure you are running the latest version of the Etherpad Lite server. If that is not possible, try rolling this client back to an earlier version."
-  end
+  Error = Class.new(StandardError)
 
-  # A thin wrapper around Etherpad Lite's HTTP JSON API
+  # Returns a new EtherpadLite::Client.
   # 
-  #  client1 = EtherpadLite::Client.new('https://etherpad.yoursite.com[https://etherpad.yoursite.com]', 'your api key')
+  #  client = EtherpadLite.client('https://etherpad.yoursite.com', 'your api key', '1.1')
   # 
-  #  # An alias for http://localhost:9001
-  #  client2 = EtherpadLite::Client.new(:local, File.new('/path/to/APIKEY.txt'))
-  # 
-  #  # An alias for http://localhost:9001
-  #  ether = EtherpadLite::Client.new(9001, File.new('/path/to/APIKEY.txt'))
-  class Client
-    # Aliases to common Etherpad Lite hosts
-    HOST_ALIASES = {:local => 'http://localhost:9001',
-                    :localhost => 'http://localhost:9001'}
-
-    # The Etherpad Lite HTTP API version this library version targets
-    API_VERSION = 1
-
-    # HTTP API response code for okay
-    CODE_OK = 0
-    # HTTP API response code for invalid method parameters
-    CODE_INVALID_PARAMETERS = 1
-    # HTTP API response code for Etherpad Lite error
-    CODE_INTERNAL_ERROR = 2
-    # HTTP API response code for invalid api method
-    CODE_INVALID_METHOD = 3
-    # HTTP API response code for invalid api key
-    CODE_INVALID_API_KEY = 4
+  #  client = EtherpadLite.client(9001, 'your api key', '1.1') # Alias to http://localhost:9001
+  def self.client(url_or_port, api_key_or_file, api_version=1)
+    Client.new(url_or_port, api_key_or_file, api_version)
+  end
 
+  # A thin wrapper around Etherpad Lite's HTTP JSON API. See the API documentation at https://github.com/Pita/etherpad-lite/wiki/HTTP-API.
+  class Client
     # A URI object containing the URL of the Etherpad Lite instance
     attr_reader :uri
     # The API key
     attr_reader :api_key
+    # The API version string
+    attr_reader :api_version
 
-    class << self
-      # Path to the system's CA certs (for connecting over SSL)
-      attr_accessor :ca_path
-    end
-
-    # Instantiate a new Etherpad Lite Client.
-    # 
-    #  client1 = EtherpadLite::Client.new('https://etherpad.yoursite.com[https://etherpad.yoursite.com]', 'your api key')
-    # 
-    #  # An alias for http://localhost:9001
-    #  client2 = EtherpadLite::Client.new(:local, File.new('/path/to/APIKEY.txt'))
-    # 
-    #  # An alias for http://localhost:9001
-    #  client3 = EtherpadLite::Client.new(9001, File.new('/path/to/APIKEY.txt'))
-    def initialize(host_or_alias, api_key_or_file)
-      # Parse the host
-      url = if host_or_alias.is_a? Symbol
-        raise ArgumentError, %Q|Unknown host alias "#{host_or_alias}"| unless HOST_ALIASES.has_key? host_or_alias
-        HOST_ALIASES[host_or_alias]
-      elsif host_or_alias.is_a? Fixnum
-        "http://localhost:#{host_or_alias}"
-      else
-        host_or_alias.clone
-      end
-      url << '/api' unless url =~ /\/api$/i
-      @uri = URI.parse(url)
-      raise ArgumentError, "#{url} does not contain a valid host and port" unless @uri.host and @uri.port
-
-      # Parse the api key
-      if api_key_or_file.is_a? File
-        @api_key = begin
-          api_key_or_file.read
-        rescue IOError
-          api_key_or_file.reopen(api_key_or_file.path, mode='r')
-          api_key_or_file.read
-        end
-        api_key_or_file.close
-      else
-        @api_key = api_key_or_file
-      end
-
-      connect!
-    end
-
-    # Groups
-    # Pads can belong to a group. There will always be public pads which don't belong to a group.
-
-    # Creates a new Group
-    def createGroup
-      post :createGroup
-    end
-
-    # Creates a new Group for groupMapper if one doesn't already exist. Helps you map your application's groups to Etherpad Lite's groups.
-    def createGroupIfNotExistsFor(groupMapper)
-      post :createGroupIfNotExistsFor, :groupMapper => groupMapper
-    end
-
-    # Deletes a group
-    def deleteGroup(groupID)
-      post :deleteGroup, :groupID => groupID
-    end
-
-    # Returns all the Pads in the given Group
-    def listPads(groupID)
-      get :listPads, :groupID => groupID
-    end
-
-    # Creates a new Pad in the given Group
-    def createGroupPad(groupID, padName, text=nil)
-      params = {:groupID => groupID, :padName => padName}
-      params[:text] = text unless text.nil?
-      post :createGroupPad, params
-    end
-
-    # Authors
-    # These authors are bound to the attributes the users choose (color and name).
-
-    # Create a new Author
-    def createAuthor(name=nil)
-      params = {}
-      params[:name] = name unless name.nil?
-      post :createAuthor, params
-    end
-
-    # Creates a new Author for authorMapper if one doesn't already exist. Helps you map your application's authors to Etherpad Lite's authors.
-    def createAuthorIfNotExistsFor(authorMapper, name=nil)
-      params = {:authorMapper => authorMapper}
-      params[:name] = name unless name.nil?
-      post :createAuthorIfNotExistsFor, params
-    end
-
-    def listPadsOfAuthor(authorID)
-      get :listPadsOfAuthor, :authorID => authorID
-    end
-
-    # Sessions
-    # Sessions can be created between a group and an author. This allows
-    # an author to access more than one group. The sessionID will be set as
-    # a cookie to the client and is valid until a certian date.
-
-    # Creates a new Session for the given Author in the given Group
-    def createSession(groupID, authorID, validUntil)
-      post :createSession, :groupID => groupID, :authorID => authorID, :validUntil => validUntil
-    end
-
-    # Deletes the given Session
-    def deleteSession(sessionID)
-      post :deleteSession, :sessionID => sessionID
-    end
-
-    # Returns information about the Session
-    def getSessionInfo(sessionID)
-      get :getSessionInfo, :sessionID => sessionID
-    end
-
-    # Returns all Sessions in the given Group
-    def listSessionsOfGroup(groupID)
-      get :listSessionsOfGroup, :groupID => groupID
-    end
-
-    # Returns all Sessions belonging to the given Author
-    def listSessionsOfAuthor(authorID)
-      get :listSessionsOfAuthor, :authorID => authorID
-    end
-
-    # Pad content
-    # Pad content can be updated and retrieved through the API
-
-    # Returns the text of the given Pad. Optionally pass a revision number to get the text for that revision.
-    def getText(padID, rev=nil)
-      params = {:padID => padID}
-      params[:rev] = rev unless rev.nil?
-      get :getText, params
+    # Instantiate a new Etherpad Lite Client. You may pass a full url or just a port number. The api key may be a string
+    # or a File object. If you do not specify an API version, it will default to the latest version that is supported.
+    def initialize(url_or_port, api_key_or_file, api_version=1)
+      url_or_port = "http://localhost:#{url_or_port}" if url_or_port.is_a? Integer
+      @uri = URI.parse(url_or_port)
+      @api_key = api_key_or_file.is_a?(IO) ? api_key_or_file.read : api_key_or_file
+      @api_version = api_version.to_s
     end
 
-    # Sets the text of the given Pad
-    def setText(padID, text)
-      post :setText, :padID => padID, :text => text
+    # Call an API method
+    def method_missing(method, params={})
+      request = method =~ /^(set|create|delete)/ \
+        ? ->(url, params) { RestClient.post(url, params) } \
+        : ->(url, params) { RestClient.get(url, :params => params) }
+      call(method, params, &request)
     end
 
-    # Returns the text of the given Pad as HTML. Optionally pass a revision number to get the HTML for that revision.
-    def getHTML(padID, rev=nil)
-      params = {:padID => padID}
-      params[:rev] = rev unless rev.nil?
-      get :getHTML, params
-    end
-
-    # Sets the HTML text of the given Pad
-    def setHTML(padID, html)
-      post :setHTML, :padID => padID, :html => html
-    end
-
-    # Pad
-    # Group pads are normal pads, but with the name schema
-    # GROUPID$PADNAME. A security manager controls access of them and
-    # forbids normal pads from including a "$" in the name.
-
-    # Create a new Pad. Optionally specify the initial text.
-    def createPad(padID, text=nil)
-      params = {:padID => padID}
-      params[:text] = text unless text.nil?
-      post :createPad, params
-    end
-
-    # Returns the number of revisions the given Pad contains
-    def getRevisionsCount(padID)
-      get :getRevisionsCount, :padID => padID
-    end
-
-    # Returns the number of users currently editing the pad
-    def padUsersCount(padID)
-      get :padUsersCount, :padID => padID
-    end
-
-    # Returns the time the pad was last edited as a Unix timestamp
-    def getLastEdited(padID)
-      get :getLastEdited, :padID => padID
-    end
-
-    # Delete the given Pad
-    def deletePad(padID)
-      post :deletePad, :padID => padID
-    end
-
-    # Returns the Pad's read-only id
-    def getReadOnlyID(padID)
-      get :getReadOnlyID, :padID => padID
-    end
-
-    def listAuthorsOfPad(padID)
-      get :listAuthorsOfPad, :padID => padID
-    end
-
-    # Sets a boolean for the public status of a Pad
-    def setPublicStatus(padID, publicStatus)
-      post :setPublicStatus, :padID => padID, :publicStatus => publicStatus
-    end
-
-    # Gets a boolean for the public status of a Pad
-    def getPublicStatus(padID)
-      get :getPublicStatus, :padID => padID
-    end
-
-    # Sets the password on a pad
-    def setPassword(padID, password)
-      post :setPassword, :padID => padID, :password => password
-    end
-
-    # Returns true if the Pad has a password, false if not
-    def isPasswordProtected(padID)
-      get :isPasswordProtected, :padID => padID
-    end
-
-    # Returns true if the connection to the Etherpad Lite instance is using SSL/HTTPS.
-    def secure?
-      @uri.port == 443
-    end
-
-    protected
-
-    # Alias to "call" using the GET HTTP method
-    def get(method, params={})
-      call method, params, :get
-    end
-
-    # Alias to "call" using the POST HTTP method
-    def post(method, params={})
-      call method, params, :post
-    end
+    private
 
     # Calls the EtherpadLite API and returns the :data portion of the response Hash.
-    # 
-    # "method" should be a valid API method name, as a String or Symbol.
-    # 
-    # "params" should be any URL or form parameters as a Hash.
-    # 
-    # "http_method" should be :get or :post, defaults to :get.
-    # 
-    def call(method, params={}, http_method=:get)
+    # If the API response contains an error code, an exception is raised.
+    def call(api_method, params={}, &request)
       params[:apikey] = @api_key
-      uri = [@uri.path, API_VERSION, method].compact.join('/')
-      http_method = :post if BAD_RUBY # XXX A horrible, horrible hack for Ruby 1.8
-      req = case http_method
-        when :get then Net::HTTP::Get.new(uri << '?' << URI.encode_www_form(params))
-        when :post
-          post = Net::HTTP::Post.new(uri)
-          post.set_form_data(params)
-          post
-        else raise ArgumentError, "#{http_method} is not a valid HTTP method"
-      end
-      response = @http.request(req)
-      handleResult response.body
-    end
+      url = [@uri.to_s, 'api', self.api_version, api_method].compact.join('/')
+      json = request.(url, params).to_s
+      response = JSON.parse(json, :symbolize_names => true)
 
-    # Parses the JSON response from the server, returning the data object as a Hash with symbolized keys.
-    # If the API response contains an error code, an exception is raised.
-    def handleResult(response)
-      begin
-        response = JSON.parse(response, :symbolize_names => true)
-      rescue JSON::ParserError
-        raise APIError, APIError::MESSAGE % response
-      end
       case response[:code]
-        when CODE_OK then response[:data]
-        when CODE_INVALID_PARAMETERS, CODE_INVALID_API_KEY, CODE_INVALID_METHOD
-          raise ArgumentError, response[:message]
-        else
-          raise APIError, "An unknown error ocurrced while handling the response: #{response.to_s}"
-      end
-    end
-
-    private
-
-    # Initialize the HTTP connection object
-    def connect!
-      @http = Net::HTTP.new(@uri.host, @uri.port)
-      if secure?
-        @http.use_ssl = true
-        if self.class.ca_path
-          @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          @http.ca_path = self.class.ca_path
-        else
-          @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-        end
+        when 0 then response[:data]
+        when (1..4) then raise Error, response[:message]
+        else raise Error, "An unknown error ocurrced while handling the API response: #{response.to_s}"
       end
     end
   end
 end
-
-# Try to find the system's CA certs
-%w{/etc/ssl/certs /etc/ssl /usr/share/ssl /usr/lib/ssl /System/Library/OpenSSL /usr/local/ssl}.each do |path|
-  EtherpadLite::Client.ca_path = path and break if File.exists? path
-end
-$stderr.puts %q|WARNING Ruby etherpad-lite client was unable to find your CA Certificates; HTTPS connections will *not* be verified! You may remedy this with "EtherpadLite::Client.ca_path = '/path/to/certs'"| unless EtherpadLite::Client.ca_path
-
-# Warn about old Ruby versions
-$stderr.puts "WARNING You are using an ancient version of Ruby which may not be supported. Upgrade Ruby!" if BAD_RUBY

data/lib/etherpad-lite/models/author.rb

@@ -7,7 +7,7 @@ module EtherpadLite
   #
   # Author Examples:
   # 
-  #  @ether = EtherpadLite.connect(:local, 'api key')
+  #  @ether = EtherpadLite.connect(9001, 'api key')
   # 
   #  # Create a new author with both a name and a mapper
   #  author1 = @ether.create_author(:name => 'Theodor Seuss Geisel', :mapper => 'author_1')
@@ -45,8 +45,6 @@ module EtherpadLite
     attr_reader :instance
     # The author's id
     attr_reader :id
-    # The author's name (if any)
-    attr_reader :name
     # The author's foreign mapper (if any)
     attr_reader :mapper
 
@@ -61,8 +59,8 @@ module EtherpadLite
     # name => Author's name
     def self.create(instance, options={})
       result = options[:mapper] \
-        ? instance.client.createAuthorIfNotExistsFor(options[:mapper], options[:name]) \
-        : instance.client.createAuthor(options[:name])
+        ? instance.client.createAuthorIfNotExistsFor(authorMapper: options[:mapper], name: options[:name]) \
+        : instance.client.createAuthor(options)
       new instance, result[:authorID], options
     end
 
@@ -77,12 +75,16 @@ module EtherpadLite
       @instance = instance
       @id = id
       @mapper = options[:mapper]
-      @name = options[:name]
+    end
+
+    # Returns the author's name
+    def name
+      @name ||= @instance.client.getAuthorName(authorID: @id)
     end
 
     # Returns an array of pad ids that this author has edited
     def pad_ids
-      @instance.client.listPadsOfAuthor(@id)[:padIDs] || []
+      @instance.client.listPadsOfAuthor(authorID: @id)[:padIDs] || []
     end
 
     # Returns an array of Pads that this author has edited
@@ -97,13 +99,13 @@ module EtherpadLite
 
     # Returns all session ids from this Author
     def session_ids
-      s = @instance.client.listSessionsOfAuthor(@id) || {}
+      s = @instance.client.listSessionsOfAuthor(authorID: @id) || {}
       s.keys
     end
 
     # Returns all sessions from this Author
     def sessions
-      s = @instance.client.listSessionsOfAuthor(@id) || {}
+      s = @instance.client.listSessionsOfAuthor(authorID: @id) || {}
       s.map { |id,info| Session.new(@instance, id, info) }
     end
   end

data/lib/etherpad-lite/models/group.rb

@@ -64,7 +64,7 @@ module EtherpadLite
     # mapper => your foreign group id
     def self.create(instance, options={})
       result = options[:mapper] \
-        ? instance.client.createGroupIfNotExistsFor(options[:mapper]) \
+        ? instance.client.createGroupIfNotExistsFor(groupMapper: options[:mapper]) \
         : instance.client.createGroup
       new instance, result[:groupID], options
     end
@@ -111,7 +111,7 @@ module EtherpadLite
 
     # Returns an array of all the Pad ids in this Group.
     def pad_ids
-      @instance.client.listPads(@id)[:padIDs]
+      @instance.client.listPads(groupID: @id)[:padIDs]
     end
 
     # Create a new session for author that will last length_in_minutes.
@@ -121,19 +121,19 @@ module EtherpadLite
 
     # Returns all session ids in this Group
     def session_ids
-      s = @instance.client.listSessionsOfGroup(@id) || {}
+      s = @instance.client.listSessionsOfGroup(groupID: @id) || {}
       s.keys
     end
 
     # Returns all sessions in this Group
     def sessions
-      s = @instance.client.listSessionsOfGroup(@id) || {}
+      s = @instance.client.listSessionsOfGroup(groupID: @id) || {}
       s.map { |id,info| Session.new(@instance, id, info) }
     end
 
     # Deletes the Group
     def delete
-      @instance.client.deleteGroup(@id)
+      @instance.client.deleteGroup(groupID: @id)
     end
 
     private

data/lib/etherpad-lite/models/instance.rb

@@ -1,35 +1,23 @@
 module EtherpadLite
   # Returns an EtherpadLite::Instance object.
   # 
-  #  ether1 = EtherpadLite.connect('https://etherpad.yoursite.com[https://etherpad.yoursite.com]', 'your api key')
+  #  ether = EtherpadLite.client('https://etherpad.yoursite.com', 'your api key', '1.1')
   # 
-  #  # An alias for http://localhost:9001
-  #  ether2 = EtherpadLite.connect(:local, File.new('/path/to/APIKEY.txt'))
-  # 
-  #  # An alias for http://localhost:9001
-  #  ether3 = EtherpadLite.connect(9001, File.new('/path/to/APIKEY.txt'))
-  def self.connect(host_or_alias, api_key_or_file)
-    Instance.new(host_or_alias, api_key_or_file)
+  #  ether = EtherpadLite.client(9001, 'your api key', '1.1') # Alias to http://localhost:9001
+  def self.connect(url_or_port, api_key_or_file, api_version=1)
+    Instance.new(url_or_port, api_key_or_file, api_version)
   end
 
-  # EtherpadLite::Instance provides a high-level interface to the EtherpadLite::Client class. See the EtherpadLite module 
-  # for examples of how to establish a connection.
+  # A high-level interface to EtherpadLite::Client.
   class Instance
     include Padded
     # Stores the EtherpadLite::Client object used to power this Instance
     attr_reader :client
 
-    # Instantiate a new Etherpad Lite Instance. The url should include the protocol (i.e. http or https).
-    # 
-    #  ether1 = EtherpadLite::Instance.new('https://etherpad.yoursite.com[https://etherpad.yoursite.com]', 'your api key')
-    # 
-    #  # An alias for http://localhost:9001
-    #  ether2 = EtherpadLite::Instance.new(:local, File.new('/path/to/APIKEY.txt'))
-    # 
-    #  # An alias for http://localhost:9001
-    #  ether3 = EtherpadLite::Instance.new(9001, File.new('/path/to/APIKEY.txt'))
-    def initialize(host_or_alias, api_key_or_file)
-      @client = Client.new(host_or_alias, api_key_or_file)
+    # Instantiate a new Etherpad Lite Instance. You may pass a full url or just a port number. The api key may be a string
+    # or a File object.
+    def initialize(url_or_port, api_key_or_file, api_version=1)
+      @client = Client.new(url_or_port, api_key_or_file, api_version)
     end
 
     # Returns, creating if necessary, a Group mapped to your foreign system's group
@@ -52,6 +40,16 @@ module EtherpadLite
       Group.create self, options
     end
 
+    # Returns an array of all group IDs
+    def group_ids
+      @client.listAllGroups[:groupIDs]
+    end
+
+    # Returns an array of all Group objects
+    def groups
+      group_ids.map { |id| Group.new self, id }
+    end
+
     # Returns, creating if necessary, a Author mapped to your foreign system's author
     # 
     # Options:

data/lib/etherpad-lite/models/pad.rb

@@ -24,12 +24,12 @@ module EtherpadLite
     def self.create(instance, id, options={})
       if options[:groupID]
         group = Group.new instance, options[:groupID]
-        instance.client.createGroupPad(group.id, degroupify_pad_id(id), options[:text])
+        instance.client.createGroupPad(groupID: group.id, padName: degroupify_pad_id(id), text: options[:text])
       else
         group = nil
-        instance.client.createPad(id, options[:text])
+        instance.client.createPad(padID: id, text: options[:text])
       end
-      new instance, id, :groupID => options[:groupID], :group => group
+      new instance, id, groupID: options[:groupID], group: group
     end
 
     # Remove the group id portion of a Group Pad's id
@@ -84,13 +84,14 @@ module EtherpadLite
     # 
     # rev => revision_number
     def text(options={})
+      options[:padID] = @id
       options[:rev] ||= @rev unless @rev.nil?
-      @instance.client.getText(@id, options[:rev])[:text]
+      @instance.client.getText(options)[:text]
     end
 
     # Writes txt to the Pad. There is no 'save' method; it is written immediately.
     def text=(txt)
-      @instance.client.setText(@id, txt)
+      @instance.client.setText(padID: @id, text: txt)
     end
 
     # Returns the Pad's text as HTML. Unless you specified a :rev when instantiating the Pad, or specify one here, this will return the latest revision.
@@ -99,18 +100,19 @@ module EtherpadLite
     # 
     # rev => revision_number
     def html(options={})
+      options[:padID] = @id
       options[:rev] ||= @rev unless @rev.nil?
-      @instance.client.getHTML(@id, options[:rev])[:html]
+      @instance.client.getHTML(options)[:html]
     end
 
     # Writes HTML to the Pad. There is no 'save' method; it is written immediately.
     def html=(html)
-      @instance.client.setHTML(@id, html)
+      @instance.client.setHTML(padID: @id, html: html)
     end
 
     # Returns an Array of all this Pad's revision numbers
     def revision_numbers
-      max = @instance.client.getRevisionsCount(@id)[:revisions]
+      max = @instance.client.getRevisionsCount(padID: @id)[:revisions]
       (0..max).to_a
     end
 
@@ -119,25 +121,30 @@ module EtherpadLite
       revision_numbers.map { |n| Pad.new(@instance, @id, :rev => n) }
     end
 
+    # Returns an array of users hashes, representing users currently using the pad
+    def users
+      @instance.client.padUsers(padID: @id)[:padUsers]
+    end
+
     # Returns the number of users currently editing a pad
     def user_count
-      @instance.client.padUsersCount(@id)[:padUsersCount]
+      @instance.client.padUsersCount(padID: @id)[:padUsersCount]
     end
     alias_method :users_count, :user_count
 
     # Returns the Pad's read-only id. This is cached.
     def read_only_id
-      @read_only_id ||= @instance.client.getReadOnlyID(@id)[:readOnlyID]
+      @read_only_id ||= @instance.client.getReadOnlyID(padID: @id)[:readOnlyID]
     end
 
     # Returns the time the pad was last edited as a Unix timestamp
     def last_edited
-      @instance.client.getLastEdited(@id)[:lastEdited]
+      @instance.client.getLastEdited(padID: @id)[:lastEdited]
     end
 
     # Returns an array of ids of authors who've edited this pad
     def author_ids
-      @instance.client.listAuthorsOfPad(@id)[:authorIDs] || []
+      @instance.client.listAuthorsOfPad(padID: @id)[:authorIDs] || []
     end
 
     # Returns an array of Authors who've edited this pad
@@ -148,13 +155,13 @@ module EtherpadLite
     # Returns true if this is a public Pad (opposite of private?).
     # This only applies to Pads belonging to a Group.
     def public?
-      @instance.client.getPublicStatus(@id)[:publicStatus]
+      @instance.client.getPublicStatus(padID: @id)[:publicStatus]
     end
 
     # Set the pad's public status to true or false (opposite of private=)
     # This only applies to Pads belonging to a Group.
     def public=(status)
-      @instance.client.setPublicStatus(@id, status)
+      @instance.client.setPublicStatus(padID: @id, publicStatus: status)
     end
 
     # Returns true if this is a private Pad (opposite of public?)
@@ -172,18 +179,18 @@ module EtherpadLite
     # Returns true if this Pad has a password, false if not.
     # This only applies to Pads belonging to a Group.
     def password?
-      @instance.client.isPasswordProtected(@id)[:isPasswordProtected]
+      @instance.client.isPasswordProtected(padID: @id)[:isPasswordProtected]
     end
 
     # Sets the Pad's password.
     # This only applies to Pads belonging to a Group.
     def password=(new_password)
-      @instance.client.setPassword(@id, new_password)
+      @instance.client.setPassword(padID: @id, password: new_password)
     end
 
     # Deletes the Pad
     def delete
-      @instance.client.deletePad(@id)
+      @instance.client.deletePad(padID: @id)
     end
   end
 end

data/lib/etherpad-lite/models/padded.rb

@@ -8,7 +8,7 @@ module EtherpadLite
       begin
         Pad.create(instance, id, options)
       # Pad alreaded exists
-      rescue ArgumentError
+      rescue Error
         Pad.new(instance, id, options)
       end
     end

data/lib/etherpad-lite/models/session.rb

@@ -16,7 +16,7 @@ module EtherpadLite
     # Creates a new Session between a Group and an Author. The session will expire after length_in_min.
     def self.create(instance, group_id, author_id, length_in_min)
       valid_until = Time.now.to_i + length_in_min * 60
-      result = instance.client.createSession(group_id, author_id, valid_until)
+      result = instance.client.createSession(groupID: group_id, authorID: author_id, validUntil: valid_until)
       new instance, result[:sessionID]
     end
 
@@ -64,14 +64,14 @@ module EtherpadLite
 
     # Deletes the Session
     def delete
-      @instance.client.deleteSession(@id)
+      @instance.client.deleteSession(sessionID: @id)
     end
 
     private
 
     # Request and cache session info from the server
     def get_info
-      @info ||= @instance.client.getSessionInfo(@id)
+      @info ||= @instance.client.getSessionInfo(sessionID: @id)
     end
   end
 end

data/lib/etherpad-lite/version.rb

@@ -1,5 +1,4 @@
 module EtherpadLite
-  MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION = 0, 1, 0, nil # :nodoc:
-  # The client version
-  VERSION = [MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION].compact.join '.'
+  # The library version
+  VERSION = '0.2.0'
 end

data/spec/author_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Author do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key], TEST_CONFIG[:api_version]
   end
 
   it "should be created" do
@@ -27,4 +27,11 @@ describe EtherpadLite::Author do
     author.pad_ids.should == []
     author.pads.should == []
   end
+
+  if TEST_CONFIG[:api_version] > 1
+    it "should get the name" do
+      author = @eth.create_author :mapper => 'Author B', :name => 'Jim Jimmers'
+      author.name.should == 'Jim Jimmers'
+    end
+  end
 end

data/spec/config.yml

@@ -1,3 +1,5 @@
-:url: 9003
-#:api_key: UrdBfgceHYDZs4yr1rQ12rVOzo31XfEW
+:url: 9001
+:api_key: #kvwTIROV9p2h2gjNRCrO8fVa6pNXSqOc
+# Full filesystem path to APIKEY.txt, may be used instead of the above :api_key setting
 :api_key_file: /home/jhollinger/devel/etherpad-lite/APIKEY.txt
+:api_version: 1.1

data/spec/config.yml.example

@@ -2,3 +2,4 @@
 :api_key: your api key
 # Full filesystem path to APIKEY.txt, may be used instead of the above :api_key setting
 :api_key_file:
+:api_version: 1.1

data/spec/group_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Group do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key], TEST_CONFIG[:api_version]
   end
 
   it "should be created" do
@@ -81,6 +81,19 @@ describe EtherpadLite::Group do
     pad.text.should == "abc\n"
   end
 
+  if TEST_CONFIG[:api_version] > 1
+    it "should list all group ids" do
+      group_ids = @eth.group_ids
+      group_ids.size.should == 4
+    end
+
+    it "should list all groups" do
+      groups = @eth.groups
+      groups.size.should == 4
+      groups.first.class.name.should == 'EtherpadLite::Group'
+    end
+  end
+
   context 'Group Pad' do
     context 'Privacy' do
       it "should be private" do

data/spec/instance_spec.rb

@@ -2,24 +2,11 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Instance do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key], TEST_CONFIG[:api_version]
   end
 
   it "should have the right API key" do
-    api_key = if TEST_CONFIG[:api_key_file]
-      begin
-        TEST_CONFIG[:api_key_file].read
-      rescue IOError
-        TEST_CONFIG[:api_key_file].reopen(TEST_CONFIG[:api_key_file].path, mode='r')
-        TEST_CONFIG[:api_key_file].read
-      end
-    else
-      TEST_CONFIG[:api_key]
-    end
+    api_key = TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
     @eth.client.api_key.should == api_key
   end
-
-  it "shouldn't be secure" do
-    @eth.client.secure?.should == false
-  end
 end

data/spec/pad_spec.rb

@@ -2,14 +2,14 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Pad do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key], TEST_CONFIG[:api_version]
   end
 
   it "should blow up when querying a non-existing pad" do
     pad = @eth.get_pad 'a non-existant pad'
     begin
       txt = pad.text
-    rescue ArgumentError => e
+    rescue EtherpadLite::Error => e
     end
     e.message.should == 'padID does not exist'
   end
@@ -22,7 +22,7 @@ describe EtherpadLite::Pad do
   it "should blow up when creating a Pad that already exists" do
     begin
       pad = @eth.create_pad 'my new pad', :text => 'The initial text'
-    rescue ArgumentError => e
+    rescue EtherpadLite::Error => e
     end
     e.message.should == 'padID does already exist'
   end
@@ -104,8 +104,25 @@ describe EtherpadLite::Pad do
     pad.user_count.should == 0
   end
 
+  it "should not crash when setting null text" do
+    err_msg = nil
+    begin
+      @eth.client.setText(:padID => 'brand new pad3')
+    rescue EtherpadLite::Error => e
+      err_msg = e.message
+    end
+    err_msg.should == 'text is no string'
+  end
+
   it "should be deleted" do
     @eth.get_pad('another new pad').delete
     @eth.create_pad('another new pad').id.should_not == nil
   end
+
+  if TEST_CONFIG[:api_version] > 1
+    it "should get the pad users" do
+      puts @eth.pad('pad with users').users
+      @eth.pad('pad with users').users.should == []
+    end
+  end
 end

data/spec/session_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Session do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key], TEST_CONFIG[:api_version]
   end
 
   it "should be created for a Group" do

data/spec/spec_helper.rb

@@ -11,4 +11,4 @@ end
 # Load test config
 require 'yaml'
 TEST_CONFIG = YAML.load_file(File.dirname(__FILE__) + '/config.yml')
-TEST_CONFIG[:api_key_file] = File.new(TEST_CONFIG[:api_key_file]) unless TEST_CONFIG[:api_key_file].nil?
+TEST_CONFIG[:api_key_file] = File.open(TEST_CONFIG[:api_key_file], &:read) unless TEST_CONFIG[:api_key_file].nil?

metadata

@@ -1,84 +1,82 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: etherpad-lite
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 0
-  version: 0.1.0
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-07-07 00:00:00 -04:00
-default_executable: 
-dependencies: []
-
+date: 2012-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.6'
 description: etherpad-lite is a Ruby interface to Etherpad Lite's HTTP JSON API
 email: jordan@jordanhollinger.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.rdoc
-files: 
+files:
 - lib/etherpad-lite.rb
-- lib/etherpad-lite/models.rb
-- lib/etherpad-lite/models/session.rb
 - lib/etherpad-lite/models/padded.rb
+- lib/etherpad-lite/models/group.rb
+- lib/etherpad-lite/models/pad.rb
 - lib/etherpad-lite/models/author.rb
 - lib/etherpad-lite/models/instance.rb
-- lib/etherpad-lite/models/pad.rb
-- lib/etherpad-lite/models/group.rb
+- lib/etherpad-lite/models/session.rb
 - lib/etherpad-lite/client.rb
 - lib/etherpad-lite/version.rb
+- lib/etherpad-lite/models.rb
+- spec/pad_spec.rb
+- spec/config.yml.example
+- spec/config.yml
 - spec/spec_helper.rb
 - spec/instance_spec.rb
 - spec/session_spec.rb
-- spec/group_spec.rb
-- spec/config.yml
-- spec/config.yml.example
 - spec/author_spec.rb
-- spec/pad_spec.rb
+- spec/group_spec.rb
 - README.rdoc
 - CHANGELOG
 - LICENSE
-has_rdoc: true
 homepage: http://github.com/jhollinger/ruby-etherpad-lite
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
 summary: A Ruby client library for Etherpad Lite
 test_files: []
-