virtualbox 0.1.0

data/lib/virtualbox/dvd.rb

@@ -0,0 +1,31 @@
+module VirtualBox
+  # Represents a DVD image stored by VirtualBox. These DVD images can be
+  # mounted onto virtual machines.
+  #
+  # # Finding all DVDs
+  #
+  # The only method at the moment of finding DVDs is to use {DVD.all}, which
+  # returns an array of {DVD}s.
+  #
+  #     DVD.all
+  #
+  class DVD < Image
+    class <<self
+      # Returns an array of all available DVDs as DVD objects
+      def all
+        raw = Command.vboxmanage("list dvds")
+        parse_raw(raw)
+      end
+    end
+    
+    # Deletes the DVD from VBox managed list and also from disk.
+    # This method will fail if the disk is currently mounted to any
+    # virtual machine.
+    #
+    # @return [Boolean]
+    def destroy
+      Command.vboxmanage("closemedium dvd #{uuid} --delete")
+      return $?.to_i == 0
+    end
+  end
+end

data/lib/virtualbox/errors.rb

@@ -0,0 +1,7 @@
+module VirtualBox
+  # Gem specific exceptions will reside under this namespace for easy
+  # documentation and searching.
+  module Errors
+    class Exception < ::Exception; end
+  end
+end

data/lib/virtualbox/ext/subclass_listing.rb

@@ -0,0 +1,24 @@
+# From: http://snippets.dzone.com/posts/show/2992
+module VirtualBox::SubclassListing
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  module ClassMethods
+    def subclasses(direct = false)
+      classes = []
+      if direct
+        ObjectSpace.each_object(Class) do |c|
+          next unless c.superclass == self
+          classes << c
+        end
+      else
+        ObjectSpace.each_object(Class) do |c|
+          next unless c.ancestors.include?(self) and (c != self)
+          classes << c
+        end
+      end
+      classes
+    end
+  end
+end

data/lib/virtualbox/hard_drive.rb

@@ -0,0 +1,169 @@
+module VirtualBox
+  # Represents a hard disk which is registered with VirtualBox.
+  #
+  # # Finding a Hard Drive
+  #
+  # Hard drives can be found use {HardDrive.all} and {HardDrive.find}, which
+  # find all or a specific hard drive, respectively. Example below:
+  #
+  #     VirtualBox::HardDrive.all
+  # 
+  # Or:
+  #
+  #     VirtualBox::HardDrive.find("Foo.vdi")
+  #
+  # # Creating a Hard Drive
+  #
+  # The hard drive is one of the few data items at the moment which supports
+  # new creation. Below is a simple example of how this works:
+  #
+  #     hd = VirtualBox::HardDrive.new
+  #     hd.location = "foo.vdi"
+  #     hd.size = 2400 # in megabytes
+  #     hd.save
+  #
+  #     # You can now access other attributes, since its saved:
+  #     hd.uuid
+  #     hd.location # will return a full path now
+  #
+  # Although `VDI` is the default format for newly created hard drives, other
+  # formats are supported:
+  #
+  #     hd = VirtualBox::HardDrive.new
+  #     hd.format = "VMDK"
+  #     hd.location = "bar.vmdk"
+  #     hd.size = 9001 # Its over 9000! (If you don't understand the reference, just ignore this comment)
+  #     hd.save
+  #
+  # Any formats listed by your VirtualBox installation's `VBoxManage list hddbackends` command
+  # can be used with the virtualbox gem.
+  #
+  # # Destroying Hard Drives
+  #
+  # Hard drives can also be deleted, which will completely remove them from
+  # disk. **This operation is not reversable**.
+  #
+  #     hd = VirtualBox::HardDrive.find("foo")
+  #     hd.destroy
+  #
+  # # Cloning Hard Drives
+  #
+  # Hard drives can just as easily be cloned as they can be created or destroyed.
+  # 
+  #     hd = VirtualBox::HardDrive.find("foo")
+  #     cloned_hd = hd.clone("bar") 
+  #
+  # In addition to simply cloning hard drives, this command can be used to
+  # clone to a different format:
+  #
+  #     hd = VirtualBox::HardDrive.find("foo")
+  #     hd.clone("bar", "VMDK") # Will clone and convert to VMDK format
+  #
+  # # Attributes
+  #
+  # 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. If you aren't sure what this means or you can't understand
+  # why the below is listed, please read {Attributable}.
+  # 
+  #     attribute :uuid, :readonly => true
+  #     attribute :location
+  #     attribute :accessible, :readonly => true
+  #     attribute :format, :default => "VDI"
+  #     attribute :size
+  #
+  class HardDrive < Image
+    attribute :format, :default => "VDI"
+    attribute :size
+    
+    class <<self
+      # Returns an array of all available hard drives as HardDrive
+      # objects.
+      #
+      # @return [Array<HardDrive>]
+      def all
+        raw = Command.vboxmanage("list hdds")
+        parse_blocks(raw).collect { |v| find(v[:uuid]) }
+      end
+      
+      # Finds one specific hard drive by UUID or file name. If the
+      # hard drive can not be found, will return `nil`.
+      #
+      # @return [HardDrive]
+      def find(id)
+        raw = Command.vboxmanage("showhdinfo #{id}")
+        
+        # Return nil if the hard drive doesn't exist
+        return nil if raw =~ /VERR_FILE_NOT_FOUND/
+        
+        data = raw.split(/\n\n/).collect { |v| parse_block(v) }.find { |v| !v.nil? }
+        
+        # Set equivalent fields
+        data[:format] = data[:"storage format"]
+        data[:size] = data[:"logical size"].split(/\s+/)[0] if data.has_key?(:"logical size")
+        
+        # Return new object
+        new(data)
+      end
+    end
+    
+    # Clone hard drive, possibly also converting formats. All formats
+    # supported by your local VirtualBox installation are supported 
+    # here. If no format is specified, the format of the source drive
+    # will be used.
+    #
+    # @param [String] outputfile The output file. This should be just a
+    #   single filename, since VirtualBox will place it in the hard
+    #   drives folder.
+    # @param [String] format The format to convert to.
+    # @return [HardDrive] The new, cloned hard drive.
+    def clone(outputfile, format="VDI")
+      raw = Command.vboxmanage("clonehd #{uuid} #{Command.shell_escape(outputfile)} --format #{format} --remember")
+      return nil unless raw =~ /UUID: (.+?)$/
+      
+      self.class.find($1.to_s)
+    end
+    
+    # Creates a new hard drive. 
+    #
+    # **This method should NEVER be called. Call {#save} instead.**
+    def create
+      raw = Command.vboxmanage("createhd --filename #{location} --size #{size} --format #{read_attribute(:format)} --remember")
+      return nil unless raw =~ /UUID: (.+?)$/
+      
+      # Just replace our attributes with the newly created ones. This also
+      # will set new_record to false.
+      populate_attributes(self.class.find($1.to_s).attributes)
+    end
+    
+    # Saves the hard drive object. If the hard drive is new,
+    # this will create a new hard drive. Otherwise, it will
+    # save any other details about the existing hard drive.
+    # 
+    # Currently, **saving existing hard drives does nothing**.
+    # This is a limitation of VirtualBox, rather than the library itself.
+    def save
+      if new_record?
+        # Create a new hard drive
+        create
+      else
+        super
+      end
+    end
+    
+    # Destroys the hard drive. This deletes the hard drive off
+    # of disk. 
+    # 
+    # **This operation is not reversable.**
+    #
+    # @return [Boolean]
+    def destroy
+      Command.vboxmanage("closemedium disk #{uuid} --delete")
+      return $?.to_i == 0
+    end
+  end
+end

data/lib/virtualbox/image.rb

@@ -0,0 +1,94 @@
+require 'virtualbox/ext/subclass_listing'
+
+module VirtualBox
+  # An abstract class which encapsulates the shared behaviour of
+  # images such as {HardDrive} and {DVD}.
+  #
+  # ## Attributes
+  #
+  # All images expose the following attributes. If you don't know how to read
+  # this than read {Attributable}.
+  #
+  #     attribute :uuid, :readonly => true
+  #     attribute :location
+  #     attribute :accessible, :readonly => true
+  #
+  # @abstract
+  class Image < AbstractModel
+    include SubclassListing
+    
+    attribute :uuid, :readonly => true
+    attribute :location
+    attribute :accessible, :readonly => true
+    
+    class <<self
+      # Parses the raw output of virtualbox into image objects. Used by
+      # subclasses to parse the output of their respective listing functions.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Image>]
+      def parse_raw(raw)
+        parse_blocks(raw).collect { |v| new(v) }
+      end
+      
+      # Parses the blocks of the output from virtualbox. VirtualBox outputs
+      # image listing in "blocks" which are then parsed down to their attributes.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Hash>]
+      def parse_blocks(raw)
+        raw.split(/\n\n/).collect { |v| parse_block(v.chomp) }.compact
+      end
+      
+      # Parses a single block from VirtualBox output. 
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Hash]
+      def parse_block(block)
+        return nil unless block =~ /^UUID:/i
+        hd = {}
+
+        # Parses each line which should be in the format:
+        # KEY: VALUE
+        block.lines.each do |line|
+          next unless line =~ /^(.+?):\s+(.+?)$/
+          hd[$1.downcase.to_sym] = $2.to_s
+        end
+        
+        # If we don't have a location but have a path, use that, as they
+        # are equivalent but not consistent.
+        hd[:location] = hd[:path] if hd.has_key?(:path)
+        
+        hd
+      end
+      
+      # Searches the subclasses which implement all method, searching for
+      # a matching UUID and returning that as the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Image>]
+      def populate_relationship(caller, data)
+        return nil if data[:uuid].nil?
+        
+        subclasses.each do |subclass|
+          next unless subclass.respond_to?(:all)
+          
+          matching = subclass.all.find { |obj| obj.uuid == data[:uuid] }
+          return matching unless matching.nil?
+        end
+      end
+    end
+    
+    # **This should never be called directly on {Image}.** Instead, initialize
+    # one of the subclasses.
+    def initialize(info=nil)
+      super()
+      
+      populate_attributes(info) if info
+    end
+  end
+end

data/lib/virtualbox/nic.rb

@@ -0,0 +1,150 @@
+module VirtualBox
+  # Represents a single NIC (Network Interface Card) of a virtual machine.
+  #
+  # **Currently, new NICs can't be created, so the only way to get this
+  # object is through a {VM}'s `nics` relationship.**
+  #
+  # # Editing a NIC
+  #
+  # Nics can be modified directly in their relationship to other
+  # virtual machines. When {VM#save} is called, it will also save any
+  # changes to its relationships.
+  #
+  #     vm = VirtualBox::VM.find("foo")
+  #     vm.nics[0].macaddress = @new_mac_address
+  #     vm.save
+  #
+  # # Attributes
+  #
+  # 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. If you aren't sure what this means or you can't understand
+  # why the below is listed, please read {Attributable}.
+  #
+  #     attribute :parent, :readonly => :readonly
+  #     attribute :nic
+  #     attribute :nictype
+  #     attribute :macaddress
+  #     attribute :cableconnected
+  #     attribute :bridgeadapter
+  #
+  class Nic < AbstractModel
+    attribute :parent, :readonly => :readonly
+    attribute :nic
+    attribute :nictype
+    attribute :macaddress
+    attribute :cableconnected
+    attribute :bridgeadapter
+    
+    class <<self
+      # Retrives the Nic data from human-readable vminfo. Since some data about
+      # nics is not exposed in the machine-readable virtual machine info, some
+      # extra parsing must be done to get these attributes. This method parses
+      # the nic-specific data from this human readable information.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Hash]
+      def nic_data(vmname)
+        raw = VM.human_info(vmname)
+        
+        # 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|
+          acc.merge({ obj[0] => obj[1] })
+        end
+      end
+      
+      # Parses nic data out of a single line of the human readable output
+      # of vm info. 
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array] First element is nic name, second is data.
+      def parse_nic(raw)
+        return unless raw =~ /^NIC\s(\d):\s+(.+?)$/
+        return if $2.to_s.strip == "disabled"
+        
+        data = {}
+        nicname = "nic#{$1}"
+        $2.to_s.split(/,\s+/).each do |raw_property|
+          next unless raw_property =~ /^(.+?):\s+(.+?)$/
+          
+          data[$1.downcase.to_sym] = $2.to_s
+        end
+        
+        return nicname.to_sym, data
+      end
+      
+      # Populates the nic relationship for anything which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Nic>]
+      def populate_relationship(caller, data)
+        nic_data = nic_data(caller.name)
+        
+        relation = []
+        
+        counter = 1
+        loop do
+          break unless data["nic#{counter}".to_sym]
+          
+          nictype = nic_data["nic#{counter}".to_sym][:type] rescue nil
+          
+          nic = new(counter, caller, data.merge({
+            "nictype#{counter}".to_sym => nictype
+          }))
+          relation.push(nic)
+          counter += 1
+        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)
+        # Just call save on each nic with the VM
+        data.each do |nic|
+          nic.save(caller.name)
+        end
+      end
+    end
+    
+    # Since there is currently no way to create a _new_ nic, this is 
+    # only used internally. Developers should NOT try to initialize their
+    # own nic objects.
+    def initialize(index, caller, data)
+      super()
+      
+      @index = index
+      
+      # Setup the index specific attributes
+      populate_data = {}
+      self.class.attributes.each do |name, options|
+        value = data["#{name}#{index}".to_sym]
+        populate_data[name] = value
+      end
+      
+      populate_attributes(populate_data.merge({
+        :parent => caller
+      }))
+    end
+    
+    # Saves a single attribute of the nic. This method is automatically
+    # called on {#save}.
+    #
+    # **This method typically won't be used except internally.**
+    def save_attribute(key, value, vmname)
+      Command.vboxmanage("modifyvm #{vmname} --#{key}#{@index} #{Command.shell_escape(value)}")
+      super
+    end
+  end
+end