This class represents the INI file and can be used to parse, modify, and write INI files.
Get and set the encoding (Ruby 1.9)
Enable or disable character escaping
Get and set the filename
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
Examples
IniFile.load('file.ini') #=> IniFile instance IniFile.load('does/not/exist.ini') #=> nil
Returns an IniFile intsnace or nil if the file could not be opened.
# File lib/inifile.rb, line 32 def self.load( filename, opts = {} ) return unless File.file? filename new(opts.merge(:filename => filename)) end
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 IniFile.new( "[global]\nfoo=bar" ) #=> an IniFile instance IniFile.new( :filename => 'file.ini', :encoding => 'UTF-8' ) #=> an IniFile instance IniFile.new( "[global]\nfoo=bar", :comment => '#' ) #=> an IniFile instance
# File lib/inifile.rb, line 75 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') @filename = opts.fetch(:filename, nil) @ini = Hash.new {|h,k| h[k] = Hash.new} if @content then parse! elsif @filename then read end 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
inifile['global'] #=> global section Hash
Returns the Hash of parameter/value pairs for this section.
# File lib/inifile.rb, line 275 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
inifile['tenderloin'] = { 'gritty' => 'yes' } #=> { 'gritty' => 'yes' }
Returns the value Hash.
# File lib/inifile.rb, line 292 def []=( section, value ) @ini[section.to_s] = value end
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 374 def clone other = dup other.freeze if self.frozen? other end
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 259 def delete_section( section ) @ini.delete section.to_s end
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.
# File lib/inifile.rb, line 359 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
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 224 def each return unless block_given? @ini.each do |section,hash| hash.each do |param,val| yield section, param, val end end 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.
Examples
inifile.each_section do |section| puts section.inspect end
Returns this IniFile.
# File lib/inifile.rb, line 247 def each_section return unless block_given? @ini.each_key {|section| yield section} self 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.
other - The other IniFile.
Returns true if the INI files are equivalent and false if they differ.
# File lib/inifile.rb, line 388 def eql?( other ) return true if equal? other return false unless other.instance_of? self.class @ini == other.instance_variable_get(:@ini) end
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(%r^tree_/) #=> Hash of matching sections
Return a Hash containing only those sections that match the given regular expression.
# File lib/inifile.rb, line 309 def match( regex ) @ini.dup.delete_if { |section, _| section !~ regex } end
Public: Merges other_inifile into this inifile, overwriting existing entries. Useful for having a system inifile with user over-ridable settings elsewhere.
other - The other IniFile.
Returns this IniFile.
# File lib/inifile.rb, line 191 def merge!( other ) my_keys = @ini.keys other_keys = case other when IniFile; other.instance_variable_get(:@ini).keys when Hash; other.keys else raise "cannot merge contents from '#{other.class.name}'" end (my_keys & other_keys).each do |key| @ini[key].merge!(other[key]) end (other_keys - my_keys).each do |key| @ini[key] = other[key] end self end
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 (Ruby 1.9)
Returns this IniFile instance if the read was successful; nil is returned if the file could not be read.
# File lib/inifile.rb, line 136 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
Returns an Array of section names contained in this IniFile.
# File lib/inifile.rb, line 325 def sections @ini.keys end
Returns this IniFile converted to a Hash.
# File lib/inifile.rb, line 168 def to_h @ini.dup end
Returns this IniFile converted to a String.
# File lib/inifile.rb, line 156 def to_s s = [] @ini.each do |section,hash| s << "[#{section}]" hash.each {|param,val| s << "#{param} #{@param} #{escape_value val}"} s << "" end s.join("\n") 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.
opts - The default options Hash
:filename - The filename as a String :encoding - The encoding as a String (Ruby 1.9)
Returns this IniFile instance.
# File lib/inifile.rb, line 104 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(filename, mode) do |f| @ini.each do |section,hash| f.puts "[#{section}]" hash.each {|param,val| f.puts "#{param} #{@param} #{escape_value val}"} f.puts end end self end