Class: IniFile

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/inifile.rb

Overview

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

Defined Under Namespace

Classes: Error, Parser

Constant Summary

VERSION =
'3.0.0'

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (IniFile) initialize(content = nil, opts = {})

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)
: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


70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
# File 'lib/inifile.rb', line 70

def initialize( content = nil, opts = {} )
  opts, content = content, nil if Hash === content

  @comment  = opts.fetch(:comment, ';#')
  @param    = opts.fetch(:parameter, '=')
  @encoding = opts.fetch(:encoding, nil)
  @default  = opts.fetch(:default, 'global')
  @filename = opts.fetch(:filename, nil)

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

  if    content   then parse(content)
  elsif @filename then read
  end
end

Instance Attribute Details

- (Object) encoding

Get and set the encoding (Ruby 1.9)



40
41
42
# File 'lib/inifile.rb', line 40

def encoding
  @encoding
end

- (Object) filename

Get and set the filename



37
38
39
# File 'lib/inifile.rb', line 37

def filename
  @filename
end

Class Method Details

+ (Object) load(filename, opts = {})

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 (Ruby 1.9)
: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 instance or nil if the file could not be opened.



31
32
33
34
# File 'lib/inifile.rb', line 31

def self.load( filename, opts = {} )
  return unless File.file? filename
  new(opts.merge(:filename => filename))
end

Instance Method Details

- (Object) [](section)

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.



248
249
250
251
# File 'lib/inifile.rb', line 248

def []( section )
  return nil if section.nil?
  @ini[section.to_s]
end

- (Object) []=(section, value)

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.



264
265
266
# File 'lib/inifile.rb', line 264

def []=( section, value )
  @ini[section.to_s] = value
end

- (Object) clone

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.



339
340
341
342
343
# File 'lib/inifile.rb', line 339

def clone
  other = dup
  other.freeze if self.frozen?
  other
end

- (Object) delete_section(section)

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

section - The section name as a String.

Returns the deleted section Hash.



233
234
235
# File 'lib/inifile.rb', line 233

def delete_section( section )
  @ini.delete section.to_s
end

- (Object) dup

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.



325
326
327
328
329
330
331
# File 'lib/inifile.rb', line 325

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

- (Object) each

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.



200
201
202
203
204
205
206
207
208
# File 'lib/inifile.rb', line 200

def each
  return unless block_given?
  @ini.each do |section,hash|
    hash.each do |param,val|
      yield section, param, val
    end
  end
  self
end

- (Object) each_section

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.



222
223
224
225
226
# File 'lib/inifile.rb', line 222

def each_section
  return unless block_given?
  @ini.each_key {|section| yield section}
  self
end

- (Boolean) eql?(other) Also known as: ==

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.



352
353
354
355
356
# File 'lib/inifile.rb', line 352

def eql?( other )
  return true if equal? other
  return false unless other.instance_of? self.class
  @ini == other.instance_variable_get(:@ini)
end

- (Object) escape_value(value)

Escape special characters.

value - The String value to escape.

Returns the escaped value.



364
365
366
367
368
369
370
371
372
# File 'lib/inifile.rb', line 364

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

- (Object) freeze

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

Returns this IniFile.



302
303
304
305
306
307
# File 'lib/inifile.rb', line 302

def freeze
  super
  @ini.each_value {|h| h.freeze}
  @ini.freeze
  self
end

- (Boolean) has_section?(section)

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.



289
290
291
# File 'lib/inifile.rb', line 289

def has_section?( section )
  @ini.has_key? section.to_s
end

- (Object) match(regex)

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.



280
281
282
# File 'lib/inifile.rb', line 280

def match( regex )
  @ini.dup.delete_if { |section, _| section !~ regex }
end

- (Object) merge(other)

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.



157
158
159
# File 'lib/inifile.rb', line 157

def merge( other )
  self.dup.merge!(other)
end

- (Object) merge!(other)

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.



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
# File 'lib/inifile.rb', line 168

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

- (Object) parse(content)



376
377
378
379
380
# File 'lib/inifile.rb', line 376

def parse( content )
  parser = Parser.new(@ini, @param, @comment, @default)
  parser.parse(content)
  self
end

- (Object) read(opts = {}) Also known as: restore

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.



124
125
126
127
128
129
130
131
132
# File 'lib/inifile.rb', line 124

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

- (Object) sections

Returns an Array of section names contained in this IniFile.



294
295
296
# File 'lib/inifile.rb', line 294

def sections
  @ini.keys
end

- (Object) taint

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

Returns this IniFile.



313
314
315
316
317
318
# File 'lib/inifile.rb', line 313

def taint
  super
  @ini.each_value {|h| h.taint}
  @ini.taint
  self
end

- (Object) to_h

Returns this IniFile converted to a Hash.



147
148
149
# File 'lib/inifile.rb', line 147

def to_h
  @ini.dup
end

- (Object) to_s

Returns this IniFile converted to a String.



136
137
138
139
140
141
142
143
144
# File 'lib/inifile.rb', line 136

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

- (Object) write(opts = {}) Also known as: save

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

Returns this IniFile instance.



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
# File 'lib/inifile.rb', line 95

def write( opts = {} )
  filename = opts.fetch(:filename, @filename)
  encoding = opts.fetch(:encoding, @encoding)
  mode = encoding ? "w:#{encoding}" : "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