inifile 1.1.0 → 2.0.0

data/History.txt

@@ -1,3 +1,13 @@
+== 2.0.0 / 2012-08-29
+
+Major Enhancements
+  - Can now initialize from Strings [issue #9]
+  - Quoted multi-line values are supported
+  - Comments can appear at the end of a line
+Enhancements
+  - TomDoc documentation
+  - Parity between read/write methods
+
 == 1.1.0 / 2012-02-28
 
 Enhancements

data/README.md

@@ -87,17 +87,42 @@ the earlier section.
 ### Comments
 
 The comment character can be either a semicolon *;* or a number sign *#*. The
-comment character must be the first non-whitespace character on the line. This
-means it is perfectly valid to include a comment character inside a **value**
-or event a property **name** (although this is not recommended). For this
-reason, comments cannot be placed on the end of a line after a name/value
-pair.
+comment character can appear anywhere on a line including at the end of a
+name/value pair declaration. If you wish to use a comment character in your
+value then you will need to either escape the character or put the value in
+double quotations.
+
+    [section1]
+    var1 = foo  # a comment
+    var2 = "foo # this is not a comment"
+    var3 = foo \# this is not a comment either
+
+### Multi-Line Values
+
+Values can be continued onto multiple lines in two separate ways. Putting a
+slash at the end of a line will continue the value declaration to the next
+line. When parsing, the trailing slash will be consumed and **will not**
+appear in the resulting value. Comments can appear to the right of the
+trailing slash.
+
+    var1 = this is a \  # these comments will
+    multiline value     # be ignored by the parser
+
+In the above example the resulting value for `var1` will be `this is a
+multiline value`. If you want to preserve newline characters in the value then
+quotations should be used.
+
+    var2 = "this is a
+    multiline value"
+
+The resulting value for `var2` will be `this is a\nmultiline value`.
 
 ### Escape Characters
 
 Several escape characters are supported within the **value** for a property.
-Most notably, a backslash *\* at the end of a line will continue the value
-onto the next line. When parsed, a literal newline will appear in the value.
+These escape sequences will be applied to quoted and unquoted values alike.
+You can enable or disable escaping by setting the **escape** flag to true or
+false when creating an IniFile instance.
 
 * \0 -- null character
 * \n -- newline character
@@ -108,7 +133,7 @@ onto the next line. When parsed, a literal newline will appear in the value.
 The backslash escape sequence is only needed if you want one of the escape
 sequences to appear literally in your value. For example:
 
-    property=this is not a tab \\t character
+    property = this is not a tab \\t character
 
 
 Install

data/a.rb

@@ -0,0 +1,125 @@
+require 'strscan'
+require 'pp'
+
+@content = <<CONTENT
+[section_one]
+one = 1
+two = 2
+
+[section_two]  # inline section comment 
+three =         3
+multi = multiline \\ # inline multiline comment
+support
+quote = "quoted # strings are the best!"
+
+; comments should be ignored
+[section three]
+four   =4
+five=5
+six =6
+"[foobar]" = 7
+
+[section_four]
+   [section_five]
+ seven and eight= 7 & 8
+CONTENT
+
+@comment = ';#'
+@param = '='
+@default = 'global'
+
+@ini = Hash.new {|h,k| h[k] = Hash.new}
+
+def parse
+
+  string = ''
+  property = ''
+
+  @ini.clear
+  @_line = nil
+  @_section = nil
+
+  scanner = StringScanner.new(@content)
+  until scanner.eos?
+
+    # keep track of the current line for error messages
+    if scanner.bol?
+      @_line = scanner.check(%r/\A.*$/) if scanner.bol?
+      puts "[line] #@_line"
+    end
+
+    # look for escaped special characters \# \" etc
+    if scanner.scan(%r/\\([\[\]#{@param}#{@comment}"])/)
+      string << scanner[1]
+
+    # look for quoted strings
+    elsif scanner.scan(%r/"/)
+      quote = scanner.scan_until(/(?:\A|[^\\])"/)
+      parse_error('Unmatched quote') if quote.nil?
+
+      quote.chomp!('"')
+      string << quote
+
+    # look for comments, empty strings, end of lines
+    elsif scanner.skip(%r/\A\s*(?:[#{@comment}].*)?$/)
+      string << scanner.getch unless scanner.eos?
+
+      process_property(property, string)
+
+    # look for the separator between property name and value
+    elsif scanner.scan(%r/#{@param}/)
+      if property.empty?
+        property = string.strip
+        string.clear
+      else
+        parse_error
+      end
+
+    # look for the start of a new section
+    elsif scanner.scan(%r/\A\s*\[([^\]]+)\]/)
+      @_section = @ini[scanner[1]]
+
+    # store the next character and loop again
+    else
+      tmp = scanner.scan_until(%r/([\n"#{@param}#{@comment}]|\\[\[\]#{@param}#{@comment}"])/m)
+      len = scanner[1].length
+      tmp.slice!(tmp.length - len, len)
+
+      scanner.pos = scanner.pos - len
+      string << tmp
+    end
+  end
+
+  process_property(property, string)
+end
+
+def process_property(property, value)
+  value.chomp!
+  return if property.empty? and value.empty?
+  return if value.sub!(%r/\\\s*\z/, '')
+
+  property.strip!
+  value.strip!
+
+  parse_error if property.empty?
+
+  current_section[property.dup] = value.dup
+
+  property.clear
+  value.clear
+
+  nil
+end
+
+def current_section
+  @_section ||= @ini[@default]
+end
+
+def parse_error( msg = 'Could not parse line' )
+  raise "#{msg}: #{@_line.inspect}"
+end
+
+parse
+
+puts '='*72
+pp @ini

data/lib/inifile.rb

@@ -1,143 +1,193 @@
-#
+#encoding: UTF-8
+require 'strscan'
+
 # This class represents the INI file and can be used to parse, modify,
 # and write INI files.
 #
-
-#encoding: UTF-8
-
 class IniFile
-
-  # Inifile is enumerable.
   include Enumerable
 
-  # :stopdoc:
   class Error < StandardError; end
-  VERSION = '1.1.0'
-  # :startdoc:
+  VERSION = '2.0.0'
 
+  # Public: Open an INI file and load the contents.
+  #
+  # filename - The name of the fiel 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
+  #            :default   - The String name of the default global section
   #
-  # call-seq:
-  #    IniFile.load( filename )
-  #    IniFile.load( filename, options )
+  # Examples
   #
-  # Open the given _filename_ and load the contents of the INI file.
-  # The following _options_ can be passed to this method:
+  #   IniFile.load('file.ini')
+  #   #=> IniFile instance
   #
-  #    :comment => ';'       The line comment character(s)
-  #    :parameter => '='     The parameter / value separator
-  #    :encoding => nil      The encoding used for read/write (RUBY 1.9)
-  #    :escape => true       Whether or not to escape values when reading/writing
-  #    :default => 'global'  Default global section name
+  #   IniFile.load('does/not/exist.ini')
+  #   #=> nil
+  #
+  # Returns an IniFile intsnace or nil if the file could not be opened.
   #
   def self.load( filename, opts = {} )
-    new(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 (Ruby 1.9)
+  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.
+  #
+  # 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
+  #
+  # Examples
+  #
+  #   IniFile.new
+  #   #=> an empty IniFile instance
   #
-  # call-seq:
-  #    IniFile.new( filename )
-  #    IniFile.new( filename, options )
+  #   IniFile.new( "[global]\nfoo=bar" )
+  #   #=> an IniFile instance
   #
-  # Create a new INI file using the given _filename_. If _filename_
-  # exists and is a regular file, then its contents will be parsed.
-  # The following _options_ can be passed to this method:
+  #   IniFile.new( :filename => 'file.ini', :encoding => 'UTF-8' )
+  #   #=> an IniFile instance
   #
-  #    :comment => ';'       The line comment character(s)
-  #    :parameter => '='     The parameter / value separator
-  #    :encoding => nil      The encoding used for read/write (RUBY 1.9)
-  #    :escape => true       Whether or not to escape values when reading/writing
-  #    :default => 'global'  Default global section name
+  #   IniFile.new( "[global]\nfoo=bar", :comment => '#' )
+  #   #=> an IniFile instance
   #
-  def initialize( filename, opts = {} )
-    @fn = filename
-    @comment = opts.fetch(:comment, ';#')
-    @param = opts.fetch(:parameter, '=')
+  def initialize( content = nil, opts = {} )
+    opts, content = content, nil if Hash === content
+
+    @content = content
+
+    @comment  = opts.fetch(:comment, ';#')
+    @param    = opts.fetch(:parameter, '=')
     @encoding = opts.fetch(:encoding, nil)
-    @escape = opts.fetch(:escape, true)
-    @default = opts.fetch(:default, 'global')
-    @ini = Hash.new {|h,k| h[k] = Hash.new}
+    @escape   = opts.fetch(:escape, true)
+    @default  = opts.fetch(:default, 'global')
+    @filename = opts.fetch(:filename, nil)
 
-    @rgxp_comment = %r/\A\s*\z|\A\s*[#{@comment}]/
-    @rgxp_section = %r/\A\s*\[([^\]]+)\]/
-    @rgxp_param   = %r/[^\\]#{@param}/
+    @ini = Hash.new {|h,k| h[k] = Hash.new}
 
-    parse
+    if    @content  then parse!
+    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.
   #
-  # call-seq:
-  #    write
-  #    write( filename )
+  # opts - The default options Hash
+  #        :filename - The filename as a String
+  #        :encoding - The encoding as a String (Ruby 1.9)
   #
-  # Write the INI file contents to the file system. The given _filename_
-  # will be used to write the file. If _filename_ is not given, then the
-  # named used when constructing this object will be used.
-  # The following _options_ can be passed to this method:
+  # Returns this IniFile instance.
   #
-  #    :encoding => nil     The encoding used for writing (RUBY 1.9)
-  #
-  def write( filename = nil, opts={} )
-    @fn = filename unless filename.nil?
-
-    encoding = opts[:encoding] || @encoding
-    mode = (RUBY_VERSION >= '1.9' && @encoding) ?
+  def write( opts = {} )
+    filename = opts.fetch(:filename, @filename)
+    encoding = opts.fetch(:encoding, @encoding)
+    mode = (RUBY_VERSION >= '1.9' && encoding) ?
          "w:#{encoding.to_s}" :
          'w'
 
-    File.open(@fn, mode) do |f|
+    File.open(filename, mode) do |f|
       @ini.each do |section,hash|
         f.puts "[#{section}]"
-        hash.each {|param,val| f.puts "#{param} #{@param} #{escape val}"}
+        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.
   #
-  # call-seq:
-  #   to_s
+  # opts - The default options Hash
+  #        :filename - The filename as a String
+  #        :encoding - The encoding as a String (Ruby 1.9)
   #
-  # Convert IniFile to text format.
+  # 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!
+    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|
       s << "[#{section}]"
-      hash.each {|param,val| s << "#{param} #{@param} #{escape val}"}
+      hash.each {|param,val| s << "#{param} #{@param} #{escape_value val}"}
       s << ""
     end
     s.join("\n")
   end
 
-  #
-  # call-seq:
-  #   to_h
-  #
-  # Convert IniFile to hash format.
+  # 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.
   #
-  # call-seq:
-  #   merge( other_inifile )
+  # other - The other IniFile.
   #
-  # Returns a copy of this inifile with the entries from the other_inifile
-  # merged into the copy.
+  # 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
+  # elsewhere.
   #
-  # call-seq:
-  #   merge!( other_inifile )
+  # other - The other IniFile.
   #
-  # Merges other_inifile into this inifile, overwriting existing entries.
-  # Useful for having a system inifile with user overridable settings elsewhere.
+  # Returns this IniFile.
   #
   def merge!( other )
     my_keys = @ini.keys
@@ -158,12 +208,19 @@ class IniFile
     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.
   #
-  # call-seq:
-  #    each {|section, parameter, value| block}
+  # Examples
   #
-  # Yield each _section_, _parameter_, _value_ in turn to the given
-  # _block_. The method returns immediately if no block is supplied.
+  #   inifile.each do |section, parameter, value|
+  #     puts "#{parameter} = #{value} [in section - #{section}]"
+  #   end
+  #
+  # Returns this IniFile.
   #
   def each
     return unless block_given?
@@ -175,12 +232,18 @@ class IniFile
     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.
   #
-  # call-seq:
-  #    each_section {|section| block}
+  # Examples
   #
-  # Yield each _section_ in turn to the given _block_. The method returns
-  # immediately if no block is supplied.
+  #   inifile.each_section do |section|
+  #     puts section.inspect
+  #   end
+  #
+  # Returns this IniFile.
   #
   def each_section
     return unless block_given?
@@ -188,77 +251,86 @@ class IniFile
     self
   end
 
+  # Public: Remove a section identified by name from the IniFile.
   #
-  # call-seq:
-  #    delete_section( section )
+  # section - The section name as a String.
   #
-  # Deletes the named _section_ from the INI file. Returns the
-  # parameter / value pairs if the section exists in the INI file. Otherwise,
-  # returns +nil+.
+  # 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
   #
-  # call-seq:
-  #    ini_file[section]
+  #   inifile['global']
+  #   #=> global section Hash
   #
-  # Get the hash of parameter/value pairs for the given _section_. If the
-  # _section_ hash does not exist it will be created.
+  # 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
   #
-  # call-seq:
-  #    ini_file[section] = hash
+  #   inifile['tenderloin'] = { 'gritty' => 'yes' }
+  #   #=> { 'gritty' => 'yes' }
   #
-  # Set the hash of parameter/value pairs for the given _section_.
+  # 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.
   #
-  # call-seq:
-  #    ini_file.match( /section/ )    #=> hash
+  # regex - The Regexp used to match section names.
   #
-  # Return a hash containing only those sections that match the given regular
+  # 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.
   #
-  # call-seq:
-  #    has_section?( section )
+  # section - The section name as a String.
   #
-  # Returns +true+ if the named _section_ exists in the INI file.
+  # Returns true if the section exists in the IniFile.
   #
   def has_section?( section )
     @ini.has_key? section.to_s
   end
 
-  #
-  # call-seq:
-  #    sections
-  #
-  # Returns an array of the section names.
+  # 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.
   #
-  # call-seq:
-  #    freeze
-  #
-  # Freeze the state of the +IniFile+ object. Any attempts to change the
-  # object will raise an error.
+  # Returns this IniFile.
   #
   def freeze
     super
@@ -267,12 +339,10 @@ class IniFile
     self
   end
 
+  # Public: Mark this IniFile as tainted -- this will traverse each section
+  # marking each as tainted.
   #
-  # call-seq:
-  #    taint
-  #
-  # Marks the INI file as tainted -- this will traverse each section marking
-  # each section as tainted as well.
+  # Returns this IniFile.
   #
   def taint
     super
@@ -281,14 +351,12 @@ class IniFile
     self
   end
 
-  #
-  # call-seq:
-  #    dup
-  #
-  # Produces a duplicate of this INI file. The duplicate is independent of the
-  # original -- i.e. the duplicate can be modified without changing the
+  # 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})
@@ -297,28 +365,26 @@ class IniFile
     other
   end
 
-  #
-  # call-seq:
-  #    clone
-  #
-  # Produces a duplicate of this INI file. The duplicate is independent of the
-  # original -- i.e. the duplicate can be modified without changing the
+  # 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.
   #
-  # call-seq:
-  #    eql?( other )
+  # other - The other IniFile.
   #
-  # Returns +true+ if the _other_ object is equivalent to this INI file. For
-  # two INI files to be equivalent, they must have the same sections with  the
-  # same parameter / value pairs in each section.
+  # Returns true if the INI files are equivalent and false if they differ.
   #
   def eql?( other )
     return true if equal? other
@@ -327,105 +393,126 @@ class IniFile
   end
   alias :== :eql?
 
-  #
-  # call-seq:
-  #   restore
-  #
-  # Restore data from the ini file. If the state of this object has been
-  # changed but not yet saved, this will effectively undo the changes.
-  #
-  def restore
-    parse
-  end
 
 private
 
-  # Parse the ini file contents.
+  # Parse the ini file contents. This will clear any values currently stored
+  # in the ini hash.
   #
-  def parse
-    return unless File.file?(@fn)
+  def parse!
+    return unless @content
 
-    @_current_section = nil
-    @_current_param = nil
-    @_current_value = nil
+    string = ''
+    property = ''
 
-    fd = (RUBY_VERSION >= '1.9' && @encoding) ?
-         File.open(@fn, 'r', :encoding => @encoding) :
-         File.open(@fn, 'r')
+    @ini.clear
+    @_line = nil
+    @_section = nil
 
-    while line = fd.gets
-      line = line.chomp
+    scanner = StringScanner.new(@content)
+    until scanner.eos?
 
-      # we ignore comment lines and blank lines
-      if line =~ @rgxp_comment
-        finish_property
-        next
-      end
+      # keep track of the current line for error messages
+      @_line = scanner.check(%r/\A.*$/) if scanner.bol?
 
-      # place values in the current section
-      if line =~ @rgxp_section
-        finish_property
-        @_current_section = @ini[$1.strip]
-        next
-      end
+      # look for escaped special characters \# \" etc
+      if scanner.scan(%r/\\([\[\]#{@param}#{@comment}"])/)
+        string << scanner[1]
 
-      parse_property line
+      # look for quoted strings
+      elsif scanner.scan(%r/"/)
+        quote = scanner.scan_until(/(?:\A|[^\\])"/)
+        parse_error('Unmatched quote') if quote.nil?
 
-    end  # while
+        quote.chomp!('"')
+        string << quote
 
-    finish_property
-  ensure
-    fd.close if defined? fd and fd
-    @_current_section = nil
-    @_current_param = nil
-    @_current_value = nil
+      # look for comments, empty strings, end of lines
+      elsif scanner.skip(%r/\A\s*(?:[#{@comment}].*)?$/)
+        string << scanner.getch unless scanner.eos?
+
+        process_property(property, string)
+
+      # 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
+        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.
+      else
+        tmp = scanner.scan_until(%r/([\n"#{@param}#{@comment}]|\\[\[\]#{@param}#{@comment}"])/m)
+        len = scanner[1].length
+        tmp.slice!(tmp.length - len, len)
+
+        scanner.pos = scanner.pos - len
+        string << tmp
+      end
+    end
+
+    process_property(property, string)
   end
 
-  # Attempt to parse a property name and value from the given _line_. This
-  # method takes into account multi-line values.
+  # 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.
   #
-  def parse_property( line )
-    p = v = nil
-    split = line =~ @rgxp_param
+  # Returns nil.
+  #
+  def process_property( property, value )
+    value.chomp!
+    return if property.empty? and value.empty?
+    return if value.sub!(%r/\\\s*\z/, '')
 
-    if split
-      p = line.slice(0, split+1).strip
-      v = line.slice(split+2, line.length).strip
-    else
-      v = line
-    end
+    property.strip!
+    value.strip!
 
-    if p.nil? and @_current_param.nil?
-      raise Error, "could not parse line '#{line}'"
-    end
+    parse_error if property.empty?
 
-    @_current_param = p unless p.nil?
+    current_section[property.dup] = unescape_value(value.dup)
 
-    if @_current_value then @_current_value << v
-    else @_current_value = v end
+    property.slice!(0, property.length)
+    value.slice!(0, value.length)
 
-    finish_property unless @_current_value.sub!(%r/\\\z/, "\n")
+    nil
   end
 
-  # If there is a current property being parsed, finish this parse step by
-  # storing the name and value in the current section and resetting for the
-  # next parse step.
+  # Returns the current section Hash.
   #
-  def finish_property
-    return unless @_current_param
-
-    @_current_section = @ini[@default] if @_current_section.nil?
-    @_current_section[@_current_param] = unescape @_current_value
+  def current_section
+    @_section ||= @ini[@default]
+  end
 
-    @_current_param = nil
-    @_current_value = nil
+  # 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
 
   # Unescape special characters found in the value string. This will convert
   # escaped null, tab, carriage return, newline, and backslash into their
   # literal equivalents.
   #
-  def unescape( value )
+  # value - The String value to unescape.
+  #
+  # Returns the unescaped value.
+  #
+  def unescape_value( value )
     return value unless @escape
 
     value = value.to_s
@@ -441,9 +528,13 @@ private
     value
   end
 
-  # Escape special characters
+  # Escape special characters.
+  #
+  # value - The String value to escape.
+  #
+  # Returns the escaped value.
   #
-  def escape( value )
+  def escape_value( value )
     return value unless @escape
 
     value = value.to_s.dup

data/test/data/comment.ini

@@ -3,3 +3,8 @@
 one = 1
 two = 2
 
+[section_two]  # you can comment here
+one = 42       # and even here!
+multi = 20 \   # and here, too
++ 22 \= 42
+

data/test/data/escape.ini

@@ -6,7 +6,8 @@ foo = http://en.wikipedia.org/wiki/Foobar
 tabs = There is a tab\tcharacter in here somewhere
 carriage return = Who uses these anyways?\r
 newline = Trust newline!\nAlways there when you need him.\nSplittin' those lines.
-null = Who'd be silly enough to put\0 a null character in the middle of a string?\
+null = Who'd be silly enough to put\0 a null character in the middle of a string? \
 Stroustrup would not approve!
 backslash = This string \\t contains \\n no \\r special \\0 characters!
+quoted = "Escaping works\tinside quoted strings!"
 

data/test/data/good.ini

@@ -4,7 +4,7 @@ two = 2
 
 [section_two]
 three =         3
-multi = multiline\
+multi = multiline \
 support
 
 ; comments should be ignored

data/test/data/multiline.ini

@@ -7,14 +7,17 @@ three =         3
 
 ; comments should be ignored
 [section_three]
-three   = hello\
+three   = hello \
 multiline
 other = "stuff"
 
 [section_four]
-four   = hello\
-multiple\
-multilines
+four   = hello \  # comments work here, too
+multiple \        # and here !!!
+multilines        # and even here (OMG)
+five = "multiple lines
+inside of quotations
+preserve everything"
 
 [empty_lines]
 empty =

data/test/test_inifile.rb

@@ -1,7 +1,3 @@
-# Code Generated by ZenTest v. 3.3.0
-#                 classname: asrt / meth =  ratio%
-#             Rini::IniFile:    0 /    9 =   0.00%
-
 # encoding: UTF-8
 
 libpath = File.expand_path '../../lib', __FILE__
@@ -13,12 +9,12 @@ require 'test/unit'
 class TestIniFile < Test::Unit::TestCase
 
   def setup
-    @ini_file = IniFile.new 'test/data/good.ini'
+    @ini_file = IniFile.new(:filename => 'test/data/good.ini')
     @contents = [
       ['section_one', 'one', '1'],
       ['section_one', 'two', '2'],
       ['section_two', 'three', '3'],
-      ['section_two', 'multi', "multiline\nsupport"],
+      ['section_two', 'multi', "multiline support"],
       ['section three', 'four', '4'],
       ['section three', 'five', '5'],
       ['section three', 'six', '6'],
@@ -128,7 +124,7 @@ class TestIniFile < Test::Unit::TestCase
     assert_equal @contents, ary.sort
 
     ary = []
-    IniFile.new('temp.ini').each {|*args| ary << args}
+    IniFile.new(:filename => 'temp.ini').each {|*args| ary << args}
     assert_equal [], ary
   end
 
@@ -144,7 +140,7 @@ class TestIniFile < Test::Unit::TestCase
     assert_equal expected, ary.sort
 
     ary = []
-    IniFile.new('temp.ini').each_section {|section| ary << section}
+    IniFile.new(:filename => 'temp.ini').each_section {|section| ary << section}
     assert_equal [], ary
   end
 
@@ -175,7 +171,7 @@ class TestIniFile < Test::Unit::TestCase
     assert_equal true,  @ini_file.has_section?(:section_two)
     assert_equal false, @ini_file.has_section?(nil)
 
-    ini_file = IniFile.new 'temp.ini'
+    ini_file = IniFile.new(:filename => 'temp.ini')
     assert_equal false, ini_file.has_section?('section_one')
     assert_equal false, ini_file.has_section?('one')
     assert_equal false, ini_file.has_section?('two')
@@ -188,7 +184,7 @@ class TestIniFile < Test::Unit::TestCase
     }
     assert_equal expected, @ini_file[:section_one]
 
-    expected = {'three' => '3', 'multi' => "multiline\nsupport"}
+    expected = {'three' => '3', 'multi' => "multiline support"}
     assert_equal expected, @ini_file['section_two']
 
     expected = {
@@ -210,7 +206,7 @@ class TestIniFile < Test::Unit::TestCase
     assert_nil @ini_file[nil]
 
     expected = {}
-    ini_file = IniFile.new 'temp.ini'
+    ini_file = IniFile.new(:filename => 'temp.ini')
     assert_equal expected, ini_file['section_one']
     assert_equal expected, ini_file['one']
     assert_nil ini_file[nil]
@@ -220,7 +216,7 @@ class TestIniFile < Test::Unit::TestCase
     expected = {
      "section_two" =>
       {
-        "three"=>"3", "multi"=>"multiline\nsupport"
+        "three"=>"3", "multi"=>"multiline support"
       },
      "section three" =>
       {
@@ -240,19 +236,33 @@ class TestIniFile < Test::Unit::TestCase
     # see if we can parse different style comments
     #assert_raise(IniFile::Error) {IniFile.new 'test/data/comment.ini'}
 
-    ini_file = IniFile.new 'test/data/comment.ini', :comment => '#'
-    assert_equal true, ini_file.has_section?('section_one')
+    ini_file = IniFile.new(:filename => 'test/data/comment.ini', :comment => '#')
+    assert ini_file.has_section?('section_one')
+    assert_equal '20 + 22 = 42', ini_file['section_two']['multi']
 
     # see if we can parse different style param separators
-    assert_raise(IniFile::Error) {IniFile.new 'test/data/param.ini'}
+    assert_raise(IniFile::Error) {IniFile.new(:filename => 'test/data/param.ini')}
 
-    ini_file = IniFile.new 'test/data/param.ini', :parameter => ':'
-    assert_equal true, ini_file.has_section?('section_one')
+    ini_file = IniFile.new(:filename => 'test/data/param.ini', :parameter => ':')
+    assert ini_file.has_section?('section_one')
     assert_equal '1', ini_file['section_one']['one']
     assert_equal '2', ini_file['section_one']['two']
 
     # make sure we error out on files with bad lines
-    assert_raise(IniFile::Error) {IniFile.new 'test/data/bad_1.ini'}
+    assert_raise(IniFile::Error) {IniFile.new :filename => 'test/data/bad_1.ini'}
+  end
+
+  def test_initialize_from_string
+    content = File.read('test/data/good.ini')
+
+    ini_file = IniFile.new(content, :comment => ';')
+    assert ini_file.has_section?('section_one')
+    assert ini_file.has_section?('section_two')
+    assert ini_file.has_section?('section three')
+    assert ini_file.has_section?('section_four')
+    assert ini_file.has_section?('section_five')
+
+    assert_equal '7 & 8', ini_file['section_five']['seven and eight']
   end
 
   def test_sections
@@ -263,7 +273,7 @@ class TestIniFile < Test::Unit::TestCase
 
     assert_equal expected, @ini_file.sections.sort
 
-    ini_file = IniFile.new 'temp.ini'
+    ini_file = IniFile.new(:filename => 'temp.ini')
     assert_equal [], ini_file.sections
   end
 
@@ -285,18 +295,34 @@ class TestIniFile < Test::Unit::TestCase
     tmp = 'test/data/temp.ini'
     File.delete tmp if Kernel.test(?f, tmp)
 
-    @ini_file.save tmp
+    @ini_file.save(:filename => tmp)
     assert_equal true, Kernel.test(?f, tmp)
 
     File.delete tmp if Kernel.test(?f, tmp)
 
-    ini_file = IniFile.new tmp
+    ini_file = IniFile.new(:filename => tmp)
     ini_file.save
     assert_nil Kernel.test(?s, tmp)
 
     File.delete tmp if Kernel.test(?f, tmp)
   end
 
+  def test_read
+    assert @ini_file.has_section?('section_one')
+
+    @ini_file['section_one']['one'] = 42
+    @ini_file['section_one']['two'] = 42
+    assert_equal 42, @ini_file['section_one']['one']
+    assert_equal 42, @ini_file['section_one']['two']
+
+    @ini_file.read
+    assert_equal '1', @ini_file['section_one']['one']
+    assert_equal '2', @ini_file['section_one']['two']
+
+    @ini_file.read(:filename => 'test/data/mixed_comment.ini')
+    assert_equal false, @ini_file.has_section?('section_two')
+  end
+
   def test_modifies_current_keys
     ini = IniFile.load("test/data/tmp.ini")
     ini["section one"]["one"] = 17
@@ -306,7 +332,7 @@ class TestIniFile < Test::Unit::TestCase
   end
 
   def test_can_add_key_to_inifile
-    ini_file = IniFile.new("test/data/tmp.ini")
+    ini_file = IniFile.new(:filename => "test/data/tmp.ini")
     ini_file["new_section"] = {}
     ini_file.save
 
@@ -314,7 +340,7 @@ class TestIniFile < Test::Unit::TestCase
   end
 
   def test_adds_correct_key_to_inifile
-    ini_file = IniFile.new("test/data/tmp.ini")
+    ini_file = IniFile.new(:filename => "test/data/tmp.ini")
     ini_file["foo"] = {}
     ini_file.save
 
@@ -322,7 +348,7 @@ class TestIniFile < Test::Unit::TestCase
   end
 
   def test_assigns_values_to_inifile
-    ini_file = IniFile.new("test/data/tmp.ini")
+    ini_file = IniFile.new(:filename => "test/data/tmp.ini")
     ini_file["foo"] = {
       :bar => "baz"
     }
@@ -331,7 +357,7 @@ class TestIniFile < Test::Unit::TestCase
   end
 
   def test_assigns_correct_values_to_inifile
-    ini_file = IniFile.new("test/data/tmp.ini")
+    ini_file = IniFile.new(:filename => "test/data/tmp.ini")
     ini_file["foo"] = {
       :one => "two"
     }
@@ -340,7 +366,7 @@ class TestIniFile < Test::Unit::TestCase
   end
 
   def test_assignment_stringifies_key
-    ini_file = IniFile.new("test/data/tmp.ini")
+    ini_file = IniFile.new(:filename => "test/data/tmp.ini")
     ini_file["foo"] = {:one => :two}
     ini_file[:foo] = {}
     assert_equal ini_file["foo"], {}
@@ -350,11 +376,12 @@ class TestIniFile < Test::Unit::TestCase
     ini_file = IniFile.load('test/data/multiline.ini')
 
     multiline = ini_file['section_three']
-    expected = {"three" => "hello\nmultiline", "other" => '"stuff"'}
+    expected = {"three" => "hello multiline", "other" => "stuff"}
     assert_equal expected, multiline
 
     multiple = ini_file['section_four']
-    expected = {"four" => "hello\nmultiple\nmultilines"}
+    expected = {"four" => "hello multiple multilines",
+                "five" => "multiple lines\ninside of quotations\npreserve everything" }
     assert_equal expected, multiple
 
     multiple = ini_file['empty_lines']
@@ -397,7 +424,7 @@ class TestIniFile < Test::Unit::TestCase
 
   if RUBY_VERSION >= '1.9'
     def test_parse_encoding
-      ini_file = IniFile.new("test/data/browscap.ini", :encoding => 'ISO-8859-1')
+      ini_file = IniFile.new(:filename => "test/data/browscap.ini", :encoding => 'ISO-8859-1')
       assert_equal ini_file['www.substancia.com AutoHTTPAgent (ver *)']['Browser'], "Subst\xE2ncia".force_encoding('ISO-8859-1')
     end
 
@@ -405,10 +432,10 @@ class TestIniFile < Test::Unit::TestCase
       tmp = 'test/data/tmp.ini'
       File.delete tmp if Kernel.test(?f, tmp)
 
-      @ini_file = IniFile.new(tmp, :encoding => 'UTF-8')
+      @ini_file = IniFile.new(:filename => tmp, :encoding => 'UTF-8')
       @ini_file['testutf-8'] = {"utf-8" => "appr\u20accier"}
 
-      @ini_file.save tmp
+      @ini_file.save(:filename => tmp)
 
       test = File.open(tmp)
       assert_equal test.external_encoding.to_s, 'UTF-8'
@@ -422,8 +449,9 @@ class TestIniFile < Test::Unit::TestCase
     assert_equal %Q{There is a tab\tcharacter in here somewhere}, escaped['tabs']
     assert_equal %Q{Who uses these anyways?\r}, escaped['carriage return']
     assert_equal %Q{Trust newline!\nAlways there when you need him.\nSplittin' those lines.}, escaped['newline']
-    assert_equal %Q{Who'd be silly enough to put\0 a null character in the middle of a string?\nStroustrup would not approve!}, escaped['null']
+    assert_equal %Q{Who'd be silly enough to put\0 a null character in the middle of a string? Stroustrup would not approve!}, escaped['null']
     assert_equal %q{This string \t contains \n no \r special \0 characters!}, escaped['backslash']
+    assert_equal %Q{Escaping works\tinside quoted strings!}, escaped['quoted']
   end
 
   def test_value_escaping_disabled
@@ -433,8 +461,9 @@ class TestIniFile < Test::Unit::TestCase
     assert_equal %q{There is a tab\tcharacter in here somewhere}, escaped['tabs']
     assert_equal %q{Who uses these anyways?\r}, escaped['carriage return']
     assert_equal %q{Trust newline!\nAlways there when you need him.\nSplittin' those lines.}, escaped['newline']
-    assert_equal %Q{Who'd be silly enough to put\\0 a null character in the middle of a string?\nStroustrup would not approve!}, escaped['null']
+    assert_equal %Q{Who'd be silly enough to put\\0 a null character in the middle of a string? Stroustrup would not approve!}, escaped['null']
     assert_equal %q{This string \\\\t contains \\\\n no \\\\r special \\\\0 characters!}, escaped['backslash']
+    assert_equal %q{Escaping works\tinside quoted strings!}, escaped['quoted']
   end
 
   def test_global_section

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inifile
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,30 +9,40 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-28 00:00:00.000000000Z
+date: 2012-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bones-git
-  requirement: &2167250880 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.2.5
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2167250880
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bones
-  requirement: &2167250400 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 3.7.2
+        version: 3.8.0
   type: :development
   prerelease: false
-  version_requirements: *2167250400
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.8.0
 description: ! "Although made popular by Windows, INI files can be used on any system
   thanks\nto their flexibility. They allow a program to store configuration data,
   which\ncan then be easily parsed and changed. Two notable systems that use the INI\nformat
@@ -61,6 +71,7 @@ files:
 - History.txt
 - README.md
 - Rakefile
+- a.rb
 - lib/inifile.rb
 - test/data/bad_1.ini
 - test/data/browscap.ini
@@ -95,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: inifile
-rubygems_version: 1.8.11
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: INI file reader and writer