virtualbox 0.1.0

data/lib/virtualbox/storage_controller.rb

@@ -0,0 +1,122 @@
+module VirtualBox
+  # Represents a single storage controller which can be attached to a
+  # virtual machine.
+  # 
+  # **Currently, storage controllers can not be created from scratch.
+  # Therefore, the only way to use this model is through a relationship
+  # of a {VM} object.**
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the storage controller 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 :type
+  #     attribute :max_ports, :populate_key => :maxportcount
+  #     attribute :ports, :populate_key => :portcount
+  #
+  # ## Relationships
+  #
+  # In addition to the basic attributes, a virtual machine is related
+  # to other things. The relationships are listed below. If you don't
+  # understand this, read {Relatable}.
+  #
+  #     relationship :devices, AttachedDevice, :dependent => :destroy
+  #
+  class StorageController < AbstractModel
+    attribute :parent, :readonly => true
+    attribute :name
+    attribute :type
+    attribute :max_ports, :populate_key => :maxportcount
+    attribute :ports, :populate_key => :portcount
+    relationship :devices, AttachedDevice, :dependent => :destroy
+    
+    class <<self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<StorageController>]
+      def populate_relationship(caller, data)
+        relation = []
+        
+        counter = 0
+        loop do
+          break unless data["storagecontrollername#{counter}".to_sym]
+          nic = new(counter, caller, data)
+          relation.push(nic)
+          counter += 1
+        end
+        
+        relation
+      end
+      
+      # Destroys a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      def destroy_relationship(caller, data, *args)
+        data.each { |v| v.destroy(*args) }
+      end
+    end
+    
+    # Since storage controllers still can't be created from scratch,
+    # this method shouldn't be called. Instead, storage controllers
+    # can be retrieved through relationships of other models such
+    # as {VM}.
+    def initialize(index, caller, data)
+      super()
+      
+      @index = index
+      
+      # Setup the index specific attributes
+      populate_data = {}
+      self.class.attributes.each do |name, options|
+        key = options[:populate_key] || name
+        value = data["storagecontroller#{key}#{index}".to_sym]
+        populate_data[key] = value
+      end
+      
+      # Make sure to merge in device data so those relationships will be
+      # setup properly
+      populate_data.merge!(extract_devices(index, data))
+      
+      populate_attributes(populate_data.merge({
+        :parent => caller
+      }))
+    end
+    
+    # Extracts related devices for a storage controller.
+    #
+    # **This method typically won't be used except internally.**
+    #
+    # @return [Hash]
+    def extract_devices(index, data)
+      name = data["storagecontrollername#{index}".downcase.to_sym].downcase
+      
+      device_data = {}
+      data.each do |k,v|
+        next unless k.to_s =~ /^#{name}-/
+        
+        device_data[k] = v
+      end
+      
+      device_data
+    end
+  end
+end

data/lib/virtualbox/vm.rb

@@ -0,0 +1,287 @@
+module VirtualBox
+  # Represents a single VirtualBox virtual machine. All attributes which are
+  # not read-only can be modified and saved. 
+  #
+  # # Finding Virtual Machines
+  #
+  # Two methods are used to find virtual machines: {VM.all} and {VM.find}. Each
+  # return a {VM} object. An example is shown below:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     puts vm.name # => "MyWindowsXP"
+  #
+  # # Modifying Virtual Machines
+  #
+  # Virtual machines can be modified a lot like [ActiveRecord](http://ar.rubyonrails.org/)
+  # objects. This is best shown through example:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     vm.memory = 256
+  #     vm.name = "WindowsXP"
+  #     vm.save
+  #
+  # # Attributes and Relationships
+  # 
+  # Properties of the virtual machine 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 a {HardDrive} 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 :uuid, :readonly => true
+  #     attribute :name
+  #     attribute :ostype
+  #     attribute :memory
+  #     attribute :vram
+  #     attribute :acpi
+  #     attribute :ioapic
+  #     attribute :cpus
+  #     attribute :synthcpu
+  #     attribute :pae
+  #     attribute :hwvirtex
+  #     attribute :hwvirtexexcl
+  #     attribute :nestedpaging
+  #     attribute :vtxvpid
+  #     attribute :accelerate3d
+  #     attribute :biosbootmenu, :populate_key => :bootmenu
+  #     attribute :boot1
+  #     attribute :boot2
+  #     attribute :boot3
+  #     attribute :boot4
+  #     attribute :clipboard
+  #     attribute :monitorcount
+  #     attribute :usb
+  #     attribute :audio
+  #     attribute :vrdp
+  #     attribute :state, :populate_key => :vmstate, :readonly => true
+  #
+  # ## Relationships
+  #
+  # In addition to the basic attributes, a virtual machine is related
+  # to other things. The relationships are listed below. If you don't
+  # understand this, read {Relatable}.
+  #
+  #     relationship :nics, Nic
+  #     relationship :storage_controllers, StorageController, :dependent => :destroy
+  #
+  class VM < AbstractModel
+    attribute :uuid, :readonly => true
+    attribute :name
+    attribute :ostype
+    attribute :memory
+    attribute :vram
+    attribute :acpi
+    attribute :ioapic
+    attribute :cpus
+    attribute :synthcpu
+    attribute :pae
+    attribute :hwvirtex
+    attribute :hwvirtexexcl
+    attribute :nestedpaging
+    attribute :vtxvpid
+    attribute :accelerate3d
+    attribute :biosbootmenu, :populate_key => :bootmenu
+    attribute :boot1
+    attribute :boot2
+    attribute :boot3
+    attribute :boot4
+    attribute :clipboard
+    attribute :monitorcount
+    attribute :usb
+    attribute :audio
+    attribute :vrdp
+    attribute :state, :populate_key => :vmstate, :readonly => true
+    relationship :nics, Nic
+    relationship :storage_controllers, StorageController, :dependent => :destroy
+    
+    class <<self
+      # Returns an array of all available VMs.
+      #
+      # @return [Array<VM>]
+      def all
+        raw = Command.vboxmanage("list vms")
+        parse_vm_list(raw)
+      end
+      
+      # Finds a VM by UUID or registered name and returns a
+      # new VM object. If the VM doesn't exist, will return `nil`.
+      #
+      # @return [VM]
+      def find(name)
+        new(raw_info(name))
+      end
+      
+      # Imports a VM, blocking the entire thread during this time. 
+      # When finished, on success, will return the VM object. This
+      # VM object can be used to make any modifications necessary
+      # (RAM, cpus, etc.).
+      #
+      # @return [VM] The newly imported virtual machine
+      def import(source_path)
+        raw = Command.vboxmanage("import #{Command.shell_escape(source_path)}")
+        return nil unless raw
+        
+        find(parse_vm_name(raw))
+      end
+      
+      # Gets the non-machine-readable info for a given VM and returns
+      # it as a raw string.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [String]
+      def human_info(name)
+        Command.vboxmanage("showvminfo #{name}")
+      end
+      
+      # Gets the VM info (machine readable) for a given VM and returns it
+      # as a hash. 
+      #
+      # @return [Hash] Parsed VM info.
+      def raw_info(name)
+        raw = Command.vboxmanage("showvminfo #{name} --machinereadable")
+        parse_vm_info(raw)
+      end
+      
+      # Parses the machine-readable format outputted by VBoxManage showvminfo
+      # into a hash. Ignores lines which don't match the format.
+      def parse_vm_info(raw)
+        parsed = {}
+        raw.lines.each do |line|
+          # Some lines aren't configuration, we just ignore them
+          next unless line =~ /^"?(.+?)"?="?(.+?)"?$/
+          parsed[$1.downcase.to_sym] = $2.strip
+        end
+
+        parsed
+      end
+      
+      # Parses the list of VMs returned by the "list vms" command used
+      # in {VM.all}.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array] Array of virtual machines.
+      def parse_vm_list(raw)
+        results = []
+        raw.lines.each do |line|
+          next unless line =~ /^"(.+?)"\s+\{(.+?)\}$/
+          results.push(find($1.to_s))
+        end
+        
+        results
+      end
+      
+      # Parses the vm name from the import results.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [String] Parsed VM name
+      def parse_vm_name(raw)
+        return nil unless raw =~ /VM name "(.+?)"/
+        $1.to_s
+      end
+    end
+    
+    # Creates a new instance of a virtual machine.
+    #
+    # **Currently can NOT be used to create a NEW virtual machine**.
+    # Support for creating new virtual machines will be added shortly.
+    # For now, this is only used by {VM.find} and {VM.all} to
+    # initialize the VMs.
+    def initialize(data)
+      super()
+      
+      populate_attributes(data)
+      @original_name = data[:name]
+    end
+    
+    # State of the virtual machine. Returns the state of the virtual
+    # machine. This state will represent the state that was assigned
+    # when the VM was found unless `reload` is set to `true`.
+    #
+    # @param [Boolean] reload If true, will reload the state to current
+    #   value.
+    # @return [String] Virtual machine state.
+    def state(reload=false)
+      if reload
+        info = self.class.raw_info(@original_name)
+        write_attribute(:state, info[:vmstate])
+      end
+      
+      read_attribute(:state)
+    end
+    
+    # Saves the virtual machine if modified. This method saves any modified
+    # attributes of the virtual machine. If any related attributes were saved
+    # as well (such as storage controllers), those will be saved, too.
+    def save
+      # Make sure we save the new name first if that was changed, or
+      # we'll get some inconsistencies later
+      if name_changed?
+        save_attribute(:name, name)
+        @original_name = name
+      end
+      
+      super
+    end
+    
+    # Saves a single attribute of the virtual machine. This should **not**
+    # be called except interally. Instead, you're probably looking for {#save}.
+    #
+    # **This method typically won't be used except internally.**
+    def save_attribute(key, value)
+      Command.vboxmanage("modifyvm #{@original_name} --#{key} #{Command.shell_escape(value.to_s)}")
+      super
+    end
+    
+    # Starts the virtual machine. The virtual machine can be started in a
+    # variety of modes:
+    #
+    # * **gui** -- The VirtualBox GUI will open with the screen of the VM.
+    # * **headless** -- The VM will run in the background. No GUI will be 
+    #   present at all.
+    #
+    # All modes will start their processes and return almost immediately.
+    # Both the GUI and headless mode will not block the ruby process.
+    def start(mode=:gui)
+      Command.vboxmanage("startvm #{@original_name} --type #{mode}")
+    end
+    
+    # Stops the VM by directly calling "poweroff." Immediately halts the
+    # virtual machine without saving state. This could result in a loss
+    # of data.
+    def stop
+      Command.vboxmanage("controlvm #{@original_name} poweroff")
+    end
+    
+    # Destroys the virtual machine. This method also removes all attached
+    # media (required by VirtualBox to destroy a VM). By default,
+    # this **will not** destroy attached hard drives, but will if given
+    # the `destroy_image` option.
+    #
+    # @overload destroy(opts = {})
+    #   Passes options to the destroy method.
+    #   @option opts [Boolean] :destroy_image (false) If true, will
+    #     also destroy all attached images such as hard drives, disk
+    #     images, etc.
+    def destroy(*args)
+      # Call super first to destroy relationships, necessary before
+      # unregistering a VM
+      super
+      
+      Command.vboxmanage("unregistervm #{@original_name} --delete")
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,25 @@
+begin
+  require File.join(File.dirname(__FILE__), '..', 'vendor', 'gems', 'environment')
+rescue LoadError
+  puts <<-ENVERR
+==================================================
+ERROR: Gem environment file not found!
+
+This gem uses bundler to handle gem dependencies. To setup the
+test environment, please run `gem bundle test` If you don't
+have bundler, you can install that with `gem install bundler`
+==================================================
+ENVERR
+  exit
+end
+
+# ruby-debug, not necessary, but useful if we have it
+begin
+  require 'ruby-debug'
+rescue LoadError; end
+
+require 'contest'
+require 'mocha'
+
+# The actual library
+require File.join(File.dirname(__FILE__), '..', 'lib', 'virtualbox')

data/test/virtualbox/abstract_model/attributable_test.rb

@@ -0,0 +1,150 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'test_helper')
+
+class AttributableTest < Test::Unit::TestCase
+  class EmptyAttributeModel
+    include VirtualBox::AbstractModel::Attributable    
+  end
+  
+  class AttributeModel < EmptyAttributeModel
+    attribute :foo
+    attribute :bar
+    
+    def initialize
+      super
+      
+      populate_attributes({
+        :foo => "foo",
+        :bar => "bar"
+      })
+    end
+  end
+  
+  context "subclasses" do
+    class SubModel < AttributeModel
+      attribute :baz
+    end
+    
+    should "have foo bar and baz" do
+      attributes = SubModel.attributes
+      assert attributes.has_key?(:foo)
+      assert attributes.has_key?(:bar)
+      assert attributes.has_key?(:baz)
+    end
+  end
+  
+  context "attribute options" do
+    context "custom populate keys" do
+      class CustomPopulateModel < AttributeModel
+        attribute :foo, :populate_key => :foo_key
+      end
+      
+      setup do
+        @model = CustomPopulateModel.new
+      end
+      
+      should "use the populate key instead of the attribute name" do
+        @model.populate_attributes({
+          :foo => "not me!",
+          :foo_key => "bar"
+        })
+        
+        assert_equal "bar", @model.foo
+      end
+    end
+    
+    context "readonly attributes" do
+      class ReadonlyModel < AttributeModel
+        attribute :foo, :readonly => :readonly
+        
+        def initialize
+          super
+          populate_attributes({ :foo => "foo" })
+        end
+      end
+      
+      setup do
+        @model = ReadonlyModel.new
+      end
+      
+      should "be readonly" do
+        assert @model.readonly_attribute?(:foo)
+      end
+      
+      should "allow reading" do
+        assert_equal "foo", @model.foo
+      end
+      
+      should "not allow writing" do
+        assert_raises(NoMethodError) { @model.foo = "YO" }
+      end
+    end
+    
+    context "default values" do
+      class DefaultModel < EmptyAttributeModel
+        attribute :foo, :default => "FOO!"
+        attribute :bar
+      end
+      
+      setup do
+        @model = DefaultModel.new
+      end
+      
+      should "read default values" do
+        assert_equal "FOO!", @model.foo
+        assert_nil @model.bar
+      end
+    end
+  end
+  
+  context "populating attributes" do
+    setup do
+      @model = AttributeModel.new
+    end
+    
+    should "write all valid attributes" do
+      new_attributes = {
+        :foo => "zxcv",
+        :bar => "qwerty"
+      }
+      
+      @model.populate_attributes(new_attributes)
+      new_attributes.each do |k,v|
+        assert_equal v, @model.send(k)
+      end
+    end
+  end
+  
+  context "reading and writing attributes" do
+    setup do
+      @model = AttributeModel.new
+      @checkstring = "HEY"
+    end
+    
+    should "be able to read an entire hash of attributes" do
+      atts = @model.attributes
+      assert atts.is_a?(Hash)
+      assert atts.has_key?(:foo)
+      assert atts.has_key?(:bar)
+    end
+    
+    should "be able to write defined attributes" do
+      assert_nothing_raised {
+        @model.foo = @check_string
+      }
+    end
+    
+    should "be able to read defined attributes" do
+      assert_nothing_raised {
+        assert_equal "foo", @model.foo
+      }
+    end
+    
+    should "raise an error if attempting to write an undefined attribute" do
+      assert_raises(NoMethodError) { @model.baz = @check_string }
+    end
+    
+    should "raise an error if attempting to read an undefined attribute" do
+      assert_raises(NoMethodError) { @model.baz }
+    end
+  end
+end