kamelopard 0.0.14 → 0.0.15

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZTY5Y2M5MWMyYWE4MGUyNTgxM2VlNzljMzYzMTJlYjkzZmU0NWYxZA==
+  data.tar.gz: !binary |-
+    M2Y2MmIwNDk4YzIwNGZkMjdjMDVhOTlmYzZlMGMyNzM4N2QxMTJhMg==
+SHA512:
+  metadata.gz: !binary |-
+    OWNkNGFjMGU0NjY3ZTU2MzUxYTg3NWUzOGNiZmI0ZDhmYTY5MTM4NTM2ODhj
+    ZmJmNDRhZmYzNzA1OTdjOTMzYTYxZGY4Y2RlMmIzY2ZiMTRiNWVkNmQ4ODU1
+    NmYyMTUzODU4NzA0Zjc5NWNhMmU4ZGM5NWJiNmExODRkN2YwZGU=
+  data.tar.gz: !binary |-
+    NGY5ZTE0NGQyNzA1OTg4NjRlZWIwNzgwMDRlYzNkZDc5ZTIyZWQ5YmE4NjUz
+    MWY4NjEwMWMzMGUyMzBlNDFhMzc3Yjc1ZTc5MWE0NjIwYjZmZjM0OTJhNTg5
+    ZjJmZGQxNDkzNTU3MmYzMDliZTg0ZGEwNmFhNmI5ZDIyMzcwYTE=

data/lib/kamelopard/classes.rb

@@ -2,11 +2,53 @@
 #--
 # vim:ts=4:sw=4:et:smartindent:nowrap
 #++
-# Classes to manage various KML objects. See
-# http://code.google.com/apis/kml/documentation/kmlreference.html for a
-# description of KML
 
-# Pretty much everything important is in this module
+# == Description
+# Kamelopard is a gem to create and manipulate Keyhole Markup Language, or KML.
+# See http://code.google.com/apis/kml/documentation/kmlreference.html for a
+# reference on the subject. Within the Kamelopard module are several classes
+# which represent KML objects. To use Kamelopard to create a KML document from
+# scratch, you'll eventually want to create instances of these classes. You can
+# manipulate these instances' attributes and connections to other classes, and
+# in the end, write the result to a KML file. Here's a simple example which
+# creates one placemark in a file called doc.kml:
+#
+#  require 'rubygems'
+#  require 'kamelopard'
+#
+#  f = Kamelopard::Folder.new('Some Folder Name')
+#  f << Kamelopard::Placemark('My placemark',
+#       :geometry => Kamelopard::Point(1, 2, 3))
+#  write_kml_to 'doc.kml'
+#
+# Kamelopard operates as a sort of state machine, with a concept of the
+# "current" document. Newly created objects are appended to the current
+# document. See the DocumentHolder class to learn about switching around
+# between different documents. Note also that whereas tour elements such as
+# FlyTo and Wait are always kept in the order in which they were created, other
+# elements like Styles and Folders might show up in different orders. Since in
+# the final output this doesn't matter (or shouldn't, anyway), this isn't
+# considered a bug, and in fact it makes it easier sometimes, because you don't
+# have to figure out the structure of your document in the proper order at run
+# time.
+#
+# Kamelopard comes with a set of helper functions which it puts in the default
+# namespace. Experienced users will probably choose use these functions to
+# create Kamelopard objects rather than instantiating these classes directly.
+#
+# Objects' attributes are often undocumented, when they correspond directly to
+# a similarly named attribute in the KML object they represent. Refer to the
+# KML reference linked above for more details about these undocumented
+# attributes. Most objects' constructors accept a hash of options you can use
+# to set these attributes, such as the :geometry option used in the sample code
+# above. Kamelopard will complain if you try to set an option it doesn't
+# recognize.
+#
+# Most objects also include a to_kml() method, which returns an XML::Node
+# containing the KML this object represents, including any other objects nested
+# inside. The write_kml_to helper function used above, and other helper
+# functions involved in KML output, generally wrap this method so it rarely
+# gets called directly.
 module Kamelopard
     require 'bundler/setup'
     require 'singleton'
@@ -58,7 +100,7 @@ module Kamelopard
         @@logger.call(level, mod, msg) unless @@logger.nil? or @@log_level > LogLevels[level]
     end
 
-    def Kamelopard.xml_to_hash(node, fields)
+    def Kamelopard.xml_to_hash(node, fields) # :nodoc:
         result = {}
         fields.each do |field|
             begin
@@ -1061,7 +1103,7 @@ module Kamelopard
 
     # Represents KML's Document class.
     class Document < Container
-        attr_accessor :flyto_mode, :folders, :tours, :uses_xal, :vsr_actions
+        attr_accessor :flyto_mode, :folders, :tours, :uses_xal, :vsr_actions, :filename
 
         # Is this KML destined for a master LG node, or a slave? True if this
         # is a master node. This defaults to true, so tours that don't need
@@ -1073,11 +1115,20 @@ module Kamelopard
             @folders = []
             @vsr_actions = []
             @master_mode = false
+            @filename = 'doc.kml'
             Kamelopard.log(:info, 'Document', "Adding myself to the document holder")
             DocumentHolder.instance << self
             super
         end
 
+        def make_current
+            Kamelopard::DocumentHolder.instance.set_current self
+        end
+
+        def activate
+            make_current
+        end
+
         # Returns viewsyncrelay actions as a hash
         def get_actions
             {
@@ -1202,6 +1253,12 @@ module Kamelopard
             #! These get printed out in the call to super, in Feature.to_kml()
             #@styles.map do |a| d << a.to_kml unless a.attached? end
 
+            # then misc
+            @features.each do |f|
+                next if f.is_a? Folder or f.is_a? Style or f.is_a? Tour
+                f.to_kml d
+            end
+
             # then folders
             @folders.map do |a|
                 a.to_kml(d) unless a.has_parent?
@@ -1685,7 +1742,10 @@ module Kamelopard
     end
 
     # Corresponds to KML's Placemark objects. The geometry attribute requires a
-    # descendant of Geometry
+    # descendant of Geometry. *Note:* whereas most objects implicitly add
+    # themselves to the end of the current Document, Placemarks do not. They
+    # must be explicitly added to the Document or other Container they live in,
+    # typically with the Container's << operator.
     class Placemark < Feature
         attr_accessor :name, :geometry, :balloonVisibility
 
@@ -2368,6 +2428,8 @@ module Kamelopard
             }.each do |k, v|
                 d = XML::Node.new k.to_s
                 d << v.to_s
+                    # Don't escape links, because Earth doesn't like that.
+                d.first.output_escaping = false
                 x << d
             end
             Kamelopard.kml_array(x, [

data/lib/kamelopard/geocode.rb

@@ -7,22 +7,53 @@ require 'uri'
 require 'cgi'
 require 'json'
 
-# Geocoder base class
+# Geocoder base class. You should use a subclass. It is your responsibility to
+# ensure you comply with all API licensing and usage requirements. Kamelopard
+# won't do it for you.
 class Geocoder
     attr_accessor :host, :path, :params
     def initialize
         @params = {}
     end
 
+    def processParam(value, key = 'location')
+        return ["#{key}=#{value}"] if key == 'key'
+        if value.kind_of? Hash then
+            p = value.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v)}" }
+        else
+            p = ["#{CGI.escape(key)}=#{CGI.escape(value)}"]
+        end
+        return p
+    end
+
     def parse_response(r)
         raise "Unimplemented -- use a child of the Geocoder class"
     end
 end
 
-# Some specific geocoding API classes follow.  Google's would seem most
-# obvious, but since it requires you to display results on a map, ... I didn't
-# want to have to evaluate other possible restrictions, or require that they be
-# imposed on Kamelopard users.
+class GoogleGeocoder < Geocoder
+    attr_reader :api_key, :response_format
+
+    def initialize(key, response_format = 'json')
+        super()
+        @proto = 'http'
+        @host = 'maps.googleapis.com'
+        @path = '/maps/api/geocode'
+        @api_key = key
+        @response_format = response_format
+    end
+
+    def getURL(params)
+        http = Net::HTTP.new(@host)
+        u = URI::HTTP.build([nil, @host, nil, "#{@path}/#{@response_format}", params, nil])
+
+        JSON.parse(Net::HTTP.get u)
+    end
+
+    def lookup(address)
+        getURL(processParam(address, 'address').join('&'))
+    end
+end
 
 class MapquestGeocoder < Geocoder
     attr_reader :api_key, :response_format
@@ -31,28 +62,38 @@ class MapquestGeocoder < Geocoder
         super()
         @proto = 'http'
         @host = 'www.mapquestapi.com'
-        @path = '/geocoding/v1/address'
+        @path = {
+            :address => '/geocoding/v1/address',
+            :batch => '/geocoding/v1/batch'
+        }
         @api_key = key
         @response_format = response_format
         @params['key'] = @api_key
     end
 
+    def getURL(args, type)
+        raise "Type (#{type}) must be one of #{ @path.keys.map { |a| ":#{a}" }.join(', ')}" unless @path.has_key? type
+
+        params = @params.map { |k, v| processParam(v, k) }.concat(args).join('&')
+
+        http = Net::HTTP.new(@host)
+        u = URI::HTTP.build([nil, @host, nil, @path[type], params, nil])
+
+        resp = Net::HTTP.get u
+        parse_response resp
+    end
+
     # Returns an object built from the JSON result of the lookup, or an exception
     def lookup(address)
         # The argument can be a string, in which case PlaceFinder does the parsing
         # The argument can also be a hash, with several possible keys. See the PlaceFinder documentation for details
         # http://developer.yahoo.com/geo/placefinder/guide/requests.html
-        http = Net::HTTP.new(@host)
-        if address.kind_of? Hash then
-            p = @params.merge address
-        else
-            p = @params.merge( { 'location' => address } )
-        end
-        q = p.map { |k,v| "#{ k == 'key' ? k : CGI.escape(k) }=#{ k == 'key' ? v : CGI.escape(v) }" }.join('&')
-        u = URI::HTTP.build([nil, @host, nil, @path, q, nil])
+        return getURL(processParam(address), :address)
+    end
 
-        resp = Net::HTTP.get u
-        parse_response resp
+    def lookupBatch(addresses)
+        # The argument should be an array of the same sorts of values that can be fed to lookup()
+        return getURL(addresses.map { |k| processParam(k) }.flatten(1), :batch)
     end
 
     def parse_response(r)