virtualbox 0.3.0 → 0.4.0

data/Gemfile

@@ -4,6 +4,7 @@ only :test do
   gem "contest", ">= 0.1.2"
   gem "mocha"
   gem "ruby-debug", ">= 0.10.3" if RUBY_VERSION < '1.9'
+  gem "ruby-debug19", ">= 0.11.6" if RUBY_VERSION >= '1.9'
 end
 
 # Makes sure that our code doesn't request gems outside

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Mitchell Hashimoto.
+
+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

@@ -35,7 +35,7 @@ Below are some examples:
     # Let's first print out some basic info about the VM
     puts "Memory: #{vm.memory}"
     
-    vm.storage_controllers.each do |sc
+    vm.storage_controllers.each do |sc|
       sc.attached_devices.each do |device|
         puts "Attached Device: #{device.uuid}"
       end

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/docs/WhatsNew.md

@@ -1,41 +1,34 @@
-# What's New in 0.3.x?
+# What's New in 0.4.x?
 
-## Shared Folders
+## "Extra Data" on VMs / Global
 
-Shared folders are a great feature of VirtualBox which allows the host system
-to share data with guest systems easily using the native filesystem. Attaching,
-modifying, and removing these shared folders are now supported. A quick example
-below:
+Extra data is persistent key-value storage which is available as a way to store any information
+wanted. VirtualBox uses it for storing statistics and settings. You can use it for anything!
+Setting extra data on virtual machines is now as easy as a ruby hash:
 
     vm = VirtualBox::VM.find("FooVM")
-    folder = VirtualBox::SharedFolder.new
-    folder.name = "hosthome"
-    folder.hostpath = "/home/username"
-    vm.shared_folders << folder
+    vm.extra_data["i_was_here"] = "yes!"
     vm.save
 
-For full documentation on this new feature, read about them at
-{VirtualBox::SharedFolder}.
+Read more about extra data {VirtualBox::ExtraData here}.
 
-## Validations
+## Port Forwarding
 
-Many of the models for the virtualbox library now come complete with data
-validations. These validations are performed within the library itself prior to
-calling the virtualbox commands. They work very much the same was as ActiveRecord
-validations:
+If a VM is using NAT for its network, the host machine can't access any outward facing
+services of the guest (for example: a web host, ftp server, etc.). Port forwarding is
+one way to facilitate this need. Port forwarding is straight forward to setup:
 
-    sf = VirtualBox::SharedFolder.new(hash_of_values)
-    if !sf.valid?
-      puts "#{sf.errors.length} errors with the folder"
-    else
-      sf.save
-    end
+    vm = VirtualBox::VM.find("FooVM")
+    port = VirtualBox::ForwardedPort.new
+    port.name = "http"
+    port.guestport = 80
+    port.hostport = 8080
+    vm.forwarded_ports << port
+    vm.save
+
+Read more about port forwarding {VirtualBox::ForwardedPort here}.
 
-In addition to `valid?` there is `errors` which returns a hash of all the errors,
-including errors on relationships. There is also the `validate` method which
-runs the validations, but you really shouldn't have the need to call that directly.
+## More Ruby Versions Supported!
 
-All validations are run automatically on `save`, which will return `false` if
-they fail. If you choose to raise errors on the save, a `ValidationFailedException`
-will be raised (in contrast to a `CommandFailedException`, which serves its own
-role).
+Previously, virtualbox only supported 1.8.7. It now supports 1.8.6 and 1.9.x thanks
+to AleksiP.

data/lib/virtualbox.rb

@@ -6,6 +6,8 @@ require 'virtualbox/proxies/collection'
 require 'virtualbox/image'
 require 'virtualbox/attached_device'
 require 'virtualbox/dvd'
+require 'virtualbox/extra_data'
+require 'virtualbox/forwarded_port'
 require 'virtualbox/hard_drive'
 require 'virtualbox/nic'
 require 'virtualbox/shared_folder'

data/lib/virtualbox/abstract_model/relatable.rb

@@ -96,8 +96,7 @@ module VirtualBox
         def relationship(name, klass, options = {})
           name = name.to_sym
           
-          @relationships ||= {}
-          @relationships[name] = { :klass => klass }.merge(options)
+          relationships << [name, { :klass => klass }.merge(options)]
           
           # Define the method to read the relationship
           define_method(name) { relationship_data[name] }
@@ -109,8 +108,22 @@ module VirtualBox
         # Returns a hash of all the relationships.
         #
         # @return [Hash]
+        def relationships_hash
+          Hash[*relationships.flatten]
+        end
+        
+        # Returns an array of the relationships in order of being added.
+        #
+        # @return [Array]
         def relationships
-          @relationships ||= {}
+          @relationships ||= []
+        end
+
+        # Returns a boolean of whether a relationship exists.
+        #
+        # @return [Boolean]
+        def has_relationship?(name)
+          !!relationships.detect { |r| r[0] == name }
         end
         
         # Used to propagate relationships to subclasses. This method makes sure that
@@ -166,7 +179,7 @@ module VirtualBox
       #
       # @param [Symbol] name The name of the relationship
       def destroy_relationship(name, *args)
-        options = self.class.relationships[name]
+        options = self.class.relationships_hash[name]
         return unless options && options[:klass].respond_to?(:destroy_relationship)
         options[:klass].destroy_relationship(self, relationship_data[name], *args)
       end
@@ -183,7 +196,7 @@ module VirtualBox
       #
       # @return [Boolean]
       def has_relationship?(key)
-        self.class.relationships.has_key?(key.to_sym)
+        self.class.has_relationship?(key.to_sym)
       end
       
       # Sets a relationship to the given value. This is not guaranteed to
@@ -201,7 +214,7 @@ module VirtualBox
       # @param [Object] value The new value of the relationship.
       def set_relationship(key, value)
         key = key.to_sym
-        relationship = self.class.relationships[key]
+        relationship = self.class.relationships_hash[key]
         return unless relationship
         
         raise Exceptions::NonSettableRelationshipException.new unless relationship[:klass].respond_to?(:set_relationship)

data/lib/virtualbox/extra_data.rb

@@ -0,0 +1,151 @@
+module VirtualBox
+  # Represents "extra data" which can be set on a specific
+  # virtual machine or on VirtualBox as a whole. Extra data is persistent
+  # key-value storage which is available as a way to store any information
+  # wanted. VirtualBox uses it for storing statistics and settings. You can
+  # use it for anything!
+  #
+  # # Extra Data on a Virtual Machine
+  #
+  # Setting extra data on a virtual machine is easy. All {VM} objects have a 
+  # `extra_data` relationship which is just a simple ruby hash, so you can treat
+  # it like one! Once the data is set, simply saving the VM will save the
+  # extra data. An example below:
+  #
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     vm.extra_data["ruby-accessed"]  = "yes, yes it was"
+  #     vm.save
+  #
+  # Now, let's say you open up the VM again some other time:
+  #
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     puts vm.extra_data["ruby-accessed"]
+  #
+  # It acts just like a hash!
+  #
+  # # Global Extra Data
+  #
+  # Extra data doesn't need to be tied to a specific virtual machine. It can also
+  # exist globally. Setting global extra-data is just as easy:
+  #
+  #     VirtualBox::ExtraData.global["some-key"] = "some value"
+  #     VirtualBox::ExtraData.global.save
+  #
+  class ExtraData < Hash
+    include AbstractModel::Dirty
+    
+    attr_accessor :parent
+    
+    @@global_data = nil
+    
+    class <<self
+      # Gets the global extra data. This will "cache" the data for
+      # future use unless you set the `reload` paramter to true.
+      #
+      # @param [Boolean] reload If true, will reload new global data.
+      # @return [Array<ExtraData>]
+      def global(reload=false)
+        if !@@global_data || reload
+          raw = Command.vboxmanage("getextradata global enumerate")
+          @@global_data = parse_kv_pairs(raw)
+        end
+        
+        @@global_data
+      end
+      
+      # Parses the key-value pairs from the extra data enumerated
+      # output.
+      #
+      # @param [String] raw The raw output from enumerating extra data.
+      # @return [Hash]
+      def parse_kv_pairs(raw, parent=nil)
+        data = new(parent)
+        raw.split("\n").each do |line|
+          next unless line =~ /^Key: (.+?), Value: (.+?)$/i
+          data[$1.to_s] = $2.strip.to_s
+        end
+        
+        data.clear_dirty!
+        data
+      end
+      
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<ExtraData>]
+      def populate_relationship(caller, data)
+        raw = Command.vboxmanage("getextradata #{Command.shell_escape(caller.name)} enumerate")
+        parse_kv_pairs(raw, caller)
+      end
+      
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.save
+      end
+    end
+    
+    # Initializes an extra data object. 
+    #
+    # @param [Hash] data Initial attributes to populate.
+    def initialize(parent=nil)
+      @parent = parent || "global"
+    end
+    
+    # Set an extradata key-value pair. Overrides ruby hash implementation
+    # to set dirty state. Otherwise that, behaves the same way.
+    def []=(key,value)
+      set_dirty!(key, self[key], value)
+      super
+    end
+    
+    # Special accessor for parent name attribute. This returns
+    # either the parent name if its a VM object, otherwise
+    # just returns the default.
+    #
+    # @return [String]
+    def parent_name
+      if parent.is_a?(VM)
+        parent.name
+      else
+        parent
+      end
+    end
+    
+    # Saves extra data. This method does the same thing for both new
+    # and existing extra data, since virtualbox will overwrite old data or
+    # create it if it doesn't exist.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save(raise_errors=false)
+      changes.each do |key, value|
+        Command.vboxmanage("setextradata #{Command.shell_escape(parent_name)} #{Command.shell_escape(key)} #{Command.shell_escape(value[1])}")
+        clear_dirty!(key)
+      end
+      
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
+    end
+    
+    # Deletes the extra data. 
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def delete(key, raise_errors=false)
+      Command.vboxmanage("setextradata #{Command.shell_escape(parent_name)} #{Command.shell_escape(key)}")
+      super(key)
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
+    end
+  end
+end

data/lib/virtualbox/forwarded_port.rb

@@ -0,0 +1,197 @@
+module VirtualBox
+  # When a VM uses NAT as its NIC type, VirtualBox acts like its
+  # own private router for all virtual machines. Because of this,
+  # the host machine can't access services within the guest machine.
+  # To get around this, NAT supports port forwarding, which allows the
+  # guest machine services to be forwarded to some port on the host 
+  # machine. Port forwarding is done completely through {ExtraData}, but
+  # is a complicated enough procedure that this class was made to
+  # faciliate it.
+  #
+  # **Note:** After changing any forwarded ports, the entire VirtualBox
+  # process must be restarted completely for them to take effect. When
+  # working with the ruby library, this isn't so much of an issue, but
+  # if you have any VMs running, they must all be shut down and restarted.
+  #
+  # # Adding a new Forwarded Port
+  #
+  # Since forwarded ports rely on being part of a {VM}, we're going to
+  # assume that `vm` points to a {VM} which has already been found.
+  #
+  #     port = VirtualBox::ForwardedPort.new
+  #     port.name = "apache" # This can be anything
+  #     port.guestport = 80
+  #     port.hostport = 8080
+  #     vm.forwarded_ports << port
+  #     port.save # Or vm.save
+  #
+  # # Modifying an Existing Forwarded Port
+  #
+  # This is assuming that `vm` is a local variable storing a {VM} object
+  # which has already been found.
+  #
+  #     vm.forwarded_ports.first.hostport = 1919
+  #     vm.save
+  #
+  # # Deleting a Forwarded Port
+  #
+  # To delete a forwarded port, you simply destroy it like any other model:
+  #
+  #     vm.forwarded_ports.first.destroy
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the model are exposed using standard ruby instance
+  # methods which are generated on the fly. Because of this, they are not listed
+  # below as available instance methods. 
+  #
+  # These attributes can be accessed and modified via standard ruby-style
+  # `instance.attribute` and `instance.attribute=` methods. The attributes are
+  # listed below.
+  #
+  # Relationships are also accessed like attributes but can't be set. Instead,
+  # they are typically references to other objects such as an {AttachedDevice} which
+  # in turn have their own attributes which can be modified.
+  #
+  # ## Attributes
+  #
+  # This is copied directly from the class header, but lists all available
+  # attributes. If you don't understand what this means, read {Attributable}.
+  #
+  #     attribute :parent, :readonly => true
+  #     attribute :name
+  #     attribute :instance, :default => "0"
+  #     attribute :device, :default => "pcnet"
+  #     attribute :protocol, :default => "TCP"
+  #     attribute :guestport
+  #     attribute :hostport
+  #
+  class ForwardedPort < AbstractModel
+    attribute :parent, :readonly => true
+    attribute :name
+    attribute :instance, :default => "0"
+    attribute :device, :default => "pcnet"
+    attribute :protocol, :default => "TCP"
+    attribute :guestport
+    attribute :hostport
+    
+    class <<self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<ForwardedPort>]
+      def populate_relationship(caller, data)
+        relation = Proxies::Collection.new(caller)
+        
+        caller.extra_data.each do |key, value|
+          next unless key =~ /^(VBoxInternal\/Devices\/(.+?)\/(.+?)\/LUN#0\/Config\/(.+?)\/)Protocol$/i
+          
+          port = new({
+            :parent => caller,
+            :name => $4.to_s,
+            :instance => $3.to_s,
+            :device => $2.to_s,
+            :protocol => value,
+            :guestport => caller.extra_data["#{$1.to_s}GuestPort"],
+            :hostport => caller.extra_data["#{$1.to_s}HostPort"]
+          })
+          
+          port.existing_record!
+          
+          relation.push(port)
+        end
+        
+        relation
+      end
+      
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.each do |fp|
+          fp.save
+        end
+      end
+    end
+    
+    # @param [Hash] data The initial attributes to populate.
+    def initialize(data={})
+      super()
+      populate_attributes(data)
+    end
+    
+    # Validates a forwarded port.
+    def validate
+      super
+      
+      validates_presence_of :parent
+      validates_presence_of :name
+      validates_presence_of :guestport
+      validates_presence_of :hostport
+    end
+    
+    # Saves the forwarded port.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save(raise_errors=false)
+      return true if !new_record? && !changed?
+      
+      if !valid?
+        raise Exceptions::ValidationFailedException.new(errors) if raise_errors
+        return false
+      end
+      
+      destroy(raise_errors) if name_changed?
+      
+      parent.extra_data["#{key_prefix}Protocol"] = protocol
+      parent.extra_data["#{key_prefix}GuestPort"] = guestport
+      parent.extra_data["#{key_prefix}HostPort"] = hostport
+      result = parent.extra_data.save(raise_errors)
+      
+      clear_dirty!
+      existing_record!
+      
+      result
+    end
+    
+    # Destroys the port forwarding mapping.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def destroy(raise_errors=false)
+      results = []
+
+      if !new_record?
+        results << parent.extra_data.delete("#{key_prefix(true)}Protocol", raise_errors)
+        results << parent.extra_data.delete("#{key_prefix(true)}GuestPort", raise_errors)
+        results << parent.extra_data.delete("#{key_prefix(true)}HostPort", raise_errors)
+        
+        new_record!
+      end
+      
+      results.empty? || results.all? { |o| o == true }
+    end
+    
+    # Relationship callback when added to a collection. This is automatically
+    # called by any relationship collection when this object is added.
+    def added_to_relationship(parent)
+      write_attribute(:parent, parent)
+    end
+    
+    # Returns the prefix to be used for the extra data key. Forwarded ports
+    # are created by simply setting {ExtraData} on a {VM}. This class hides most
+    # of the inner workings of it, but it requires a common prefix. This method
+    # generates that.
+    #
+    # @return [String]
+    def key_prefix(old_name=false)
+      name_value = old_name && name_changed? ? name_was : name
+      "VBoxInternal\/Devices\/#{device}\/#{instance}\/LUN#0\/Config\/#{name_value}\/"
+    end
+  end
+end

data/lib/virtualbox/image.rb

@@ -53,7 +53,7 @@ module VirtualBox
 
         # Parses each line which should be in the format:
         # KEY: VALUE
-        block.lines.each do |line|
+        block.split("\n").each do |line|
           next unless line =~ /^(.+?):\s+(.+?)$/
           hd[$1.downcase.to_sym] = $2.to_s
         end

data/lib/virtualbox/nic.rb

@@ -54,7 +54,7 @@ module VirtualBox
         
         # Complicated chain of methods just maps parse_nic over each line,
         # removing invalid ones, and then converting it into a single hash.
-        raw.lines.collect { |v| parse_nic(v) }.compact.inject({}) do |acc, obj|
+        raw.split("\n").collect { |v| parse_nic(v) }.compact.inject({}) do |acc, obj|
           acc.merge({ obj[0] => obj[1] })
         end
       end

data/lib/virtualbox/shared_folder.rb

@@ -96,7 +96,7 @@ module VirtualBox
       #
       # @return [Array<SharedFolder>]
       def populate_relationship(caller, data)
-        relation = []
+        relation = Proxies::Collection.new(caller)
         
         counter = 1
         loop do

data/lib/virtualbox/storage_controller.rb

@@ -79,7 +79,6 @@ module VirtualBox
       #
       # **This method typically won't be used except internally.**
       def save_relationship(caller, data)
-        # Just call save on each nic with the VM
         data.each do |sc|
           sc.save
         end

data/lib/virtualbox/vm.rb

@@ -75,6 +75,8 @@ module VirtualBox
   #     relationship :nics, Nic
   #     relationship :storage_controllers, StorageController, :dependent => :destroy
   #     relationship :shared_folders, SharedFolder
+  #     relationship :extra_data, ExtraData
+  #     relationship :forwarded_ports, ForwardedPort
   #
   class VM < AbstractModel
     attribute :uuid, :readonly => true
@@ -106,6 +108,8 @@ module VirtualBox
     relationship :nics, Nic
     relationship :storage_controllers, StorageController, :dependent => :destroy
     relationship :shared_folders, SharedFolder
+    relationship :extra_data, ExtraData
+    relationship :forwarded_ports, ForwardedPort
     
     class <<self
       # Returns an array of all available VMs.
@@ -144,7 +148,7 @@ module VirtualBox
       #
       # @return [String]
       def human_info(name)
-        Command.vboxmanage("showvminfo #{name}")
+        Command.vboxmanage("showvminfo #{Command.shell_escape(name)}")
       end
       
       # Gets the VM info (machine readable) for a given VM and returns it
@@ -152,7 +156,7 @@ module VirtualBox
       #
       # @return [Hash] Parsed VM info.
       def raw_info(name)
-        raw = Command.vboxmanage("showvminfo #{name} --machinereadable")
+        raw = Command.vboxmanage("showvminfo #{Command.shell_escape(name)} --machinereadable")
         parse_vm_info(raw)
       end
       
@@ -160,7 +164,7 @@ module VirtualBox
       # into a hash. Ignores lines which don't match the format.
       def parse_vm_info(raw)
         parsed = {}
-        raw.lines.each do |line|
+        raw.split("\n").each do |line|
           # Some lines aren't configuration, we just ignore them
           next unless line =~ /^"?(.+?)"?="?(.+?)"?$/
           parsed[$1.downcase.to_sym] = $2.strip
@@ -177,7 +181,7 @@ module VirtualBox
       # @return [Array] Array of virtual machines.
       def parse_vm_list(raw)
         results = []
-        raw.lines.each do |line|
+        raw.split("\n").each do |line|
           next unless line =~ /^"(.+?)"\s+\{(.+?)\}$/
           results.push(find($1.to_s))
         end

data/test/virtualbox/abstract_model/relatable_test.rb

@@ -22,6 +22,19 @@ class RelatableTest < Test::Unit::TestCase
     @data = {}
   end
   
+  context "class methods" do
+    should "read back relationships in order added" do
+      order = mock("order")
+      order_seq = sequence("order_seq")
+      order.expects(:foos).in_sequence(order_seq)
+      order.expects(:bars).in_sequence(order_seq)
+      
+      RelatableModel.relationships.each do |name, options|
+        order.send(name)
+      end
+    end
+  end
+  
   context "setting a relationship" do
     setup do
       @model = RelatableModel.new
@@ -55,7 +68,7 @@ class RelatableTest < Test::Unit::TestCase
   
   context "subclasses" do
     class SubRelatableModel < RelatableModel
-      relationship :bars, Relatee
+      relationship :bars, RelatableTest::Relatee
     end
     
     setup do
@@ -63,12 +76,12 @@ class RelatableTest < Test::Unit::TestCase
     end
     
     should "inherit relationships of parent" do
-      assert @relationships.has_key?(:foos)
-      assert @relationships.has_key?(:bars)
+      assert SubRelatableModel.has_relationship?(:foos)
+      assert SubRelatableModel.has_relationship?(:bars)
     end
     
     should "inherit options of relationships" do
-      assert_equal Relatee, @relationships[:foos][:klass]
+      assert_equal Relatee, SubRelatableModel.relationships_hash[:foos][:klass]
     end
   end
   
@@ -161,6 +174,11 @@ class RelatableTest < Test::Unit::TestCase
       @model = RelatableModel.new
     end
     
+    should "have a class method as well" do
+      assert RelatableModel.has_relationship?(:foos)
+      assert !RelatableModel.has_relationship?(:bazs)
+    end
+    
     should "return true for existing relationships" do
       assert @model.has_relationship?(:foos)
     end

data/test/virtualbox/extra_data_test.rb

@@ -0,0 +1,218 @@
+require File.join(File.dirname(__FILE__), '..', 'test_helper')
+
+class ExtraDataTest < Test::Unit::TestCase
+  setup do
+    @raw = <<-raw
+.
+Key: GUI/LastVMSelected, Value: 02573b8e-f628-43ed-b688-e488414e07ac
+Key: GUI/LastWindowPostion, Value: 99,457,770,550
+Key: GUI/SUNOnlineData, Value: triesLeft=0
+Key: GUI/SuppressMessages, Value: ,confirmInputCapture,remindAboutAutoCapture,confirmRemoveMedium,remindAboutInaccessibleMedia,confirmGoingFullscreen,remindAboutMouseIntegrationOn
+Key: GUI/UpdateCheckCount, Value: 13
+Key: GUI/UpdateDate, Value: 1 d, 2010-01-29, stable 
+raw
+
+    VirtualBox::Command.stubs(:execute)
+
+    @ed = VirtualBox::ExtraData.new
+    @ed["foo"] = "bar"
+    @ed.clear_dirty!
+  end
+  
+  context "attributes" do
+    should "return parent name if its a VM object" do
+      vm = mock("vm")
+      vm.stubs(:is_a?).with(VirtualBox::VM).returns(true)
+      vm.stubs(:name).returns("FOO")
+      
+      @ed.parent = vm
+      assert_equal "FOO", @ed.parent_name
+    end
+    
+    should "return default otherwise" do
+      assert_equal "global", @ed.parent_name
+    end
+  end
+  
+  context "relationships" do
+    setup do
+      @caller = mock("caller")
+      @caller.stubs(:name).returns("foocaller")
+      
+      VirtualBox::Command.stubs(:vboxmanage).returns(@raw)      
+    end
+    
+    context "populating" do
+      should "call VBoxManage for the caller" do
+        VirtualBox::Command.expects(:vboxmanage).with("getextradata #{@caller.name} enumerate").returns(@raw)
+        VirtualBox::ExtraData.populate_relationship(@caller, {})
+      end
+      
+      should "call pairs_to_objects with parent set to the caller" do
+        VirtualBox::ExtraData.expects(:parse_kv_pairs).with(@raw, @caller).once
+        VirtualBox::ExtraData.populate_relationship(@caller, {})        
+      end
+      
+      should "return an array of ExtraData objects" do
+        result = VirtualBox::ExtraData.populate_relationship(@caller, {})
+        assert result.is_a?(VirtualBox::ExtraData)
+      end
+    end
+    
+    context "saving" do
+      should "call save on the ExtraData object" do
+        object = mock("object")
+        object.expects(:save).once
+        
+        VirtualBox::ExtraData.save_relationship(@caller, object)
+      end
+    end
+  end
+  
+  context "destroying (deleting)" do
+    setup do
+      @key = "foo"
+    end
+    
+    should "call the proper vbox command" do
+      VirtualBox::Command.expects(:vboxmanage).with("setextradata global foo")
+      assert @ed.delete(@key)
+    end
+    
+    should "remove the key from the hash" do
+      assert @ed.has_key?(@key)
+      assert @ed.delete(@key)
+      assert !@ed.has_key?(@key)
+    end
+    
+    should "raise an exception if true sent to save and error occured" do
+      VirtualBox::Command.stubs(:vboxmanage).raises(VirtualBox::Exceptions::CommandFailedException)
+      assert_raises(VirtualBox::Exceptions::CommandFailedException) {
+        @ed.delete(@key, true)
+      }
+    end
+    
+    should "return false if the command failed" do
+      VirtualBox::Command.stubs(:vboxmanage).raises(VirtualBox::Exceptions::CommandFailedException)
+      assert !@ed.delete(@key)
+    end
+  end
+  
+  context "saving" do
+    setup do
+      @ed["foo"] = "BAR"
+      assert @ed.changed?
+    end
+    
+    should "do nothing if there are no changes" do
+      @ed.clear_dirty!
+      VirtualBox::Command.expects(:vboxmanage).never
+      assert @ed.save
+    end
+    
+    should "call the proper vbox command" do
+      VirtualBox::Command.expects(:vboxmanage).with("setextradata global foo BAR")
+      assert @ed.save
+    end
+    
+    should "return false if the command failed" do
+      VirtualBox::Command.stubs(:vboxmanage).raises(VirtualBox::Exceptions::CommandFailedException)
+      assert !@ed.save
+    end
+    
+    should "raise an exception if true sent to save and error occured" do
+      VirtualBox::Command.stubs(:vboxmanage).raises(VirtualBox::Exceptions::CommandFailedException)
+      assert_raises(VirtualBox::Exceptions::CommandFailedException) {
+        @ed.save(true)
+      }
+    end
+    
+    should "clear dirty state" do
+      @ed["value"] = "rawr"
+      assert @ed.changed?
+      assert @ed.save
+      assert !@ed.changed?
+    end
+  end
+
+  context "setting dirty state" do
+    setup do
+      @ed = VirtualBox::ExtraData.new
+    end
+
+    should "not be dirty initially" do
+      assert !@ed.changed?
+    end
+    
+    should "be dirty when setting a value" do
+      @ed["foo"] = "bar"
+      assert @ed.changed?
+      assert @ed.changes.has_key?("foo")
+    end
+  end
+  
+  context "global extra data" do
+    setup do
+      get_seq = sequence("get_seq")
+      VirtualBox::Command.expects(:vboxmanage).with("getextradata global enumerate").once.in_sequence(get_seq)
+      VirtualBox::ExtraData.expects(:parse_kv_pairs).returns(@ed).once.in_sequence(get_seq)
+      @global = VirtualBox::ExtraData.global(true)
+    end
+    
+    should "call the command, parse it, then turn it into objects" do
+      assert_equal "bar", @global["foo"]
+    end
+    
+    should "return the same object if it exists for global data, rather than recreating it" do
+      VirtualBox::Command.expects(:vboxmanage).never
+      assert_equal @global, VirtualBox::ExtraData.global
+    end
+    
+    should "return a new object if reload is true" do
+      VirtualBox::Command.expects(:vboxmanage).once
+      VirtualBox::ExtraData.expects(:parse_kv_pairs).returns(@ed.dup).once
+      assert !@global.equal?(VirtualBox::ExtraData.global(true))
+    end
+  end
+  
+  context "constructor" do
+    should "set the parent with the given argument" do
+      ed = VirtualBox::ExtraData.new("JOEY")
+      assert_equal "JOEY", ed.parent
+    end
+    
+    should "be global by default" do
+      ed = VirtualBox::ExtraData.new
+      assert_equal "global", ed.parent
+    end
+  end
+  
+  context "parsing KV pairs" do
+    setup do
+      @data = VirtualBox::ExtraData.parse_kv_pairs(@raw)
+    end
+    
+    should "return the proper number of items" do
+      # Shows that it skips over non-matching lines as well
+      assert_equal 6, @data.length
+    end
+    
+    should "return as an ExtraData Hash" do
+      assert @data.is_a?(Hash)
+      assert @data.is_a?(VirtualBox::ExtraData)
+    end
+    
+    should "return proper values, trimmed" do
+      assert_equal "1 d, 2010-01-29, stable", @data["GUI/UpdateDate"]
+    end
+    
+    should  "send the 2nd param as the parent to the ED object" do
+      @data = VirtualBox::ExtraData.parse_kv_pairs(@raw, "FOO")
+      assert_equal "FOO", @data.parent
+    end
+    
+    should "return an unchanged ED object" do
+      assert !@data.changed?
+    end
+  end
+end

data/test/virtualbox/forwarded_port_test.rb

@@ -0,0 +1,206 @@
+require File.join(File.dirname(__FILE__), '..', 'test_helper')
+
+class ForwardedPortTest < Test::Unit::TestCase
+  setup do
+    @caller = mock("caller")
+  end
+  
+  context "validations" do
+    setup do
+      @port = VirtualBox::ForwardedPort.new
+      @port.name = "foo"
+      @port.guestport = "22"
+      @port.hostport = "2222"
+      @port.added_to_relationship(@caller)
+    end
+    
+    should "be valid with all fields" do
+      assert @port.valid?
+    end
+    
+    should "be invalid with no name" do
+      @port.name = nil
+      assert !@port.valid?
+    end
+    
+    should "be invalid with no guest port" do
+      @port.guestport = nil
+      assert !@port.valid?
+    end
+
+    should "be invalid with no host port" do
+      @port.hostport = nil
+      assert !@port.valid?
+    end
+    
+    should "be invalid if not in a relationship" do
+      @port.write_attribute(:parent, nil)
+      assert !@port.valid?
+    end
+  end
+  
+  context "with an instance" do
+    setup do
+      @port = VirtualBox::ForwardedPort.new({
+        :parent => @caller,
+        :name => "foo",
+        :guestport => "22",
+        :hostport => "2222"
+      })
+      
+      @ed = mock("extradata")
+      @ed.stubs(:[]=)
+      @ed.stubs(:save)
+      @ed.stubs(:delete)
+      @caller.stubs(:extra_data).returns(@ed)
+    end
+    
+    context "saving" do
+      context "an existing record" do
+        setup do
+          @port.existing_record!
+        end
+        
+        should "not do anything and return true if its unchanged" do
+          @caller.expects(:extra_data).never
+          assert @port.save
+        end
+        
+        should "clear the dirty state after saving" do
+          @port.name = "diff"
+          @port.save
+          assert !@port.changed?
+        end
+        
+        should "call destroy if the name changed" do
+          @port.name = "diff"
+          @port.expects(:destroy).once
+          @port.save
+        end
+        
+        should "not call destroy if the name didn't change" do
+          assert !@port.name_changed?
+          @port.expects(:destroy).never
+          @port.save
+        end
+      end
+      
+      context "a new record" do
+        setup do
+          assert @port.new_record!
+        end
+        
+        should "no longer be a new record after saving" do
+          @port.save
+          assert !@port.new_record?
+        end
+        
+        should "return false and do nothing if invalid" do
+          @caller.expects(:extra_data).never
+          @port.expects(:valid?).returns(false)
+          assert !@port.save
+        end
+        
+        should "raise a ValidationFailedException if invalid and raise_errors is true" do
+          @port.expects(:valid?).returns(false)
+          assert_raises(VirtualBox::Exceptions::ValidationFailedException) {
+            @port.save(true)
+          }
+        end
+        
+        should "call save on the extra_data" do
+          @ed = mock("ed")
+          @ed.expects(:[]=).times(3)
+          @ed.expects(:save).once
+          @caller.expects(:extra_data).times(4).returns(@ed)
+          @port.save
+        end
+      end
+    end
+    
+    context "key prefix" do
+      should "return a proper key prefix constructed with the attributes" do
+        assert_equal "VBoxInternal\/Devices\/#{@port.device}\/#{@port.instance}\/LUN#0\/Config\/#{@port.name}\/", @port.key_prefix
+      end
+      
+      should "return with previous name if parameter is true" do
+        @port.name = "diff"
+        assert @port.name_changed?
+        assert_equal "VBoxInternal\/Devices\/#{@port.device}\/#{@port.instance}\/LUN#0\/Config\/#{@port.name_was}\/", @port.key_prefix(true)
+      end
+      
+      should "not use previous name if parameter is true and name didn't change" do
+        assert !@port.name_changed?
+        assert_equal "VBoxInternal\/Devices\/#{@port.device}\/#{@port.instance}\/LUN#0\/Config\/#{@port.name}\/", @port.key_prefix(true)
+      end
+    end
+    
+    context "destroying" do
+      setup do
+        @port.existing_record!
+      end
+      
+      should "call delete on the extra data for each key" do
+        @ed = mock("ed")
+        @ed.expects(:delete).times(3)
+        @caller.expects(:extra_data).times(3).returns(@ed)
+        @port.destroy
+      end
+      
+      should "do nothing if the record is new" do
+        @port.new_record!
+        @caller.expects(:extra_data).never
+        @port.destroy
+      end
+      
+      should "be a new record after destroying" do
+        @port.destroy
+        assert @port.new_record?
+      end
+    end
+  end
+  
+  context "relationships" do
+    context "saving" do
+      should "call #save on every object" do
+        objects = []
+        5.times do |i|
+          object = mock("object#{i}")
+          object.expects(:save).once
+          objects.push(object)
+        end
+        
+        VirtualBox::ForwardedPort.save_relationship(@caller, objects)
+      end
+    end
+    
+    context "populating" do
+      setup do
+        @caller.stubs(:extra_data).returns({
+          "invalid" => "7",
+          "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/GuestPort" => "22",
+          "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/HostPort" => "2222",
+          "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/Protocol" => "TCP"
+        })
+        
+        @objects = VirtualBox::ForwardedPort.populate_relationship(@caller, {})
+      end
+      
+      should "return an array of ForwardedPorts" do
+        assert @objects.is_a?(VirtualBox::Proxies::Collection)
+        assert @objects.all? { |o| o.is_a?(VirtualBox::ForwardedPort) }
+      end
+      
+      should "have the proper data" do
+        object = @objects.first
+        assert_equal "22", object.guestport
+        assert_equal "2222", object.hostport
+        assert_equal "TCP", object.protocol
+      end
+      
+      should "be existing records" do
+        assert !@objects.first.new_record?
+      end
+    end
+  end
+end

data/test/virtualbox/shared_folder_test.rb

@@ -213,6 +213,10 @@ class SharedFolderTest < Test::Unit::TestCase
     setup do
       @value = VirtualBox::SharedFolder.populate_relationship(@caller, @data)
     end
+    
+    should "be a 'collection'" do
+      assert @value.is_a?(VirtualBox::Proxies::Collection)
+    end
 
     should "create the correct amount of objects" do
       assert_equal 2, @value.length

data/test/virtualbox/vm_test.rb

@@ -89,6 +89,7 @@ showvminfo
     VirtualBox::Command.expects(:vboxmanage).with("showvminfo #{@name}").returns("")
     VirtualBox::Command.expects(:vboxmanage).with("list hdds").returns("")
     VirtualBox::Command.expects(:vboxmanage).with("list dvds").returns("")
+    VirtualBox::Command.expects(:vboxmanage).with("getextradata #{@name} enumerate").returns("")
     vm = VirtualBox::VM.find(@name)
     assert vm
     vm
@@ -99,6 +100,11 @@ showvminfo
       VirtualBox::Command.expects(:vboxmanage).with("showvminfo #{@name}").once
       VirtualBox::VM.human_info(@name)
     end
+    
+    should "shell escape parameter" do
+      VirtualBox::Command.expects(:vboxmanage).with("showvminfo hello\\ world").once
+      VirtualBox::VM.human_info("hello world")
+    end
   end
   
   context "reading the VM state" do
@@ -359,6 +365,8 @@ raw
       VirtualBox::Nic.expects(:save_relationship).once
       VirtualBox::StorageController.expects(:save_relationship).once
       VirtualBox::SharedFolder.expects(:save_relationship).once
+      VirtualBox::ExtraData.expects(:save_relationship).once
+      VirtualBox::ForwardedPort.expects(:save_relationship).once
       assert @vm.save
     end
   end
@@ -379,6 +387,11 @@ raw
       assert @vm
     end
     
+    should "shell escape the VM name" do
+      VirtualBox::Command.expects(:vboxmanage).with("showvminfo hello\\ world --machinereadable").returns(@raw)
+      assert VirtualBox::VM.find("hello world")
+    end
+    
     should "return a VM object with proper attributes" do      
       @expected.each do |k,v|
         assert_equal v, @vm.read_attribute(k)

data/virtualbox.gemspec

@@ -5,20 +5,22 @@
 
 Gem::Specification.new do |s|
   s.name = %q{virtualbox}
-  s.version = "0.3.0"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mitchell Hashimoto"]
-  s.date = %q{2010-01-28}
+  s.date = %q{2010-01-29}
   s.description = %q{Create and modify virtual machines in VirtualBox using pure ruby.}
   s.email = %q{mitchell.hashimoto@gmail.com}
   s.extra_rdoc_files = [
-    "TODO"
+    "LICENSE",
+     "TODO"
   ]
   s.files = [
     ".gitignore",
      ".yardopts",
      "Gemfile",
+     "LICENSE",
      "Rakefile",
      "Readme.md",
      "TODO",
@@ -36,6 +38,8 @@ Gem::Specification.new do |s|
      "lib/virtualbox/dvd.rb",
      "lib/virtualbox/exceptions.rb",
      "lib/virtualbox/ext/subclass_listing.rb",
+     "lib/virtualbox/extra_data.rb",
+     "lib/virtualbox/forwarded_port.rb",
      "lib/virtualbox/hard_drive.rb",
      "lib/virtualbox/image.rb",
      "lib/virtualbox/nic.rb",
@@ -53,6 +57,8 @@ Gem::Specification.new do |s|
      "test/virtualbox/command_test.rb",
      "test/virtualbox/dvd_test.rb",
      "test/virtualbox/ext/subclass_listing_test.rb",
+     "test/virtualbox/extra_data_test.rb",
+     "test/virtualbox/forwarded_port_test.rb",
      "test/virtualbox/hard_drive_test.rb",
      "test/virtualbox/image_test.rb",
      "test/virtualbox/nic_test.rb",
@@ -78,6 +84,8 @@ Gem::Specification.new do |s|
      "test/virtualbox/command_test.rb",
      "test/virtualbox/dvd_test.rb",
      "test/virtualbox/ext/subclass_listing_test.rb",
+     "test/virtualbox/extra_data_test.rb",
+     "test/virtualbox/forwarded_port_test.rb",
      "test/virtualbox/hard_drive_test.rb",
      "test/virtualbox/image_test.rb",
      "test/virtualbox/nic_test.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: virtualbox
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Mitchell Hashimoto
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-28 00:00:00 -08:00
+date: 2010-01-29 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
@@ -20,11 +20,13 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
+- LICENSE
 - TODO
 files: 
 - .gitignore
 - .yardopts
 - Gemfile
+- LICENSE
 - Rakefile
 - Readme.md
 - TODO
@@ -42,6 +44,8 @@ files:
 - lib/virtualbox/dvd.rb
 - lib/virtualbox/exceptions.rb
 - lib/virtualbox/ext/subclass_listing.rb
+- lib/virtualbox/extra_data.rb
+- lib/virtualbox/forwarded_port.rb
 - lib/virtualbox/hard_drive.rb
 - lib/virtualbox/image.rb
 - lib/virtualbox/nic.rb
@@ -59,6 +63,8 @@ files:
 - test/virtualbox/command_test.rb
 - test/virtualbox/dvd_test.rb
 - test/virtualbox/ext/subclass_listing_test.rb
+- test/virtualbox/extra_data_test.rb
+- test/virtualbox/forwarded_port_test.rb
 - test/virtualbox/hard_drive_test.rb
 - test/virtualbox/image_test.rb
 - test/virtualbox/nic_test.rb
@@ -106,6 +112,8 @@ test_files:
 - test/virtualbox/command_test.rb
 - test/virtualbox/dvd_test.rb
 - test/virtualbox/ext/subclass_listing_test.rb
+- test/virtualbox/extra_data_test.rb
+- test/virtualbox/forwarded_port_test.rb
 - test/virtualbox/hard_drive_test.rb
 - test/virtualbox/image_test.rb
 - test/virtualbox/nic_test.rb