iniparse 0.2.1

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008-2009 Anthony Williams
+
+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/README.rdoc

@@ -0,0 +1,75 @@
+= IniParse
+
+IniParse is a pure Ruby library for parsing
+INI[http://en.wikipedia.org/wiki/INI_file] configuration and data
+files.
+
+This rubygem is in ongoing development and - specs aside - hasn't yet been
+properly tested in a production environment. If you think you've found a bug,
+or you feed it an INI file which doesn't work as you'd expected, please mail
+me at +anthony at ninecraft dot com+, ideally with a copy of the INI file in
+question.
+
+=== Main features
+
+* <b>Support for duplicate options.</b> While not common, some INI files
+  contain an option more than once. IniParse does not overwrite previous
+  options, but allows you to access all of the duplicate values.
+
+* <b>Preservation of white space and blank lines.</b> When writing back to
+  your INI file, line indents, white space and comments (and their indents)
+  are preserved. Only trailing white space (which has no significance in INI
+  files) will be removed.
+
+* <b>Preservation of section and option ordering.</b> Sections and options
+  are kept in the same order they are in the original document ensuring that
+  nothing gets mangled when writing back to the file.
+
+If you don't need the above mentioned features, you may find the simpler
+IniFile gem does all you need.
+
+=== Opening an INI file
+
+Parsing an INI file is fairly simple:
+
+    IniParse.parse( File.open('path/to/my/file.ini') ) # => IniParse::Document
+
+IniParse.parse returns an IniParse::Document instance which represents the
+passed "INI string". Assuming you know the structure of the document, you can
+access the sections in the INI document with IniParse::Document#[]. For
+example:
+
+    document = IniParse.parse( File.read('path/to/my/file.ini') )
+
+    document['a_section']
+      # => IniParse::Lines::Section
+
+    document['a_section']['an_option']
+      # => "a value"
+    document['a_section']['another_option']
+      # => "another value"
+
+In the event that duplicate options were found, an array of the values will
+be supplied to you.
+
+    document = IniParse.parse <<-EOS
+      [my_section]
+      key = value
+      key = another value
+      key = a third value
+    EOS
+
+    document['my_section']['key']
+      # => ['value', 'another value', 'third value']
+
+=== Updating an INI file
+
+    document['a_section']['an_option']
+      # => "a value"
+    document['a_section']['an_option'] = 'a new value'
+    document['a_section']['an_option']
+      # => "a new value"
+
+=== Creating a new INI file
+
+See IniParse::Generator.

data/Rakefile

@@ -0,0 +1,102 @@
+require 'rubygems'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'date'
+require 'spec/rake/spectask'
+
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
+require 'lib/iniparse/version'
+
+GEM = 'iniparse'
+GEM_VERSION = IniParse::VERSION
+
+##############################################################################
+# Packaging & Installation
+##############################################################################
+
+CLEAN.include ['pkg', '*.gem', 'doc', 'coverage']
+
+spec = Gem::Specification.new do |s|
+  s.name        = GEM
+  s.version     = GEM_VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.summary     = "A pure Ruby library for parsing INI documents."
+  s.description = s.summary
+  s.author      = 'Anthony Williams'
+  s.email       = 'anthony@ninecraft.com'
+  s.homepage    = 'http://github.com/anthonyw/iniparse'
+
+  # rdoc
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w(README.rdoc LICENSE)
+
+  # Dependencies
+  s.add_dependency 'extlib', '>= 0.9.9'
+
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README.rdoc Rakefile) + Dir.glob("{lib,spec}/**/*")
+  
+  s.rubyforge_project = 'iniparse'
+end
+
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Run :package and install the resulting .gem"
+task :install => :package do
+  sh %(gem install --local pkg/#{GEM}-#{GEM_VERSION}.gem)
+end
+
+desc "Run :clean and uninstall the .gem"
+task :uninstall => :clean do
+  sh %(gem uninstall #{GEM})
+end
+
+desc "Create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+##############################################################################
+# Documentation
+##############################################################################
+task :doc => ['doc:rdoc']
+namespace :doc do
+
+  Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_files.add(%w(LICENSE README.rdoc lib/**/*.rb))
+    rdoc.main = "README.rdoc"
+    rdoc.title = "IniParse API Documentation"
+    rdoc.options << "--line-numbers" << "--inline-source"
+    rdoc.rdoc_dir = 'doc'
+  end
+
+end
+
+##############################################################################
+# rSpec & rcov
+##############################################################################
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ['-c -f s']
+end
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('spec:rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ['-c -f s']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end

data/lib/iniparse.rb

@@ -0,0 +1,68 @@
+require 'rubygems'
+require 'extlib'
+
+dir = Pathname(__FILE__).dirname.expand_path / 'iniparse'
+
+require dir / 'document'
+require dir / 'generator'
+require dir / 'line_collection'
+require dir / 'lines'
+require dir / 'parser'
+require dir / 'version'
+
+module IniParse
+  # A base class for IniParse errors.
+  class IniParseError < StandardError; end
+
+  # Raised if an error occurs parsing an INI document.
+  class ParseError < IniParseError; end
+
+  # Raised when an option line is found during parsing before the first
+  # section.
+  class NoSectionError < ParseError; end
+
+  # Raised when a line is added to a collection which isn't allowed (e.g.
+  # adding a Section line into an OptionCollection).
+  class LineNotAllowed < IniParseError; end
+
+  module_function
+
+  # Parse given given INI document source +source+.
+  #
+  # See IniParse::Parser.parse
+  #
+  # ==== Parameters
+  # source<String>:: The source from the INI document.
+  #
+  # ==== Returns
+  # IniParse::Document
+  #
+  def parse(source)
+    IniParse::Parser.new(source).parse
+  end
+
+  # Opens the file at +path+, reads and parses it's contents.
+  #
+  # ==== Parameters
+  # path<String>:: The path to the INI document.
+  #
+  # ==== Returns
+  # IniParse::Document
+  #
+  def open(path)
+    document = IniParse::Parser.new(File.read(path)).parse
+    document.path = path
+    document
+  end
+
+  # Creates a new IniParse::Document using the specification you provide.
+  #
+  # See IniParse::Generator.
+  #
+  # ==== Returns
+  # IniParse::Document
+  #
+  def gen(&blk)
+    IniParse::Generator.new.gen(&blk)
+  end
+end

data/lib/iniparse/document.rb

@@ -0,0 +1,62 @@
+module IniParse
+  # Represents an INI document.
+  class Document
+    attr_reader   :lines
+    attr_accessor :path
+
+    # Creates a new Document instance.
+    def initialize(path = nil)
+      @path  = path
+      @lines = IniParse::SectionCollection.new
+    end
+
+    # Enumerates through each Section in this document.
+    #
+    # 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
+
+    # Returns the section identified by +key+.
+    #
+    # Returns nil if there is no Section with the given key.
+    #
+    def [](key)
+      @lines[key.to_s]
+    end
+
+    # Returns this document as a string suitable for saving to a file.
+    def to_ini
+      @lines.to_a.map { |line| line.to_ini }.join($/)
+    end
+
+    # Returns true if a section with the given +key+ exists in this document.
+    def has_section?(key)
+      @lines.has_key?(key.to_s)
+    end
+
+    # Saves a copy of this Document to disk.
+    #
+    # If a path was supplied when the Document was initialized then nothing
+    # needs to be given to Document#save. If Document was not given a file
+    # path, or you wish to save the document elsewhere, supply a path when
+    # calling Document#save.
+    #
+    # ==== Parameters
+    # path<String>:: A path to which this document will be saved.
+    #
+    # ==== Raises
+    # IniParseError:: If your document couldn't be saved.
+    #
+    def save(path = nil)
+      @path = path if path
+      raise IniParseError, 'No path given to Document#save' if @path.blank?
+      File.open(@path, 'w') { |f| f.write(self.to_ini) }
+    end
+  end
+end

data/lib/iniparse/generator.rb

@@ -0,0 +1,200 @@
+module IniParse
+  # Generator provides a means for easily creating new INI documents.
+  #
+  # Rather than trying to hack together new INI documents by manually creating
+  # Document, Section and Option instances, it is preferable to use Generator
+  # which will handle it all for you.
+  #
+  # The Generator is exposed through IniParse.gen.
+  #
+  #   IniParse.gen do |doc|
+  #     doc.section("vehicle") do |vehicle|
+  #       vehicle.option("road_side", "left")
+  #       vehicle.option("realistic_acceleration", true)
+  #       vehicle.option("max_trains", 500)
+  #     end
+  #
+  #     doc.section("construction") do |construction|
+  #       construction.option("build_on_slopes", true)
+  #       construction.option("autoslope", true)
+  #     end
+  #   end
+  #
+  #   # => IniParse::Document
+  #
+  # This can be simplified further if you don't mind the small overhead
+  # which comes with +method_missing+:
+  #
+  #   IniParse.gen do |doc|
+  #     doc.vehicle do |vehicle|
+  #       vehicle.road_side = "left"
+  #       vehicle.realistic_acceleration = true
+  #       vehicle.max_trains = 500
+  #     end
+  #
+  #     doc.construction do |construction|
+  #       construction.build_on_slopes = true
+  #       construction.autoslope = true
+  #     end
+  #   end
+  #
+  #   # => IniParse::Document
+  #
+  # If you want to add slightly more complicated formatting to your document,
+  # each line type (except blanks) takes a number of optional parameters:
+  #
+  # :comment::
+  #   Adds an inline comment at the end of the line.
+  # :comment_offset::
+  #   Indent the comment. Measured in characters from _beginning_ of the line.
+  #   See String#ljust.
+  # :indent::
+  #   Adds the supplied text to the beginning of the line.
+  #
+  # If you supply +:indent+, +:comment_sep+, or +:comment_offset+ options when
+  # adding a section, the same options will be inherited by all of the options
+  # which belong to it.
+  #
+  #   IniParse.gen do |doc|
+  #     doc.section("vehicle",
+  #       :comment => "Options for vehicles", :indent  => "    "
+  #     ) do |vehicle|
+  #       vehicle.option("road_side", "left")
+  #       vehicle.option("realistic_acceleration", true)
+  #       vehicle.option("max_trains", 500, :comment => "More = slower")
+  #     end
+  #   end.to_ini
+  #
+  #       [vehicle] ; Options for vehicles
+  #       road_side = left
+  #       realistic_acceleration = true
+  #       max_trains = 500 ; More = slower
+  #
+  class Generator
+    attr_reader :context
+    attr_reader :document
+
+    def initialize(opts = {}) # :nodoc:
+      @document   = IniParse::Document.new
+      @context    = @document
+
+      @in_section = false
+      @opt_stack  = [opts]
+    end
+
+    def gen # :nodoc:
+      yield self
+      @document
+    end
+
+    # Creates a new IniParse::Document with the given sections and options.
+    #
+    # ==== Returns
+    # IniParse::Document
+    #
+    def self.gen(opts = {}, &blk)
+      new(opts).gen(&blk)
+    end
+
+    # Creates a new section with the given name and adds it to the document.
+    #
+    # You can optionally supply a block (as detailed in the documentation for
+    # Generator#gen) in order to add options to the section.
+    #
+    # ==== Parameters
+    # name<String>:: A name for the given section.
+    #
+    def section(name, opts = {})
+      if @in_section
+        # Nesting sections is bad, mmmkay?
+        raise LineNotAllowed, "You can't nest sections in INI files."
+      end
+
+      @context = Lines::Section.new(name, line_options(opts))
+      @document.lines << @context
+
+      if block_given?
+        begin
+          @in_section = true
+          with_options(opts) { yield self }
+          @context = @document
+          blank()
+        ensure
+          @in_section = false
+        end
+      end
+    end
+
+    # Adds a new option to the current section.
+    #
+    # Can only be called as part of a section block, or after at least one
+    # section has been added to the document.
+    #
+    # ==== Parameters
+    # key<String>:: The key (name) for this option.
+    # value::       The option's value.
+    # opts<Hash>::  Extra options for the line (formatting, etc).
+    #
+    # ==== Raises
+    # IniParse::NoSectionError::
+    #   If no section has been added to the document yet.
+    #
+    def option(key, value, opts = {})
+      @context.lines << Lines::Option.new(
+        key, value, line_options(opts)
+      )
+    rescue LineNotAllowed
+      # Tried to add an Option to a Document.
+      raise NoSectionError, <<-EOS.compress_lines
+        Your INI document contains an option before the first section is
+        declared which is not allowed.
+      EOS
+    end
+
+    # Adds a new comment line to the document.
+    #
+    # ==== Parameters
+    # comment<String>:: The text for the comment line.
+    #
+    def comment(comment, opts = {})
+      @context.lines << Lines::Comment.new(
+        line_options(opts.merge(:comment => comment))
+      )
+    end
+
+    # Adds a new blank line to the document.
+    def blank
+      @context.lines << Lines::Blank.new
+    end
+
+    # Wraps lines, setting default options for each.
+    def with_options(opts = {}) # :nodoc:
+      opts = opts.dup
+      opts.delete(:comment)
+      @opt_stack.push( @opt_stack.last.merge(opts))
+      yield self
+      @opt_stack.pop
+    end
+
+    def method_missing(name, *args, &blk) # :nodoc:
+      if m = name.to_s.match(/(.*)=$/)
+        option(m[1], *args)
+      else
+        section(name.to_s, *args, &blk)
+      end
+    end
+
+    #######
+    private
+    #######
+
+    # Returns options for a line.
+    #
+    # If the context is a section, we use the section options as a base,
+    # rather than the global defaults.
+    #
+    def line_options(given_opts) # :nodoc:
+      @opt_stack.last.empty? ? given_opts : @opt_stack.last.merge(given_opts)
+    end
+  end
+end