class IniFile

This class represents the INI file and can be used to parse, modify, and write INI files.

Constants

VERSION

Attributes

encoding[RW]

Get and set the encoding

filename[RW]

Get and set the filename

Public Class Methods

load( filename, opts = {} ) click to toggle source

Public: Open an INI file and load the contents.

filename - The name of the file as a String opts - The Hash of options (default: {})

:comment   - String containing the comment character(s)
:parameter - String used to separate parameter and value
:encoding  - Encoding String for reading / writing
:default   - The String name of the default global section
:continuation  - Use backslash as a line contintuation

Examples

IniFile.load('file.ini')
#=> IniFile instance

IniFile.load('does/not/exist.ini')
#=> nil

Returns an IniFile instance or nil if the file could not be opened.

# File lib/inifile.rb, line 31
def self.load( filename, opts = {} )
  return unless File.file? filename
  new(opts.merge(:filename => filename))
end
new( opts = {} ) click to toggle source

Public: Create a new INI file from the given set of options. If :content is provided then it will be used to populate the INI file. If a :filename is provided then the contents of the file will be parsed and stored in the INI file. If neither the :content or :filename is provided then an empty INI file is created.

opts - The Hash of options (default: {})

:content   - The String/Hash containing the INI contents
:comment   - String containing the comment character(s)
:parameter - String used to separate parameter and value
:encoding  - Encoding String for reading / writing
:default   - The String name of the default global section
:filename  - The filename as a String
:permissions - Permission bits to assign the new file
:continuation  - Use backslash as a line continuation
:separator - what to output between the key, operator, and value
:force_array  - Keep all values with same key in an array

Examples

IniFile.new
#=> an empty IniFile instance

IniFile.new( :content => "[global]\nfoo=bar" )
#=> an IniFile instance

IniFile.new( :filename => 'file.ini', :encoding => 'UTF-8' )
#=> an IniFile instance

IniFile.new( :content => "[global]\nfoo=bar", :comment => '#' )
#=> an IniFile instance

IniFile.new( :permissions => 0644 )
#=> an IniFile instance
# File lib/inifile.rb, line 77
def initialize( opts = {} )
  @comment  = opts.fetch(:comment, ';#')
  @param    = opts.fetch(:parameter, '=')
  @encoding = opts.fetch(:encoding, nil)
  @default  = opts.fetch(:default, 'global')
  @filename = opts.fetch(:filename, nil)
  @permissions = opts.fetch(:permissions, nil)
  @continuation  = opts.fetch(:continuation, true)
  @separator = opts.fetch(:separator, ' ')
  @force_array = opts.fetch(:force_array, nil)
  content   = opts.fetch(:content, nil)

  @ini = Hash.new {|h,k| h[k] = Hash.new}

  if    content.is_a?(Hash) then merge!(content)
  elsif content             then parse(content)
  elsif @filename           then read
  end
end

Public Instance Methods

==( other )
Alias for: eql?
[]( section ) click to toggle source

Public: Get the section Hash by name. If the section does not exist, then it will be created.

section - The section name as a String.

Examples

inifile['global']
#=> global section Hash

Returns the Hash of parameter/value pairs for this section.

# File lib/inifile.rb, line 297
def []( section )
  return nil if section.nil?
  @ini[section.to_s]
end
[]=( section, value ) click to toggle source

Public: Set the section to a hash of parameter/value pairs.

section - The section name as a String. value - The Hash of parameter/value pairs.

Examples

inifile['tenderloin'] = { 'gritty' => 'yes' }
#=> { 'gritty' => 'yes' }

Returns the value Hash.

# File lib/inifile.rb, line 313
def []=( section, value )
  @ini[section.to_s] = value
end
clone() click to toggle source

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.

# File lib/inifile.rb, line 388
def clone
  other = dup
  other.freeze if self.frozen?
  other
end
delete_section( section ) click to toggle source

Public: Remove a section identified by name from the IniFile.

section - The section name as a String.

Returns the deleted section Hash.

# File lib/inifile.rb, line 282
def delete_section( section )
  @ini.delete section.to_s
end
dup() click to toggle source

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.

Calls superclass method
# File lib/inifile.rb, line 374
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
each() { |section, param, val| ... } click to toggle source

Public: Yield each INI file section, parameter, and value in turn to the given block.

block - The block that will be iterated by the each method. The block will

be passed the current section and the parameter/value pair.

Examples

inifile.each do |section, parameter, value|
  puts "#{parameter} = #{value} [in section - #{section}]"
end

Returns this IniFile.

# File lib/inifile.rb, line 249
def each
  return unless block_given?
  @ini.each do |section,hash|
    hash.each do |param,val|
      yield section, param, val
    end
  end
  self
end
each_section() { |section| ... } click to toggle source

Public: Yield each section in turn to the given block.

block - The block that will be iterated by the each method. The block will

be passed the current section as a Hash.

Examples

inifile.each_section do |section|
  puts section.inspect
end

Returns this IniFile.

# File lib/inifile.rb, line 271
def each_section
  return unless block_given?
  @ini.each_key {|section| yield section}
  self
end
eql?( other ) click to toggle source

Public: Compare this IniFile to some other IniFile. For two INI files to be equivalent, they must have the same sections with the same parameter / value pairs in each section.

other - The other IniFile.

Returns true if the INI files are equivalent and false if they differ.

# File lib/inifile.rb, line 401
def eql?( other )
  return true if equal? other
  return false unless other.instance_of? self.class
  @ini == other.instance_variable_get(:@ini)
end
Also aliased as: ==
escape_value( value ) click to toggle source

Escape special characters.

value - The String value to escape.

Returns the escaped value.

# File lib/inifile.rb, line 413
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
freeze() click to toggle source

Public: Freeze the state of this IniFile object. Any attempts to change the object will raise an error.

Returns this IniFile.

Calls superclass method
# File lib/inifile.rb, line 351
def freeze
  super
  @ini.each_value {|h| h.freeze}
  @ini.freeze
  self
end
has_section?( section ) click to toggle source

Public: Check to see if the IniFile contains the section.

section - The section name as a String.

Returns true if the section exists in the IniFile.

# File lib/inifile.rb, line 338
def has_section?( section )
  @ini.has_key? section.to_s
end
match( regex ) click to toggle source

Public: Create a Hash containing only those INI file sections whose names match the given regular expression.

regex - The Regexp used to match section names.

Examples

inifile.match(/^tree_/)
#=> Hash of matching sections

Return a Hash containing only those sections that match the given regular expression.

# File lib/inifile.rb, line 329
def match( regex )
  @ini.dup.delete_if { |section, _| section !~ regex }
end
merge( other ) click to toggle source

Public: Creates a copy of this inifile with the entries from the other_inifile merged into the copy.

other - The other IniFile.

Returns a new IniFile.

# File lib/inifile.rb, line 185
def merge( other )
  self.dup.merge!(other)
end
merge!( other ) click to toggle source

Public: Merges other_inifile into this inifile, overwriting existing entries. Useful for having a system inifile with user overridable settings elsewhere.

other - The other IniFile.

Returns this IniFile.

# File lib/inifile.rb, line 196
def merge!( other )
  return self if other.nil?

  my_keys = @ini.keys
  other_keys = case other
    when IniFile
      other.instance_variable_get(:@ini).keys
    when Hash
      other.keys
    else
      raise Error, "cannot merge contents from '#{other.class.name}'"
    end

  (my_keys & other_keys).each do |key|
    case other[key]
    when Hash
      @ini[key].merge!(other[key])
    when nil
      nil
    else
      raise Error, "cannot merge section #{key.inspect} - unsupported type: #{other[key].class.name}"
    end
  end

  (other_keys - my_keys).each do |key|
    case other[key]
    when Hash
      @ini[key] = other[key].dup
    when nil
      @ini[key] = {}
    when String
      @ini[@default].merge!({key => other[key]})
    else
      raise Error, "cannot merge section #{key.inspect} - unsupported type: #{other[key].class.name}"
    end
  end

  self
end
parse( content ) click to toggle source

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.

# File lib/inifile.rb, line 430
def parse( content )
  parser = Parser.new(@ini, @param, @comment, @default, @continuation, @force_array)
  parser.parse(content)
  self
end
read( opts = {} ) click to toggle source

Public: Read the contents of the INI file from the file system and replace and set the state of this IniFile instance. If left unspecified the currently configured filename and encoding will be used when reading from the file system. Otherwise the filename and encoding can be specified in the options hash.

opts - The default options Hash

:filename - The filename as a String
:encoding - The encoding as a String

Returns this IniFile instance if the read was successful; nil is returned if the file could not be read.

# File lib/inifile.rb, line 149
def read( opts = {} )
  filename = opts.fetch(:filename, @filename)
  encoding = opts.fetch(:encoding, @encoding)
  return unless File.file? filename

  mode = encoding ? "r:#{encoding}" : "r"
  File.open(filename, mode) { |fd| parse fd }
  self
end
Also aliased as: restore
restore( opts = {} )
Alias for: read
save( opts = {} )
Alias for: write
sections() click to toggle source

Returns an Array of section names contained in this IniFile.

# File lib/inifile.rb, line 343
def sections
  @ini.keys
end
taint() click to toggle source

Public: Mark this IniFile as tainted – this will traverse each section marking each as tainted.

Returns this IniFile.

Calls superclass method
# File lib/inifile.rb, line 362
def taint
  super
  @ini.each_value {|h| h.taint}
  @ini.taint
  self
end
to_h() click to toggle source

Returns this IniFile converted to a Hash.

# File lib/inifile.rb, line 175
def to_h
  @ini.dup
end
to_s() click to toggle source

Returns this IniFile converted to a String.

# File lib/inifile.rb, line 161
def to_s
  s = []
  hash = @ini.dup
  default = hash.delete(@default)
  default.each {|param,val| s << "#{param} #{@param} #{escape_value val}"}
  hash.each do |section,hash|
    s << "[#{section}]"
    hash.each {|param,val| s << "#{param}#{@separator}#{@param}#{@separator}#{escape_value val}"}
    s << ""
  end
  s.join("\n")
end
write( opts = {} ) click to toggle source

Public: Write the contents of this IniFile to the file system. If left unspecified, the currently configured filename and encoding will be used. Otherwise the filename and encoding can be specified in the options hash.

opts - The default options Hash

:filename - The filename as a String
:encoding - The encoding as a String
:permissions - The permission bits as a Fixnum

Returns this IniFile instance.

# File lib/inifile.rb, line 107
def write( opts = {} )
  filename = opts.fetch(:filename, @filename)
  encoding = opts.fetch(:encoding, @encoding)
  permissions = opts.fetch(:permissions, @permissions)
  mode = encoding ? "w:#{encoding}" : "w"

  File.open(filename, mode, permissions) do |f|
    @ini.each do |section,hash|
      f.puts "[#{section}]"
      hash.each {|param,val|
        if val.class == Hash and val.empty?
          f.puts param
        else
          if !val.is_a?(Array) || !@force_array
            f.puts "#{param}#{@separator}#{@param}#{@separator}#{escape_value val}"
          else
            val.each do |subval|
              f.puts "#{param}#{@separator}#{@param}#{@separator}#{escape_value subval}"
            end
          end
        end
      }
      f.puts
    end
  end

  self
end
Also aliased as: save