inifile 0.1.0

data/README.txt

@@ -0,0 +1,61 @@
+
+ = Ruby INI File Parser and Writer
+
+ == Introduction
+
+ An initialization file, or INI file, is a configuration file that contains
+ configuration data for Microsoft Windows based applications. Starting with
+ Windows 95, the INI file format was superseded but not entirely replaced by a
+ registry database in Microsoft operating systems.
+
+ Although made popular by Windows, INI files can be used on any system thanks
+ to their flexibility. They allow a program to store configuration data, which
+ can then be easily parsed and changed.
+
+ == File Format
+
+ A typical INI file might look like this:
+
+     [section1]
+
+     ; some comment on section1
+     var1 = foo
+     var2 = doodle
+ 
+     [section2]
+
+     ; another comment
+     var1 = baz
+     var2 = shoodle
+
+ === Format
+
+ This describes the elements of the INI file format:
+
+ * *Sections*: Section declarations start with '[' and end with ']' as in [section1] and [section2] above. And sections start with section declarations.
+ * *Parameters*: The "var1 = foo" above is an example of a parameter (also known as an item). Parameters are made up of a key ('var1'), equals sign ('='), and a value ('foo').
+ * *Comments*: All the lines starting with a ';' are assumed to be comments, and are ignored.
+
+ === Differences
+
+ The format of INI files is not well defined. Many programs interpret their
+ structure differently than the basic structure that was defined in the above
+ example. The following is a basic list of some of the differences:
+
+ * *Comments*: Programs like Samba accept either ';' or '#' as comments. Comments can be added after parameters with several formats.
+ * *Backslashes*: Adding a backslash '\' allows you to continue the value from one line to another. Some formats also allow various escapes with a '\', such as '\n' for newline.
+ * <b>Duplicate parameters</b>: Most of the time, you can't have two parameters with the same name in one section. Therefore one can say that parameters are local to the section. Although this behavior can vary between implementations, it is advisable to stick with this rule.
+ * <b>Duplicate sections</b>: If you have more than one section with the same name then the last section overrides the previous one. (Some implementations will merge them if they have different keys.)
+ * Some implementations allow ':' in place of '='.
+
+ == This Package
+
+ This package supports the standard INI file format described in the *Format*
+ section above. The following differences are also supported:
+
+ * *Comments*: The comment character can be specified when an +IniFile+ is created. The comment character must be the first non-whitespace character on a line.
+ * *Backslashes*: Backslashes are not supported by this package.
+ * <b>Duplicate parameters</b>: Duplicate parameters are allowed in a single section. The last parameter value is the one that will be stored in the +IniFile+.
+ * <b>Duplicate sections</b>: Duplicate sections will be merged. Parameters duplicated between to the two sections follow the duplicate parameters rule above.
+ * *Parameters*: The parameter separator character can be specified when an +IniFile+ is created.
+

data/lib/inifile.rb

@@ -0,0 +1,264 @@
+# $Id: inifile.rb 57 2006-11-19 20:51:45Z tpease $
+
+#
+# This class represents the INI file and can be used to parse, modify,
+# and write INI files.
+#
+class IniFile
+
+  # :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  # class IniFile
+
+# EOF

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,55 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: inifile
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-11-26 00:00:00 -07:00
+summary: INI file reader and writer
+require_paths: 
+- lib
+- test
+email: tim.pease@gmail.com
+homepage: 
+rubyforge_project: codeforpeople.com
+description: Although made popular by Windows, INI files can be used on any system thanks to their flexibility. They allow a program to store configuration data, which can then be easily parsed and changed. Two notable systems that use the INI format are Samba and Trac.  This is a native Ruby package for reading and writing INI files.
+autorequire: 
+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: 
+- Tim Pease
+files: 
+- README.txt
+- 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: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+