etherpad-lite 0.0.1

data/LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2011 Jordan Hollinger
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.rdoc

@@ -0,0 +1,58 @@
+= 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).
+
+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.
+
+== 1 Installation
+    gem install etherpad-lite
+
+== 2 Basic usage
+    require 'etherpad-lite'
+
+    # Connect to your Etherpad Lite instance (passing no arguments will connect you to beta.etherpad.org)
+    ether = EtherpadLite.connect('http://etherpad-lite.example.com', 'your api key')
+
+    # Get a Pad (or create one if it doesn't exist)
+    pad = ether.pad('my first etherpad lite pad')
+
+    puts pad.text
+    => "Welcome to Etherpad Lite!\n\nThis pad text is synchronized as you type, so that everyone viewing..."
+
+    # Write your the changes to the Pad
+    pad.text = "What hath God wrought?"
+
+    # There are now 2 revisions!
+    puts pad.revison_numbers.size
+    => 2
+
+    # Iterate through each revision
+    pad.revisions.each do |pad_rev|
+      puts pad_rev.rev
+      puts pad_rev.text
+    end
+
+For advanced functionality (i.e. Groups, Authors, Sessions), read the full docs at http://jordanhollinger.com/docs/ruby-etherpad-lite/. Also, the RSpec tests under /spec may provide some pointers.
+
+== 3 Why is the Ruby client so different from the others? What gives you the right?!?
+The PHP and Python clients are extremely thin wrappers of 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 certainly value in supporting the defacto standard set by the PHP and Python clients. With that in mind, 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.
+
+In the examples above, the "traditional" client can be accessed with
+    client = ether.client
+    client.getText('my first etherpad lite pad')
+    => {:text => "What hath God wrought?"}
+
+Or you can explicitly load only the standard client
+    require 'etherpad-lite/client'
+    client = EtherpadLite::Client.new('api key', 'http://beta.etherpad.org/api')
+
+== 4 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.

data/lib/etherpad-lite.rb

@@ -0,0 +1,2 @@
+require 'etherpad-lite/client'
+require 'etherpad-lite/models'

data/lib/etherpad-lite/client.rb

@@ -0,0 +1,229 @@
+require 'uri'
+require 'net/http'
+require 'net/https'
+require 'json'
+
+module EtherpadLite
+  # A thin wrapper over Etherpad Lite's HTTP JSON API
+  class Client
+    API_VERSION = 1
+
+    CODE_OK = 0
+    CODE_INVALID_PARAMETERS = 1
+    CODE_INTERNAL_ERROR = 2
+    CODE_INVALID_METHOD = 3
+    CODE_INVALID_API_KEY = 4
+
+    attr_reader :uri, :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
+
+    # Instantiate a new Etherpad Lite Instance. The url should include the protocol (i.e. http or https).
+    def initialize(api_key, url='http://localhost:9001/api')
+      @uri = URI.parse(url)
+      raise ArgumentError, "#{url} is not a valid url" unless @uri.host and @uri.port
+      @api_key = api_key
+      connect!
+    end
+
+    # Pad, Group, etc. all use this to send the HTTP API requests.
+    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
+    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
+      call :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
+    end
+
+    # Deletes a group
+    def deleteGroup(groupID)
+      call :deleteGroup, :groupID => groupID
+    end
+
+    # Returns all the Pads in the given Group
+    def listPads(groupID)
+      call :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
+    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?
+      call :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
+    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)
+      call :createSession, :groupID => groupID, :authorID => authorID, :validUntil => validUntil
+    end
+
+    # Deletes the given Session
+    def deleteSession(sessionID)
+      call :deleteSession, :sessionID => sessionID
+    end
+
+    # Returns information about the Session
+    def getSessionInfo(sessionID)
+      call :getSessionInfo, :sessionID => sessionID
+    end
+
+    # Returns all Sessions in the given Group
+    def listSessionsOfGroup(groupID)
+      call :listSessionsOfGroup, :groupID => groupID
+    end
+
+    # Returns all Sessions belonging to the given Author
+    def listSessionsOfAuthor(authorID)
+      call :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?
+      call :getText, params
+    end
+
+    # Sets the text of the given Pad
+    def setText(padID, text)
+      call :setText, :padID => padID, :text => text
+    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?
+      call :createPad, params
+    end
+
+    # Returns the number of revisions the given Pad contains
+    def getRevisionsCount(padID)
+      call :getRevisionsCount, :padID => padID
+    end
+
+    # Delete the given Pad
+    def deletePad(padID)
+      call :deletePad, :padID => padID
+    end
+
+    # Returns the Pad's read-only id
+    def getReadOnlyID(padID)
+      call :getReadOnlyID, :padID => padID
+    end
+
+    # Sets a boolean for the public status of a Pad
+    def setPublicStatus(padID, publicStatus)
+      call :setPublicStatus, :padID => padID, :publicStatus => publicStatus
+    end
+
+    # Gets a boolean for the public status of a Pad
+    def getPublicStatus(padID)
+      call :getPublicStatus, :padID => padID
+    end
+
+    # Sets the password on a pad
+    def setPassword(padID, password)
+      call :setPassword, :padID => padID, :password => password
+    end
+
+    # Returns true if the Pad has a password, false if not
+    def isPasswordProtected(padID)
+      call :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
+
+    # 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)
+      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}"
+      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 @@ca_path
+          @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          @http.ca_path = @@ca_path
+        else
+          @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+      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 Unable to find your CA Certificates; HTTPS connections will *not* be verified! You may remedy this with "EtherpadLite::Instance.ca_path = '/path/to/certs'"| unless EtherpadLite::Client.ca_path

data/lib/etherpad-lite/models.rb

@@ -0,0 +1,6 @@
+require 'etherpad-lite/models/padded'
+require 'etherpad-lite/models/instance'
+require 'etherpad-lite/models/pad'
+require 'etherpad-lite/models/group'
+require 'etherpad-lite/models/author'
+require 'etherpad-lite/models/session'

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

@@ -0,0 +1,53 @@
+module EtherpadLite
+  # An Author of Pad content
+  class Author
+    attr_reader :id, :instance, :name, :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.
+    # If you pass the mapper option, the method behaves like "create author for <mapper> if it doesn't already exist".
+    # 
+    # Options:
+    # 
+    #  mapper => uid of Author from another system
+    # 
+    #  name => Author's name
+    def self.create(instance, options={})
+      result = options[:mapper] \
+        ? instance.client.createAuthorIfNotExistsFor(options[:mapper], options[:name]) \
+        : instance.client.createAuthor(options[:name])
+      new instance, result[:authorID], options
+    end
+
+    # Instantiates an Author object (presumed it already exists)
+    # 
+    # Options:
+    # 
+    #  mapper => the foreign author id it's mapped to
+    # 
+    #  name => the Author's name
+    def initialize(instance, id, options={})
+      @instance = instance
+      @id = id
+      @mapper = options[:mapper]
+      @name = options[:name]
+    end
+
+    # Create a new session for group that will last length_in_minutes.
+    def create_session(group, length_in_min)
+      Session.create(@instance, group.id, @id, length_in_min)
+    end
+
+    # Returns all session ids from this Author
+    def session_ids
+      s = @instance.client.listSessionsOfAuthor(@id) || {}
+      s.keys
+    end
+
+    # Returns all sessions from this Author
+    def sessions
+      s = @instance.client.listSessionsOfAuthor(@id) || {}
+      s.map { |id,info| Session.new(@instance, id, info) }
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module EtherpadLite
+  # A Group of Pads
+  class Group
+    GROUP_ID_REGEX = /^g\.[^\$]+/
+    include Padded
+
+    attr_reader :id, :instance, :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.
+    # If you pass the mapper option, the method behaves like "create group for <mapper> if it doesn't already exist".
+    # 
+    # Options:
+    # 
+    #  mapper => your foreign group id
+    def self.create(instance, options={})
+      result = options[:mapper] \
+        ? instance.client.createGroupIfNotExistsFor(options[:mapper]) \
+        : instance.client.createGroup
+      new instance, result[:groupID], options
+    end
+
+    # Instantiates a Group object (presumed it already exists)
+    # 
+    # Options:
+    # 
+    #  mapper => the foreign id it's mapped to
+    def initialize(instance, id, options={})
+      @instance = instance
+      @id = id
+      @mapper = options[:mapper]
+    end
+
+    # 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 Group#get_pad instead.
+    def pad(id, options={})
+      options[:groupID] = @id
+      super groupify_pad_id(id), options
+    end
+
+    # Returns the Pad with the given id (presumed to already exist).
+    # Use this instead of Group#pad when you *know* the Pad already exists; it will save an HTTP request.
+    def get_pad(id, options={})
+      options[:group] = self
+      super groupify_pad_id(id), options
+    end
+
+    # Creates and returns a Pad with the given id.
+    # 
+    # Options:
+    # 
+    #  text => 'initial Pad text'
+    def create_pad(id, options={})
+      options[:groupID] = @id
+      super groupify_pad_id(id), options
+    end
+
+    # Returns an array of all the Pads in this Group.
+    def pads
+      pad_ids.map { |id| Pad.new(@instance, id, :group => self) }
+    end
+
+    # Returns an array of all the Pad ids in this Group.
+    def pad_ids
+      @instance.client.listPads(@id)[:padIDs].keys
+    end
+
+    # Create a new session for author that will last length_in_minutes.
+    def create_session(author, length_in_min)
+      Session.create(@instance, @id, author.id, length_in_min)
+    end
+
+    # Returns all session ids in this Group
+    def session_ids
+      s = @instance.client.listSessionsOfGroup(@id) || {}
+      s.keys
+    end
+
+    # Returns all sessions in this Group
+    def sessions
+      s = @instance.client.listSessionsOfGroup(@id) || {}
+      s.map { |id,info| Session.new(@instance, id, info) }
+    end
+
+    # Deletes the Group
+    def delete
+      @instance.client.deleteGroup(@id)
+    end
+
+    private
+
+    # Prepend the group_id to the pad name
+    def groupify_pad_id(pad_id)
+      "#{@id}$#{pad_id}"
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+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')
+  # 
+  # ether2 = EtherpadLite.connect(:local, File.new('/file/path/to/APIKEY.txt'))
+  # 
+  # ether3 = EtherpadLite.connect(:public, "beta.etherpad.org's api key")
+  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)
+  end
+
+  # An EtherpadLite::Instance provides a hight-level interface to an Etherpad Lite system.
+  class Instance
+    include Padded
+    API_ROOT = 'api'
+
+    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}")
+    end
+
+    # Returns, creating if necessary, a Group mapped to your foreign system's group
+    def group(mapper)
+      create_group(:mapper => mapper)
+    end
+
+    # Returns a Group with the given id (it is presumed to already exist).
+    def get_group(id)
+      Group.new self, id
+    end
+
+    # 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.
+    # 
+    # Options:
+    # 
+    #  mapper => your foreign group id
+    def create_group(options={})
+      Group.create self, options
+    end
+
+    # Returns, creating if necessary, a Author mapped to your foreign system's author
+    # 
+    # Options:
+    # 
+    #  name => the Author's name
+    def author(mapper, options={})
+      options[:mapper] = mapper
+      create_author options
+    end
+
+    # Returns an Author with the given id (it is presumed to already exist).
+    def get_author(id)
+      Author.new self, id
+    end
+
+    # 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.
+    # 
+    # Options:
+    # 
+    #  mapper => your foreign author id
+    # 
+    #  name => the Author's name
+    def create_author(options={})
+      Author.create self, options
+    end
+
+    def instance; self; end
+  end
+end

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

@@ -0,0 +1,135 @@
+module EtherpadLite
+  # An Etherpad Lite Pad
+  class Pad
+    attr_reader :id, :instance, :rev
+
+    # Creates and returns a new Pad.
+    # 
+    # Options:
+    # 
+    #  text => 'initial Pad text'
+    # 
+    #  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]
+        instance.client.createGroupPad(group.id, degroupify_pad_id(id), options[:text])
+      else
+        group = nil
+        instance.client.createPad(id, options[:text])
+      end
+      new instance, id, :group => group
+    end
+
+    # Remove the group id portion of a Group Pad's id
+    def self.degroupify_pad_id(pad_id)
+      pad_id.to_s.sub(Group::GROUP_ID_REGEX, '').sub(/^\$/, '')
+    end
+
+    # Instantiate a Pad. It is presumed to already exist (via Pad.create).
+    # 
+    # Options:
+    # 
+    #  group
+    # 
+    #  rev
+    def initialize(instance, id, options={})
+      @instance = instance
+      @id = id.to_s
+      @group = options[:group]
+      @rev = options[:rev]
+    end
+
+    # Returns the name of the Pad. For a normal pad, this is the same as it's id. But for a Group Pad,
+    # this strips away the group id part of the pad id.
+    def name
+      @name ||= self.class.degroupify_pad_id(@id)
+    end
+
+    # Returns the group_id of this Pad, if any
+    def group_id
+      unless @group_id
+        match = Group::GROUP_ID_REGEX.match(@id)
+        @group_id = match ? match[0] : nil
+      end
+      @group_id
+    end
+
+    # Returns this Pad's group, if any
+    def group
+      return nil unless group_id
+      @group ||= Group.new(@instance, group_id)
+    end
+
+    # Returns the Pad's text. Unless you specified a :rev when instantiating the Pad, or specify one here, this will return the latest revision.
+    # 
+    # Options:
+    # 
+    #  rev => revision_number
+    def text(options={})
+      @instance.client.getText(@id, options[:rev])[:text]
+    end
+
+    # Writes txt to the Pad. There is no 'save' method; it is written immediately.
+    def text=(txt)
+      @instance.client.setText(@id, txt)
+    end
+
+    # Returns a Range of all this Pad's revision numbers
+    def revision_numbers
+      max = @instance.client.getRevisionsCount(@id)[:revisions]
+      (0..max).to_a
+    end
+
+    # Returns an array of Pad objects, each with an increasing revision of the text.
+    def revisions
+      revision_numbers.map { |n| Pad.new(@instance, @id, :rev => n) }
+    end
+
+    # Returns the Pad's read-only id. This is cached.
+    def read_only_id
+      @read_only_id ||= @instance.client.getReadOnlyID(@id)[:readOnlyID]
+    end
+
+    # 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]
+    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)
+    end
+
+    # Returns true if this is a private Pad (opposite of public)
+    # This only applies to Pads belonging to a Group.
+    def private?
+      not public?
+    end
+
+    # Set the pad's private status to true or false (opposite of public=)
+    # This only applies to Pads belonging to a Group.
+    def private=(status)
+      public = !status
+    end
+
+    # 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]
+    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)
+    end
+
+    # Deletes the Pad
+    def delete
+      @instance.client.deletePad(@id)
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module EtherpadLite
+  # Methods for dealing with pads belonging to something. Both Instance and Group include this, as they each have pads.
+  # This will work with any object which has an instance method, returning an EtherpadLite Instance object.
+  module Padded
+    # 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)
+    end
+
+    # Returns the Pad with the given id (presumed to already exist).
+    # Use this instead of Instance#pad when you *know* the Pad already exists; it will save an HTTP request.
+    def get_pad(id, options={})
+      Pad.new instance, id, options
+    end
+
+    # Creates and returns a Pad with the given id.
+    # 
+    # Options:
+    # 
+    #  text => 'initial Pad text'
+    def create_pad(id, options={})
+      Pad.create instance, id, options
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module EtherpadLite
+  # An Etherpad Lite Session between a Group and an Author
+  class Session
+    attr_reader :id, :instance
+
+    # 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)
+      new instance, result[:sessionID]
+    end
+
+    # Instantiates a Session object (presumed to already exist)
+    def initialize(instance, id, info=nil)
+      @instance = instance
+      @id = id
+      @info = info
+    end
+
+    # Returns the Session's group id
+    def group_id
+      get_info[:groupID]
+    end
+
+    # Returns the Session's group
+    def group
+      @group ||= Group.new @instance, group_id
+    end
+
+    # Returns the Session's author id
+    def author_id
+      get_info[:authorID]
+    end
+
+    # Returns the Session's author
+    def author
+      @author ||= Author.new @instance, author_id
+    end
+
+    # Returns the Session's expiration date is a Unix timestamp in seconds
+    def valid_until
+      get_info[:validUntil]
+    end
+
+    def valid?
+      valid_until < Time.now.to_i
+    end
+
+    def expired?
+      not valid?
+    end
+
+    # Deletes the Session
+    def delete
+      @instance.client.deleteSession(@id)
+    end
+
+    private
+
+    # Request and cache session info from the server
+    def get_info
+      @info ||= @instance.client.getSessionInfo(@id)
+    end
+  end
+end

data/spec/author_spec.rb

@@ -0,0 +1,24 @@
+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]
+  end
+
+  it "should be created" do
+    author = @eth.create_author
+    author.id.nil?.should == false
+  end
+
+  it "should be mapped to 'Author A'" do
+    author = @eth.create_author :mapper => 'Author A'
+    author.id.nil?.should == false
+  end
+
+  it "should be mapped to 'Author A'" do
+    author1 = @eth.create_author :mapper => 'Author A'
+    author2 = @eth.author 'Author A'
+    # They should be the same
+    author1.id.should == author2.id
+  end
+end

data/spec/config.yml

@@ -0,0 +1,9 @@
+:instances:
+  :http:
+    :url: http://localhost:9003
+    :api_key: faia3X2dT0u57Du6io44h4WKvePnUltg
+
+  # Uncomment to test https connections
+  #:https:
+  #  :url: https://localhost:9001
+  #  :api_key: api key

data/spec/config.yml.example

@@ -0,0 +1,9 @@
+: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

data/spec/group_spec.rb

@@ -0,0 +1,102 @@
+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]
+  end
+
+  it "should be created" do
+    group = @eth.create_group
+    group.id.nil?.should == false
+  end
+
+  it "should be mapped to 'Group A'" do
+    group = @eth.create_group :mapper => 'Group A'
+    group.id.nil?.should == false
+  end
+
+  it "should be mapped to 'Group A'" do
+    group1 = @eth.create_group :mapper => 'Group A'
+    group2 = @eth.group 'Group A'
+    # They should be the same
+    group1.id.should == group2.id
+  end
+
+  it "should create a Group Pad" do
+    group = @eth.group 'Group A'
+    pad = group.pad 'Important Group Stuff'
+    pad.id.should == "#{group.id}$Important Group Stuff"
+  end
+
+  it "should create a Group Pad with the right name" do
+    group = @eth.group 'Group A'
+    pad = group.pad 'Important Group Stuff'
+    pad.name.should == "Important Group Stuff"
+  end
+
+  it "should find a Group Pad with the right group" do
+    group = @eth.group 'Group A'
+    group.get_pad('Important Group Stuff').group_id.should == group.id
+  end
+
+  it "should find a Group Pad with the right id" do
+    group = @eth.group 'Group A'
+    group.pad_ids.should == [:"#{group.id}$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"
+  end
+
+  it "should explicitly create a Group Pad" do
+    group = @eth.group 'Group A'
+    pad = group.create_pad 'new group pad', :text => 'abc'
+    pad.text.should == "abc\n"
+  end
+
+  context 'Group Pad' do
+    context 'Privacy' do
+      it "should be private" do
+        group = @eth.group 'Group A'
+        pad = group.get_pad 'new group pad'
+        pad.private?.should == true
+      end
+
+      it "should not be public" do
+        group = @eth.group 'Group A'
+        pad = group.get_pad 'new group pad'
+        pad.public?.should == false
+      end
+
+      it "should change to public" do
+        group = @eth.group 'Group A'
+        pad = group.get_pad 'new group pad'
+        pad.public = true
+        pad.public?.should == true
+      end
+
+      it "should change to not private" do
+        group = @eth.group 'Group A'
+        pad = group.get_pad 'new group pad'
+        pad.private = false
+        pad.private?.should == false
+      end
+    end
+
+    context 'Password' do
+      it "should not have a password" do
+        group = @eth.group 'Group A'
+        pad = group.get_pad 'new group pad'
+        pad.password?.should == false
+      end
+
+      it "should have a password set" do
+        group = @eth.group 'Group A'
+        pad = group.get_pad 'new group pad'
+        pad.password = 'correct horse battery staple'
+        pad.password?.should == true
+      end
+    end
+  end
+end

data/spec/instance_spec.rb

@@ -0,0 +1,15 @@
+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]
+  end
+
+  it "should have the right API key" do
+    @eth.client.api_key.should == TEST_CONFIG[:instances][:http][:api_key]
+  end
+
+  it "shouldn't be secure" do
+    @eth.client.secure?.should == false
+  end
+end

data/spec/pad_spec.rb

@@ -0,0 +1,81 @@
+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]
+  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
+    end
+    e.message.should == 'padID does not exist'
+  end
+
+  it "should create a new pad" do
+    pad = @eth.create_pad 'my new pad', :text => 'The initial text'
+    pad.text.should == "The initial text\n"
+  end
+
+  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
+    end
+    e.message.should == 'padID does already exist'
+  end
+
+  it "should automatically create a Pad" do
+    pad = @eth.pad 'another new pad'
+    pad.text = "The initial text"
+    pad.text.should == "The initial text\n"
+  end
+
+  it "should automatically find a Pad" do
+    pad = @eth.pad 'another new pad'
+    pad.text.should == "The initial text\n"
+  end
+
+  it "should find a Pad" do
+    pad = @eth.get_pad 'another new pad'
+    pad.text.should == "The initial text\n"
+  end
+
+  it "should have a read-only id" do
+    pad = @eth.get_pad 'another new pad'
+    pad.read_only_id.should =~ /^r\.\w+/
+  end
+
+  it "should add revisions" do
+    pad = @eth.get_pad 'another new pad'
+    pad.text == "New text"
+    pad.revision_numbers.last == 2
+  end
+
+  it "should have the first revision" do
+    pad = @eth.get_pad 'another new pad'
+    pad.text(:rev => 1).should == "The initial text\n"
+  end
+
+  it "should have the first revision" do
+    pad = @eth.get_pad 'another new pad'
+    pad.revisions[1].text.should == "The initial text\n"
+  end
+
+  it "should have the same name and id" do
+    pad = @eth.get_pad 'another new pad'
+    pad.name.should == pad.id
+  end
+
+  it "should be initialized as revision 1" do
+    pad = @eth.get_pad 'another new pad', :rev => 1
+    pad.text.should == "The initial text\n"
+  end
+
+  it "should be deleted" do
+    @eth.get_pad('another new pad').delete
+    @eth.create_pad('another new pad').id.should_not == nil
+  end
+end

data/spec/session_spec.rb

@@ -0,0 +1,45 @@
+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]
+  end
+
+  it "should be created for a Group" do
+    group = @eth.group 'Maycomb'
+    author = @eth.author 'Atticus'
+    session = group.create_session(author, 20)
+    session.valid_until.should == Time.now.to_i + 20 * 60
+  end
+
+  it "should be created for an Author" do
+    group = @eth.group 'Maycomb'
+    author = @eth.author 'Scout'
+    session = author.create_session(group, 15)
+    session.valid_until.should == Time.now.to_i + 15 * 60
+  end
+
+  it "should be found in a Group" do
+    group = @eth.group 'Maycomb'
+    author = @eth.author 'Atticus'
+    group.sessions.map(&:author_id).include?(author.id).should == true
+  end
+
+  it "shouldn be found in a Group" do
+    group = @eth.group 'Maycomb'
+    author = @eth.author 'Atticus'
+    author.sessions.map(&:group_id).include?(group.id).should == true
+  end
+
+  it "shouldn't be found in the wrong Group" do
+    group = @eth.group 'Other group'
+    author = @eth.author 'Scout'
+    group.sessions.map(&:author_id).include?(author.id).should == false
+  end
+
+  it "shouldn't be found in the wrong Group" do
+    group = @eth.group 'Other group'
+    author = @eth.author 'Scout'
+    author.sessions.map(&:group_id).include?(group.id).should == false
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+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'
+
+Rspec.configure do |c|
+  c.mock_with :rspec
+end
+
+# Load test config
+require 'yaml'
+TEST_CONFIG = YAML.load_file(File.dirname(__FILE__) + '/config.yml')

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: etherpad-lite
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jordan Hollinger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-30 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: etherpad-lite is a Ruby interface to Etherpad Lite's HTTP JSON API
+email: jordan@jordanhollinger.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+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/author.rb
+- lib/etherpad-lite/models/instance.rb
+- lib/etherpad-lite/models/pad.rb
+- lib/etherpad-lite/models/group.rb
+- lib/etherpad-lite/client.rb
+- 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
+- README.rdoc
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/jhollinger/etherpad-lite
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+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 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A Ruby client library for Etherpad Lite
+test_files: []
+