hosts 0.1.0

data/lib/aef/hosts/file.rb

@@ -0,0 +1,252 @@
+# encoding: UTF-8
+=begin
+Copyright Alexander E. Fischer <aef@raxys.net>, 2012
+
+This file is part of Hosts.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'aef/hosts'
+
+module Aef
+  module Hosts
+
+    # This class represents a hosts file and aggregates its elements.
+    #
+    # It is able to parse host files from file-system or String and can
+    # generate a String representation of itself to String or file-system.
+    class File
+
+      include Helpers
+
+      # Regular expression to extract a comment line.
+      #
+      # @private
+      COMMENT_LINE_PATTERN   = /^\s*#(.*)$/
+
+      # Regular expression to extract section headers and footers.
+      #
+      # @private
+      SECTION_MARKER_PATTERN = /^ -----(BEGIN|END) SECTION (.*)-----(?:[\r])?$/
+
+      # Regular expression to extract entry lines.
+      #
+      # @private
+      ENTRY_LINE_PATTERN     = /^([^#]*)(?:#(.*))?$/
+
+      # The hosts file's elements.
+      #
+      # @return [Array<Aef::Hosts::Element>]
+      attr_accessor :elements
+
+      # The filesystem path of the hosts file.
+      #
+      # @return [Pathname, nil]
+      attr_reader :path
+
+      class << self
+        # Parses a hosts file given as path.
+        #
+        # @param [Pathname] the hosts file path
+        # @return [Aef::Hosts::File] a file
+        def read(path)
+          new(path).read
+        end
+
+        # Parses a hosts file given as String.
+        #
+        # @param [String] data a String representation of the hosts file
+        # @return [Aef::Hosts::File] a file
+        def parse(data)
+          new.parse(data)
+        end
+      end
+
+      # Initializes a file.
+      #
+      # @param [Pathname] path path to the hosts file
+      def initialize(path = nil)
+        reset
+        self.path = path
+      end
+
+      # Removes all elements.
+      #
+      # @return [Aef::Hosts::File] a self reference
+      def reset
+        @elements = []
+
+        self
+      end
+
+      # Deletes the cached String representations of all elements.
+      #
+      # @return [Aef::Hosts::File] a self reference
+      def invalidate_cache!
+        elements.each do |element|
+          element.invalidate_cache!
+        end
+
+        self
+      end
+
+      # Sets the filesystem path of the hosts file.
+      def path=(path)
+        @path = to_pathname(path)
+      end
+
+      # Parses a hosts file given as path.
+      #
+      # @param [Pathname] path override the path attribute for this operation
+      # @return [Aef::Hosts::File] a self reference
+      def read(path = nil)
+        path = path.nil? ? @path : to_pathname(path)
+
+        raise ArgumentError, 'No path given' unless path
+
+        parse(path.read)
+
+        self
+      end
+
+      # Parses a hosts file given as String.
+      #
+      # @param [String] data a String representation of the hosts file
+      # @return [Aef::Hosts::File] a self reference
+      def parse(data)
+        current_section = self
+
+        data.to_s.lines.each_with_index do |line, line_number|
+          line = Linebreak.encode(line, :unix)
+
+          if COMMENT_LINE_PATTERN =~ line
+            comment = $1
+
+            if SECTION_MARKER_PATTERN =~ comment
+              type = $1
+              name = $2
+
+              case type
+              when 'BEGIN'
+                unless current_section.is_a?(Section)
+                  current_section = Section.new(
+                    name,
+                    :cache => {:header => line, :footer => nil}
+                  )
+                else
+                  raise ParserError, "Invalid cascading of sections. Cannot start new section '#{name}' without first closing section '#{current_section.name}' on line #{line_number + 1}."
+                end
+              when 'END'
+                if name == current_section.name
+                  current_section.cache[:footer] = line
+                  elements << current_section
+                  current_section = self
+                else
+                  raise ParserError, "Invalid closing of section. Found attempt to close section '#{name}' in body of section '#{current_section.name}' on line #{line_number + 1}."
+                end
+              end
+            else
+              current_section.elements << Comment.new(
+                comment,
+                :cache => line
+              )
+            end
+          else
+            ENTRY_LINE_PATTERN =~ line
+
+            entry   = $1
+            comment = $2
+
+            if entry and not entry =~ /^\s+$/
+
+              split = entry.split(/\s+/)
+              split.shift if split.first == ''
+
+              address, name, *aliases = *split
+
+              current_section.elements << Entry.new(
+                address, name,
+                :aliases => aliases,
+                :comment => comment,
+                :cache   => line
+              )
+            else
+              current_section.elements << EmptyElement.new(
+                :cache => line
+              )
+            end
+          end
+        end
+
+        self
+      end
+
+      # Generates a hosts file and writes it to a path.
+      #
+      # @param [Hash] options
+      # @option options [Pathname] :path overrides the path attribute for this
+      #   operation
+      # @option options [true, false] :force_generation if set to true, the
+      #   cache won't be used, even if it not empty
+      # @option options [:unix, :windows, :mac] :linebreak_encoding the
+      #   linebreak encoding of the result. If nothing is specified the result
+      #   will be encoded as if :unix was specified.
+      # @see Aef::Linebreak#encode
+      def write(options = {})
+        validate_options(options, :force_generation, :linebreak_encoding, :path)
+
+        path = options[:path].nil? ? @path : to_pathname(options[:path])
+
+        raise ArgumentError, 'No path given' unless path
+
+        options.delete(:path)
+
+        path.open('w') do |file|
+          file.write(to_s(options))
+        end
+
+        true
+      end
+
+      # A String representation for debugging purposes.
+      #
+      # @return [String]
+      def inspect
+        generate_inspect(self, :path, :elements)
+      end
+
+      # A String representation of the hosts file.
+      #
+      # @param [Hash] options
+      # @option options [true, false] :force_generation if set to true, the
+      #   cache won't be used, even if it not empty
+      # @option options [:unix, :windows, :mac] :linebreak_encoding the
+      #   linebreak encoding of the result. If nothing is specified the result
+      #   will be encoded as if :unix was specified.
+      # @see Aef::Linebreak#encode
+      def to_s(options = {})
+        validate_options(options, :force_generation, :linebreak_encoding)
+
+        string = ''
+
+        @elements.each do |element|
+          string << element.to_s(options)
+        end
+
+        string
+      end
+
+    end
+  end
+end

data/lib/aef/hosts/helpers.rb

@@ -0,0 +1,121 @@
+# encoding: UTF-8
+=begin
+Copyright Alexander E. Fischer <aef@raxys.net>, 2012
+
+This file is part of Hosts.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'aef/hosts'
+
+module Aef
+  module Hosts
+
+    # Helper methods used internally in the hosts library
+    #
+    # @private
+    module Helpers
+
+      protected
+
+      # Ensures that an options Hash has includes only valid keys
+      #
+      # @param [Hash] options the options Hash to verify
+      # @param [Array<Symbol>] valid_keys a list of valid keys for the Hash
+      # @raise [ArgumentError] if Hash includes invalid keys
+      def validate_options(options, *valid_keys)
+        remainder = options.keys - valid_keys
+
+        unless remainder.empty?
+          raise ArgumentError, "Invalid option keys: #{remainder.map(&:inspect).join(',')}"
+        end
+      end
+
+      # Casts a given object to Pathname or passes through a given nil
+      #
+      # @param [String, Pathname, nil] path a filesystem path
+      # @return [Pathname, nil]
+      def to_pathname(path)
+        path.nil? ? nil : Pathname.new(path)
+      end
+
+      # Generates a String representation for debugging purposes.
+      #
+      # @param [Object] model a model for which the String is generated
+      # @param [Array<Symbol, String>] attributes Attributes to be displayed.
+      #   If given as Symbol, the attribute's value will be presented by name
+      #   and the inspect output of its value. If given as String, the String
+      #   will represent it instead.
+      # @return [String] a string representation for debugging purposes
+      def generate_inspect(model, *attributes)
+        string = "#<#{model.class}"
+
+        components = []
+
+        attributes.each do |attribute|
+          if attribute == :cache
+            components << 'cached!' if model.send(:cache_filled?)
+          elsif attribute == :elements
+            components << generate_elements_partial(model.elements)
+          elsif attribute.is_a?(Symbol)
+            components << "#{attribute}=#{model.send(attribute).inspect}"
+          else
+            components << attribute
+          end
+        end
+
+        components.unshift(':') unless components.empty?
+        
+        string << components.join(' ')
+        string << '>'
+      end
+
+      # Generate a partial String for an element listing in inspect output.
+      #
+      # @return [String] element partial
+      def generate_elements_partial(elements)
+        elements_string = 'elements=['
+
+        unless elements.empty?
+          elements_string << "\n"
+          elements_string << elements.map{|element|
+            element.inspect.lines.map{|line| "  #{line}"}.join
+          }.join(",\n")
+          elements_string << "\n"
+        end
+
+        elements_string << "]"
+      end
+
+      # Sets a given attribute and executes the block if the current value
+      # differs from the given.
+      #
+      # @param [Symbol] attribute the attribute's name
+      # @param [Object] new_value the value to be assigned to the attribute if
+      #   it differs from its current value
+      # @yield Executed if current value differs from the given
+      def set_if_changed(attribute, new_value)
+        variable_name = :"@#{attribute}"
+        old_value = instance_variable_get(variable_name)
+
+        if new_value != old_value
+          instance_variable_set(variable_name, new_value)
+
+          yield if block_given?
+        end
+      end
+
+    end
+  end
+end

data/lib/aef/hosts/section.rb

@@ -0,0 +1,141 @@
+# encoding: UTF-8
+=begin
+Copyright Alexander E. Fischer <aef@raxys.net>, 2012
+
+This file is part of Hosts.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'aef/hosts'
+
+module Aef
+  module Hosts
+
+    # This represents a section as element of a hosts file. It consists of a
+    # header, futher included elements and a footer
+    class Section < Element
+
+      # Title of the section
+      #
+      # @return [String]
+      attr_reader :name
+
+      # Elements inside the section
+      #
+      # @note If the Array is modified in place, you need to manually
+      #   invalidate the cache with option :only_section => true.
+      # @see #invalidate_cache!
+      # @return [Array<Aef::Host::Element>]
+      attr_reader :elements
+
+      # Initializes a section
+      #
+      # @param [String] name title of the section
+      # @param [Hash] options
+      # @option options [String] :cache sets a cached String representation
+      # @option options [Array<Aef::Hosts::Element>] :elements a list of
+      #   elements in the section
+      def initialize(name, options = {})
+        validate_options(options, :cache, :elements)
+
+        raise ArgumentError, 'Name cannot be empty' unless name
+
+        @name     = name.to_s
+        @elements = options[:elements] || []
+        @cache    = options[:cache] || {:header => nil, :footer => nil}
+      end
+
+      # Deletes the cached String representation
+      #
+      # @param [Hash] options
+      # @option [true, false] :only_section if set to true, the invalidation
+      #   will not cascade onto the elements. Default is false.
+      # @return [Aef::Hosts::Section] a self reference
+      def invalidate_cache!(options = {})
+        @cache = {:header => nil, :footer => nil}
+
+        unless options[:only_section]
+          elements.each do |element|
+            element.invalidate_cache!
+          end
+        end
+      end
+
+      # Tells if a String representation is cached or not
+      #
+      # @return [true, false] true if cache is not empty
+      def cache_filled?
+        !!@cache[:header] && !!@cache[:footer]
+      end
+
+      # Sets the title of the section
+      def name=(name)
+        set_if_changed(:name, name.to_s) do
+          invalidate_cache!(:only_section => true)
+        end
+      end
+
+      # Sets the elements inside the section
+      def elements=(elements)
+        set_if_changed(:elements, [*elements]) do
+          invalidate_cache!(:only_section => true)
+        end
+      end
+
+      # A String representation for debugging purposes
+      #
+      # @return [String]
+      def inspect
+        generate_inspect(self, :name, :cache, :elements)
+      end
+
+      protected
+
+      # Defines the algorithm to generate a String representation from scratch.
+      #
+      # @return [String] a generated String representation
+      def generate_string(options = {})
+        string = ''
+
+        string << "# -----BEGIN SECTION #{name}-----\n"
+
+        @elements.each do |element|
+          string << element.to_s(options)
+        end
+
+        string << "# -----END SECTION #{name}-----\n"
+
+        string
+      end
+
+      # Defines the algorithm to construct the String representation from cache
+      #
+      # @return [String] the cached String representation
+      def cache_string(options = {})
+        string = ''
+
+        string << @cache[:header]
+
+        @elements.each do |element|
+          string << element.to_s(options)
+        end
+
+        string << @cache[:footer]
+
+        string
+      end
+
+    end
+  end
+end