actionio-inifile 2.0.3

data/README.md

@@ -0,0 +1,193 @@
+inifile [![Build Status](https://secure.travis-ci.org/TwP/inifile.png)](http://travis-ci.org/TwP/inifile)
+=======
+
+This is a native Ruby package for reading and writing INI files.
+
+
+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.
+
+More information about INI files can be found on the [Wikipedia Page](http://en.wikipedia.org/wiki/INI_file).
+
+### Properties
+
+The basic element contained in an INI file is the property. Every property has
+a name and a value, delimited by an equals sign *=*. The name appears to the
+left of the equals sign and the value to the right.
+
+    name=value
+
+### Sections
+
+Section declarations start with *[* and end with *]* as in `[section1]` and
+`[section2]` shown in the example below. The section declaration marks the
+beginning of a section. All properties after the section declaration will be
+associated with that section.
+
+### Comments
+
+All lines beginning with a semicolon *;* or a number sign *#* are considered
+to be comments. Comment lines are ignored when parsing INI files.
+
+### Example File Format
+
+A typical INI file might look like this:
+
+    [section1]
+    ; some comment on section1
+    var1 = foo
+    var2 = doodle
+    var3 = multiline values \
+    are also possible
+
+    [section2]
+    # another comment
+    var1 = baz
+    var2 = shoodle
+
+
+Implementation
+--------------
+
+The format of INI files is not well defined. Several assumptions are made by
+the **inifile** gem when parsing INI files. Most of these assumptions can be
+modified at, but the defaults are listed below.
+
+### Global Properties
+
+If the INI file lacks any section declarations, or if there are properties
+decalared before the first section, then these properties will be placed into
+a default "global" section. The name of this section can be configured when
+creating an `IniFile` instance.
+
+### Duplicate Properties
+
+Duplicate properties are allowed in a single section. The last property value
+set is the one that will be stored in the `IniFile` instance.
+
+    [section1]
+    var1 = foo
+    var2 = bar
+    var1 = poodle
+
+The resulting value of `var1` will be `poodle`.
+
+### Duplicate Sections
+
+If you have more than one section with the same name then the sections will be
+merged. Duplicate properties between the two sections will follow the rules
+discussed above. Properties in the latter section will override properties in
+the earlier section.
+
+### Comments
+
+The comment character can be either a semicolon *;* or a number sign *#*. The
+comment character can appear anywhere on a line including at the end of a
+name/value pair declaration. If you wish to use a comment character in your
+value then you will need to either escape the character or put the value in
+double quotations.
+
+    [section1]
+    var1 = foo  # a comment
+    var2 = "foo # this is not a comment"
+    var3 = foo \# this is not a comment either
+
+### Multi-Line Values
+
+Values can be continued onto multiple lines in two separate ways. Putting a
+slash at the end of a line will continue the value declaration to the next
+line. When parsing, the trailing slash will be consumed and **will not**
+appear in the resulting value. Comments can appear to the right of the
+trailing slash.
+
+    var1 = this is a \  # these comments will
+    multiline value     # be ignored by the parser
+
+In the above example the resulting value for `var1` will be `this is a
+multiline value`. If you want to preserve newline characters in the value then
+quotations should be used.
+
+    var2 = "this is a
+    multiline value"
+
+The resulting value for `var2` will be `this is a\nmultiline value`.
+
+### Escape Characters
+
+Several escape characters are supported within the **value** for a property.
+These escape sequences will be applied to quoted and unquoted values alike.
+You can enable or disable escaping by setting the **escape** flag to true or
+false when creating an IniFile instance.
+
+* \0 -- null character
+* \n -- newline character
+* \r -- carriage return character
+* \t -- tab character
+* \\\\ -- backslash character
+
+The backslash escape sequence is only needed if you want one of the escape
+sequences to appear literally in your value. For example:
+
+    property = this is not a tab \\t character
+
+
+Install
+-------
+
+    gem install inifile
+
+
+Testing
+-------
+
+To run the tests:
+
+    $ rake
+
+
+Contributing
+------------
+
+Contributions are gladly welcome! For small modifications (fixing typos,
+improving documentation) you can use GitHub's in-browser editing capabilities
+to create a pull request. For larger modifications I would recommend forking
+the project, creating your patch, and then submitting a pull request.
+
+Mr Bones is used to manage rake tasks and to install dependent files. To setup
+your environment ...
+
+    $ gem install bones
+    $ rake gem:install_dependencies
+
+And always remember that `rake -T` will show you the list of available tasks.
+
+
+License
+-------
+
+MIT License
+Copyright (c) 2006 - 2012
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/inifile.rb

@@ -0,0 +1,554 @@
+#encoding: UTF-8
+require 'strscan'
+
+# This class represents the INI file and can be used to parse, modify,
+# and write INI files.
+#
+class IniFile
+  include Enumerable
+
+  class Error < StandardError; end
+  VERSION = '2.0.2'
+
+  # 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.
+ #
+  def self.load( filename, opts = {} )
+    return unless File.file? filename
+    new(opts.merge(:filename => filename))
+  end
+
+  # Get and set the filename
+  attr_accessor :filename
+
+  # Get and set the encoding (Ruby 1.9)
+  attr_accessor :encoding
+
+  # Enable or disable character escaping
+  attr_accessor :escape
+
+  # 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
+  #
+  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: 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.
+  #
+  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
+  alias :save :write
+
+  # 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.
+  #
+  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
+  alias :restore :read
+
+  # Returns this IniFile converted to a String.
+  #
+  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
+
+  # Returns this IniFile converted to a Hash.
+  #
+  def to_h
+    @ini.dup
+  end
+
+  # 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.
+  #
+  def merge( other )
+    self.dup.merge!(other)
+  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.
+  #
+  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: 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.
+  #
+  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.
+  #
+  def each_section
+    return unless block_given?
+    @ini.each_key {|section| yield section}
+    self
+  end
+
+  # Public: Remove a section identified by name from the IniFile.
+  #
+  # section - The section name as a String.
+  #
+  # Returns the deleted section Hash.
+  #
+  def delete_section( section )
+    @ini.delete section.to_s
+  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.
+  #
+  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.
+  #
+  def []=( section, value )
+    @ini[section.to_s] = value
+  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(/^tree_/)
+  #   #=> Hash of matching sections
+  #
+  # Return a Hash containing only those sections that match the given regular
+  # expression.
+  #
+  def match( regex )
+    @ini.dup.delete_if { |section, _| section !~ regex }
+  end
+
+  # 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.
+  #
+  def has_section?( section )
+    @ini.has_key? section.to_s
+  end
+
+  # Returns an Array of section names contained in this IniFile.
+  #
+  def sections
+    @ini.keys
+  end
+
+  # Public: Freeze the state of this IniFile object. Any attempts to change
+  # the object will raise an error.
+  #
+  # Returns this IniFile.
+  #
+  def freeze
+    super
+    @ini.each_value {|h| h.freeze}
+    @ini.freeze
+    self
+  end
+
+  # Public: Mark this IniFile as tainted -- this will traverse each section
+  # marking each as tainted.
+  #
+  # Returns this IniFile.
+  #
+  def taint
+    super
+    @ini.each_value {|h| h.taint}
+    @ini.taint
+    self
+  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.
+  #
+  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: 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.
+  #
+  def clone
+    other = dup
+    other.freeze if self.frozen?
+    other
+  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.
+  #
+  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
+
+  # Parse the ini file contents. This will clear any values currently stored
+  # in the ini hash.
+  #
+  def parse!
+    return unless @content
+
+    string = ''
+    property = ''
+
+    @ini.clear
+    @_line = nil
+    @_section = nil
+
+    scanner = StringScanner.new(@content)
+    until scanner.eos?
+
+      # keep track of the current line for error messages
+      @_line = scanner.check(%r/\A.*$/) if scanner.bol?
+
+      # look for escaped special characters \# \" etc
+      if scanner.scan(%r/\\([\[\]#{@param}#{@comment}"])/)
+        string << scanner[1]
+
+      # look for quoted strings
+      elsif scanner.scan(%r/"/)
+        quote = scanner.scan_until(/(?:\A|[^\\])"/)
+        parse_error('Unmatched quote') if quote.nil?
+
+        quote.chomp!('"')
+        string << quote
+
+      # look for comments, empty strings, end of lines
+      elsif scanner.skip(%r/\A\s*(?:[#{@comment}].*)?$/)
+        string << scanner.getch unless scanner.eos?
+
+        process_property(property, string)
+
+      # look for the separator between property name and value
+      elsif scanner.scan(%r/#{@param}/)
+        if property.empty?
+          property = string.strip
+          string.slice!(0, string.length)
+        else
+          parse_error
+        end
+
+      # look for the start of a new section
+      elsif scanner.scan(%r/\A\s*\[([^\]]+)\]/)
+        @_section = @ini[scanner[1]]
+
+      # otherwise scan and store characters till we hit the start of some
+      # special section like a quote, newline, comment, etc.
+      else
+        tmp = scanner.scan_until(%r/([\n"#{@param}#{@comment}] | \z | \\[\[\]#{@param}#{@comment}"])/mx)
+        parse_error if tmp.nil?
+
+        len = scanner[1].length
+        tmp.slice!(tmp.length - len, len)
+
+        scanner.pos = scanner.pos - len
+        string << tmp
+      end
+    end
+
+    process_property(property, string)
+  end
+
+  # Store the property / value pair in the currently active section. This
+  # method checks for continuation of the value to the next line.
+  #
+  # property - The property name as a String.
+  # value    - The property value as a String.
+  #
+  # Returns nil.
+  #
+  def process_property( property, value )
+    value.chomp!
+    return if property.empty? and value.empty?
+    return if value.sub!(%r/\\\s*\z/, '')
+
+    property.strip!
+    value.strip!
+
+    if property.empty?
+      current_section['values'] ||= []
+      current_section['values'] << value
+    else
+      current_section[property.dup] = unescape_value(value.dup)
+    end
+
+    property.slice!(0, property.length)
+    value.slice!(0, value.length)
+
+    nil
+  end
+
+  # Returns the current section Hash.
+  #
+  def current_section
+    @_section ||= @ini[@default]
+  end
+
+  # Raise a parse error using the given message and appending the current line
+  # being parsed.
+  #
+  # msg - The message String to use.
+  #
+  # Raises IniFile::Error
+  #
+  def parse_error( msg = 'Could not parse line' )
+    raise Error, "#{msg}: #{@_line.inspect}"
+  end
+
+  # Unescape special characters found in the value string. This will convert
+  # escaped null, tab, carriage return, newline, and backslash into their
+  # literal equivalents.
+  #
+  # value - The String value to unescape.
+  #
+  # Returns the unescaped value.
+  #
+  def unescape_value( value )
+    return value unless @escape
+
+    value = value.to_s
+    value.gsub!(%r/\\[0nrt\\]/) { |char|
+      case char
+      when '\0';   "\0"
+      when '\n';   "\n"
+      when '\r';   "\r"
+      when '\t';   "\t"
+      when '\\\\'; "\\"
+      end
+    }
+    value
+  end
+
+  # Escape special characters.
+  #
+  # value - The String value to escape.
+  #
+  # Returns the escaped value.
+  #
+  def escape_value( value )
+    return value unless @escape
+
+    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
+
+end  # IniFile

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: actionio-inifile
+version: !ruby/object:Gem::Version
+  version: 2.0.3
+  prerelease: 
+platform: ruby
+authors:
+- Tim Pease
+- Wong Liang Zan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bones-git
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Parses ansible ini files
+email:
+- zan@liangzan.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/inifile.rb
+- README.md
+homepage: http://github.com/action-io/inifile
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Parses ansible ini files.
+test_files: []