trac4r 1.0.0

data/README.rdoc

@@ -0,0 +1,35 @@
+trac4r: Ruby wrapper for the Trac XML-RPC API
+=============================================
+
+Author::   Niklas Cathor
+License:: See LICENSE in source distribution
+
+For more information on the Trac XML-RPC see the {plugin's page on trac-hacks.com}[http://trac-hacks.org/wiki/XmlRpcPlugin#UsingfromRuby]
+
+Thanks to the original author, Niklas Cathor, who has done most of the work.
+
+== Install
+
+    # Only if you haven't set up gemcutter yet
+    sudo gem install gemcutter
+    sudo gem tumble
+
+    # Once Gemcutter is setup
+    sudo gem install trac4r
+
+== Overview
+
+This wraps the Trac XML-RPC plugin.
+
+    require 'rubygems'
+    require 'trac4r'
+
+    # Note that you need to point to the XMLRPC root and not the root of the trac web interface
+    trac = Trac.new("http://www.example.com/trac/project/xmlrpc","username","password")
+    trac.tickets.list # get all tickets
+    trac.tickets.get 2334 # Get ticket #2334
+
+== More Info
+
+* {RDoc}[http://davetron5000.github.com/trac4r]
+* {Source}[http://www.github.com/davetron5000/trac4r]

data/lib/trac4r/error.rb

@@ -0,0 +1,44 @@
+module Trac
+  class TracException < Exception
+    # Creates new TracException
+    # 
+    # [+http_error+] the error message, possibly mulit-line
+    # [+host+] host on which we are connecting to Trac
+    # [+port+] port we're using
+    # [+path+] the path to the Trac API
+    # [+method+] the XML RPC method being called
+    # [+args+] the args (as an array) that were sent with the call
+    def initialize(http_error,host,port,path,method,args)
+      http_error = http_error.sub 'HTTP-Error: ',''
+      if http_error =~ /\n/
+        http_error.split(/\n/).each do |line|
+          if line =~ /^\d\d\d/
+            http_error = line
+            break
+          end
+        end
+      end
+      @http_status,@http_message = http_error.split(/\s+/,2)
+      @host = host
+      @port = port
+      @path = path
+      @method = method
+      @args = args
+    end
+
+    # Gives a more useful message for common problems
+    def message
+      if @http_status == '404'
+        "Couldn't find Trac API at #{url}, check your configuration"
+      elsif @http_status == '401'
+        "Your username/password didn't authenticate, check your configuration"
+      else
+        "#{@http_message} (#{@http_status}) when trying URL http://#{@host}:#{@port}#{@path} and method #{@command}(#{@args.join('.')})"
+      end
+    end
+
+    def url
+      "http://#{@host}:#{@port}#{@path}"
+    end
+  end
+end

data/lib/trac4r/query.rb

@@ -0,0 +1,62 @@
+=begin
+Copyright (c) 2008 Niklas E. Cathor <niklas@brueckenschlaeger.de>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+DON'T USE IT IF YOU'RE AN ASSHOLE!
+=end
+
+require 'xmlrpc/client'
+
+module Trac
+  class Query
+    def initialize url,user,pass
+      if user && pass
+        url = url.sub 'xmlrpc','login/xmlrpc'
+      end
+      uri = URI.parse(url)
+      use_ssl = (uri.scheme == 'https') ? true : false
+      @host = uri.host
+      @path = uri.path
+      @port = uri.port
+      @connection = XMLRPC::Client.new(@host,
+                                       @path,
+                                       @port,
+                                       nil,
+                                       nil,
+                                       user,
+                                       pass,
+                                       use_ssl,
+                                       nil)
+    end
+    
+    def query command, *args
+      begin
+        return @connection.call(command,*args)
+      rescue => e
+        if e.message =~ /HTTP-Error/
+          errorcode = e.message.sub 'HTTP-Error: ',''
+          raise TracException.new(errorcode,@host,@port,@path,command,args)
+        else
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/trac4r/ticket.rb

@@ -0,0 +1,45 @@
+module Trac
+  # This class represents a ticket as it is retrieved from the database
+  class Ticket
+    attr_accessor(:id,          # Integer
+                  :severity,    # String
+                  :milestone,   # String
+                  :status,      # String
+                  :type,        # String
+                  :priority,    # String
+                  :version,     # String
+                  :reporter,    # String
+                  :owner,       # String
+                  :cc,          # String
+                  :summary,     # String
+                  :description, # String
+                  :keywords,    # String
+                  :created_at,  # XMLRPC::DateTime
+                  :updated_at)  # XMLRPC::DateTime
+    # returns a new ticket
+    def initialize id=0
+      @id = id
+      @severity=@milestone=@status=@type=@priority=@version=@reporter=@owner= @cc= @summary=@description=@keywords=""
+    end
+    
+    # checks if all attributes are set
+    def check
+      instance_variables.each do |v|
+        return false if instance_variable_get(v.to_sym).nil?
+      end
+      return true
+    end
+    
+    # loads a ticket from the XMLRPC response
+    def self.load params
+      ticket = self.new params[0]
+      ticket.created_at = params[1]
+      ticket.updated_at = params[2]
+      attributes = params[3]
+      attributes.each do |key,value|
+        ticket.instance_variable_set("@#{key}".to_sym,value)
+      end
+      return ticket
+    end
+  end
+end

data/lib/trac4r/tickets.rb

@@ -0,0 +1,159 @@
+=begin
+Copyright (c) 2008 Niklas E. Cathor <niklas@brueckenschlaeger.de>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+DON'T USE IT IF YOU'RE AN ASSHOLE!
+=end
+
+module Trac
+  class Tickets
+    def initialize trac
+      @trac = trac
+    end
+    
+    # returns a list of all tickets (the ids), by performing two
+    # queries, one for closed tickets, one for opened. use
+    #   list :include_closed => false
+    # to only get open tickets.
+    def list options={ }
+      include_closed = options[:include_closed] || true
+      tickets = @trac.query("ticket.query","status!=closed")
+      tickets += @trac.query("ticket.query","status=closed") if include_closed
+      return tickets
+    end
+    
+    # like `list', but only gets closed tickets
+    def list_closed
+      @trac.query("ticket.query","status=closed")
+    end
+  
+    # returns all tickets (not just the ids) in a hash
+    # warning: to avoid heavy traffic load the results are cached
+    # and will only be updated after 5 minutes. use
+    #   get_all :cached_results => false
+    # to avoid this.
+    # other options:
+    #   :include_closed - see Tickets#list for a description
+    def get_all options={ }
+      include_closed = options[:include_closed] || true
+      cached_results = options[:cached_results] || true
+      if(cached_results == true &&
+         @cache_last_update &&
+         @cache_last_update > Time.now - 300)
+        return @cache
+      end
+      tickets = { }
+      list(:include_closed => include_closed).each do |ticket|
+        tickets[ticket] = get ticket
+      end
+      @cache = tickets
+      @cache_last_update = Time.now
+      return tickets
+    end
+    
+    # fetch a ticket. Returns instance of Trac::Ticket
+    def get id
+      Ticket.load @trac.query("ticket.get",id)
+    end
+    
+    # create a new ticket returning the ticket id
+    def create summary,description,attributes={ },notify=false
+      @trac.query("ticket.create",summary,description,attributes,notify)
+    end
+    
+    # update ticket returning the ticket in the same orm as ticket.get
+    def update id,comment,attributes={ },notify=false
+      attr = {}
+      attributes.each_pair do |key, value|
+        unless(value.nil? || value.size == 0 || value.empty?)
+          attr[key] = value
+        end
+      end
+      @trac.query("ticket.update",id,comment,attr,notify)
+    end
+    
+    # delete ticket by id
+    def delete id
+      @trac.query("ticket.delete",id)
+    end
+    
+    # return the changelog as a list of tuples of the form (time,author,
+    # field,oldvalue,newvalue,permanent). While the other tuples elements
+    # are quite self-explanatory, the permanent flag is used to distinguish
+    # collateral changes that are not yet immutable (like attachments, 
+    # currently).
+    def changelog ticket_id,w=0
+      @trac.query("ticket.changeLog",ticket_id,w)
+    end
+    
+    # returns a list of ids of tickets that have changed since `time'
+    def changes time
+      @trac.query("ticket.getRecentChanges",time)
+    end
+    
+    # returns a list of attachments for the given ticket
+    def attachments ticket_id
+      @trac.query("ticket.listAttachments",ticket_id)
+    end
+    
+    # returns the content of an attachment
+    def get_attachment ticket_id,filename
+      @trac.query("ticket.getAttachment",ticket_id,filename)
+    end
+    
+    # adds an attachment to a ticket
+    def put_attachment ticket_id,filename,description,data,replace=true
+      @trac.query("ticket.putAttachment",ticket_id,filename,description,data,replace)
+    end
+    
+    # deletes given attachment
+    def delete_attachment ticket_id,filename
+      @trac.query("ticket.deleteAttachment",ticket_id,filename)
+    end
+    
+    # returns the actions that can be performed on the ticket
+    def actions ticket_id
+      @trac.query("ticket.getAvailableActions",ticket_id)
+    end
+    
+    
+    # returns all settings (possible values for status, version,
+    # priority, resolution, component, type, severity or milestone)
+    # as a hash in the form: { :status => ["assigned","closed",...], ... }
+    # this method only gets the settings once per session. To update
+    # them please refer to Tickets#get_settings
+    def settings
+      @settings || get_settings
+    end
+    
+    
+    # returns the settings in the same form as Tickets#settings, but
+    # refreshes them every time we call it.
+    def get_settings
+      @settings = { }
+      ['status','version','priority','resolution',
+       'component','type','severity','milestone'].each do |setting|
+        @settings[setting.to_sym] = @trac.query("ticket.#{setting}.getAll")
+      end
+      return @settings
+    end
+  end
+end

data/lib/trac4r/wiki.rb

@@ -0,0 +1,86 @@
+=begin
+Copyright (c) 2008 Niklas E. Cathor <niklas@brueckenschlaeger.de>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+DON'T USE IT IF YOU'RE AN ASSHOLE!
+=end
+
+module Trac
+  class Wiki
+    def initialize trac
+      @trac = trac
+    end
+    
+    # returns a list of all pages
+    def list
+      @trac.query('wiki.getAllPages')
+    end
+    
+    # convert a raw page to html (e.g. for preview)
+    def raw_to_html content
+      @trac.query('wiki.wikiToHtml',content)
+    end
+    
+    # returns a whole page in HTML
+    def get_html name
+      @trac.query('wiki.getPageHTML',name)
+    end
+    
+    # returns a whole page in raw format
+    def get_raw name
+      @trac.query('wiki.getPage',name)
+    end    
+    
+    # sends a page. if the page doesn't exist yet it is created
+    # otherwise it will be overwritten with the new content.
+    def put name,content,attributes={ }
+      @trac.query('wiki.putPage',name,content,attributes)
+    end
+    
+    # deletes page with given name, returning true on success.
+    def delete name
+      @trac.query('wiki.deletePage',name)
+    end
+    
+    # returns a list of all attachments of a page
+    def attachments page
+      @trac.query("wiki.listAttachments",page)
+    end
+    
+    # returns the content of an attachment
+    def get_attachment path
+      @trac.query("wiki.getAttachment",path)
+    end
+    
+    # uploads given `data' as an attachment to given `page'.
+    # returns true on success.
+    # unlike the XMLRPC-Call this method defaults `replace'
+    # to false as we don't want to destroy anything.
+    def put_attachment page,filename,description,data,replace=false
+      @trac.query("wiki.putAttachmentEx",page,filename,description,data,replace)
+    end
+    
+    # deletes attachment with given `path'
+    def delete_attachment path
+      @trac.query("wiki.deleteAttachment",path)
+    end
+  end
+end

data/lib/trac4r.rb

@@ -0,0 +1,79 @@
+=begin
+Copyright (c) 2008 Niklas E. Cathor <niklas@brueckenschlaeger.de>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+DON'T USE IT IF YOU'RE AN ASSHOLE!
+=end
+
+filedir = File.dirname(__FILE__)
+
+require "trac4r/query"
+require "trac4r/tickets"
+require "trac4r/ticket"
+require "trac4r/wiki"
+require "trac4r/error"
+
+
+# This module wraps the XMLRPC interface of
+# trac (http://trac.edgewall.org/) into a ruby library.
+# You can now easily access trac from any ruby
+# application without having to handle all the 
+# (trivial) XMLRPC calls.
+#
+# Example (receive list of opened tickets):
+#   require 'trac4r/trac'
+#   trac = Trac.new "http://dev.example.com/trac/my_awesome_project"
+#   trac.tickets.list :include_closed => false #=> [7,9,3,5,14,...]
+#
+# Receive one single ticket
+#   ticket = trac.tickets.get 9 #=> #<Trac::Ticket:0xb76de9b4 ... >
+#   ticket.summary #=> 'foo'
+#   ticket.description #=> 'bar'
+# See documentation for Trac::Ticket for what methods you can call on ticket.
+#
+# Create a new ticket
+#   trac.tickets.create "summary", "description", :type => 'defect', :version => '1.0', :milestone => 'bug free' #=> 10
+# summary and description are required, the rest is optional. It can be one of the following:
+# :severity, :milestone, :status, :type, :priority, :version, :reporter, :owner, :cc, :keywords
+# 
+module Trac
+  # returns a new instance of Trac::Base
+  def self.new url, user=nil,pass=nil
+    Base.new url,user,pass
+  end
+  
+  class Base
+    attr_reader :wiki, :tickets, :user, :pass
+    def initialize url,user,pass
+      @user = user
+      @pass = pass
+      if url.split('/').last != 'xmlrpc'
+        url = url+'/xmlrpc'
+      end
+       @connection = Query.new(url,user,pass)
+      @wiki = Wiki.new(@connection)
+      @tickets = Tickets.new(@connection)
+    end
+    
+    def api_version
+      @connection.query("system.getAPIVersion")
+    end
+  end  
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: trac4r
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Niklas Cathro
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-20 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: Basic ruby client library for accessing Trac instances via its XML RPC API
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/trac4r/error.rb
+- lib/trac4r/query.rb
+- lib/trac4r/ticket.rb
+- lib/trac4r/tickets.rb
+- lib/trac4r/wiki.rb
+- lib/trac4r.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/csexton/trac4r/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- trac4r Trac Ruby Client
+- --main
+- README.rdoc
+- -ri
+require_paths: 
+- lib
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: trac4r
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby Client Library for Trac
+test_files: []
+