class Hashery::IniHash

Hash class with methods to read from and write into ini files.

A ini file is a text file in a specific format, it may include several fields which are sparated by field headlines which are enclosured by “[]”. Each field may include several key-value pairs.

Each key-value pair is represented by one line and the value is sparated from the key by a “=”.

Examples¶ ↑

Example ini file¶ ↑

# this is the first comment which will be saved in the comment attribute
mail=info@example.com
domain=example.com # this is a comment which will not be saved
[database]
db=example
user=john
passwd=very-secure
host=localhost
# this is another comment
[filepaths]
tmp=/tmp/example
lib=/home/john/projects/example/lib
htdocs=/home/john/projects/example/htdocs
[ texts ]
wellcome=Wellcome on my new website!
Website description = This is only a example. # and another comment

Example object¶ ↑

Ini#comment stores:

"this is the first comment which will be saved in the comment attribute"

Ini’s internal hash stores:

{
 "mail" => "info@example.com",
 "domain" => "example.com",
 "database" => {
  "db" => "example",
  "user" => "john",
  "passwd" => "very-secure",
  "host" => "localhost"
 },
 "filepaths" => {
  "tmp" => "/tmp/example",
  "lib" => "/home/john/projects/example/lib",
  "htdocs" => "/home/john/projects/example/htdocs"
 }
 "texts" => {
  "wellcome" => "Wellcome on my new website!",
  "Website description" => "This is only a example."
 }
}

As you can see this module gets rid of all comments, linebreaks and unnecessary spaces at the beginning and the end of each field headline, key or value.

Using the object¶ ↑

Using the object is stright forward:

ini = IniHash.new("path/settings.ini")
ini["mail"] = "info@example.com"
ini["filepaths"] = { "tmp" => "/tmp/example" }
ini.comment = "This is\na comment"
puts ini["filepaths"]["tmp"]
# => /tmp/example
ini.write()

Acknowlegements¶ ↑

IniHash is based on ini.rb.

Attributes

comment[RW]

The string which holds the comments on the top of the file

inihash[RW]

The hash which holds all INI data.

Public Class Methods

load(path, load=true) click to toggle source

NOTE: In future versions, ‘#new` will not take a path, and `#load` will have to be used.

# File lib/hashery/ini_hash.rb, line 92
def self.load(path, load=true)
  new(path, load)
end

new(path, load=nil) click to toggle source

Creating a new IniHash object.

path - is a path to the ini file load - if nil restores the data if possible

if true restores the data, if not possible raises an error
if false does not resotre the data

# File lib/hashery/ini_hash.rb, line 114
def initialize(path, load=nil)
  @path    = path if String === path
  @inihash = (Hash === path ? path.dup : {})

  if load or ( load.nil? and FileTest.readable_real? @path )
    restore()
  end
end

read_comment_from_file(path) click to toggle source

Reading comments from file

path - a path to the INI file

Returns a ‘String` with the comments from the beginning of the INI file.

# File lib/hashery/ini_hash.rb, line 261
def self.read_comment_from_file(path)
  comment = ""
  
  IO.foreach(path) do |line|
    line.strip!

    break unless line[0,1] == "#" or line == ""

    comment_line = line[1, line.length].to_s
    comment << "#{comment_line.strip}\n"
  end
  
  comment
end

read_from_file(path) click to toggle source

Reading data from file

path - a path to the ini file

Returns a ‘Hash` which represents the data from the file.

# File lib/hashery/ini_hash.rb, line 218
def self.read_from_file(path)
  raise "file not found - #{path}" unless File.file?(path)

  inihash = {}
  headline = nil

  IO.foreach(path) do |line|
    line = line.strip.split(/#/)[0].to_s

    # read it only if the line doesn't begin with a "=" and is long enough
    unless line.length < 2 and line[0,1] == "="
      
      # it's a headline if the line begins with a "[" and ends with a "]"
      if line[0,1] == "[" and line[line.length - 1, line.length] == "]"

        # get rid of the [] and unnecessary spaces
        headline = line[1, line.length - 2 ].strip
        inihash[headline] = {}
      else
        key, value = line.split(/=/, 2)
        
        key = key.strip unless key.nil?
        value = value.strip unless value.nil?
        
        unless headline.nil?
          inihash[headline][key] = value
        else
          inihash[key] = value unless key.nil?
        end
      end        
    end
  end
  
  inihash
end

text(inihash={}) click to toggle source

Turn a hash (up to 2 levels deepness) into a ini string

inihash - Hash representing the ini File. Default is a empty hash.

Returns a String in the ini file format.

TODO: Rename ‘IniHash.text` method to something else ?

# File lib/hashery/ini_hash.rb, line 310
def self.text(inihash={})
  new(inihash).to_s
end

Also aliased as: to_s

to_s(inihash={})

@deprecated

Alias for: text

write_to_file(path, inihash={}, comment=nil) click to toggle source

Writing a ini hash into a file

path - Path to the INI file. inihash - Hash representing the ini File. Default is a empty hash. comment - String with comments which appear on the

top of the file. Each line will get a "#" before.
Default is no comment.

# File lib/hashery/ini_hash.rb, line 285
def self.write_to_file(path, inihash={}, comment=nil)
  raise TypeError, "String expected" unless comment.is_a? String or comment.nil?
  
  raise TypeError, "Hash expected" unless inihash.is_a? Hash
  File.open(path, "w") { |file|
    
    unless comment.nil?
      comment.each do |line|
        file << "# #{line}"
      end
    end

    file << IniHash.text(inihash)
  }
end

Public Instance Methods

[](key) click to toggle source

Retrive the ini data for the key key

# File lib/hashery/ini_hash.rb, line 126
def [](key)
  @inihash[key]
end

[]=(key, value) click to toggle source

Set the ini data for the key key

key - Index key. value - The value to index.

Returns value.

# File lib/hashery/ini_hash.rb, line 138
def []=(key, value)
  #raise TypeError, "String expected" unless key.is_a? String
  key = key.to_str
 
  #raise TypeError, "String or Hash expected" unless value.is_a? String or value.is_a? Hash
  value = value.to_str unless Hash === value

  @inihash[key] = value
end

inspect()

Alias for: to_s

method_missing(s,*a,&b) click to toggle source

Delegate missing mthods to underlying Hash.

TODO: Sublcass Hash instead of delegating.

# File lib/hashery/ini_hash.rb, line 207
def method_missing(s,*a,&b)
  @inihash.send(s, *a, &b) if @inihash.respond_to?(s)
end

restore() click to toggle source

Restores the data from file into the object

# File lib/hashery/ini_hash.rb, line 151
def restore
  @inihash = IniHash.read_from_file(@path)
  @comment = IniHash.read_comment_from_file(@path)
end

save() click to toggle source

Store data from the object in the file.

# File lib/hashery/ini_hash.rb, line 159
def save
  IniHash.write_to_file(@path, @inihash, @comment)
end

to_h() click to toggle source

Convert to hash by duplicating the underlying hash table.

# File lib/hashery/ini_hash.rb, line 174
def to_h
  @inihash.dup
end

to_s() click to toggle source

Turn a hash (up to 2 levels deepness) into a ini string

inihash - Hash representing the ini File. Default is a empty hash.

Returns a string in the ini file format.

# File lib/hashery/ini_hash.rb, line 187
def to_s
  str = ""
  inihash.each do |key, value|
    if value.is_a? Hash
      str << "[#{key.to_s}]\n"
      value.each do |under_key, under_value|
        str << "#{under_key.to_s}=#{under_value.to_s unless under_value.nil?}\n"
      end
    else
      str << "#{key.to_s}=#{value.to_s unless value.nil?}\n"
    end
  end
  str
end

Also aliased as: inspect

update() click to toggle source

Deprecated: Save INI data to file path. Use save instead.

# File lib/hashery/ini_hash.rb, line 166
def update
  warn 'IniHash#update is deprecated for this use, use IniHash#save instead.'
  save
end