inifile 2.0.2 → 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1b35f40f3c6c004a85d1b6b43766951b49a301e9
+  data.tar.gz: 789bc7312e534942372b41591b2099bf80508b46
+SHA512:
+  metadata.gz: 2aa8846aa49b6557fd860f66557b78a9a02bea56d3f5bb2e7b8bec2577a2557eb172464a618dee4d32fe5dde70c8453cbe67f71a3c6da4528ea3ba40317afb70
+  data.tar.gz: 73e1a6df1802d34439e0ec2924ab84511b58190f64b13072d734bd90fee048224e35ce378c678d9b8a76805e5d51066fd00ab1d877dbc89fd7349b5885451551

data/.gitignore

@@ -15,3 +15,4 @@ announcement.txt
 coverage
 doc
 pkg
+vendor

data/README.md

@@ -135,6 +135,19 @@ sequences to appear literally in your value. For example:
 
     property = this is not a tab \\t character
 
+### Value Type Casting
+
+Some values will be type cast when parsed by the code. Those values are
+booleans, integers, floats, and empty strings are cast to `nil`.
+
+* ""  -->  nil
+* "42"  -->  42
+* "3.14159"  -->  3.14159
+* "true"  -->  true
+* "false"  -->  false
+* "normal string"  -->  "normal string"
+
+Pretty basic stuff.
 
 Install
 -------
@@ -150,6 +163,15 @@ To run the tests:
     $ rake
 
 
+Examples
+--------
+
+    require 'inifile'
+    myini = IniFile.load('mytest.ini')
+    myini.each_section do |section|
+      puts "I want #{myini[section]['somevar']} printed here!"
+    end
+
 Contributing
 ------------
 
@@ -171,7 +193,7 @@ License
 -------
 
 MIT License
-Copyright (c) 2006 - 2012
+Copyright (c) 2006 - 2014
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -20,5 +20,5 @@ Bones {
   version      IniFile::VERSION
 
   use_gmail
-  depend_on    'bones-git', :development => true
+  depend_on    'bones-git', "~> 1.3", :development => true
 }

data/inifile.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'inifile'
+
+Gem::Specification.new do |spec|
+  spec.name          = "inifile"
+  spec.version       = IniFile::VERSION
+  spec.authors       = ["Tim Pease"]
+  spec.email         = ["tim.pease@gmail.com"]
+  spec.summary       = %q{INI file reader and writer}
+  spec.description   = %q{INI file reader and writer}
+  spec.description   = %q{IniFile is a pure ruby gem that can read and write most INI file formats}
+  spec.homepage      = "https://rubygems.org/gems/inifile"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bones",      "~> 3.8"
+  spec.add_development_dependency "bones-git",  "~> 1.3"
+end

data/lib/inifile.rb

@@ -1,23 +1,20 @@
 #encoding: UTF-8
-require 'strscan'
 
 # 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 = '2.0.2'
+  VERSION = '3.0.0'
 
   # Public: Open an INI file and load the contents.
   #
-  # filename - The name of the fiel as a String
+  # 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 (Ruby 1.9)
-  #            :escape    - Boolean used to control character escaping
+  #            :encoding  - Encoding String for reading / writing
   #            :default   - The String name of the default global section
   #
   # Examples
@@ -28,8 +25,7 @@ class IniFile
   #   IniFile.load('does/not/exist.ini')
   #   #=> nil
   #
-  # Returns an IniFile intsnace or nil if the file could not be opened.
-  #
+  # 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))
@@ -38,57 +34,50 @@ class IniFile
   # Get and set the filename
   attr_accessor :filename
 
-  # Get and set the encoding (Ruby 1.9)
+  # Get and set the encoding
   attr_accessor :encoding
 
-  # Enable or disable character escaping
-  attr_accessor :escape
-
-  # Public: Create a new INI file from the given content String which
-  # contains the INI file lines. If the content are omitted, then the
-  # :filename option is used to read in the content of the INI file. If
-  # neither the content for a filename is provided then an empty INI file is
-  # created.
+  # 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.
   #
-  # content - The String containing the INI file contents
-  # 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 (Ruby 1.9)
-  #           :escape    - Boolean used to control character escaping
-  #           :default   - The String name of the default global section
-  #           :filename  - The filename as a String
+  # 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( "[global]\nfoo=bar" )
+  #   IniFile.new( :content => "[global]\nfoo=bar" )
   #   #=> an IniFile instance
   #
   #   IniFile.new( :filename => 'file.ini', :encoding => 'UTF-8' )
   #   #=> an IniFile instance
   #
-  #   IniFile.new( "[global]\nfoo=bar", :comment => '#' )
+  #   IniFile.new( :content => "[global]\nfoo=bar", :comment => '#' )
   #   #=> an IniFile instance
   #
-  def initialize( content = nil, opts = {} )
-    opts, content = content, nil if Hash === content
-
-    @content = content
-
+  def initialize( opts = {} )
     @comment  = opts.fetch(:comment, ';#')
     @param    = opts.fetch(:parameter, '=')
     @encoding = opts.fetch(:encoding, nil)
-    @escape   = opts.fetch(:escape, true)
     @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  then parse!
-    elsif @filename then read
+    if    content.is_a?(Hash) then merge!(content)
+    elsif content             then parse(content)
+    elsif @filename           then read
     end
   end
 
@@ -98,16 +87,13 @@ class IniFile
   #
   # opts - The default options Hash
   #        :filename - The filename as a String
-  #        :encoding - The encoding as a String (Ruby 1.9)
+  #        :encoding - The encoding as a String
   #
   # Returns this IniFile instance.
-  #
   def write( opts = {} )
     filename = opts.fetch(:filename, @filename)
     encoding = opts.fetch(:encoding, @encoding)
-    mode = (RUBY_VERSION >= '1.9' && encoding) ?
-         "w:#{encoding.to_s}" :
-         'w'
+    mode = encoding ? "w:#{encoding}" : "w"
 
     File.open(filename, mode) do |f|
       @ini.each do |section,hash|
@@ -129,31 +115,22 @@ class IniFile
   #
   # opts - The default options Hash
   #        :filename - The filename as a String
-  #        :encoding - The encoding as a String (Ruby 1.9)
+  #        :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 = (RUBY_VERSION >= '1.9' && encoding) ?
-           "r:#{encoding.to_s}" :
-           'r'
-    fd = File.open(filename, mode)
-    @content = fd.read
-
-    parse!
+    mode = encoding ? "r:#{encoding}" : "r"
+    File.open(filename, mode) { |fd| parse fd }
     self
-  ensure
-    fd.close if fd && !fd.closed?
   end
   alias :restore :read
 
   # Returns this IniFile converted to a String.
-  #
   def to_s
     s = []
     @ini.each do |section,hash|
@@ -165,7 +142,6 @@ class IniFile
   end
 
   # Returns this IniFile converted to a Hash.
-  #
   def to_h
     @ini.dup
   end
@@ -176,33 +152,50 @@ class IniFile
   # 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 over-ridable settings
+  # 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 "cannot merge contents from '#{other.class.name}'" end
+    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|
-      @ini[key].merge!(other[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] = other[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
@@ -212,7 +205,7 @@ class IniFile
   # 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.
+  #         be passed the current section and the parameter/value pair.
   #
   # Examples
   #
@@ -221,7 +214,6 @@ class IniFile
   #   end
   #
   # Returns this IniFile.
-  #
   def each
     return unless block_given?
     @ini.each do |section,hash|
@@ -244,7 +236,6 @@ class IniFile
   #   end
   #
   # Returns this IniFile.
-  #
   def each_section
     return unless block_given?
     @ini.each_key {|section| yield section}
@@ -256,7 +247,6 @@ class IniFile
   # section - The section name as a String.
   #
   # Returns the deleted section Hash.
-  #
   def delete_section( section )
     @ini.delete section.to_s
   end
@@ -272,7 +262,6 @@ class IniFile
   #   #=> global section Hash
   #
   # Returns the Hash of parameter/value pairs for this section.
-  #
   def []( section )
     return nil if section.nil?
     @ini[section.to_s]
@@ -289,7 +278,6 @@ class IniFile
   #   #=> { 'gritty' => 'yes' }
   #
   # Returns the value Hash.
-  #
   def []=( section, value )
     @ini[section.to_s] = value
   end
@@ -306,7 +294,6 @@ class IniFile
   #
   # Return a Hash containing only those sections that match the given regular
   # expression.
-  #
   def match( regex )
     @ini.dup.delete_if { |section, _| section !~ regex }
   end
@@ -316,13 +303,11 @@ class IniFile
   # 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
@@ -331,7 +316,6 @@ class IniFile
   # the object will raise an error.
   #
   # Returns this IniFile.
-  #
   def freeze
     super
     @ini.each_value {|h| h.freeze}
@@ -343,7 +327,6 @@ class IniFile
   # marking each as tainted.
   #
   # Returns this IniFile.
-  #
   def taint
     super
     @ini.each_value {|h| h.taint}
@@ -356,7 +339,6 @@ class IniFile
   # 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})
@@ -371,7 +353,6 @@ class IniFile
   # to the duplicate.
   #
   # Returns a new IniFile.
-  #
   def clone
     other = dup
     other.freeze if self.frozen?
@@ -385,7 +366,6 @@ class IniFile
   # 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
@@ -393,159 +373,255 @@ class IniFile
   end
   alias :== :eql?
 
-
-private
-
-  # Parse the ini file contents. This will clear any values currently stored
-  # in the ini hash.
+  # Escape special characters.
   #
-  def parse!
-    return unless @content
-
-    string = ''
-    property = ''
+  # 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
 
-    @ini.clear
-    @_line = nil
-    @_section = nil
+  # 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
 
-    scanner = StringScanner.new(@content)
-    until scanner.eos?
+  # 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
 
-      # keep track of the current line for error messages
-      @_line = scanner.check(%r/\A.*$/) if scanner.bol?
+    # Returns `true` if the current value starts with a leading double quote.
+    # Otherwise returns false.
+    def leading_quote?
+      value && value =~ %r/\A"/
+    end
 
-      # look for escaped special characters \# \" etc
-      if scanner.scan(%r/\\([\[\]#{@param}#{@comment}"])/)
-        string << scanner[1]
+    # 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
 
-      # look for quoted strings
-      elsif scanner.scan(%r/"/)
-        quote = scanner.scan_until(/(?:\A|[^\\])"/)
-        parse_error('Unmatched quote') if quote.nil?
+      # not currently processing a continuation line
+      else
+        case string
+        when @full_quote
+          self.value = $1
 
-        quote.chomp!('"')
-        string << quote
+        when @open_quote
+          self.value = $1
+          continuation = true
 
-      # look for comments, empty strings, end of lines
-      elsif scanner.skip(%r/\A\s*(?:[#{@comment}].*)?$/)
-        string << scanner.getch unless scanner.eos?
+        when @trailing_slash
+          self.value ?  self.value << $1 : self.value = $1
+          continuation = true
 
-        process_property(property, string)
+        when @normal_value
+          self.value ?  self.value << $1 : self.value = $1
 
-      # look for the separator between property name and value
-      elsif scanner.scan(%r/#{@param}/)
-        if property.empty?
-          property = string.strip
-          string.slice!(0, string.length)
         else
-          parse_error
+          error
         end
+      end
 
-      # look for the start of a new section
-      elsif scanner.scan(%r/\A\s*\[([^\]]+)\]/)
-        @_section = @ini[scanner[1]]
-
-      # otherwise scan and store characters till we hit the start of some
-      # special section like a quote, newline, comment, etc.
+      if continuation
+        self.value << $/ if leading_quote?
       else
-        tmp = scanner.scan_until(%r/([\n"#{@param}#{@comment}] | \z | \\[\[\]#{@param}#{@comment}"])/mx)
-        parse_error if tmp.nil?
-
-        len = scanner[1].length
-        tmp.slice!(tmp.length - len, len)
-
-        scanner.pos = scanner.pos - len
-        string << tmp
+        process_property
       end
+
+      continuation
     end
 
-    process_property(property, string)
-  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
 
-  # Store the property / value pair in the currently active section. This
-  # method checks for continuation of the value to the next line.
-  #
-  # property - The property name as a String.
-  # value    - The property value as a String.
-  #
-  # Returns nil.
-  #
-  def process_property( property, value )
-    value.chomp!
-    return if property.empty? and value.empty?
-    return if value.sub!(%r/\\\s*\z/, '')
+      continuation = false
 
-    property.strip!
-    value.strip!
+      @hash.clear
+      @line = nil
+      self.section = nil
 
-    parse_error if property.empty?
+      content.each_line do |line|
+        @line = line.chomp
 
-    current_section[property.dup] = unescape_value(value.dup)
+        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
 
-    property.slice!(0, property.length)
-    value.slice!(0, value.length)
+      # 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
+      nil
+    end
 
-  # Returns the current section Hash.
-  #
-  def current_section
-    @_section ||= @ini[@default]
-  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!
 
-  # 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 parse_error( msg = 'Could not parse line' )
-    raise Error, "#{msg}: #{@_line.inspect}"
-  end
+      self.value = $1 if value =~ %r/\A"(.*)(?<!\\)"\z/m
 
-  # 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 )
-    return value unless @escape
+      section[property] = typecast(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
+      self.property = nil
+      self.value = nil
+    end
 
-  # Escape special characters.
-  #
-  # value - The String value to escape.
-  #
-  # Returns the escaped value.
-  #
-  def escape_value( value )
-    return value unless @escape
+    # Returns the current section Hash.
+    def section
+      @section ||= @hash[@default]
+    end
 
-    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
+    # 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