jirarest2 0.0.4 → 0.0.5

data/lib/connect.rb

@@ -22,14 +22,12 @@ require 'jirarest2/result'
 require "pp"
 
 
-=begin
- An Connect object encasulates the connection to jira via REST. It takes an Credentials object and returns a Jirarest2::Result object or an exception if something went wrong.
-=end
+
+# A Connect object encasulates the connection to jira via REST. It takes an Credentials object and returns a Jirarest2::Result object or an exception if something went wrong.
 class Connect
   
-=begin
- Create an instance of Connect. It needs an Credentials object to be created.
-=end
+# Create an instance of Connect.
+# @param [Credentials] credentials
   def initialize(credentials)
     @pass = credentials.password
     @user = credentials.username
@@ -37,12 +35,12 @@ class Connect
   end
 
   
-=begin
- Execute the request
- * operation = one of Get, Post, Delete, Put
- * uritail = the last part of the REST URI
- * data = data to be sent.
-=end
+
+# Execute the request
+# @param [String, "Get", "Post", "Delete", "Put"] operation HTTP method:  GET, POST, DELETE, PUT
+# @param [String] uritail The last part of the REST URI
+# @param [Hash] data Data to be sent.
+# @return [Jirarest2::Result]
   def execute(operation,uritail,data)
     uri = nil
     uri = URI(@CONNECTURL+uritail)
@@ -85,9 +83,9 @@ class Connect
     return Jirarest2::Result.new(result)
   end # execute
 
-=begin
- Is the rest API really at the destination we think it is?
-=end
+
+# Is the rest API really at the destination we think it is?
+# @return [Boolean] 
   def check_uri
     begin 
       begin
@@ -98,9 +96,9 @@ class Connect
     end
   end
 
-=begin
- Try to be nice. Parse the URI and see if you can find a pattern to the problem
-=end
+# Try to be nice. Parse the URI and see if you can find a pattern to the problem
+# @param [String] url
+# @return [String] a fixed URL
   def heal_uri(url = @CONNECTURL)
     splitURI = URI.split(url) # [Scheme,Userinfo,Host,Port,Registry,Path,Opaque,Query,Fragment]
     splitURI[5].gsub!(/^(.*)2$/,'\12/')
@@ -115,12 +113,10 @@ class Connect
     end
     return url
   end
-end # class
 
-=begin
- try to fix the connecteurl of this instance 
-=end
-public
+
+# try to fix the connecturl of this instance 
+# @return [String,Jirarest2::CouldNotHealURIError] Fixed URL or Exception
  def heal_uri!
    if ! check_uri then
      @CONNECTURL = heal_uri(@CONNECTURL)
@@ -132,8 +128,9 @@ public
    end
  end
 
-=begin
+end # class
 
+=begin
 
 # Add a Key-Value for every search parameter you'd usually have.
 query={"jql"=>"project = MFTP", "startAt"=>0, "maxResults"=>4 }

data/lib/credentials.rb

@@ -18,9 +18,7 @@
 
 require "uri"
 
-=begin
- A Credentials object contains the data required to connect to a JIRA(tm) instance.
-=end
+# A Credentials object contains the data required to connect to a JIRA(tm) instance.
 class Credentials
 
   # username to use
@@ -30,10 +28,10 @@ class Credentials
   # url to connect to the JIRA(tm) instance
   attr_reader :connecturl
 
-=begin
-  Create an instance of Credentials. 
-  Requires username, password and the url for the JIRA(tm) instance. (The URL should stop after the port. There is no guarantee it would work if there is any path component given.) 
-=end
+
+  # @param [String] url URL to JIRA(tm) instance
+  # @param [String] username
+  # @param [String] password
   def initialize(url,username,password)
     @username = username
     @password = password
@@ -45,11 +43,8 @@ class Credentials
     end
   end
 
-=begin
- Setter for the URL.
-
- Throws an Jirarest2::NotAnURLError if the given String is not an URI.
-=end  
+  # Throws an Jirarest2::NotAnURLError if the given String is not an URI.
+  # @param [String] url
   def connecturl=(url)
     uri = URI(url)
     if uri.instance_of?(URI::HTTP) || uri.instance_of?(URI::HTTPS) then

data/lib/exceptions.rb

@@ -15,9 +15,7 @@
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-=begin
- Keep all the Exceptions in their own module
-=end
+# Keep all the Exceptions in their own module
 module Jirarest2
   ## connections.rb
 

data/lib/issue.rb

@@ -16,11 +16,10 @@
 #
 
 =begin
- An Issue object contains all the data of an issue
+# An Issue object contains all the data of an issue
 =end
 class Issue
-  
-  
+    
   # issue type of the issue 
   attr_reader :issuetype
   # project the issue belongs to
@@ -28,10 +27,9 @@ class Issue
   # The issue numer if we got it somehow
   attr_reader :issuekey
   
-=begin
-  New initialize method we take the project and the type we want to use and a connection
-  project Name of the project this issue is to live in
-=end
+  # @param [String] project Key of the JIRA(tm) project the issue belongs to
+  # @param [String] type Issuetype the issue belongs to
+  # @param [Connection] connection
   def initialize (project,type,connection)
     query = {:projectKeys => project, :issuetypeNames => type, :expand => "projects.issuetypes.fields" }
     answer = connection.execute("Get","issue/createmeta/",query)
@@ -41,10 +39,8 @@ class Issue
     raise Jirarest2::WrongIssuetypeException, type if @issuetype == ""
   end
 
-=begin
- It needs the hashed version of the json-snippet jira returns
- It produces an instance-variable @issuefields that can be 
-=end
+  # produces an instance-variable @issuefields that can be 
+  # @param [Hash] jhash Hashed version of the json-snippet JIRA(tm) returns
   def parse_json (jhash)
     @issuefields = Hash.new
     @project = ""
@@ -84,9 +80,8 @@ class Issue
     }
   end
   
-=begin
- Return the type of a field
-=end
+  # @param [String] field Name of the field
+  # @return [String] type of the Field 
   def fieldtype(field)
     # If the fieldname is wrong we want to tell this and stop execution (or maybe let the caller fix it)
     if @issuefields[field].nil? then
@@ -96,9 +91,7 @@ class Issue
     end
   end
   
-=begin
- Return all the fields that are required for this issuetype
-=end
+  # @return [Array] Names of required fields
   def get_requireds
     names = Array.new
     @issuefields.each {|key,value|
@@ -109,9 +102,7 @@ class Issue
     return names
   end
 
-=begin
- Return all the names of the fields
-=end
+  # @return [Array] Names of all fields
   def get_fieldnames
     names = Array.new
     @issuefields.each {|key,value|
@@ -120,26 +111,25 @@ class Issue
     return names
   end
 
-=begin
- return the id of a field name
-=end
+  # @param [String] name Name of a field
+  # @return [String] id of the field
   protected
   def get_id(name)
     return @issuefields["name"]["id"]
   end
 
 =begin
- return a hash that can be sent to jira
-Lets create a new issue
-query=
-{"fields"=>
-  { "project"=>{"key"=>"MFTP"}, 
-    "environment"=>"REST ye merry gentlemen.", 
-    "My own text"=>"Creating of an issue using project keys and issue type names using the REST API",
-    "issuetype"=> {"name"=>"My own type"}
-  }
-}
+# query=
+# {"fields"=>
+#  { "project"=>{"key"=>"MFTP"}, 
+#    "environment"=>"REST ye merry gentlemen.", 
+#    "My own text"=>"Creating of an issue using project keys and issue type names using the REST API",
+#    "issuetype"=> {"name"=>"My own type"}
+#  }
+# }
 =end
+
+  # @return [Hash] Hash to be sent to JIRA(tm) in a JSON representation
   public
   def jirahash
     h = Hash.new
@@ -161,9 +151,10 @@ query=
     return h
   end
 
-=begin
- checks if the value is allowed for this field
-=end
+  # check if the value is allowed for this field
+  # @param [String] key Name of the field
+  # @param [String] value Value to be checked
+  # @return [Boolean, Jirarest2::ValueNotAllowedException]
   protected
   def value_allowed?(key,value)
     if @issuefields[key]["allowedValues"].include?(value) 
@@ -174,11 +165,12 @@ query=
     end
   end
 
-=begin
- Special setter for fields that have a limited numer of allowed values.
 
- This setter might be included in set_field at a later date.
-=end
+  # Special setter for fields that have a limited numer of allowed values.
+  #
+  # This setter might be included in set_field at a later date.
+  # @param [String] key Name of the field
+  # @param [String] value Value to be checked
   def set_allowed_value(key,value)
     if @issuefields[key]["type"] == "array" && value.instance_of?(Array)  then
       array = Array.new
@@ -195,12 +187,10 @@ query=
     end
   end
 
-=begin
-  Setter fuer die Felder des Issues
-  :key is the name of the field
-  :value is is the value the field should get , this is either a String or an Array (don't know if numbers work too)
-TODO We are not yet able to work with "Cascading Select" fields ( "custom": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect")
-=end
+
+  # TODO We are not yet able to work with "Cascading Select" fields ( "custom": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect")
+  # @param [String] key Name of the field
+  # @param [String] value Value the field should be set to, this is either a String or an Array (don't know if numbers work too)
   public
   def set_field(key, value)
     if  @issuefields.include?(key) then
@@ -215,16 +205,15 @@ TODO We are not yet able to work with "Cascading Select" fields ( "custom": "com
     end
   end
 
-=begin
-  Get the value of a certain field
-=end
+  # @param [String] field Name of the field
+  # @return [String] value of the field
   def get_field(field)
     @issuefields[field]["value"]
   end
 
-=begin
- create a new ticket
-=end
+  # persitence of this Issue object instance
+  # @param [Connection] connection
+  # @return [Jirarest2::Result]
   def persist(connection)
     get_requireds.each { |fieldname| 
       if @issuefields[fieldname]["value"].nil? then
@@ -240,10 +229,11 @@ TODO We are not yet able to work with "Cascading Select" fields ( "custom": "com
   end
 
 
-=begin
- Set the watchers for this Ticket
- watchers has to be an Array
-=end
+
+  # Set the watchers for this Ticket
+  # @param [Connection] connection
+  # @param [Array] watchers Watchers to be added
+  # @return [Boolean] True if successfull for all
   def add_watchers(connection,watchers)
     success = false # Return whether we were successful with the watchers
     watch = Watcher.new(connection,@issuekey)
@@ -255,5 +245,3 @@ TODO We are not yet able to work with "Cascading Select" fields ( "custom": "com
 
   
 end # class
-
-

data/lib/jirarest2.rb

@@ -17,7 +17,7 @@
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-VERSION = "0.0.4"
+VERSION = "0.0.5"
 
 require_relative "connect"
 require_relative "issue"

data/lib/jirarest2/result.rb

@@ -20,36 +20,40 @@
 require 'json'
 
 module Jirarest2
-=begin
-  An object of Result contians the result of a Net::HTTP REST request that has a JSON-Body with easily accessable parameters.
-=end
-class Result
 
+#  An object of Result contians the result of a Net::HTTP REST request that has a JSON-Body with easily accessable parameters.
+  class Result
+    
   # The statuscode of the result
-  attr_reader :code
-  # header lines
-  attr_reader :header
-  # The original body of the result
-  attr_reader :body
-  # The JSON part of the body
-  attr_reader :result
-
-=begin
- Takes an Net::HTTPResponse object and builds itself from there
-=end
- def initialize(httpResponse)
-#   pp httpResponse
-#   pp httpResponse.body
-   @code = httpResponse.code
-   @header = httpResponse.to_hash
-   @body = httpResponse.body
-   if httpResponse.instance_of?(Net::HTTPNoContent) or httpResponse.body == "" then # If there is nothing in the body it would be hard to parse it.
-     @result = @body
-   else
-     @result = JSON.parse(@body)
-   end
- end # initialize
-
-end # class
-
+    attr_reader :code
+    # header lines
+    attr_reader :header
+    # The original body of the result
+    attr_reader :body
+    # The JSON part of the body
+    attr_reader :result
+    
+    
+    # Show the result in a more usable form
+    # @param [Net::HTTPResponse]
+    def initialize(httpResponse)
+      #   pp httpResponse
+      #   pp httpResponse.class
+      #   pp httpResponse.body
+      @code = httpResponse.code
+      @header = httpResponse.to_hash
+      @body = httpResponse.body
+      #pp @body
+      if httpResponse.instance_of?(Net::HTTPNoContent) or httpResponse.body == "" then # If there is nothing in the body it would be hard to parse it.
+        @result = @body
+      else
+        @result = JSON.parse(@body)
+      end
+      #pp @code
+      #pp @header
+      
+    end # initialize
+    
+  end # class
+  
 end # module

data/lib/madbitconfig.rb

@@ -0,0 +1,82 @@
+# Module to handle configuration files
+#    Copyright (C) 2012 Cyril Bitterich
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+# Module to handle configuration files
+module MadbitConfig
+
+
+# Special exception to make the point why we threw it around
+  class FileExistsException < IOError ; end
+  
+
+# Inspired by http://www.erickcantwell.com/2011/01/simple-configuration-file-reading-with-ruby/
+
+# reads a config-file and returns a hash
+# @param [String] configfile
+  def self.read_configfile(config_file)
+    config_file = File.expand_path(config_file)
+
+    unless File.exists?(config_file) then
+      raise IOError, "Unable to find config file \"#{config_file}\""
+    end
+    
+    regexp = Regexp.new(/\s+|"|\[|\]/)
+    
+    temp = Array.new
+    vars = Hash.new
+    
+    IO.foreach(config_file) { |line|
+      if line.match(/^\s*#/) #  don't care about lines starting with an # (even after whitespace)
+        next
+      elsif line.match(/^\s*$/) # no text, no content
+        next
+      else
+        # Right now I don't know what to use scan for. It will escape " nice enough. But once that is excaped the regexp doesn't work any longer.
+        #        temp[0],temp[1] = line.to_s.scan(/^.*$/).to_s.split("=")
+        temp[0],temp[1] = line.to_s.split("=")
+        temp.collect! { |val|
+          val.gsub(regexp, "")
+        }
+        vars[temp[0]] = temp[1]
+      end
+    }
+    return vars
+  end # read.configfile
+
+
+# write a configfile
+# @param [String] config_file Name (and path) of the config file
+# @param [Hash] configoptions Hash of "option" => "value" pairs
+# @param [Symbol] save Determines if an existing file is to be kept. :force replaces an existing file
+  def self.write_configfile(config_file, configoptions, save = :noforce)
+    config_file = File.expand_path(config_file) # Be save
+    
+    # First we make sure we don't overwrite a file if the save - flag is set.
+    if save != :force then
+      if File.exists?(config_file) then
+        raise FileExistsException, config_file
+      end
+    end
+    # write the file
+    File.open(config_file, File::CREAT|File::TRUNC|File::RDWR,0600) { |f|
+      configoptions.each { |option,value|
+        f.write( option + " = " + value  + "\n")
+      }
+    } # File
+  end # write_configfile
+
+end # module