honeybadger 2.0.0.beta.7 → 2.0.0.beta.8

data/lib/honeybadger/cli/heroku.rb

@@ -0,0 +1,148 @@
+$:.unshift(File.expand_path('../../../../vendor/inifile/lib', __FILE__))
+
+require 'honeybadger/cli/helpers'
+
+module Honeybadger
+  module CLI
+    class Heroku < Thor
+      include Helpers
+
+      class_option :app, aliases: :'-a', type: :string, default: nil, desc: 'Specify optional Heroku APP'
+
+      desc 'install_deploy_notification', 'Install Heroku deploy notifications addon'
+      option :api_key, aliases: :'-k', type: :string, desc: 'Api key of your Honeybadger application'
+      option :environment, aliases: :'-e', type: :string, desc: 'Environment of your Heroku application (i.e. "production", "staging")'
+      def install_deploy_notification
+        app       = options.has_key?('app') ? options['app'] : detect_heroku_app(false)
+        rails_env = options['environment'] || heroku_var('RAILS_ENV', app)
+        api_key   = options['api_key'] || heroku_var('HONEYBADGER_API_KEY', app)
+
+        unless api_key =~ /\S/
+          say("Unable to detect your API key from Heroku.", :red)
+          say('Have you configured multiple Heroku apps? Try using --app APP', :red) unless app
+          exit(1)
+        end
+
+        unless rails_env =~ /\S/
+          say("Unable to detect your environment from Heroku. Use --environment ENVIRONMENT.", :red)
+          say('Have you configured multiple Heroku apps? Try using --app APP', :red) unless app
+          exit(1)
+        end
+
+        command = %Q(heroku addons:add deployhooks:http --url="https://api.honeybadger.io/v1/deploys?deploy[environment]=#{rails_env}&deploy[local_username]={{user}}&deploy[revision]={{head}}&api_key=#{api_key}"#{app ? " --app #{app}" : ''})
+
+        say("Running: `#{command}`")
+        say(`#{command}`)
+      end
+
+      desc 'install API_KEY', 'Install Honeybadger on Heroku using API_KEY'
+      def install(api_key)
+        say("Installing Honeybadger #{VERSION} for Heroku")
+
+        load_rails(verbose: true)
+
+        ENV['HONEYBADGER_LOGGING_LEVEL']     = '2'
+        ENV['HONEYBADGER_LOGGING_TTY_LEVEL'] = '0'
+        ENV['HONEYBADGER_LOGGING_PATH']      = 'STDOUT'
+        ENV['HONEYBADGER_REPORT_DATA']       = 'true'
+
+        ENV['HONEYBADGER_API_KEY'] = api_key
+
+        app = options[:app] || detect_heroku_app(false)
+        say("Adding config HONEYBADGER_API_KEY=#{api_key} to Heroku.", :magenta)
+        unless write_heroku_env({'HONEYBADGER_API_KEY' => api_key}, app)
+          say('Unable to update heroku config. Do you need to specify an app name?', :red)
+          exit(1)
+        end
+
+        if env = heroku_var('RAILS_ENV', app, heroku_var('RACK_ENV', app))
+          say('Installing deploy notification addon', :magenta)
+          invoke :install_deploy_notification, [], { app: app, api_key: api_key, environment: env }
+        else
+          say('Skipping deploy notification installation: we were unable to determine the environment name from your Heroku app.', :yellow)
+          say("To install manually, try `honeybadger heroku install_deploy_notification#{app ? " -a #{app}" : ""} -k #{api_key} --environment ENVIRONMENT`", :yellow)
+        end
+
+        config = Config.new(rails_framework_opts)
+        Honeybadger.start(config) unless load_rails_env(verbose: true)
+        say('Sending test notice')
+        unless Agent.instance && send_test(false)
+          say("Honeybadger is installed, but failed to send a test notice. Try `HONEYBADGER_API_KEY=#{api_key} honeybadger test`.", :red)
+          exit(1)
+        end
+
+        say("Installation complete. Happy 'badgering!", :green)
+      end
+
+      private
+
+      # Public: Detects the Heroku app name from GIT.
+      #
+      # prompt_on_default - If a single remote is discoverd, should we prompt the
+      #                     user before returning it?
+      #
+      # Returns the String app name if detected, otherwise nil.
+      def detect_heroku_app(prompt_on_default = true)
+        apps, git_config = {}, File.join(Dir.pwd, '.git', 'config')
+        if File.exist?(git_config)
+          require 'inifile'
+          ini = IniFile.load(git_config)
+          ini.each_section do |section|
+            if match = section.match(/remote \"(?<remote>.+)\"/)
+              url = ini[section]['url']
+              if url_match = url.match(/heroku\.com:(?<app>.+)\.git$/)
+                apps[match[:remote]] = url_match[:app]
+              end
+            end
+          end
+
+          if apps.size == 1
+            if !prompt_on_default
+              apps.values.first
+            else
+              say "We detected a Heroku app named #{apps.values.first}. Do you want to load the config? (y/yes or n/no)"
+              if STDIN.gets.chomp =~ /(y|yes)/i
+                apps.values.first
+              end
+            end
+          elsif apps.size > 1
+            say "We detected the following Heroku apps:"
+            apps.each_with_index {|a,i| say "\s\s#{i+1}. #{a[1]}" }
+            say "\s\s#{apps.size+1}. Use default"
+            say "Please select an option (1-#{apps.size+1}):"
+            apps.values[STDIN.gets.chomp.to_i-1]
+          end
+        end
+      end
+
+      def heroku_var(var, app_name, default = nil)
+        app = app_name ? "--app #{app_name}" : ''
+        result = Bundler.with_clean_env { `heroku config:get #{var} #{app} 2> /dev/null`.strip }
+        result.split.find(lambda { default }) {|x| x =~ /\S/ }
+      end
+
+      def read_heroku_env(app = nil)
+        cmd = ['heroku config']
+        cmd << "--app #{app}" if app
+        output = Bundler.with_clean_env { `#{cmd.join("\s")}` }
+        return false unless $?.to_i == 0
+        Hash[output.scan(/(HONEYBADGER_[^:]+):\s*(\S.*)\s*$/)]
+      end
+
+      def set_env_from_heroku(app = nil)
+        return false unless env = read_heroku_env(app)
+        env.each_pair do |k,v|
+          ENV[k] ||= v
+        end
+      end
+
+      def write_heroku_env(env, app = nil)
+        cmd = ["heroku config:set"]
+        Hash(env).each_pair {|k,v| cmd << "#{k}=#{v}" }
+        cmd << "--app #{app}" if app
+        Bundler.with_clean_env { `#{cmd.join("\s")}` }
+        $?.to_i == 0
+      end
+    end
+  end
+end

data/lib/honeybadger/cli/main.rb

@@ -0,0 +1,179 @@
+require 'stringio'
+
+require 'honeybadger/cli/helpers'
+
+module Honeybadger
+  module CLI
+    class Main < Thor
+      include Helpers
+
+      class HoneybadgerTestingException < RuntimeError; end
+
+      NOT_BLANK = Regexp.new('\S').freeze
+
+      desc 'deploy', 'Notify Honeybadger of deployment'
+      option :environment, aliases: :'-e', type: :string, desc: 'Environment of the deploy (i.e. "production", "staging")'
+      option :revision, aliases: :'-s', type: :string, desc: 'The revision/sha that is being deployed'
+      option :repository, aliases: :'-r', type: :string, desc: 'The address of your repository'
+      option :user, aliases: :'-u', type: :string, default: ENV['USER'] || ENV['USERNAME'], desc: 'The local user who is deploying'
+      option :api_key, aliases: :'-k', type: :string, desc: 'Api key of your Honeybadger application'
+      def deploy
+        load_rails(verbose: true)
+
+        payload = Hash[[:environment, :revision, :repository, :user].map {|k| [k, options[k]] }]
+
+        say('Loading configuration')
+        config = Config.new(rails_framework_opts)
+        config.update(api_key: options[:api_key]) if options[:api_key] =~ NOT_BLANK
+
+        unless (payload[:environment] ||= config[:env]) =~ NOT_BLANK
+          say('Unable to determine environment. (see: `honeybadger help deploy`)', :red)
+          exit(1)
+        end
+
+        unless config.valid?
+          say("Invalid configuration: #{config.inspect}", :red)
+          exit(1)
+        end
+
+        response = config.backend.notify(:deploys, payload)
+        if response.success?
+          say("Deploy notification for #{payload[:environment]} complete.", :green)
+        else
+          say("Deploy notification failed: #{response.code}", :red)
+        end
+      rescue => e
+        say("An error occurred during deploy notification: #{e}\n\t#{e.backtrace.join("\n\t")}", :red)
+        exit(1)
+      end
+
+      desc 'config', 'List configuration options'
+      option :default, aliases: :'-d', type: :boolean, default: true, desc: 'Output default options'
+      def config
+        load_rails
+        config = Config.new(rails_framework_opts)
+        output_config(config.to_hash(options[:default]))
+      end
+
+      desc 'test', 'Output test/debug information'
+      option :dry_run, aliases: :'-d', type: :boolean, default: false, desc: 'Skip sending data to Honeybadger'
+      option :file, aliases: :'-f', type: :string, default: nil, desc: 'Write the output to FILE'
+      def test
+        if options[:file]
+          out = StringIO.new
+          $stdout = out
+
+          flush = Proc.new do
+            $stdout = STDOUT
+            File.open(options[:file], 'w+') do |f|
+              out.rewind
+              out.each_line {|l| f.write(l) }
+            end
+
+            say("Output written to #{options[:file]}", :green)
+          end
+
+          Agent.at_exit(&flush)
+
+          at_exit do
+            # If the agent couldn't be started, the callback should happen here
+            # instead.
+            flush.() unless Agent.running?
+          end
+        end
+
+        say("Detecting framework\n\n", :bold)
+        load_rails(verbose: true)
+
+        ENV['HONEYBADGER_LOGGING_LEVEL']     = '0'
+        ENV['HONEYBADGER_LOGGING_TTY_LEVEL'] = '0'
+        ENV['HONEYBADGER_LOGGING_PATH']      = 'STDOUT'
+        ENV['HONEYBADGER_DEBUG']             = 'true'
+        ENV['HONEYBADGER_REPORT_DATA']       = options[:dry_run] ? 'false' : 'true'
+
+        config = Config.new(rails_framework_opts)
+        say("\nConfiguration\n\n", :bold)
+        output_config(config.to_hash)
+
+        say("\nStarting Honeybadger\n\n", :bold)
+        Honeybadger.start(config) unless load_rails_env(verbose: true)
+
+        say("\nSending test notice\n\n", :bold)
+        send_test
+
+        say("\nRunning at exit hooks\n\n", :bold)
+      end
+
+      desc 'install API_KEY', 'Install Honeybadger into the current directory using API_KEY'
+      option :test, aliases: :'-t', type: :boolean, default: nil, desc: 'Send a test error'
+      def install(api_key)
+        say("Installing Honeybadger #{VERSION}")
+
+        load_rails(verbose: true)
+
+        ENV['HONEYBADGER_LOGGING_LEVEL']     = '2'
+        ENV['HONEYBADGER_LOGGING_TTY_LEVEL'] = '0'
+        ENV['HONEYBADGER_LOGGING_PATH']      = 'STDOUT'
+        ENV['HONEYBADGER_REPORT_DATA']       = 'true'
+
+        config = Config.new(rails_framework_opts)
+        config[:api_key] = api_key
+
+        if (path = config.config_path).exist?
+          say("You're already on Honeybadger, so you're all set.", :yellow)
+          skip_test = true if options[:test].nil? # Only if it wasn't specified.
+        else
+          say("Writing configuration to: #{path}", :yellow)
+
+          begin
+            config.write
+          rescue Config::ConfigError => e
+            error("Error: Unable to write configuration file:\n\t#{e}")
+            return
+          rescue StandardError => e
+            error("Error: Unable to write configuration file:\n\t#{e.class} -- #{e.message}\n\t#{e.backtrace.join("\n\t")}")
+            return
+          end
+        end
+
+        if !skip_test && (options[:test].nil? || options[:test])
+          Honeybadger.start(config) unless load_rails_env(verbose: true)
+          say('Sending test notice', :yellow)
+          unless Agent.instance && send_test(false)
+            say('Honeybadger is installed, but failed to send a test notice. Try `honeybadger test`.', :red)
+            exit(1)
+          end
+        end
+
+        say("Installation complete. Happy 'badgering!", :green)
+      end
+
+      desc 'heroku SUBCOMMAND ...ARGS', 'Manage Honeybadger on Heroku'
+      subcommand 'heroku', Heroku
+
+      private
+
+      def output_config(nested_hash, hierarchy = [])
+        nested_hash.each_pair do |key, value|
+          if value.kind_of?(Hash)
+            say(tab_indent(hierarchy.size) << "#{key}:")
+            output_config(value, hierarchy + [key])
+          else
+            dotted_key = (hierarchy + [key]).join('.').to_sym
+            say(tab_indent(hierarchy.size) << "#{key}:")
+            indent = tab_indent(hierarchy.size+1)
+            say(indent + "Description: #{Config::OPTIONS[dotted_key][:description]}")
+            say(indent + "Default: #{Config::OPTIONS[dotted_key][:default].inspect}")
+            say(indent + "Current: #{value.inspect}")
+          end
+        end
+      end
+
+      def tab_indent(number)
+        ''.tap do |s|
+          number.times { s << "\s\s" }
+        end
+      end
+    end
+  end
+end

data/lib/honeybadger/init/rails.rb

@@ -5,6 +5,10 @@ module Honeybadger
   module Init
     module Rails
       class Railtie < ::Rails::Railtie
+        rake_tasks do
+          load 'honeybadger/tasks.rb'
+        end
+
         initializer 'honeybadger.install' do
           config = Config.new(local_config)
           if Honeybadger.start(config)

data/lib/honeybadger/notice.rb

@@ -27,6 +27,9 @@ module Honeybadger
   # Internal: Empty String (used for equality comparisons and assignment)
   STRING_EMPTY = ''.freeze
 
+  # Internal: A Regexp which matches non-blank characters.
+  NOT_BLANK = /\S/.freeze
+
   # Internal: Matches lines beginning with ./
   RELATIVE_ROOT = Regexp.new('^\.\/').freeze
 
@@ -43,6 +46,12 @@ module Honeybadger
   class Notice
     extend Forwardable
 
+    # Internal: The String character used to split tag strings.
+    TAG_SEPERATOR = ','.freeze
+
+    # Internal: The Regexp used to strip invalid characters from individual tags.
+    TAG_SANITIZER = /[^\w]/.freeze
+
     # Public: The unique ID of this notice which can be used to reference the
     # error in Honeybadger.
     attr_reader :id
@@ -56,6 +65,9 @@ module Honeybadger
     # Public: Custom fingerprint for error, used to group similar errors together.
     attr_reader :fingerprint
 
+    # Public: Tags which will be applied to error.
+    attr_reader :tags
+
     # Public: The name of the class of error. (example: RuntimeError)
     attr_reader :error_class
 
@@ -143,6 +155,9 @@ module Honeybadger
       @request = OpenStruct.new(construct_request_hash(config.request, opts, @request_sanitizer, config.excluded_request_keys))
       @context = construct_context_hash(opts, @sanitizer)
 
+      @tags = construct_tags(opts[:tags])
+      @tags = construct_tags(context[:tags]) | @tags if context
+
       @stats = Util::Stats.all
 
       @local_variables = send_local_variables?(config) ? local_variables_from_exception(exception, config) : {}
@@ -163,7 +178,8 @@ module Honeybadger
           message: error_message,
           backtrace: backtrace,
           source: source,
-          fingerprint: fingerprint
+          fingerprint: fingerprint,
+          tags: tags
         },
         request: {
           url: url,
@@ -370,6 +386,18 @@ module Honeybadger
       end
     end
 
+    def construct_tags(tags)
+      ret = []
+      Array(tags).flatten.each do |val|
+        val.to_s.split(TAG_SEPERATOR).each do |tag|
+          tag.gsub!(TAG_SANITIZER, STRING_EMPTY)
+          ret << tag if tag =~ NOT_BLANK
+        end
+      end
+
+      ret
+    end
+
     # Internal: Fetch local variables from first frame of backtrace.
     #
     # exception - The Exception containing the bindings stack.

data/lib/honeybadger/tasks.rb

@@ -0,0 +1,22 @@
+namespace :honeybadger do
+  def warn_task_moved(old_name, new_cmd = "honeybadger help #{old_name}")
+    puts "This task was moved to the CLI in honeybadger 2.0. To learn more, run `#{new_cmd}`."
+  end
+
+  desc "Verify your gem installation by sending a test exception to the honeybadger service"
+  task :test do
+    warn_task_moved('test')
+  end
+
+  desc "Notify Honeybadger of a new deploy."
+  task :deploy do
+    warn_task_moved('deploy')
+  end
+
+  namespace :heroku do
+    desc "Install Heroku deploy notifications addon"
+    task :add_deploy_notification do
+      warn_task_moved('heroku:add_deploy_notification', 'honeybadger heroku help install_deploy_notification')
+    end
+  end
+end

data/lib/honeybadger/version.rb

@@ -1,4 +1,4 @@
 module Honeybadger
   # Public: The current String Honeybadger version.
-  VERSION = '2.0.0.beta.7'.freeze
+  VERSION = '2.0.0.beta.8'.freeze
 end

data/vendor/inifile/lib/inifile.rb

@@ -0,0 +1,628 @@
+#encoding: UTF-8
+
+# This class represents the INI file and can be used to parse, modify,
+# and write INI files.
+class IniFile
+  include Enumerable
+
+  class Error < StandardError; end
+  VERSION = '3.0.0'
+
+  # Public: Open an INI file and load the contents.
+  #
+  # filename - The name of the file as a String
+  # opts     - The Hash of options (default: {})
+  #            :comment   - String containing the comment character(s)
+  #            :parameter - String used to separate parameter and value
+  #            :encoding  - Encoding String for reading / writing
+  #            :default   - The String name of the default global section
+  #
+  # Examples
+  #
+  #   IniFile.load('file.ini')
+  #   #=> IniFile instance
+  #
+  #   IniFile.load('does/not/exist.ini')
+  #   #=> nil
+  #
+  # Returns an IniFile instance or nil if the file could not be opened.
+  def self.load( filename, opts = {} )
+    return unless File.file? filename
+    new(opts.merge(:filename => filename))
+  end
+
+  # Get and set the filename
+  attr_accessor :filename
+
+  # Get and set the encoding
+  attr_accessor :encoding
+
+  # Public: Create a new INI file from the given set of options. If :content
+  # is provided then it will be used to populate the INI file. If a :filename
+  # is provided then the contents of the file will be parsed and stored in the
+  # INI file. If neither the :content or :filename is provided then an empty
+  # INI file is created.
+  #
+  # opts - The Hash of options (default: {})
+  #   :content   - The String/Hash containing the INI contents
+  #   :comment   - String containing the comment character(s)
+  #   :parameter - String used to separate parameter and value
+  #   :encoding  - Encoding String for reading / writing
+  #   :default   - The String name of the default global section
+  #   :filename  - The filename as a String
+  #
+  # Examples
+  #
+  #   IniFile.new
+  #   #=> an empty IniFile instance
+  #
+  #   IniFile.new( :content => "[global]\nfoo=bar" )
+  #   #=> an IniFile instance
+  #
+  #   IniFile.new( :filename => 'file.ini', :encoding => 'UTF-8' )
+  #   #=> an IniFile instance
+  #
+  #   IniFile.new( :content => "[global]\nfoo=bar", :comment => '#' )
+  #   #=> an IniFile instance
+  #
+  def initialize( opts = {} )
+    @comment  = opts.fetch(:comment, ';#')
+    @param    = opts.fetch(:parameter, '=')
+    @encoding = opts.fetch(:encoding, nil)
+    @default  = opts.fetch(:default, 'global')
+    @filename = opts.fetch(:filename, nil)
+    content   = opts.fetch(:content, nil)
+
+    @ini = Hash.new {|h,k| h[k] = Hash.new}
+
+    if    content.is_a?(Hash) then merge!(content)
+    elsif content             then parse(content)
+    elsif @filename           then read
+    end
+  end
+
+  # Public: Write the contents of this IniFile to the file system. If left
+  # unspecified, the currently configured filename and encoding will be used.
+  # Otherwise the filename and encoding can be specified in the options hash.
+  #
+  # opts - The default options Hash
+  #        :filename - The filename as a String
+  #        :encoding - The encoding as a String
+  #
+  # Returns this IniFile instance.
+  def write( opts = {} )
+    filename = opts.fetch(:filename, @filename)
+    encoding = opts.fetch(:encoding, @encoding)
+    mode = encoding ? "w:#{encoding}" : "w"
+
+    File.open(filename, mode) do |f|
+      @ini.each do |section,hash|
+        f.puts "[#{section}]"
+        hash.each {|param,val| f.puts "#{param} #{@param} #{escape_value val}"}
+        f.puts
+      end
+    end
+
+    self
+  end
+  alias :save :write
+
+  # Public: Read the contents of the INI file from the file system and replace
+  # and set the state of this IniFile instance. If left unspecified the
+  # currently configured filename and encoding will be used when reading from
+  # the file system. Otherwise the filename and encoding can be specified in
+  # the options hash.
+  #
+  # opts - The default options Hash
+  #        :filename - The filename as a String
+  #        :encoding - The encoding as a String
+  #
+  # Returns this IniFile instance if the read was successful; nil is returned
+  # if the file could not be read.
+  def read( opts = {} )
+    filename = opts.fetch(:filename, @filename)
+    encoding = opts.fetch(:encoding, @encoding)
+    return unless File.file? filename
+
+    mode = encoding ? "r:#{encoding}" : "r"
+    File.open(filename, mode) { |fd| parse fd }
+    self
+  end
+  alias :restore :read
+
+  # Returns this IniFile converted to a String.
+  def to_s
+    s = []
+    @ini.each do |section,hash|
+      s << "[#{section}]"
+      hash.each {|param,val| s << "#{param} #{@param} #{escape_value val}"}
+      s << ""
+    end
+    s.join("\n")
+  end
+
+  # Returns this IniFile converted to a Hash.
+  def to_h
+    @ini.dup
+  end
+
+  # Public: Creates a copy of this inifile with the entries from the
+  # other_inifile merged into the copy.
+  #
+  # other - The other IniFile.
+  #
+  # Returns a new IniFile.
+  def merge( other )
+    self.dup.merge!(other)
+  end
+
+  # Public: Merges other_inifile into this inifile, overwriting existing
+  # entries. Useful for having a system inifile with user overridable settings
+  # elsewhere.
+  #
+  # other - The other IniFile.
+  #
+  # Returns this IniFile.
+  def merge!( other )
+    return self if other.nil?
+
+    my_keys = @ini.keys
+    other_keys = case other
+      when IniFile
+        other.instance_variable_get(:@ini).keys
+      when Hash
+        other.keys
+      else
+        raise Error, "cannot merge contents from '#{other.class.name}'"
+      end
+
+    (my_keys & other_keys).each do |key|
+      case other[key]
+      when Hash
+        @ini[key].merge!(other[key])
+      when nil
+        nil
+      else
+        raise Error, "cannot merge section #{key.inspect} - unsupported type: #{other[key].class.name}"
+      end
+    end
+
+    (other_keys - my_keys).each do |key|
+      @ini[key] = case other[key]
+        when Hash
+          other[key].dup
+        when nil
+          {}
+        else
+          raise Error, "cannot merge section #{key.inspect} - unsupported type: #{other[key].class.name}"
+        end
+    end
+
+    self
+  end
+
+  # Public: Yield each INI file section, parameter, and value in turn to the
+  # given block.
+  #
+  # block - The block that will be iterated by the each method. The block will
+  #         be passed the current section and the parameter/value pair.
+  #
+  # Examples
+  #
+  #   inifile.each do |section, parameter, value|
+  #     puts "#{parameter} = #{value} [in section - #{section}]"
+  #   end
+  #
+  # Returns this IniFile.
+  def each
+    return unless block_given?
+    @ini.each do |section,hash|
+      hash.each do |param,val|
+        yield section, param, val
+      end
+    end
+    self
+  end
+
+  # Public: Yield each section in turn to the given block.
+  #
+  # block - The block that will be iterated by the each method. The block will
+  #         be passed the current section as a Hash.
+  #
+  # Examples
+  #
+  #   inifile.each_section do |section|
+  #     puts section.inspect
+  #   end
+  #
+  # Returns this IniFile.
+  def each_section
+    return unless block_given?
+    @ini.each_key {|section| yield section}
+    self
+  end
+
+  # Public: Remove a section identified by name from the IniFile.
+  #
+  # section - The section name as a String.
+  #
+  # Returns the deleted section Hash.
+  def delete_section( section )
+    @ini.delete section.to_s
+  end
+
+  # Public: Get the section Hash by name. If the section does not exist, then
+  # it will be created.
+  #
+  # section - The section name as a String.
+  #
+  # Examples
+  #
+  #   inifile['global']
+  #   #=> global section Hash
+  #
+  # Returns the Hash of parameter/value pairs for this section.
+  def []( section )
+    return nil if section.nil?
+    @ini[section.to_s]
+  end
+
+  # Public: Set the section to a hash of parameter/value pairs.
+  #
+  # section - The section name as a String.
+  # value   - The Hash of parameter/value pairs.
+  #
+  # Examples
+  #
+  #   inifile['tenderloin'] = { 'gritty' => 'yes' }
+  #   #=> { 'gritty' => 'yes' }
+  #
+  # Returns the value Hash.
+  def []=( section, value )
+    @ini[section.to_s] = value
+  end
+
+  # Public: Create a Hash containing only those INI file sections whose names
+  # match the given regular expression.
+  #
+  # regex - The Regexp used to match section names.
+  #
+  # Examples
+  #
+  #   inifile.match(/^tree_/)
+  #   #=> Hash of matching sections
+  #
+  # Return a Hash containing only those sections that match the given regular
+  # expression.
+  def match( regex )
+    @ini.dup.delete_if { |section, _| section !~ regex }
+  end
+
+  # Public: Check to see if the IniFile contains the section.
+  #
+  # section - The section name as a String.
+  #
+  # Returns true if the section exists in the IniFile.
+  def has_section?( section )
+    @ini.has_key? section.to_s
+  end
+
+  # Returns an Array of section names contained in this IniFile.
+  def sections
+    @ini.keys
+  end
+
+  # Public: Freeze the state of this IniFile object. Any attempts to change
+  # the object will raise an error.
+  #
+  # Returns this IniFile.
+  def freeze
+    super
+    @ini.each_value {|h| h.freeze}
+    @ini.freeze
+    self
+  end
+
+  # Public: Mark this IniFile as tainted -- this will traverse each section
+  # marking each as tainted.
+  #
+  # Returns this IniFile.
+  def taint
+    super
+    @ini.each_value {|h| h.taint}
+    @ini.taint
+    self
+  end
+
+  # Public: Produces a duplicate of this IniFile. The duplicate is independent
+  # of the original -- i.e. the duplicate can be modified without changing the
+  # original. The tainted state of the original is copied to the duplicate.
+  #
+  # Returns a new IniFile.
+  def dup
+    other = super
+    other.instance_variable_set(:@ini, Hash.new {|h,k| h[k] = Hash.new})
+    @ini.each_pair {|s,h| other[s].merge! h}
+    other.taint if self.tainted?
+    other
+  end
+
+  # Public: Produces a duplicate of this IniFile. The duplicate is independent
+  # of the original -- i.e. the duplicate can be modified without changing the
+  # original. The tainted state and the frozen state of the original is copied
+  # to the duplicate.
+  #
+  # Returns a new IniFile.
+  def clone
+    other = dup
+    other.freeze if self.frozen?
+    other
+  end
+
+  # Public: Compare this IniFile to some other IniFile. For two INI files to
+  # be equivalent, they must have the same sections with the same parameter /
+  # value pairs in each section.
+  #
+  # other - The other IniFile.
+  #
+  # Returns true if the INI files are equivalent and false if they differ.
+  def eql?( other )
+    return true if equal? other
+    return false unless other.instance_of? self.class
+    @ini == other.instance_variable_get(:@ini)
+  end
+  alias :== :eql?
+
+  # Escape special characters.
+  #
+  # value - The String value to escape.
+  #
+  # Returns the escaped value.
+  def escape_value( value )
+    value = value.to_s.dup
+    value.gsub!(%r/\\([0nrt])/, '\\\\\1')
+    value.gsub!(%r/\n/, '\n')
+    value.gsub!(%r/\r/, '\r')
+    value.gsub!(%r/\t/, '\t')
+    value.gsub!(%r/\0/, '\0')
+    value
+  end
+
+  # Parse the given content and store the information in this IniFile
+  # instance. All data will be cleared out and replaced with the information
+  # read from the content.
+  #
+  # content - A String or a file descriptor (must respond to `each_line`)
+  #
+  # Returns this IniFile.
+  def parse( content )
+    parser = Parser.new(@ini, @param, @comment, @default)
+    parser.parse(content)
+    self
+  end
+
+  # The IniFile::Parser has the responsibility of reading the contents of an
+  # .ini file and storing that information into a ruby Hash. The object being
+  # parsed must respond to `each_line` - this includes Strings and any IO
+  # object.
+  class Parser
+
+    attr_writer :section
+    attr_accessor :property
+    attr_accessor :value
+
+    # Create a new IniFile::Parser that can be used to parse the contents of
+    # an .ini file.
+    #
+    # hash    - The Hash where parsed information will be stored
+    # param   - String used to separate parameter and value
+    # comment - String containing the comment character(s)
+    # default - The String name of the default global section
+    #
+    def initialize( hash, param, comment, default )
+      @hash = hash
+      @default = default
+
+      comment = comment.to_s.empty? ? "\\z" : "\\s*(?:[#{comment}].*)?\\z"
+
+      @section_regexp  = %r/\A\s*\[([^\]]+)\]#{comment}/
+      @ignore_regexp   = %r/\A#{comment}/
+      @property_regexp = %r/\A(.*?)(?<!\\)#{param}(.*)\z/
+
+      @open_quote      = %r/\A\s*(".*)\z/
+      @close_quote     = %r/\A(.*(?<!\\)")#{comment}/
+      @full_quote      = %r/\A\s*(".*(?<!\\)")#{comment}/
+      @trailing_slash  = %r/\A(.*)(?<!\\)\\#{comment}/
+      @normal_value    = %r/\A(.*?)#{comment}/
+    end
+
+    # Returns `true` if the current value starts with a leading double quote.
+    # Otherwise returns false.
+    def leading_quote?
+      value && value =~ %r/\A"/
+    end
+
+    # Given a string, attempt to parse out a value from that string. This
+    # value might be continued on the following line. So this method returns
+    # `true` if it is expecting more data.
+    #
+    # string - String to parse
+    #
+    # Returns `true` if the next line is also part of the current value.
+    # Returns `fase` if the string contained a complete value.
+    def parse_value( string )
+      continuation = false
+
+      # if our value starts with a double quote, then we are in a
+      # line continuation situation
+      if leading_quote?
+        # check for a closing quote at the end of the string
+        if string =~ @close_quote
+          value << $1
+
+        # otherwise just append the string to the value
+        else
+          value << string
+          continuation = true
+        end
+
+      # not currently processing a continuation line
+      else
+        case string
+        when @full_quote
+          self.value = $1
+
+        when @open_quote
+          self.value = $1
+          continuation = true
+
+        when @trailing_slash
+          self.value ?  self.value << $1 : self.value = $1
+          continuation = true
+
+        when @normal_value
+          self.value ?  self.value << $1 : self.value = $1
+
+        else
+          error
+        end
+      end
+
+      if continuation
+        self.value << $/ if leading_quote?
+      else
+        process_property
+      end
+
+      continuation
+    end
+
+    # Parse the ini file contents. This will clear any values currently stored
+    # in the ini hash.
+    #
+    # content - Any object that responds to `each_line`
+    #
+    # Returns nil.
+    def parse( content )
+      return unless content
+
+      continuation = false
+
+      @hash.clear
+      @line = nil
+      self.section = nil
+
+      content.each_line do |line|
+        @line = line.chomp
+
+        if continuation
+          continuation = parse_value @line
+        else
+          case @line
+          when @ignore_regexp
+            nil
+          when @section_regexp
+            self.section = @hash[$1]
+          when @property_regexp
+            self.property = $1.strip
+            error if property.empty?
+
+            continuation = parse_value $2
+          else
+            error
+          end
+        end
+      end
+
+      # check here if we have a dangling value ... usually means we have an
+      # unmatched open quote
+      if leading_quote?
+        error "Unmatched open quote"
+      elsif property && value
+        process_property
+      elsif value
+        error
+      end
+
+      nil
+    end
+
+    # Store the property/value pair in the currently active section. This
+    # method checks for continuation of the value to the next line.
+    #
+    # Returns nil.
+    def process_property
+      property.strip!
+      value.strip!
+
+      self.value = $1 if value =~ %r/\A"(.*)(?<!\\)"\z/m
+
+      section[property] = typecast(value)
+
+      self.property = nil
+      self.value = nil
+    end
+
+    # Returns the current section Hash.
+    def section
+      @section ||= @hash[@default]
+    end
+
+    # Raise a parse error using the given message and appending the current line
+    # being parsed.
+    #
+    # msg - The message String to use.
+    #
+    # Raises IniFile::Error
+    def error( msg = 'Could not parse line' )
+      raise Error, "#{msg}: #{@line.inspect}"
+    end
+
+    # Attempt to typecast the value string. We are looking for boolean values,
+    # integers, floats, and empty strings. Below is how each gets cast, but it
+    # is pretty logical and straightforward.
+    #
+    #  "true"  -->  true
+    #  "false" -->  false
+    #  ""      -->  nil
+    #  "42"    -->  42
+    #  "3.14"  -->  3.14
+    #  "foo"   -->  "foo"
+    #
+    # Returns the typecast value.
+    def typecast( value )
+      case value
+      when %r/\Atrue\z/i;  true
+      when %r/\Afalse\z/i; false
+      when %r/\A\s*\z/i;   nil
+      else
+        Integer(value) rescue \
+        Float(value)   rescue \
+        unescape_value(value)
+      end
+    end
+
+    # Unescape special characters found in the value string. This will convert
+    # escaped null, tab, carriage return, newline, and backslash into their
+    # literal equivalents.
+    #
+    # value - The String value to unescape.
+    #
+    # Returns the unescaped value.
+    def unescape_value( value )
+      value = value.to_s
+      value.gsub!(%r/\\[0nrt\\]/) { |char|
+        case char
+        when '\0';   "\0"
+        when '\n';   "\n"
+        when '\r';   "\r"
+        when '\t';   "\t"
+        when '\\\\'; "\\"
+        end
+      }
+      value
+    end
+  end
+
+end  # IniFile
+