etherpad-lite 0.0.4 → 0.1.0.rc2

data/CHANGELOG

@@ -1,3 +1,11 @@
+** RELEASE 0.1.0 (Pending) **
+
+* Requires Etherpad Lite 1.1+
+* Added support for get/setHTML
+* Uses POST for API calls which alter data - this allows much larger pad content to be written
+* Various minor improvements and bugfixes
+* More complete documentation and examples
+
 ** RELEASE 0.0.4 (09/12/2011) **
 
 * Bugfix to Pads. A Pad initialied with a specific revision was not returning that revision's text.

data/README.rdoc

@@ -1,13 +1,15 @@
 = Etherpad Lite Ruby Client
 
-etherpad-lite is a Ruby client for Etherpad Lite's HTTP JSON API. Etherpad Lite is a collaborative editor provided by the Etherpad Foundation (http://etherpad.org).
+The etherpad-lite Ruby Gem is a Ruby client for Etherpad Lite's HTTP JSON API. Etherpad Lite is a collaborative editor provided by the {Etherpad Foundation}[http://etherpad.org].
 
-See https://github.com/Pita/etherpad-lite for information on how to install and configure your own Etherpad Lite instance, and read https://github.com/Pita/etherpad-lite/wiki/HTTP-API for an in-depth description of Etherpad Lite's HTTP API.
+See {github.com/Pita/etherpad-lite}[https://github.com/Pita/etherpad-lite] for information on how to install and configure your own Etherpad Lite instance, and read {github.com/Pita/etherpad-lite/wiki/HTTP-API}[https://github.com/Pita/etherpad-lite/wiki/HTTP-API] for an in-depth description of Etherpad Lite's HTTP API.
 
-== 1 Installation
+== Installation
     gem install etherpad-lite
 
-== 2 Basic usage
+*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.
+
+== Basic usage
     require 'etherpad-lite'
 
     # Connect to your Etherpad Lite instance
@@ -23,19 +25,24 @@ See https://github.com/Pita/etherpad-lite for information on how to install and
     pad.text = "What hath God wrought?"
 
     # There are now 2 revisions!
-    puts pad.revison_numbers.size
-    => 2
+    puts pad.revision_numbers
+    => [0, 1]
 
     # Iterate through each revision
     pad.revisions.each do |pad_rev|
-      puts pad_rev.rev
+      puts "Revision #{pad_rev.rev}:"
       puts pad_rev.text
     end
 
-Read the full docs at http://jordanhollinger.com/docs/ruby-etherpad-lite/.
+Full docs are at {jordanhollinger.com/docs/ruby-etherpad-lite/}[http://jordanhollinger.com/docs/ruby-etherpad-lite/]
+
+== Advanced usage
+The above example deals with public pads, accessible to anyone through the Web UI. There is another class of pads - group pads - which deal with groups, authors and sessions.
+Examples are documented in EtherpadLite::Group, EtherpadLite::Author, and EtherpadLite::Session.
 
-== 3 Example use in Rails
-For your view, I recommend the jQuery plugin at https://github.com/johnyma22/etherpad-lite-jquery-plugin.
+== Example use in Rails
+For your view, I recommend the jQuery plugin at {github.com/johnyma22/etherpad-lite-jquery-plugin}[https://github.com/johnyma22/etherpad-lite-jquery-plugin].
+Also, I recommend reading the docs for EtherpadLite::Group first.
 
 Add the following to your Gemfile
   gem 'etherpad-lite'
@@ -46,27 +53,28 @@ On login, create a Hash in your session to store EtherpadLite API sessions:
 Some example controller actions:
 
   class EtherpadController < ApplicationController
+    # /etherpad
     def index
       # The idea is that 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, 'api key')
+      ether = EtherpadLite.connect(:local, File.new('/var/www/etherpad-lite/APIKEY.txt'))
       @app_group = YourAppGroup.find(params[:id])
-      # Map your app's group to an EtherpadLite Group
+      # Map your app's group to an EtherpadLite Group, and list all its pads
       group = ether.group("my_app_group_#{@app_group.id}")
-      # List all the pads in group
       @pads = group.pads
     end
 
+    # /etherpad/pads/:ep_group_id/:ep_pad_name
     def pad
-      ether = EtherpadLite.connect(:local, 'api key')
-      # Get the EtherpadLite Group by id
-      @group = ether.get_group(params[:group_id])
-      # Get the pad
-      @pad = @group.pad(params[:pad_name])
+      ether = EtherpadLite.connect(:local, File.new('/var/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])
       # Map the user to an EtherpadLite Author
       author = ether.author("my_app_user_#{current_user.id}", :name => current_user.name)
       # Get or create an hour-long session for this Author in this Group
@@ -81,24 +89,42 @@ Some example controller actions:
     end
   end
 
-== 4 Why is the Ruby client so different from the others? What gives you the right?!?
-The PHP and Python clients are extremely thin wrappers around the HTTP API; their method names map directly to urls. The Ruby client offers a slightly higher level of abstration,
-with the goal of making Etherpad Lite integration in Ruby projects as simple, poweful, and dare I say fun, as possible. That said, there is nothing wrong with the thinly-wrapped API.
-So in the interests of being a good citizen, the Ruby client is written in two layers, one conforming to the other clients, and a higher-level "models" API riding on top of it.
+== 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)
 
-In the examples above, the "standard" client can be accessed with
+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')
     => {:text => "What hath God wrought?"}
 
-Or you can explicitly load only the standard client
+or you can explicitly load just the low-level client:
     require 'etherpad-lite/client'
-    client = EtherpadLite::Client.new('api key', 'http://beta.etherpad.org/api')
+    client = EtherpadLite::Client.new('http://beta.etherpad.org/api', 'api key')
+
+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.
+
+== Testing
+Testing this library is fairly simple. It requires:
+- A recent version of Rspec
+- A running copy of Etherpad Lite with a fresh db for each run of the tests (configure connection in spec/config.yml)
+
+Bring up Etherpad Lite with:
+
+    rm var/dirty.db && bin/run.sh
+
+Run the tests with
+
+    rspec spec
 
-== 5 License
+== License
 Copyright 2011 Jordan Hollinger
 
 Licensed under the Apache License
 
-== 5 Credit
-This Ruby client was inspired by TomNomNom's and devjones's PHP and Python clients, found at https://github.com/TomNomNom/etherpad-lite-client and https://github.com/devjones/PyEtherpadLite.
+== Credit
+This Ruby client was inspired by {TomNomNom's PHP client}[https://github.com/TomNomNom/etherpad-lite-client] and {devjones's Python client}[https://github.com/devjones/PyEtherpadLite].

data/lib/etherpad-lite/client.rb

@@ -3,46 +3,94 @@ 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:
+
 module EtherpadLite
+  MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION = 0, 1, 0, 'rc2' # :nodoc:
+  # The client version
+  VERSION = [MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION].compact.join '.'
+
+  # 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
+
   # A thin wrapper around Etherpad Lite's HTTP JSON API
+  # 
+  #  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
+  #  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
 
-    attr_reader :uri, :api_key
+    # A URI object containing the URL of the Etherpad Lite instance
+    attr_reader :uri
+    # The API key
+    attr_reader :api_key
 
-    # Path to the system's CA cert paths (for connecting over SSL)
-    @@ca_path = nil
-
-    # Get path to the system's CA certs
-    def self.ca_path; @@ca_path; end
-
-    # Manually set path to the system's CA certs. Use this if the location couldn't be determined automatically.
-    def self.ca_path=(path); @@ca_path = path; end
+    class << self
+      # Path to the system's CA certs (for connecting over SSL)
+      attr_accessor :ca_path
+    end
 
-    # Instantiate a new Etherpad Lite Client. The url should include the protocol (i.e. http or https).
-    def initialize(api_key, url='http://localhost:9001/api')
+    # 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} is not a valid url" unless @uri.host and @uri.port
-      @api_key = api_key
-      connect!
-    end
+      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
 
-    # Calls the EtherpadLite API and returns the :data portion of the response Hash.
-    def call(method, params={})
-      # Build path
-      params[:apikey] = @api_key
-      params = params.map { |p| p.join('=') }.join('&').gsub(/\s/, '%20')
-      path = [@uri.path, API_VERSION, method].compact.join('/') << '?' << params
-      # Send request
-      get = Net::HTTP::Get.new(path)
-      response = @http.request(get)
-      handleResult response.body
+      connect!
     end
 
     # Groups
@@ -50,29 +98,29 @@ module EtherpadLite
 
     # Creates a new Group
     def createGroup
-      call :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)
-      call :createGroupIfNotExistsFor, :groupMapper => groupMapper
+      post :createGroupIfNotExistsFor, :groupMapper => groupMapper
     end
 
     # Deletes a group
     def deleteGroup(groupID)
-      call :deleteGroup, :groupID => groupID
+      post :deleteGroup, :groupID => groupID
     end
 
     # Returns all the Pads in the given Group
     def listPads(groupID)
-      call :listPads, :groupID => 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?
-      call :createGroupPad, params
+      post :createGroupPad, params
     end
 
     # Authors
@@ -82,14 +130,14 @@ module EtherpadLite
     def createAuthor(name=nil)
       params = {}
       params[:name] = name unless name.nil?
-      call :createAuthor, params
+      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?
-      call :createAuthorIfNotExistsFor, params
+      post :createAuthorIfNotExistsFor, params
     end
 
     # Sessions
@@ -99,27 +147,27 @@ module EtherpadLite
 
     # Creates a new Session for the given Author in the given Group
     def createSession(groupID, authorID, validUntil)
-      call :createSession, :groupID => groupID, :authorID => authorID, :validUntil => validUntil
+      post :createSession, :groupID => groupID, :authorID => authorID, :validUntil => validUntil
     end
 
     # Deletes the given Session
     def deleteSession(sessionID)
-      call :deleteSession, :sessionID => sessionID
+      post :deleteSession, :sessionID => sessionID
     end
 
     # Returns information about the Session
     def getSessionInfo(sessionID)
-      call :getSessionInfo, :sessionID => sessionID
+      get :getSessionInfo, :sessionID => sessionID
     end
 
     # Returns all Sessions in the given Group
     def listSessionsOfGroup(groupID)
-      call :listSessionsOfGroup, :groupID => groupID
+      get :listSessionsOfGroup, :groupID => groupID
     end
 
     # Returns all Sessions belonging to the given Author
     def listSessionsOfAuthor(authorID)
-      call :listSessionsOfAuthor, :authorID => authorID
+      get :listSessionsOfAuthor, :authorID => authorID
     end
 
     # Pad content
@@ -129,12 +177,24 @@ module EtherpadLite
     def getText(padID, rev=nil)
       params = {:padID => padID}
       params[:rev] = rev unless rev.nil?
-      call :getText, params
+      get :getText, params
     end
 
     # Sets the text of the given Pad
     def setText(padID, text)
-      call :setText, :padID => padID, :text => text
+      post :setText, :padID => padID, :text => text
+    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
@@ -146,42 +206,42 @@ module EtherpadLite
     def createPad(padID, text=nil)
       params = {:padID => padID}
       params[:text] = text unless text.nil?
-      call :createPad, params
+      post :createPad, params
     end
 
     # Returns the number of revisions the given Pad contains
     def getRevisionsCount(padID)
-      call :getRevisionsCount, :padID => padID
+      get :getRevisionsCount, :padID => padID
     end
 
     # Delete the given Pad
     def deletePad(padID)
-      call :deletePad, :padID => padID
+      post :deletePad, :padID => padID
     end
 
     # Returns the Pad's read-only id
     def getReadOnlyID(padID)
-      call :getReadOnlyID, :padID => padID
+      get :getReadOnlyID, :padID => padID
     end
 
     # Sets a boolean for the public status of a Pad
     def setPublicStatus(padID, publicStatus)
-      call :setPublicStatus, :padID => padID, :publicStatus => publicStatus
+      post :setPublicStatus, :padID => padID, :publicStatus => publicStatus
     end
 
     # Gets a boolean for the public status of a Pad
     def getPublicStatus(padID)
-      call :getPublicStatus, :padID => padID
+      get :getPublicStatus, :padID => padID
     end
 
     # Sets the password on a pad
     def setPassword(padID, password)
-      call :setPassword, :padID => padID, :password => password
+      post :setPassword, :padID => padID, :password => password
     end
 
     # Returns true if the Pad has a password, false if not
     def isPasswordProtected(padID)
-      call :isPasswordProtected, :padID => padID
+      get :isPasswordProtected, :padID => padID
     end
 
     # Returns true if the connection to the Etherpad Lite instance is using SSL/HTTPS.
@@ -191,16 +251,54 @@ module EtherpadLite
 
     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
+
+    # 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)
+      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
+
     # 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)
-      response = JSON.parse(response, :symbolize_names => true)
+      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 StandardError, "An unknown error ocurrced while handling the response: #{response.to_s}"
+          raise APIError, "An unknown error ocurrced while handling the response: #{response.to_s}"
       end
     end
 
@@ -211,9 +309,9 @@ module EtherpadLite
       @http = Net::HTTP.new(@uri.host, @uri.port)
       if secure?
         @http.use_ssl = true
-        if @@ca_path
+        if self.class.ca_path
           @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          @http.ca_path = @@ca_path
+          @http.ca_path = self.class.ca_path
         else
           @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
         end
@@ -227,3 +325,6 @@ end
   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

@@ -1,7 +1,54 @@
 module EtherpadLite
   # An Author of Pad content
+  # 
+  # Authors are used to create a Session in a Group. Authors may be created with
+  # a name and a mapper. A mapper is usually an identifier stored in your third-party system,
+  # like a foreign key or username.
+  #
+  # Author Examples:
+  # 
+  #  @ether = EtherpadLite.connect(:local, 'api key')
+  # 
+  #  # Create a new author with both a name and a mapper
+  #  author1 = @ether.create_author(:name => 'Theodor Seuss Geisel', :mapper => 'author_1')
+  # 
+  #  # Load (and create, if necessary) a mapped author with a name
+  #  author2 = @ether.author('author_2', :name => 'Richard Bachman')
+  #
+  #  # Load (and create, if necessary) a author by mapper
+  #  author3 = @ether.author('author_3')
+  # 
+  #  # Load author1 by id
+  #  author4 = @ether.get_author(author1.id)
+  # 
+  # Session examples:
+  # 
+  #  # Create two hour-long session for author 1 in two different groups
+  #  group1 = @ether.group('my awesome group')
+  #  group2 = @ether.group('my other awesome group')
+  # 
+  #  session1 = author1.create_session(group1, 60)
+  #  session2 = author1.create_session(group2, 60)
+  # 
+  # Attribute examples:
+  # 
+  #  author1.name #> "Theodor Seuss Geisel"
+  # 
+  #  author1.mapper #> "author_1"
+  # 
+  #  author2.sessions #> [#<EtherpadLite::Session>, #<EtherpadLite::Session>]
+  # 
+  #  author2.session_ids.include? session1.id #> true
+  # 
   class Author
-    attr_reader :id, :instance, :name, :mapper
+    # The EtherpadLite::Instance object
+    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
 
     # Creates a new Author. Optionally, you may pass the :mapper option your third party system's author id.
     # This will allow you to find the Author again later using the same identifier as your foreign system.
@@ -9,9 +56,9 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  mapper => uid of Author from another system
+    # mapper => uid of Author from another system
     # 
-    #  name => Author's name
+    # name => Author's name
     def self.create(instance, options={})
       result = options[:mapper] \
         ? instance.client.createAuthorIfNotExistsFor(options[:mapper], options[:name]) \
@@ -23,9 +70,9 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  mapper => the foreign author id it's mapped to
+    # mapper => the foreign author id it's mapped to
     # 
-    #  name => the Author's name
+    # name => the Author's name
     def initialize(instance, id, options={})
       @instance = instance
       @id = id

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

@@ -1,10 +1,59 @@
 module EtherpadLite
-  # A Group of Pads
+  # A Group serves as a container for related pads. Only an Author with a Session can access a group Pad.
+  # 
+  # Group examples:
+  # 
+  #  # Create a new group
+  #  group1 = @ether.create_group
+  #  # Etherpad Lite will assign it an internal id
+  #  group.id #> 'g.asdflsadf7w9823kjlasdf' 
+  # 
+  #  # Create a new group with a mapper, so it can be easily found again
+  #  group2 = @ether.create_group :mapper => 'Blurg'
+  # 
+  #  # Load (or create, if it doesn't exist) a group mapped to "Flarb"
+  #  group3 = @ether.group('Flarb')
+  # 
+  #  # Load an existing group based on its internal id
+  #  group4 = @ether.get_group('g.823lasdlfj98asdfj')
+  # 
+  # Group pad examples:
+  # 
+  #  # Create a new pad in this group, optionally specifying its initial text
+  #  pad1 = group1.create_pad('group 1 pad', :text => 'Words!')
+  # 
+  #  # Load (or create, if it doesn't exist) a pad in this group
+  #  pad2 = group2.pad('group 2 pad')
+  # 
+  #  # Load an existing pad from group 2
+  #  pad3 = group2.get_pad('important pad')
+  # 
+  # Session examples:
+  # 
+  #  # Create two hour-long session for an author in group 1
+  #  author = @ether.author('author_1')
+  #  session = group1.create_session(author, 60)
+  # 
+  # Understand how ids work. A group pad's id is the group_id + '$' + pad_name:
+  # 
+  #  pad2.group_id == group2.id #> true
+  # 
+  #  pad2.id == group2.id + '$' + pad2.name #> true
+  # 
+  #  pad2 == group2.pad('group 2 pad') == @ether.get_pad("#{group2.id}$group 2 pad") == @ether.get_pad('group 2 pad', :groupID => group2.id) #> true
+  # 
+  #  group2.mapper #> "Blurg"
+  # 
   class Group
     GROUP_ID_REGEX = /^g\.[^\$]+/
     include Padded
 
-    attr_reader :id, :instance, :mapper
+    # The EtherpadLite::Instance object
+    attr_reader :instance
+    # The group id
+    attr_reader :id
+    # An optional identifier used to map the group to something outside Etherpad Lite
+    attr_reader :mapper
 
     # Creates a new Group. Optionally, you may pass the :mapper option your third party system's group id.
     # This will allow you to find your Group again later using the same identifier as your foreign system.
@@ -12,7 +61,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  mapper => your foreign group id
+    # mapper => your foreign group id
     def self.create(instance, options={})
       result = options[:mapper] \
         ? instance.client.createGroupIfNotExistsFor(options[:mapper]) \
@@ -24,7 +73,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  mapper => the foreign id it's mapped to
+    # mapper => the foreign id it's mapped to
     def initialize(instance, id, options={})
       @instance = instance
       @id = id
@@ -49,7 +98,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  text => 'initial Pad text'
+    # text => 'initial Pad text'
     def create_pad(id, options={})
       options[:groupID] = @id
       super groupify_pad_id(id), options
@@ -62,7 +111,7 @@ module EtherpadLite
 
     # Returns an array of all the Pad ids in this Group.
     def pad_ids
-      @instance.client.listPads(@id)[:padIDs].keys
+      @instance.client.listPads(@id)[:padIDs]
     end
 
     # Create a new session for author that will last length_in_minutes.
@@ -91,7 +140,7 @@ module EtherpadLite
 
     # Prepend the group_id to the pad name
     def groupify_pad_id(pad_id)
-      "#{@id}$#{pad_id}"
+      pad_id =~ GROUP_ID_REGEX ? pad_id : "#{@id}$#{pad_id}"
     end
   end
 end

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

@@ -1,43 +1,35 @@
 module EtherpadLite
-  # Aliases to common Etherpad Lite hosts
-  HOST_ALIASES = {:local => 'http://localhost:9001',
-                  :public => 'http://beta.etherpad.org'}
-
   # Returns an EtherpadLite::Instance object.
   # 
-  # ether1 = EtherpadLite.connect('https://etherpad.yoursite.com[https://etherpad.yoursite.com]', 'your api key')
+  #  ether1 = EtherpadLite.connect('https://etherpad.yoursite.com[https://etherpad.yoursite.com]', 'your api key')
+  # 
+  #  # An alias for http://localhost:9001
+  #  ether2 = EtherpadLite.connect(:local, File.new('/path/to/APIKEY.txt'))
   # 
-  # ether2 = EtherpadLite.connect(:local, File.new('/file/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)
-    # Parse the host
-    host = 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]
-    else
-      host_or_alias
-    end
-
-    # Parse the api key
-    if api_key_or_file.is_a? File
-      api_key = api_key_or_file.read
-      api_key_or_file.close
-    else
-      api_key = api_key_or_file
-    end
-
-    Instance.new(host, api_key)
+    Instance.new(host_or_alias, api_key_or_file)
   end
 
-  # An EtherpadLite::Instance provides a hight-level interface to an Etherpad Lite system.
+  # EtherpadLite::Instance provides a high-level interface to the EtherpadLite::Client class. See the EtherpadLite module 
+  # for examples of how to establish a connection.
   class Instance
     include Padded
-    API_ROOT = 'api'
-
+    # 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).
-    def initialize(url, api_key)
-      @client = Client.new(api_key, url + "/#{API_ROOT}")
+    # 
+    #  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)
     end
 
     # Returns, creating if necessary, a Group mapped to your foreign system's group
@@ -55,7 +47,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  mapper => your foreign group id
+    # mapper => your foreign group id
     def create_group(options={})
       Group.create self, options
     end
@@ -64,7 +56,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  name => the Author's name
+    # name => the Author's name
     def author(mapper, options={})
       options[:mapper] = mapper
       create_author options
@@ -80,7 +72,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  mapper => your foreign author id
+    # mapper => your foreign author id
     # 
     #  name => the Author's name
     def create_author(options={})
@@ -92,6 +84,7 @@ module EtherpadLite
       Session.new self, session_id
     end
 
+    # Returns itself
     def instance; self; end
   end
 end

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

@@ -1,15 +1,26 @@
 module EtherpadLite
   # An Etherpad Lite Pad
+  # 
+  # This class allows you to interact with pads stored in an Etherpad Lite server. The README 
+  # has some basic examples.
+  # 
+  # Note that some functions are restricted to Group pads.
+  # 
   class Pad
-    attr_reader :id, :instance, :rev
+    # The EtherpadLite::Instance object
+    attr_reader :instance
+    # The pad id
+    attr_reader :id
+    # An optional pad revision number
+    attr_reader :rev
 
     # Creates and returns a new Pad.
     # 
     # Options:
     # 
-    #  text => 'initial Pad text'
+    # text => 'initial Pad text'
     # 
-    #  groupID => group id of Group new Pad should belong to
+    # groupID => group id of Group new Pad should belong to
     def self.create(instance, id, options={})
       if options[:groupID]
         group = Group.new instance, options[:groupID]
@@ -18,7 +29,7 @@ module EtherpadLite
         group = nil
         instance.client.createPad(id, options[:text])
       end
-      new instance, id, :group => group
+      new instance, id, :groupID => options[:groupID], :group => group
     end
 
     # Remove the group id portion of a Group Pad's id
@@ -30,12 +41,18 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  group
+    # groupID => a group id
     # 
-    #  rev
+    # group => an EtherpadLite::Group object
+    # 
+    # rev => a pad revision number
     def initialize(instance, id, options={})
       @instance = instance
       @id = id.to_s
+      if options[:groupID]
+        @group_id = options[:groupID]
+        @id = "#{@group_id}$#{@id}" unless @id =~ Group::GROUP_ID_REGEX
+      end
       @group = options[:group]
       @rev = options[:rev]
     end
@@ -65,7 +82,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  rev => revision_number
+    # rev => revision_number
     def text(options={})
       options[:rev] ||= @rev unless @rev.nil?
       @instance.client.getText(@id, options[:rev])[:text]
@@ -76,6 +93,21 @@ module EtherpadLite
       @instance.client.setText(@id, 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.
+    # 
+    # Options:
+    # 
+    # rev => revision_number
+    def html(options={})
+      options[:rev] ||= @rev unless @rev.nil?
+      @instance.client.getHTML(@id, options[:rev])[:html]
+    end
+
+    # Writes HTML to the Pad. There is no 'save' method; it is written immediately.
+    def html=(html)
+      @instance.client.setHTML(@id, html)
+    end
+
     # Returns an Array of all this Pad's revision numbers
     def revision_numbers
       max = @instance.client.getRevisionsCount(@id)[:revisions]

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

@@ -5,7 +5,12 @@ module EtherpadLite
     # Returns the Pad with the given id, creating it if it doesn't already exist.
     # This requires an HTTP request, so if you *know* the Pad already exists, use Instance#get_pad instead.
     def pad(id, options={})
-      Pad.create(instance, id, options) rescue Pad.new(instance, id, options)
+      begin
+        Pad.create(instance, id, options)
+      # Pad alreaded exists
+      rescue ArgumentError
+        Pad.new(instance, id, options)
+      end
     end
 
     # Returns the Pad with the given id (presumed to already exist).
@@ -18,7 +23,7 @@ module EtherpadLite
     # 
     # Options:
     # 
-    #  text => 'initial Pad text'
+    # text => 'initial Pad text'
     def create_pad(id, options={})
       Pad.create instance, id, options
     end

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

@@ -1,7 +1,17 @@
 module EtherpadLite
-  # An Etherpad Lite Session between a Group and an Author
+  # An Etherpad Lite Session between a Group and an Author. See those classes for examples of how to create a session.
+  # 
+  # Sessions are useful for embedding an Etherpad Lite Pad into a external application. For public pads, sessions 
+  # are not necessary. However Group pads require a Session to access to the pad via the Web UI.
+  # 
+  # Generally, you will create the session server side, then pass its id to the embedded pad using a cookie. See the README
+  # for an example in a Rails app.
+  # 
   class Session
-    attr_reader :id, :instance
+    # The EtherpadLite::Instance object
+    attr_reader :instance
+    # The session id
+    attr_reader :id
 
     # 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)

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[:instances][:http][:url], TEST_CONFIG[:instances][:http][:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
   end
 
   it "should be created" do

data/spec/config.yml

@@ -1,9 +1,4 @@
-:instances:
-  :http:
-    :url: http://localhost:9003
-    :api_key: faia3X2dT0u57Du6io44h4WKvePnUltg
-
-  # Uncomment to test https connections
-  #:https:
-  #  :url: https://localhost:9001
-  #  :api_key: api key
+: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

data/spec/config.yml.example

@@ -1,9 +1,4 @@
-:instances:
-  :http:
-    :url: http://localhost:9001
-    :api_key: your api key
-
-  # Uncomment to test https connections
-  #:https:
-  #  :url: https://localhost:9001
-  #  :api_key: api key
+:url: http://localhost:9001
+:api_key: your api key
+# Full filesystem path to APIKEY.txt, may be used instead of the above :api_key setting
+:api_key_file:

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[:instances][:http][:url], TEST_CONFIG[:instances][:http][:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
   end
 
   it "should be created" do
@@ -28,6 +28,12 @@ describe EtherpadLite::Group do
     pad.id.should == "#{group.id}$Important Group Stuff"
   end
 
+  it "should create another Group Pad" do
+    group = @eth.group 'Group A'
+    pad = @eth.create_pad 'Other Important Group Stuff', :groupID => group.id, :text => 'foo'
+    pad.text.should == "foo\n"
+  end
+
   it "should create a Group Pad with the right name" do
     group = @eth.group 'Group A'
     pad = group.pad 'Important Group Stuff'
@@ -39,14 +45,34 @@ describe EtherpadLite::Group do
     group.get_pad('Important Group Stuff').group_id.should == group.id
   end
 
-  it "should find a Group Pad with the right id" do
+  it "should find another Group Pad with the right group" do
+    group = @eth.group 'Group A'
+    @eth.get_pad('Other Important Group Stuff', :groupID => group.id).group_id.should == group.id
+  end
+
+  it "should find yet another Group Pad with the right group" do
+    group = @eth.group 'Group A'
+    @eth.get_pad("Other Important Group Stuff", :groupID => group.id).text.should == "foo\n"
+  end
+
+  it "should find another Group Pad with the right text" do
+    group = @eth.group 'Group A'
+    @eth.get_pad("#{group.id}$Other Important Group Stuff").text.should == "foo\n"
+  end
+
+  it "should find yet another Group Pad with the right text" do
+    group = @eth.group 'Group A'
+    @eth.get_pad("#{group.id}$Other Important Group Stuff").text.should == "foo\n"
+  end
+
+  it "should find a Group Pad with the right ids" do
     group = @eth.group 'Group A'
-    group.pad_ids.should == [:"#{group.id}$Important Group Stuff"]
+    group.pad_ids.should == ["#{group.id}$Important_Group_Stuff", "#{group.id}$Other_Important_Group_Stuff"]
   end
 
   it "should find a Group Pad with the right name" do
     group = @eth.group 'Group A'
-    group.pads.first.name.should == "Important Group Stuff"
+    group.pads.first.name.should == "Important_Group_Stuff"
   end
 
   it "should explicitly create a Group Pad" do

data/spec/instance_spec.rb

@@ -2,11 +2,21 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Instance do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:instances][:http][:url], TEST_CONFIG[:instances][:http][:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
   end
 
   it "should have the right API key" do
-    @eth.client.api_key.should == TEST_CONFIG[:instances][:http][:api_key]
+    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
+    @eth.client.api_key.should == api_key
   end
 
   it "shouldn't be secure" do

data/spec/pad_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe EtherpadLite::Pad do
   before do
-    @eth = EtherpadLite.connect TEST_CONFIG[:instances][:http][:url], TEST_CONFIG[:instances][:http][:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
   end
 
   it "should blow up when querying a non-existing pad" do
@@ -54,6 +54,12 @@ describe EtherpadLite::Pad do
     pad.revision_numbers.last == 2
   end
 
+  it "should set HTML" do
+    pad = @eth.get_pad 'another new pad'
+    pad.html = "<div><p>Here's some HTML.</p>\n<p>Please rewind it when you're finished.</p></div>"
+    pad.html.should == "Here&#x27;s some HTML.<br>Please rewind it when you&#x27;re finished.<br>"
+  end
+
   it "should have the first revision" do
     pad = @eth.get_pad 'another new pad'
     pad.text(:rev => 1).should == "The initial text\n"
@@ -64,6 +70,11 @@ describe EtherpadLite::Pad do
     pad.revisions[1].text.should == "The initial text\n"
   end
 
+  it "should have the first revision as HTML" do
+    pad = @eth.get_pad 'another new pad'
+    pad.revisions[1].html.should == "The initial text<br>"
+  end
+
   it "should have the same name and id" do
     pad = @eth.get_pad 'another new pad'
     pad.name.should == pad.id

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[:instances][:http][:url], TEST_CONFIG[:instances][:http][:api_key]
+    @eth = EtherpadLite.connect TEST_CONFIG[:url], TEST_CONFIG[:api_key_file] || TEST_CONFIG[:api_key]
   end
 
   it "should be created for a Group" do

data/spec/spec_helper.rb

@@ -1,18 +1,14 @@
 require 'rspec'
 
 # Load etherpad-lite
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/client'
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/models/padded'
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/models/instance'
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/models/pad'
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/models/group'
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/models/author'
-require File.dirname(__FILE__) + '/../lib/etherpad-lite/models/session'
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/..'
+require 'etherpad-lite'
 
-Rspec.configure do |c|
+RSpec.configure do |c|
   c.mock_with :rspec
 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?

metadata

@@ -1,83 +1,65 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: etherpad-lite
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 4
-  version: 0.0.4
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc2
+  prerelease: 6
 platform: ruby
-authors: 
+authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-12 00:00:00 -04:00
-default_executable: 
+date: 2012-06-20 00:00:00.000000000 Z
 dependencies: []
-
 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/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: 1.3.1
 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: []
-