ruby_kml 0.1.7

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2006-2007 Anthony Eden
+
+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.md

@@ -0,0 +1,34 @@
+ruby_kml
+========
+
+Overview
+--------
+
+Library for generating KML(Keyhole Markup Language) files in Ruby.
+Sweet if you want to place markers, overlays, and other awesome things over a google map or google earth.
+
+
+Install
+-------
+
+    gem install ruby_kml
+
+
+Examples
+--------
+
+See `test/kml_file_test.rb` for more examples
+
+    kml = KMLFile.new
+    folder = KML::Folder.new(:name => 'Melbourne Stations')
+    [
+      ["Flinders St",    -37.818078, 144.966811],
+      ["Southern Cross", -37.818358, 144.952417],
+    ].each do |name, lat, lng|
+      folder.features << KML::Placemark.new(
+        :name => name,
+        :geometry => KML::Point.new(:coordinates => {:lat => lat, :lng => lng})
+      )
+    end
+    kml.objects << folder
+    puts kml.render

data/Rakefile

@@ -0,0 +1,52 @@
+#!/usr/bin/env rake
+
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'rubygems/package_task'
+
+require File.join(File.dirname(__FILE__), 'lib/kml', 'version')
+
+spec = Gem::Specification.load('ruby_kml.gemspec')
+Gem::PackageTask.new(spec) {}
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the library.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'KMLr'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Generate code statistics"
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+
+  for file_name in FileList["lib/**/*.rb"]
+    next if file_name =~ /vendor/
+    f = File.open(file_name)
+
+    while line = f.gets
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+
+    total_lines     += lines
+    total_codelines += codelines
+
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end
+
+task :default => :test

data/examples/melbourne-stations.kml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.1">
+  <Folder>
+    <name>Melbourne Stations</name>
+    <Placemark>
+      <name>Flinders St</name>
+      <Point>
+        <coordinates>144.966811,-37.818078</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>Southern Cross</name>
+      <Point>
+        <coordinates>144.952417,-37.818358</coordinates>
+      </Point>
+    </Placemark>
+  </Folder>
+</kml>

data/lib/kml/color_style.rb

@@ -0,0 +1,34 @@
+module KML #:nodoc:
+  # Base class for specifying the color and color mode of extended style types.
+  class ColorStyle < KML::Object
+    # Color and opacity (alpha) values are expressed in hexadecimal notation. The range of values for any one color 
+    # is 0 to 255 (00 to ff). For alpha, 00 is fully transparent and ff is fully opaque. The order of expression is 
+    # aabbggrr, where aa=alpha (00 to ff); bb=blue (00 to ff); gg=green (00 to ff); rr=red (00 to ff). For example, 
+    # if you want to apply a blue color with 50 percent opacity to an overlay, you would specify the following: 
+    # 
+    #   style.color = '7fff0000'
+    # 
+    # where alpha=0x7f, blue=0xff, green=0x00, and red=0x00.
+    attr_accessor :color
+    
+    # Values for +color_mode+ are normal (no effect) and random. A value of random applies a random linear scale to 
+    # the base +color+ as follows. 
+    # 
+    # * To achieve a truly random selection of colors, specify a base +color+ of white (ffffffff).
+    # * If you specify a single color component (for example, a value of ff0000ff for red), random color values for 
+    #   that one component (red) will be selected. In this case, the values would range from 00 (black) to ff (full red).
+    # * If you specify values for two or for all three color components, a random linear scale is applied to each color 
+    #   component, with results ranging from black to the maximum values specified for each component.
+    # * The opacity of a color comes from the alpha component of <color> and is never randomized.
+    attr_accessor :color_mode
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.color(color) unless color.nil?
+      xm.colorMode(color_mode) unless color_mode.nil?
+    end
+  end
+end
+
+require 'kml/line_style'
+require 'kml/poly_style'
+require 'kml/icon_style'

data/lib/kml/container.rb

@@ -0,0 +1,42 @@
+module KML
+  # A Container is an abstract base class that holds one or more Features and allows the creation of nested hierarchies.
+  class Container < Feature
+
+    # Access the features in the container
+    attr_accessor :features
+    attr_accessor :plain_children
+
+    # Get the features in the container
+    def features
+      @features ||= []
+    end
+
+    def plain_children
+      @plain_children ||= []
+    end
+
+    def parse(node)
+      super(node) do |cld|
+        case cld.name
+        when 'Document'
+          self.features << KML::Document.parse(cld)
+        when 'Folder'
+          self.features << KML::Folder.parse(cld)
+        when 'NetworkLink'
+        when 'Placemark'
+          self.features << KML::Placemark.parse(cld)
+        when 'GroundOverlay'
+        when 'PhotoOverlay'
+        when 'ScreenOverlay'
+        else
+          yield cld
+        end
+      end
+      self
+    end
+
+  end
+end
+
+require 'kml/folder'
+require 'kml/document'

data/lib/kml/document.rb

@@ -0,0 +1,46 @@
+module KML #:nodoc:
+  # A document contains 0 or more features and 0 or more schemas.
+  class Document < Container
+    attr_accessor :schemas
+
+    # Shared styles
+    attr_accessor :styles
+
+    def schemas
+      @schemas ||= []
+    end
+
+    def styles
+      @styles ||= []
+    end
+
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Document {
+        super
+        styles.each { |style| style.render(xm) }
+        features.each { |feature| feature.render(xm) }
+        schemas.each { |schema| schema.render(xm) }
+      }
+    end
+
+    def self.parse(node)
+      self.new.parse(node)
+    end
+
+    def parse(node)
+      super(node) do |cld|
+        case cld.name
+        when 'Style'
+          # TODO
+        when 'Schema'
+          # TODO
+        else
+          puts "Document"
+          p cld
+          puts
+        end
+      end
+      self
+    end
+  end
+end

data/lib/kml/feature.rb

@@ -0,0 +1,185 @@
+# This source file implements the Feature class of KML.
+#
+# Basic XML chunk structure:
+#
+#   <name>...</name>                      <!-- string -->
+#   <visibility>1</visibility>            <!-- boolean -->
+#   <open>1</open>                        <!-- boolean -->
+#   <address>...</address>                <!-- string -->
+#   <AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">...
+#       </AddressDetails>                 <!-- string -->
+#   <phoneNumber>...</phoneNumber>        <!-- string -->
+#   <Snippet maxLines="2">...</Snippet>   <!-- string -->
+#   <description>...</description>        <!-- string -->
+#   <LookAt>...</LookAt>
+#   <TimePrimitive>...</TimePrimitive>
+#   <styleUrl>...</styleUrl>              <!-- anyURI -->
+#   <StyleSelector>...</StyleSelector>
+#   <Region>...</Region>
+#   <Metadata>...</Metadata>              <!-- user-defined data -->
+
+module KML #:nodoc:
+  # A feature is an abstract base class.
+  class Feature < KML::Object
+    # Accessor for the feature name
+    attr_accessor :name
+
+    # Return true if the feature is visible
+    def visibility?
+      @visibility || true
+    end
+
+    # If the visibility has been set then return '0' for false and '1' for true. If the visibility
+    # has never been explicitly set then return nil (which means that the associated KML tag will
+    # not be rendered)
+    def visibility
+      return nil if @visibility.nil?
+      @visibility ? '1' : '0'
+    end
+
+    # Set to true to indicate that the feature is visible.
+    def visibility=(v)
+      @visibility = v
+    end
+
+    # Return true if the feature is expanded when initially displayed.
+    def open?
+      @open || true
+    end
+
+    # If the open has been set then return '0' for false and '1' for true. If the open has never been 
+    # explicitly set then return nil (which means that the associated KML tag will not be rendered)
+    def open
+      return nil if @open.nil?
+      @open ? '1' : '0'
+    end
+
+    # Set to true to indicate that the feature is expanded when displayed. Set to false to indicate that the
+    # feature is collapsed.
+    def open=(v)
+      @open = v
+    end
+
+    # A string value representing an unstructured address written as a standard street, city, state address, and/or as 
+    # a postal code. You can use the +address+ attribute to specify the location of a point instead of using latitude and 
+    # longitude coordinates. (However, if a Point is provided, it takes precedence over the +address+.) To find out 
+    # which locales are supported for this tag in Google Earth, go to the 
+    # <a href="http://maps.google.com/support/bin/answer.py?answer=16634">Google Maps Help</a>.
+    attr_accessor :address
+
+    # A structured address, formatted as xAL, or eXtensible Address Language, an international standard for address 
+    # formatting. AddressDetails is used by KML for geocoding in Google Maps only. For details, see the Google Maps 
+    # API documentation. Currently, Google Earth does not use this attribute; use +address+ instead.
+    attr_accessor :address_details
+
+    # A string value representing a telephone number. This element is used by Google Maps Mobile only. The industry 
+    # standard for Java-enabled cellular phones is RFC2806. For more information, see 
+    # <a href="http://www.ietf.org/rfc/rfc2806.txt">http://www.ietf.org/rfc/rfc2806.txt</a>.
+    attr_accessor :phone_number
+
+    # Accessor for the snippet. See +KML::Snippet+
+    attr_accessor :snippet
+    # Set the snippet. See +KML::Snippet+
+    def snippet=(v)
+      case v
+      when String
+        @snippet = Snippet.new(v)
+      when Snippet
+        @snippet = v
+      else
+        raise ArgumentError, "Snippet must be a String or a Snippet"
+      end
+    end
+
+    # User-supplied text that appears in the description balloon when the user clicks on either the feature name 
+    # in the Places panel or the Placemark icon in the 3D viewer. This text also appears beneath the feature name 
+    # in the Places panel if no Snippet is specified for the feature.
+    # 
+    # Description supports plain text as well as a subset of HTML formatting elements, including tables. It does 
+    # not support other web-based technology, such as dynamic page markup (PHP, JSP, ASP), scripting languages 
+    # (VBScript, Javascript), nor application languages (Java, Python).
+    # 
+    # If your description contains no HTML markup, Google Earth attempts to format it, replacing newlines with 
+    # &lt;br&gt; and wrapping URLs with anchor tags. A valid URL string for the World Wide Web is automatically 
+    # converted to a hyperlink to that URL (e.g., http://www.google.com). Consequently, you do not need to surround 
+    # a URL with the &lt;a href="http://.."&gt;&lt;/a&gt; tags in order to achieve a simple link.
+    attr_accessor :description
+
+    # Defines a camera viewpoint associated with any element derived from Feature. See LookAt.
+    attr_accessor :look_at
+
+    attr_accessor :time_primitive
+
+    # URI (a URI equals [URL]#ID) of a Style or StyleMap defined in a Document. If the style is in the same file, 
+    # use a # reference. If the style is defined in an external file, use a full URL along with # referencing. Examples:
+    #
+    #   +style_url='#myIconStyleID'
+    #   +style_url='http://someserver.com/somestylefile.xml#restaurant'
+    attr_accessor :style_url
+
+    # One or more Styles and StyleMaps can be defined to customize the appearance of any element derived from Feature 
+    # or of the Geometry in a Placemark. (See BalloonStyle, ListStyle, StyleSelector, and the styles derived from 
+    # ColorStyle.) A style defined within a Feature is called an "inline style" and applies only to the Feature that 
+    # contains it. A style defined as the child of a Document is called a "shared style." A shared style must have an id 
+    # defined for it. This id is referenced by one or more Features within the <Document>. In cases where a style element 
+    # is defined both in a shared style and in an inline style for a Feature—that is, a Folder, GroundOverlay, 
+    # NetworkLink, Placemark, or ScreenOverlay—the value for the Feature's inline style takes precedence over the value 
+    # for the shared style.
+    attr_accessor :style_selector
+    attr_accessor :region
+    attr_accessor :metadata
+
+    # Render the object and all of its sub-elements.
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      [:name, :visibility, :address].each do |a|
+        xm.__send__(a, self.__send__(a)) unless self.__send__(a).nil?
+      end
+
+      xm.description { xm.cdata!(description) } unless description.nil?
+      xm.open(self.open) unless open.nil?
+
+      xm.phoneNumber(phone_number) unless phone_number.nil?
+      xm.styleUrl(style_url) unless style_url.nil?
+
+      unless address_details.nil?
+        xm.AddressDetails(:xmlns => "urn:oasis:names:tc:ciq:xsdschema:xAL:2.0") { address_details.render(xm) } 
+      end
+
+      xm.Snippet(snippet.text, snippet.max_lines) unless snippet.nil?
+
+      xm.LookAt { look_at.render(xm) } unless look_at.nil?
+      xm.TimePrimitive { time_primitive.render(xm) } unless time_primitive.nil?
+      xm.StyleSelector { style_selector.render(xm) } unless style_selector.nil?
+    end
+
+    def parse(node)
+      super(node) do |cld|
+        case cld.name
+        when 'name'
+          self.name = cld.content
+        when 'visibility'
+          self.visibility = cld.content
+        when 'description'
+          self.description = cld.content
+        when 'styleUrl'
+          self.style_url = cld.content
+        when 'Region'
+          # TODO
+        when 'ExtendedData'
+          # TODO
+        when 'Snippet'
+          # TODO
+        else
+          yield cld
+        end
+      end
+      self
+    end
+  end
+end
+
+require 'kml/container'
+require 'kml/placemark'
+require 'kml/overlay'
+
+require 'kml/snippet'

data/lib/kml/folder.rb

@@ -0,0 +1,29 @@
+module KML #:nodoc:
+  # A Folder is used to arrange other Features hierarchically (Folders, Placemarks, NetworkLinks, 
+  # or Overlays). A Feature is visible only if it and all its ancestors are visible.
+  class Folder < Container
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Folder {
+        super
+        features.each { |f| f.render(xm) }
+      }
+    end
+
+    def self.parse(node)
+      self.new.parse(node)
+    end
+
+    def parse(node)
+      super(node) do |cld|
+        case cld.name
+        when 'Stylex'
+        when 'Schemax'
+        else
+          puts "Folder"
+          p cld
+          puts
+        end
+      end
+    end
+  end
+end