ini 0.1.1

data/README

@@ -0,0 +1,113 @@
+
+= Conventional INI File Parsing and Writing
+
+== Introduction
+
+Ah yes, INI files. We love them. We hate them. We cannot escape
+them. Originally made popular by Windows, INI files are everywhere
+including in Samba[www.samba.org] and Trac[trac.edgewall.org]. This
+gem has one goal: make INI file, structure, and stream manipulation
+as fast, safe, and simple as possible. We take a modal approach
+with a pluggable parser class.
+
+== Sample File
+
+  ; some comment about section1
+  [section1]
+  var1 = foo
+  var2 = doodle
+
+  [section2]
+
+  ; some comment about var1
+  var1 = baz
+
+  ; some comment about var2    
+  var2 = shoodle
+
+== Conventional Format
+
+There is no formal INI specification but most parsers observe the
+following so we do also by default:
+
+=== Sections
+
+Section declarations are wrapped in square brackets
+(<tt>[section1]</tt>) with no spaces surrounding the section
+name. Duplicate sections are discouraged but if included are merged.
+
+=== Parameters
+
+The <tt>var1 = foo</tt> above is an example of a parameter, also
+frequently referred to a property, item, or pair.  Each parameter is
+made up of a key name (<tt>var1</tt>), an equals sign (<tt>=</tt>),
+and a value (<tt>foo</tt>) with optional spaces. Leading spaces
+before the key name are allowed and leading spaces before or after
+the value are trimmed. Values are literally the characters that
+remain, even if quoted (<tt>var1 = "foo"</tt> would include the
+quotes in the value). Duplicate parameters, either in the same
+section or merged duplicate sections, play 'last one wins'.
+
+=== Comments
+
+All lines starting with a semicolon (<tt>;</tt>) are assumed to be
+comments and are ignored. This character must be the first on the line.
+
+=== Blank Lines
+
+All lines that contain nothing but spaces are ignored.
+
+=== Line Endings
+
+Lines end at either a CRLF or just a LF (CR=\015, LF=\012). Files
+may mix the two within the same file to accomodate edits from
+different platforms.
+
+=== Format Variations Supported
+
+Because INI format is not formally specified, many variations exist
+in the wild. Some of these are supported by extra parsers that are
+included and set by changing the <tt>mode</tt> of the <ini> instance.
+
+To maintain backward compatibility with the original 'inifile' gem,
+the following variations are supported by the default parser: 
+
+* <b>Comments:</b> the comment character can be specified when an instance is created
+* <b>Parameters:</b> separator character can be specified when an instance is created
+* <b>Duplicate Sections:</b> merged
+* <b>Duplicate Parameters:</b> the last one wins
+
+=== Currently Unsupported Format Variations
+
+If it isn't listed above, chances are it isn't supported. But here
+are some specific variations in case you are wondering (and, yes,
+we do have plans eventually support them, either as defaults or options):
+
+* Parameter value continuation with backslash (<tt>\\</tt>)
+* Parameter value double-quoting with escapes (<tt>foo = "value with \\n in it"</tt>)
+* Parameter values using braces (<tt>{}</tt>)
+* Parameter values using simple commas parsing into arrays
+
+== Copyright and License
+
+Copyright (c) 2006-2007 The 'ini' and 'inifile' Gem Team
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/lib/ini.rb

@@ -0,0 +1,264 @@
+# $Id: ini.rb 1 2007-01-17 15:21:30Z ironmo $
+
+#
+# This class represents the INI file and can be used to parse, modify,
+# and write INI files.
+#
+class Ini
+
+  # :stopdoc:
+  class Error < StandardError; end
+  # :startdoc:
+
+  #
+  # call-seq:
+  #    IniFile.load( filename )
+  #    IniFile.load( filename, options )
+  #
+  # Open the given _filename_ and load the contetns of the INI file.
+  # The following _options_ can be passed to this method:
+  #
+  #    :comment => ';'      The line comment character(s)
+  #    :parameter => '='    The parameter / value separator
+  #
+  def self.load( filename, opts = {} )
+    new(filename, opts)
+  end
+
+  #
+  # call-seq:
+  #    IniFile.new( filename )
+  #    IniFile.new( filename, options )
+  #
+  # 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:
+  #
+  #    :comment => ';'      The line comment character(s)
+  #    :parameter => '='    The parameter / value separator
+  #
+  def initialize( filename, opts = {} )
+    @fn = filename
+    @comment = opts[:comment] || ';'
+    @param = opts[:parameter] || '='
+    @ini = Hash.new {|h,k| h[k] = Hash.new}
+
+    @rgxp_comment = %r/\A\s*\z|\A\s*[#{@comment}]/
+    @rgxp_section = %r/\A\s*\[([^\]]+)\]/o
+    @rgxp_param   = %r/\A([^#{@param}]+)#{@param}(.*)\z/
+
+    parse
+  end
+
+  #
+  # call-seq:
+  #    write
+  #    write( filename )
+  #
+  # Write the INI file contents to the filesystem. 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.
+  #
+  def write( filename = nil )
+    @fn = filename unless filename.nil?
+
+    ::File.open(@fn, 'w') do |f|
+      @ini.each do |section,hash|
+        f.puts "[#{section}]"
+        hash.each {|param,val| f.puts "#{param} #{@param} #{val}"}
+        f.puts
+      end
+    end
+    self
+  end
+  alias :save :write
+
+  #
+  # call-seq:
+  #    each {|section, parameter, value| block}
+  #
+  # Yield each _section_, _parameter_, _value_ in turn to the given
+  # _block_. The method returns immediately if no block is supplied.
+  #
+  def each
+    return unless block_given?
+    @ini.each do |section,hash|
+      hash.each do |param,val|
+        yield section, param, val
+      end
+    end
+    self
+  end
+
+  #
+  # call-seq:
+  #    each_section {|section| block}
+  #
+  # Yield each _section_ in turn to the given _block_. The method returns
+  # immediately if no block is supplied.
+  #
+  def each_section
+    return unless block_given?
+    @ini.each_key {|section| yield section}
+    self
+  end
+
+  #
+  # call-seq:
+  #    delete_section( section )
+  #
+  # Deletes the named _section_ from the INI file. Returns the
+  # parameter / value pairs if the section exists in the INI file. Otherwise,
+  # returns +nil+.
+  #
+  def delete_section( section )
+    @ini.delete section.to_s
+  end
+
+  #
+  # call-seq:
+  #    ini_file[section]
+  #
+  # Get the hash of parameter/value pairs for the given _section_. If the
+  # _section_ hash does not exist it will be created.
+  #
+  def []( section )
+    return nil if section.nil?
+    @ini[section.to_s]
+  end
+
+  #
+  # call-seq:
+  #    has_section?( section )
+  #
+  # Returns +true+ if the named _section_ exists in the INI file.
+  #
+  def has_section?( section )
+    @ini.has_key? section.to_s
+  end
+
+  #
+  # call-seq:
+  #    sections
+  #
+  # Returns an array of the section names.
+  #
+  def sections
+    @ini.keys
+  end
+
+  #
+  # call-seq:
+  #    freeze
+  #
+  # Freeze the state of the +IniFile+ object. Any attempts to change the
+  # object will raise an error.
+  #
+  def freeze
+    super
+    @ini.each_value {|h| h.freeze}
+    @ini.freeze
+    self
+  end
+
+  #
+  # call-seq:
+  #    taint
+  #
+  # Marks the INI file as tainted -- this will traverse each section marking
+  # each section as tainted as well.
+  #
+  def taint
+    super
+    @ini.each_value {|h| h.taint}
+    @ini.taint
+    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
+  # orgiinal. The tainted state of the original is copied to the duplicate.
+  #
+  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
+
+  #
+  # 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
+  # orgiinal. The tainted state and the frozen state of the original is copied
+  # to the duplicate.
+  #
+  def clone
+    other = dup
+    other.freeze if self.frozen?
+    other
+  end
+
+  #
+  # call-seq:
+  #    eql?( other )
+  #
+  # 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.
+  #
+  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?
+
+
+  private
+  #
+  # call-seq
+  #    parse
+  #
+  # Parse the ini file contents.
+  #
+  def parse
+    return unless ::Kernel.test ?f, @fn
+    section = nil
+
+    ::File.open(@fn, 'r') do |f|
+      while line = f.gets
+        line = line.chomp
+
+        case line
+        # ignore blank lines and comment lines
+        when @rgxp_comment: next
+
+        # this is a section declaration
+        when @rgxp_section: section = @ini[$1.strip]
+
+        # otherwise we have a parameter
+        when @rgxp_param
+          begin
+            section[$1.strip] = $2.strip
+          rescue NoMethodError
+            raise Error, "parameter encountered before first section"
+          end
+
+        else
+          raise Error, "could not parse line '#{line}"
+        end
+      end  # while
+    end  # File.open
+  end
+
+end
+
+# EOF

data/lib/inifile.rb

@@ -0,0 +1,10 @@
+# $Id: inifile.rb 1 2007-01-17 15:21:30Z ironmo $
+
+# The 'inifile' gem will eventually be deprecated in favor of the
+# 'ini' gem as it becomes able to handle streams, stringio and string buffers of INI
+# formatted data.
+
+require 'ini'
+
+class IniFile < Ini
+end

data/test/data/bad_1.ini

@@ -0,0 +1,6 @@
+; having a paramater / value pair outside a section is an error
+one = 1
+
+[section_one]
+one = 1
+two = 2

data/test/data/bad_2.ini

@@ -0,0 +1,6 @@
+[section_one]
+one = 1
+two = 2
+
+; the following is not a valid line
+invalid line

data/test/data/comment.ini

@@ -0,0 +1,5 @@
+# comments should be ignored
+[section_one]
+one = 1
+two = 2
+

data/test/data/good.ini

@@ -0,0 +1,17 @@
+[section_one]
+one = 1
+two = 2
+
+[section_two]
+three =         3    
+
+; comments should be ignored
+[section three]
+four   =4
+five=5
+six =6
+
+[section_four]
+   [section_five]
+ seven and eight= 7 & 8
+

data/test/data/mixed_comment.ini

@@ -0,0 +1,7 @@
+# comments should be ignored
+; multiple comments characeters are supported
+; (I'm lookin' at you, samba)
+[section_one]
+one = 1
+two = 2
+

data/test/data/param.ini

@@ -0,0 +1,5 @@
+; comments should be ignored
+[section_one]
+one : 1
+two:2
+

data/test/test_inifile.rb

@@ -0,0 +1,277 @@
+# Code Generated by ZenTest v. 3.3.0
+#                 classname: asrt / meth =  ratio%
+#             Rini::IniFile:    0 /    9 =   0.00%
+
+begin
+  require 'inifile'
+rescue LoadError
+  require 'rubygems'
+  require 'inifile'
+end
+
+begin; require 'turn'; rescue LoadError; end
+require 'test/unit' unless defined? $ZENTEST and $ZENTEST
+
+class TestIniFile < Test::Unit::TestCase
+
+  def setup
+    @ini_file = ::IniFile.new 'test/data/good.ini'
+    @contents = [
+      ['section_one', 'one', '1'],
+      ['section_one', 'two', '2'],
+      ['section_two', 'three', '3'],
+      ['section three', 'four', '4'],
+      ['section three', 'five', '5'],
+      ['section three', 'six', '6'],
+      ['section_five', 'seven and eight', '7 & 8']
+    ].sort
+  end
+
+  def test_class_load
+    ini_file = ::IniFile.load 'test/data/good.ini'
+    assert_instance_of ::IniFile, ini_file
+
+    # see if we can parse different style comments
+    assert_raise(::IniFile::Error) {::IniFile.load 'test/data/comment.ini'}
+
+    ini_file = ::IniFile.load 'test/data/comment.ini', :comment => '#'
+    assert_instance_of ::IniFile, ini_file
+
+    # see if we can parse mixed style comments
+    assert_raise(::IniFile::Error) {::IniFile.load 'test/data/mixed_comment.ini'}
+
+    ini_file = ::IniFile.load 'test/data/mixed_comment.ini', :comment => ';#'
+    assert_instance_of ::IniFile, ini_file
+
+    # see if we can parse different style param separators
+    assert_raise(::IniFile::Error) {::IniFile.load 'test/data/param.ini'}
+
+    ini_file = ::IniFile.load 'test/data/param.ini', :parameter => ':'
+    assert_instance_of ::IniFile, ini_file
+
+    # make sure we error out on files with bad lines
+    assert_raise(::IniFile::Error) {::IniFile.load 'test/data/bad_1.ini'}
+    assert_raise(::IniFile::Error) {::IniFile.load 'test/data/bad_2.ini'}
+  end
+
+  def test_clone
+    clone = @ini_file.clone
+    assert_equal @ini_file, clone
+    assert !clone.tainted?
+    assert !clone.frozen?
+
+    # the clone should be completely independent of the original
+    clone['new_section']['one'] = 1
+    assert_not_equal @ini_file, clone
+
+    # the tainted state is copied to clones
+    @ini_file.taint
+    assert @ini_file.tainted?
+
+    clone = @ini_file.clone
+    assert clone.tainted?
+
+    # the frozen state is also copied to clones
+    @ini_file.freeze
+    assert @ini_file.frozen?
+
+    clone = @ini_file.clone
+    assert clone.tainted?
+    assert clone.frozen?
+  end
+
+  def test_delete_section
+    assert_nil @ini_file.delete_section('section_nil')
+
+    h = {'one' => '1', 'two' => '2'}
+    assert_equal true, @ini_file.has_section?('section_one')
+    assert_equal h, @ini_file.delete_section('section_one')
+    assert_equal false, @ini_file.has_section?('section_one')
+    assert_nil @ini_file.delete_section('section_one')
+  end
+
+  def test_dup
+    dup = @ini_file.dup
+    assert_equal @ini_file, dup
+    assert !dup.tainted?
+    assert !dup.frozen?
+
+    # the duplicate should be completely independent of the original
+    dup['new_section']['one'] = 1
+    assert_not_equal @ini_file, dup
+
+    # the tainted state is copied to duplicates
+    @ini_file.taint
+    assert @ini_file.tainted?
+
+    dup = @ini_file.dup
+    assert dup.tainted?
+
+    # the frozen state, however, is not
+    @ini_file.freeze
+    assert @ini_file.frozen?
+
+    dup = @ini_file.dup
+    assert dup.tainted?
+    assert !dup.frozen?
+  end
+
+  def test_each
+    ary = []
+    @ini_file.each {|*args| ary << args}
+
+    assert_equal @contents, ary.sort
+
+    ary = []
+    ::IniFile.new('temp.ini').each {|*args| ary << args}
+    assert_equal [], ary
+  end
+
+  def test_each_section
+    expected = [
+      'section_one', 'section_two', 'section three',
+      'section_four', 'section_five'
+    ].sort
+
+    ary = []
+    @ini_file.each_section {|section| ary << section}
+
+    assert_equal expected, ary.sort
+
+    ary = []
+    ::IniFile.new('temp.ini').each_section {|section| ary << section}
+    assert_equal [], ary
+  end
+
+  def test_eql_eh
+    assert @ini_file.eql?(@ini_file)
+    assert @ini_file.eql?(@ini_file.clone)
+    assert !@ini_file.eql?('string')
+    assert !@ini_file.eql?(IniFile.new(''))
+  end
+
+  def test_freeze
+    assert_equal false, @ini_file.frozen?
+    @ini_file.each_section do |s|
+      assert_equal false, @ini_file[s].frozen?
+    end
+
+    @ini_file.freeze
+
+    assert_equal true, @ini_file.frozen?
+    @ini_file.each_section do |s|
+      assert_equal true, @ini_file[s].frozen?
+    end
+  end
+
+  def test_has_section_eh
+    assert_equal true,  @ini_file.has_section?('section_one')
+    assert_equal false, @ini_file.has_section?('section_ten')
+    assert_equal true,  @ini_file.has_section?(:section_two)
+    assert_equal false, @ini_file.has_section?(nil)
+
+    ini_file = ::IniFile.new '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')
+  end
+
+  def test_index
+    expected = {
+      'one' => '1',
+      'two' => '2'
+    }
+    assert_equal expected, @ini_file[:section_one]
+
+    expected = {'three' => '3'}
+    assert_equal expected, @ini_file['section_two']
+
+    expected = {
+      'four' => '4',
+      'five' => '5',
+      'six'  => '6',
+    }
+    assert_equal expected, @ini_file['section three']
+
+    expected = {}
+    assert_equal expected, @ini_file['section_four']
+
+    expected = {'seven and eight' => '7 & 8'}
+    assert_equal expected, @ini_file['section_five']
+
+    expected = {}
+    assert_equal expected, @ini_file['section_six']
+
+    assert_nil @ini_file[nil]
+
+    expected = {}
+    ini_file = ::IniFile.new 'temp.ini'
+    assert_equal expected, ini_file['section_one']
+    assert_equal expected, ini_file['one']
+    assert_nil ini_file[nil]
+  end
+
+  def test_initialize
+    # 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')
+
+    # see if we can parse different style param separators
+    assert_raise(::IniFile::Error) {::IniFile.new 'test/data/param.ini'}
+
+    ini_file = ::IniFile.new 'test/data/param.ini', :parameter => ':'
+    assert_equal true, 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 'test/data/bad_2.ini'}
+  end
+
+  def test_sections
+    expected = [
+      'section_one', 'section_two', 'section three',
+      'section_four', 'section_five'
+    ].sort
+
+    assert_equal expected, @ini_file.sections.sort
+
+    ini_file = ::IniFile.new 'temp.ini'
+    assert_equal [], ini_file.sections
+  end
+
+  def test_taint
+    assert_equal false, @ini_file.tainted?
+    @ini_file.each_section do |s|
+      assert_equal false, @ini_file[s].tainted?
+    end
+
+    @ini_file.taint
+
+    assert_equal true, @ini_file.tainted?
+    @ini_file.each_section do |s|
+      assert_equal true, @ini_file[s].tainted?
+    end
+  end
+
+  def test_write
+    tmp = 'test/data/temp.ini'
+    ::File.delete tmp if ::Kernel.test(?f, tmp)
+
+    @ini_file.save tmp
+    assert_equal true, ::Kernel.test(?f, tmp)
+
+    ::File.delete tmp if ::Kernel.test(?f, tmp)
+
+    ini_file = ::IniFile.new tmp
+    ini_file.save
+    assert_nil ::Kernel.test(?s, tmp)
+
+    ::File.delete tmp if ::Kernel.test(?f, tmp)
+  end
+end
+
+# EOF

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.1
+specification_version: 1
+name: ini
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+date: 2007-01-17 00:00:00 -05:00
+summary: INI file reader and writer
+require_paths: 
+  - lib
+  - test
+email: inifile-talk@rubyforge.org
+homepage: 
+rubyforge_project: inifile
+description: "Ah yes, INI files. We love them. We hate them. We cannot escape them. Originally
+  made popular by Windows, INI files are everywhere including in Samba and Trac.
+  This gem has one goal: make INI file, structure, and stream manipulation as
+  fast, safe, and simple as possible. We take a modal approach with a pluggable
+  parser class."
+autorequire: ini
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+  - Rob Muhlestein
+  - Tim Pease
+files: 
+  - README
+  - lib/ini.rb
+  - lib/inifile.rb
+  - test/data/bad_1.ini
+  - test/data/bad_2.ini
+  - test/data/comment.ini
+  - test/data/good.ini
+  - test/data/mixed_comment.ini
+  - test/data/param.ini
+  - test/test_inifile.rb
+test_files: 
+  - test/test_inifile.rb
+rdoc_options: []
+extra_rdoc_files: 
+  - README
+executables: []
+extensions: []
+requirements: []
+dependencies: []