trac4r 1.1.0 → 1.2.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+pkg
+coverage
+html
+api.yaml

data/LICENCE

@@ -0,0 +1,42 @@
+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.
+
+
+
+
+Copyright (c) 2008 Niklas E. Cathor <niklas@brueckenschlaeger.de>
+
+Hiermit wird unentgeltlich, jeder Person, die eine Kopie der Software und
+der zugeh�rigen Dokumentationen (die "Software") erh�lt, die Erlaubnis
+erteilt, uneingeschr�nkt zu benutzen, inklusive und ohne au�nahme, dem
+Recht, sie zu verwenden, kopieren, �ndern, fusionieren, verlegen, verbreiten, 
+unterlizenzieren und/oder zu verkaufen, und Personen, die diese Software
+erhalten, diese Rechte zu geben, unter den folgenden Bedingungen:
+
+Der obige Urheberrechtsvermerk und dieser Erlaubnisvermerk sind in alle
+Kopien oder Teilkopien der Software beizulegen.
+
+DIE SOFTWARE WIRD OHNE JEDE AUSDR�CKLICHE ODER IMPLIZIERTE GARANTIE BEREITGE-
+STELLT, EINSCHIESSLICH DER GARANTIE ZUR BENUTZUNG F�R DEN VORGESEHENEN ODER
+EINEM BESTIMMTEN ZWECK SOWIE JEGLICHER RECHTSVERLETZUNG, JEDOCH NICHT DARAUF
+BESCHR�NKT. IN KEINEM FALL SIND DIE AUTOREN ODER COPYRIGHTINHABER F�R
+JEGLICHEN SCHADEN ODER SONSTIGE ANSPRUCH HAFTBAR ZU MACHEN, OB INFOLGE DER
+ERF�LLUNG VON EINEM VERTRAG, EINEM DELIKT ODER ANDERS IM ZUSAMMENHANG MIT
+DER BENUTZUNG ODER SONSTIGE VERWENDUNG DER SOFTWARE ENTSTANDEN.

data/README.rdoc

@@ -2,6 +2,7 @@ trac4r: Ruby wrapper for the Trac XML-RPC API
 =============================================
 
 Author::   Niklas Cathor
+Author::   David Copeland
 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]
@@ -29,6 +30,21 @@ This wraps the Trac XML-RPC plugin.
     trac.tickets.list # get all tickets
     trac.tickets.get 2334 # Get ticket #2334
 
+=== Tickets
+
+Trac's backbone is tickets.  The Tickets class contains many useful methods, but can also run arbitrary queries against Trac using
+a more Rubyesque syntax:
+
+    # Gets all tickets in the "Web" component with a status of either "assigned"
+    # "accepted", or "new"
+    available_web_tickets = trac.tickets.query(:component => 'Web', :status => [:assigned,:accepted,:new])
+
+    # Ticktes that are not closed
+    unclosed_tickets = trac.tickets.query(:status => "!closed")
+
+    # This is a bit wierd, the "!" in the first element means "none of these values"
+    not_closed_nor_testing = trac.tickets.query(:status => ["!closed","test"])
+
 == More Info
 
 * {RDoc}[http://davetron5000.github.com/trac4r]

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rake/clean'
+require 'hanna/rdoctask'
+require 'rubygems'
+require 'rake/gempackagetask'
+
+$: << '../grancher/lib'
+begin
+  require 'grancher/task'
+  Grancher::Task.new do |g|
+    g.branch = 'gh-pages'
+    g.push_to = 'origin'
+    g.directory 'html'
+  end
+rescue LoadError
+  #puts "you may install the optional gem 'grancher'"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "trac4r"
+    s.executables = "trac"
+    s.summary = 'Ruby Client Library for Trac'
+    s.email = "davidcopeland@naildrivin5.com"
+    s.description = 'Basic ruby client library and command line interface for accessing Trac instances via its XML RPC API'
+    s.authors = ['Niklas Cathro','David Copeland']
+    s.add_dependency('rainbow', '>= 1.0.4')
+    s.add_dependency('gli', '>= 1.1.0')
+    s.has_rdoc = true
+    s.extra_rdoc_files = ['README.rdoc']
+    s.rdoc_options << '--title' << 'trac4r Trac Ruby Client' << '--main' << 'README.rdoc' << '-ri'
+    s.require_paths << 'lib'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install jeweler"
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc","lib/**/*.rb","bin/**/*")
+  rd.title = 'Ruby interface to Trac'
+end
+
+task :default => :test
+
+task :publish_rdoc => [:rdoc,:publish]

data/VERSION

@@ -0,0 +1 @@
+1.2.1

data/bin/trac

@@ -0,0 +1,289 @@
+#!/usr/bin/ruby
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'rubygems'
+require 'gli'
+require 'trac4r'
+require 'rainbow'
+require 'cgi'
+
+include GLI
+
+OPENER_DEFAULT = RUBY_PLATFORM =~ /darwin/ ? 'open' : nil
+begin
+  # TODO: Figure out a better way to do this
+  cols = `stty -a | grep "columns;" | head -1`.split(/;/)
+  COLUMNS_DEFAULT = cols[2].gsub(' columns','')
+rescue
+  COLUMNS_DEFAULT = nil
+end
+
+config_file '.trac4r'
+
+desc 'Command to use to open URLs'
+default_value OPENER_DEFAULT
+flag [:o,:open]
+
+desc 'URL to trac'
+flag [:url]
+
+desc 'Your username'
+flag [:u,:user]
+
+desc 'Your password'
+flag [:p,:password]
+
+desc 'Do not format output'
+long_desc 'By default, the output is formatted fo readability in the terminal.  By disabling this, the output is more "machine readable" and parsable by other scripts'
+switch [:noformat]
+
+desc 'number of columns for formatting'
+default_value COLUMNS_DEFAULT
+flag [:cols]
+
+desc 'Open the ticket or wiki page'
+arg_name 'the id of the ticket or name of wiki page'
+command :open do |c|
+  c.action do |global_options,options,args|
+    raise "You must supply a ticket ID or WikiName" if args.empty?
+    id = args[0]
+    if id =~ /^\d+$/
+      system "#{global_options[:o]} #{$url}/ticket/#{id}"
+    else
+      system "#{global_options[:o]} #{$url}/wiki/#{args.map{ |x| x[0..0].upcase + x[1..-1]}.join('')}"
+    end
+  end
+end
+
+desc 'Go to the new ticket web interface'
+long_desc 'Navigates your browser to the web interface, initialized with the values you provide, but does not actually create the ticket'
+arg_name 'summary for the ticket'
+command [:newticket] do |c|
+  c.desc 'component'
+  c.flag [:c,:component]
+
+  c.desc 'type'
+  c.flag [:t,:type]
+
+  c.desc 'priority'
+  c.flag [:p,:priority]
+
+  c.action do |global_options,options,args|
+    query_params = {}
+    query_params['priority'] = options[:p] if options[:p]
+    query_params['component'] = options[:c] if options[:c]
+    query_params['type'] = options[:t] if options[:t]
+    query_params['summary'] = args.join(' ')
+    query_string = ''
+    query_params.each do |key,value|
+      query_string += key
+      query_string += '='
+      query_string += CGI.escape(value)
+      query_string += '&'
+    end
+
+    url = $url.gsub(/\/xmlrpc/,'') + '/newticket?' + query_string
+    system "#{global_options[:o]} \"#{url}\""
+  end
+end
+
+FORMATTING = {
+  'id' => { :color => :green, :size => 6 },
+  'status' => { :color => :cyan, :size => 9 },
+  'owner' => { :size => 17 },
+  'component' => { :size => 10, :color => :magenta },
+  'milestone' => { :size => 28, :color => :cyan },
+}
+desc 'Lists tickets'
+arg_name 'ticket ids (blank for all)'
+command [:tickets,:ls] do |c|
+  c.desc 'Show tickets accepted'
+  c.switch [:a,:accepted]
+
+  c.desc 'Component'
+  c.flag [:c,:component]
+
+  c.desc 'Show full description'
+  c.switch [:l,:description]
+
+  c.desc 'Arbitrary query (flags are included, too)'
+  c.flag [:q,:query]
+
+  c.desc 'Owner ("ME" for the -u user)'
+  c.flag [:o,:owner]
+
+  c.desc 'Columns to show'
+  c.long_desc 'comma-delimited list of the column names from the tickets to show in the output'
+  c.flag [:columns]
+
+  c.action do |global_options,options,args|
+    opts = {}
+
+    if options[:q]
+      raise "bad query" if options[:q] =~ /\}/
+      opts = instance_eval('{' + options[:q] + '}')
+    else
+      opts[:owner] = options[:o]
+      opts[:owner] = global_options[:u] if options[:o] == "ME"
+      if options[:a]
+        opts[:status] = :accepted
+      else
+        opts[:status] = ["!closed","testing"]
+      end
+      opts[:component] = options[:c] if options[:c]
+    end
+    ids = args
+    ids = $trac.tickets.query(opts) if ids.empty?
+    tickets = ids.map{ |id| $trac.tickets.get(id) } 
+    tickets.sort{ |a,b| a.summary.downcase <=> b.summary.downcase }.each do |ticket|
+      if global_options[:noformat]
+        puts [ticket.id,ticket.status,ticket.owner,ticket.summary].join("\t")
+      else
+        columns = options[:columns]
+        columns = 'id,status,owner,summary' if !columns
+        columns = columns.split(/,/)
+        printf_string = ""
+        padding = 0
+        args = []
+        columns.each do |col|
+          if col != 'summary'
+            size = FORMATTING[col] && FORMATTING[col][:size]
+            size = 10 if !size
+            padding += size == "" ? 3 : (size.to_i + 3)
+            size += 9 if size && FORMATTING[col] && FORMATTING[col][:color]
+            printf_string += "%#{size}s - "
+            if FORMATTING[col] && FORMATTING[col][:color]
+              args << ticket.send(col.to_sym).to_s.color(FORMATTING[col][:color])
+            else
+              args << ticket.send(col.to_sym).to_s
+            end
+          end
+        end
+        printf_string.gsub!(/ - $/,'')
+        if columns.include? 'summary'
+          args << wrap(ticket.summary,padding+1,global_options[:cols])
+          printf_string += " - %s"
+        end
+        printf("#{printf_string}\n",*args)
+      end
+      if (options[:l])
+        description = ticket.description
+        if !global_options[:noformat]
+          description = bold(description)
+          description = italic(description)
+          description = code(description)
+        end
+        puts 
+        puts "#{description}"
+        puts "----"
+      end
+    end
+  end
+end
+
+# Not sure about this
+def wrap(string,indent,cols)
+  cols_left = cols.to_i - indent
+  raise "Your terminal is too small for formatting" if (cols_left < 5)
+  return_me = ""
+  line = ""
+  prev_word = ""
+  string.split(/\s/).each do |word|
+    if line.length <= cols_left
+      line += " #{word}" if line != ""
+      line += "#{word}" if line == ""
+      prev_word = word
+    else
+      line.gsub!(/#{prev_word}$/,'')
+      return_me += line.underline + "\n"
+      indent.times { return_me +=  " " }
+      line = prev_word
+    end
+  end
+  if (line.length > cols_left)
+    line.gsub!(/#{prev_word}$/,'')
+    return_me += line.underline + "\n"
+    indent.times { return_me +=  " " }
+    line = prev_word
+  end
+  return_me += line.underline
+  return_me.gsub(/^\s/,'')
+end
+
+def bold(string)
+  desc = string.split("'''")
+  description = ""
+  bold = false
+  desc.each do |part|
+    description << part.bright.foreground(:cyan) if bold
+    description << part.reset if !bold
+    bold = !bold
+  end
+  description
+end
+
+def italic(string)
+  desc = string.split("''")
+  description = ""
+  bold = false
+  desc.each do |part|
+    description << part.italic.foreground(:magenta) if bold
+    description << part.reset if !bold
+    bold = !bold
+  end
+  description
+end
+
+def code(string)
+  desc = string.split("`")
+  description = ""
+  bold = false
+  desc.each do |part|
+    description << part.bright.foreground(:green) if bold
+    description << part.reset if !bold
+    bold = !bold
+  end
+  in_code = false
+  coded = ''
+  description.split(/\n/).each do |line|
+    ignore = false
+    if line =~ /^\{\{\{\s*$/
+      in_code = true
+      ignore = true
+    elsif line =~ /^\}\}\}/
+      in_code = false
+      ignore = true
+    end
+    if !ignore
+      if in_code
+        coded += line.bright.foreground(:green)
+      else
+        coded += line
+      end
+    end
+    coded += "\n"
+  end
+  coded
+end
+
+pre do |global,command,options,args|
+  if command.nil? || command.name == :help
+    # not creating a trac instance
+  else
+    $url = global[:url]
+    raise "You must specify a URL" if $url.nil?
+    $trac = Trac.new($url,global[:u],global[:p])
+  end
+  true
+end
+
+post do |global,command,options,args|
+  # Post logic here
+end
+
+on_error do |exception|
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
+
+GLI.run(ARGV)

data/lib/trac4r/error.rb

@@ -8,22 +8,28 @@ module Trac
     # [+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|
+    # [+exception+] the exception that was caught
+    def initialize(http_error,host,port,path,method,args,exception)
+      if (http_error =~ /HTTP-Error: /)
+        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)
+      else
+        @http_message = http_error
       end
-      @http_status,@http_message = http_error.split(/\s+/,2)
       @host = host
       @port = port
       @path = path
       @method = method
       @args = args
+      @exception = exception
     end
 
     # Gives a more useful message for common problems
@@ -32,8 +38,10 @@ module Trac
         "Couldn't find Trac API at #{url}, check your configuration"
       elsif @http_status == '401'
         "Your username/password didn't authenticate, check your configuration"
+      elsif @http_status
+        "#{@http_message} (#{@http_status}) when trying URL #{url} and method #{@method}(#{@args.join('.')})"
       else
-        "#{@http_message} (#{@http_status}) when trying URL http://#{@host}:#{@port}#{@path} and method #{@command}(#{@args.join('.')})"
+        "#{@http_message} when trying URL #{url} and method #{@method}(#{@args.join('.')})"
       end
     end
 

data/lib/trac4r/query.rb

@@ -50,11 +50,7 @@ module Trac
       begin
         return @connection.call(command,*args)
       rescue => e
-        if e.message =~ /HTTP-Error/
-          raise TracException.new(e.message,@host,@port,@path,command,args)
-        else
-          raise
-        end
+        raise TracException.new(e.message,@host,@port,@path,command,args,e)
       end
     end
   end

data/lib/trac4r/ticket.rb

@@ -36,10 +36,17 @@ module Trac
     # we return its value.  e.g. if our tickets have a custom field
     # called +work_units+, then +some_ticket.work_units+ will
     # retrieve that value.  This currently only allows retrieval and
-    # not updating the value.
+    # not updating the value.  Also note that you can retrieve a custom
+    # field using "!" and this will silently return nil if the instance
+    # variable didn't exist.  This is useful if some tickets just don't
+    # have the custom field, but you don't wish to check for it
     def method_missing(sym,*args)
+      method = sym.to_s
+      method = method[0..-2] if method =~ /!$/
       if args.size == 0 && instance_variables.include?("@" + sym.to_s)
         instance_eval("@" + sym.to_s)
+      elsif method != sym.to_s
+        nil
       else
         super.method_missing(sym,args)
       end

data/lib/trac4r/tickets.rb

@@ -34,15 +34,25 @@ module Trac
     #   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
+      include_closed = true
+      include_closed = options[:include_closed] if !options[:include_closed].nil?
+      tickets = query(:status => "!closed")
+      tickets += query(:status => "closed") if include_closed
       return tickets
     end
-    
+
+    # Run an arbitrary ticket query
+    # [+args+] a hash of options, each should use a symbol or string
+    # as the key and a symbol/string or array of symbols/strings as the value.  If the
+    # value starts with a +!+, it will be treated as a not equal.
+    # Multiple values mean "or", as in any value may match
+    def query(args)
+      @trac.query("ticket.query",args_to_trac_args(args))
+    end
+
     # like `list', but only gets closed tickets
     def list_closed
-      @trac.query("ticket.query","status=closed")
+      query(:status => "closed")
     end
   
     # returns all tickets (not just the ids) in a hash
@@ -155,5 +165,17 @@ module Trac
       end
       return @settings
     end
+
+    private 
+
+    def args_to_trac_args(args)
+      trac_args = []
+      args.each do |key,value|
+        value = [value].flatten.map{ |x| x.to_s }.join('|')
+        trac_args << key.to_s + (value =~ /^!/ ? "!=#{value[1..-1]}" : "=#{value}")
+      end
+      trac_args.join('&')
+    end
+    
   end
 end

data/lib/trac4r/wiki.rb

@@ -44,6 +44,11 @@ module Trac
       @trac.query('wiki.getPageHTML',name)
     end
     
+    # returns a whole page in HTML
+    def get_info name
+      @trac.query('wiki.getPageInfo',name)
+    end
+    
     # returns a whole page in raw format
     def get_raw name
       @trac.query('wiki.getPage',name)

data/lib/trac4r.rb

@@ -64,13 +64,19 @@ module Trac
     def initialize url,user,pass
       @user = user
       @pass = pass
-      if url.split('/').last != 'xmlrpc'
-        url = url+'/xmlrpc'
+      @url = url
+      @url.gsub!(/\/$/,'')
+      if @url.split('/').last != 'xmlrpc'
+        @url = url+'/xmlrpc'
       end
-       @connection = Query.new(url,user,pass)
+      @connection = Query.new(@url,@user,@pass)
       @wiki = Wiki.new(@connection)
       @tickets = Tickets.new(@connection)
     end
+
+    def query(command,*args)
+      @connection.query(command,*args)
+    end
     
     def api_version
       @connection.query("system.getAPIVersion")

metadata

@@ -1,40 +1,66 @@
 --- !ruby/object:Gem::Specification 
 name: trac4r
 version: !ruby/object:Gem::Version 
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors: 
 - Niklas Cathro
+- David Copeland
 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: []
-
+date: 2010-01-03 00:00:00 -05:00
+default_executable: trac
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rainbow
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: gli
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.0
+    version: 
+description: Basic ruby client library and command line interface for accessing Trac instances via its XML RPC API
+email: davidcopeland@naildrivin5.com
+executables: 
+- trac
 extensions: []
 
 extra_rdoc_files: 
 - README.rdoc
 files: 
+- .gitignore
+- LICENCE
+- README.rdoc
+- Rakefile
+- VERSION
+- bin/trac
+- lib/trac4r.rb
 - 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/
+homepage: 
 licenses: []
 
 post_install_message: 
 rdoc_options: 
+- --charset=UTF-8
 - --title
 - trac4r Trac Ruby Client
 - --main
@@ -43,6 +69,7 @@ rdoc_options:
 require_paths: 
 - lib
 - lib
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
@@ -57,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   version: 
 requirements: []
 
-rubyforge_project: trac4r
+rubyforge_project: 
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3