iniparse 0.2.1

data/lib/iniparse/line_collection.rb

@@ -0,0 +1,164 @@
+module IniParse
+  # Represents a collection of lines in an INI document.
+  #
+  # LineCollection acts a bit like an Array/Hash hybrid, allowing arbitrary
+  # lines to be added to the collection, but also indexes the keys of Section
+  # and Option lines to enable O(1) lookup via LineCollection#[].
+  #
+  # The lines instances are stored in an array, +@lines+, while the index of
+  # each Section/Option is held in a Hash, +@indicies+, keyed with the
+  # Section/Option#key value (see LineCollection#[]=).
+  #
+  module LineCollection
+    include Enumerable
+
+    def initialize
+      @lines    = []
+      @indicies = {}
+    end
+
+    # Retrive a value identified by +key+.
+    def [](key)
+      has_key?(key) ? @lines[ @indicies[key] ] : nil
+    end
+
+    # Set a +value+ identified by +key+.
+    #
+    # If a value with the given key already exists, the value will be replaced
+    # with the new one, with the new value taking the position of the old.
+    #
+    def []=(key, value)
+      key = key.to_s
+
+      if has_key?(key)
+        @lines[ @indicies[key] ] = value
+      else
+        @lines << value
+        @indicies[key] = @lines.length - 1
+      end
+    end
+
+    # Appends a line to the collection.
+    #
+    # Note that if you pass a line with a key already represented in the
+    # collection, the old item will be replaced.
+    #
+    def <<(line)
+      line.blank? ? (@lines << line) : (self[line.key] = line) ; self
+    end
+
+    alias_method :push, :<<
+
+    # Enumerates through the collection.
+    #
+    # By default #each does not yield blank and comment lines.
+    #
+    # ==== Parameters
+    # include_blank<Boolean>:: Include blank/comment lines?
+    #
+    def each(include_blank = false)
+      @lines.each do |line|
+        yield(line) if include_blank || (! line.blank?)
+      end
+    end
+
+    # Removes the value identified by +key+.
+    def delete(key)
+      unless (idx = @indicies[key]).nil?
+        @indicies.delete(key)
+        @indicies.each { |k,v| @indicies[k] = v -= 1 if v > idx }
+        @lines.delete_at(idx)
+      end
+    end
+
+    # Returns whether +key+ is in the collection.
+    def has_key?(*args)
+      @indicies.has_key?(*args)
+    end
+
+    # Return an array containing the keys for the lines added to this
+    # collection.
+    def keys
+      map { |line| line.key }
+    end
+
+    # Returns this collection as an array. Includes blank and comment lines.
+    def to_a
+      @lines.dup
+    end
+
+    # Returns this collection as a hash. Does not contain blank and comment
+    # lines.
+    def to_hash
+      Hash[ map { |line| [line.key, line] } ]
+    end
+
+    alias_method :to_h, :to_hash
+  end
+
+  # A implementation of LineCollection used for storing (mostly) Option
+  # instances contained within a Section.
+  #
+  # Since it is assumed that an INI document will only represent a section
+  # once, if SectionCollection encounters a Section key already held in the
+  # collection, the existing section is merged with the new one (see
+  # IniParse::Lines::Section#merge!).
+  class SectionCollection
+    include LineCollection
+
+    def <<(line)
+      if line.kind_of?(IniParse::Lines::Option)
+        raise IniParse::LineNotAllowed,
+          "You can't add an Option to a SectionCollection."
+      end
+
+      if line.blank? || (! has_key?(line.key))
+        super # Adding a new section, comment or blank line.
+      else
+        self[line.key].merge!(line)
+      end
+
+      self
+    end
+  end
+
+  # A implementation of LineCollection used for storing (mostly) Option
+  # instances contained within a Section.
+  #
+  # Whenever OptionCollection encounters an Option key already held in the
+  # collection, it treats it as a duplicate. This means that instead of
+  # overwriting the existing value, the value is changed to an array
+  # containing the previous _and_ the new Option instances.
+  class OptionCollection
+    include LineCollection
+
+    # Appends a line to the collection.
+    #
+    # If you push an Option with a key already represented in the collection,
+    # the previous Option will not be overwritten, but treated as a duplicate.
+    #
+    # ==== Parameters
+    # line<IniParse::LineType::Line>:: The line to be added to this section.
+    #
+    def <<(line)
+      if line.kind_of?(IniParse::Lines::Section)
+        raise IniParse::LineNotAllowed,
+          "You can't add a Section to an OptionCollection."
+      end
+
+      if line.blank? || (! has_key?(line.key))
+        super # Adding a new option, comment or blank line.
+      else
+        self[line.key] = [self[line.key], line].flatten
+      end
+
+      self
+    end
+
+    # Return an array containing the keys for the lines added to this
+    # collection.
+    def keys
+      map { |line| line.kind_of?(Array) ? line.first.key : line.key }
+    end
+  end
+end

data/lib/iniparse/lines.rb

@@ -0,0 +1,290 @@
+module IniParse
+  module Lines
+    # A base class from which other line types should inherit.
+    module Line
+      # ==== Parameters
+      # opts<Hash>:: Extra options for the line.
+      #
+      def initialize(opts = {})
+        @comment        = opts.fetch(:comment, nil)
+        @comment_sep    = opts.fetch(:comment_sep, ';')
+        @comment_offset = opts.fetch(:comment_offset, 0)
+        @indent         = opts.fetch(:indent, '')
+      end
+
+      # Returns if this line has an inline comment.
+      def has_comment?
+        not @comment.nil?
+      end
+
+      # Returns this line as a string as it would be represented in an INI
+      # document.
+      def to_ini
+        ini = line_contents
+        ini = @indent + ini if @indent
+
+        if has_comment?
+          ini += ' ' unless ini.blank?
+          ini  = ini.ljust(@comment_offset)
+          ini += comment
+        end
+
+        ini
+      end
+
+      # Returns the contents for this line.
+      def line_contents
+        ''
+      end
+
+      # Returns the inline comment for this line. Includes the comment
+      # separator at the beginning of the string.
+      def comment
+        '%s %s' % [@comment_sep, @comment]
+      end
+    end
+
+    # Represents a section header in an INI document. Section headers consist
+    # of a string of characters wrapped in square brackets.
+    #
+    #   [section]
+    #   key=value
+    #   etc
+    #   ...
+    #
+    class Section
+      include Line
+
+      @regex = /^\[        # Opening bracket
+                 ([^\]]+)  # Section name
+                 \]$       # Closing bracket
+               /x
+
+      attr_accessor :key
+      attr_reader   :lines
+
+      include Enumerable
+
+      # ==== Parameters
+      # key<String>:: The section name.
+      # opts<Hash>::  Extra options for the line.
+      #
+      def initialize(key, opts = {})
+        super(opts)
+        @key   = key.to_s
+        @lines = IniParse::OptionCollection.new
+      end
+
+      def self.parse(line, opts)
+        if m = @regex.match(line)
+          [:section, m[1], opts]
+        end
+      end
+
+      # Returns this line as a string as it would be represented in an INI
+      # document. Includes options, comments and blanks.
+      def to_ini
+        coll = lines.to_a
+
+        if coll.any?
+          super + $/ + coll.to_a.map do |line|
+            if line.kind_of?(Array)
+              line.map { |dup_line| dup_line.to_ini }.join($/)
+            else
+              line.to_ini
+            end
+          end.join($/)
+        else
+          super
+        end
+      end
+
+      # Enumerates through each Option in this section.
+      #
+      # Does not yield blank and comment lines by default; if you want _all_
+      # lines to be yielded, pass true.
+      #
+      # ==== Parameters
+      # include_blank<Boolean>:: Include blank/comment lines?
+      #
+      def each(*args, &blk)
+        @lines.each(*args, &blk)
+      end
+
+      # Adds a new option to this section, or updates an existing one.
+      #
+      # Note that +[]=+ has no knowledge of duplicate options and will happily
+      # overwrite duplicate options with your new value.
+      #
+      #   section['an_option']
+      #     # => ['duplicate one', 'duplicate two', ...]
+      #   section['an_option'] = 'new value'
+      #   section['an_option]
+      #     # => 'new value'
+      #
+      # If you do not wish to overwrite duplicates, but wish instead for your
+      # new option to be considered a duplicate, use +add_option+ instead.
+      #
+      def []=(key, value)
+        @lines[key.to_s] = IniParse::Lines::Option.new(key.to_s, value)
+      end
+
+      # Returns the value of an option identified by +key+.
+      #
+      # Returns nil if there is no corresponding option. If the key provided
+      # matches a set of duplicate options, an array will be returned containing
+      # the value of each option.
+      #
+      def [](key)
+        key = key.to_s
+
+        if @lines.has_key?(key)
+          if (match = @lines[key]).kind_of?(Array)
+            match.map { |line| line.value }
+          else
+            match.value
+          end
+        end
+      end
+
+      # Like [], except instead of returning just the option value, it returns
+      # the matching line instance.
+      #
+      # Will return an array of lines if the key matches a set of duplicates.
+      #
+      def option(key)
+        @lines[key.to_s]
+      end
+
+      # Returns true if an option with the given +key+ exists in this section.
+      def has_option?(key)
+        @lines.has_key?(key.to_s)
+      end
+
+      # Merges section +other+ into this one. If the section being merged into
+      # this one contains options with the same key, they will be handled as
+      # duplicates.
+      #
+      # ==== Parameters
+      # other<IniParse::Section>:: The section to merge into this one.
+      #
+      def merge!(other)
+        other.lines.each(true) do |line|
+          if line.kind_of?(Array)
+            line.each { |duplicate| @lines << duplicate }
+          else
+            @lines << line
+          end
+        end
+      end
+
+      #######
+      private
+      #######
+
+      def line_contents
+        '[%s]' % key
+      end
+    end
+
+    # Represents probably the most common type of line in an INI document:
+    # an option. Consists of a key and value, usually separated with an =.
+    #
+    #   key = value
+    #
+    class Option
+      include Line
+
+      @regex = /^(.*)     # Key
+                 =
+                 (.*?)$   # Value
+               /x
+
+      attr_accessor :key, :value
+
+      # ==== Parameters
+      # key<String>::   The option key.
+      # value<String>:: The value for this option.
+      # opts<Hash>::    Extra options for the line.
+      #
+      def initialize(key, value, opts = {})
+        super(opts)
+        @key, @value = key.to_s, value
+      end
+
+      def self.parse(line, opts)
+        if m = @regex.match(line)
+          [:option, m[1].strip, typecast(m[2].strip), opts]
+        end
+      end
+
+      # Attempts to typecast values.
+      def self.typecast(value)
+        case value
+          when /^\s*$/                                        then nil
+          when /^-?(?:\d|[1-9]\d+)$/                          then Integer(value)
+          when /^-?(?:\d|[1-9]\d+)(?:\.\d+)?(?:e[+-]?\d+)?$/i then Float(value)
+          when /true/i                                        then true
+          when /false/i                                       then false
+          else                                                     value
+        end
+      end
+
+      #######
+      private
+      #######
+
+      def line_contents
+        '%s = %s' % [key, value]
+      end
+    end
+
+    # Represents a blank line. Used so that we can preserve blank lines when
+    # writing back to the file.
+    class Blank
+      include Line
+
+      def blank?
+        true
+      end
+
+      def self.parse(line, opts)
+        if line.blank?
+          if opts[:comment].nil?
+            [:blank]
+          else
+            [:comment, opts[:comment], opts]
+          end
+        end
+      end
+    end
+
+    # Represents a comment. Comment lines begin with a semi-colon or hash.
+    #
+    #   ; this is a comment
+    #   # also a comment
+    #
+    class Comment < Blank
+      # Returns if this line has an inline comment.
+      #
+      # Being a Comment this will always return true, even if the comment
+      # is nil. This would be the case if the line starts with a comment
+      # seperator, but has no comment text. See spec/fixtures/smb.ini for a
+      # real-world example.
+      #
+      def has_comment?
+        true
+      end
+
+      # Returns the inline comment for this line. Includes the comment
+      # separator at the beginning of the string.
+      #
+      # In rare cases where a comment seperator appeared in the original file,
+      # but without a comment, just the seperator will be returned.
+      #
+      def comment
+        @comment.blank? ? @comment_sep : super
+      end
+    end
+  end # Lines
+end # IniParse