virtualbox 0.1.1 → 0.2.0

data/.gitignore

@@ -2,4 +2,5 @@ bin/*
 vendor/gems/*
 doc/*
 .yardoc/*
-pkg/*
+pkg/*
+test/coverage/*

data/.yardopts

@@ -0,0 +1,3 @@
+-
+docs/GettingStarted.md
+TODO

data/Rakefile

@@ -26,8 +26,22 @@ end
 begin
   require 'yard'
   YARD::Rake::YardocTask.new do |t|
-    t.options = ['--main', 'Readme.md', '--markup', 'markdown', '--files', 'TODO']
+    t.options = ['--main', 'Readme.md', '--markup', 'markdown']
+    t.options += ['--title', 'VirtualBox Ruby Library Documentation']
   end
 rescue LoadError
   puts "Yard not available. Install it with: gem install yard"
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.libs << "test"
+    t.test_files = FileList["test/**/*_test.rb"]
+    t.output_dir = "test/coverage"
+    t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available. Coverage data tasks not available."
+  puts "Install it with: gem install rcov"
 end

data/Readme.md

@@ -21,6 +21,9 @@ the gem, you must set the path to your `VBoxManage` binary:
 The virtualbox gem is modeled after ActiveRecord. If you've used ActiveRecord, you'll
 feel very comfortable using the virtualbox gem. 
 
+There is a [quick getting started guide](http://mitchellh.github.com/virtualbox/file.GettingStarted.html) to 
+get you acquainted with the conventions of the virtualbox gem.
+
 Complete documentation can be found at [http://mitchellh.github.com/virtualbox](http://mitchellh.github.com/virtualbox).
 
 Below are some examples:

data/TODO

@@ -4,9 +4,6 @@ Not all these features will make it into initial releases of virtualbox ruby gem
 But they will definitely all make it for version 1.0.
 
 * Creating a VM from scratch (non-import)
-* Pause/Resume VMs
-* Exporting a VM
-* Modifying attached devices
 * Parsing bridged IFs
 * Shared folders
 * Snapshots

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/docs/GettingStarted.md

@@ -0,0 +1,196 @@
+# Getting Started with the VirtualBox Gem
+
+* [Basic Conventions](#basic-conventions)
+    * [Finding Models](#bc-finding-models)
+    * [Accessing Models](#bc-accessing-models)
+    * [Modifying Models](#bc-modifying-models)
+    * [Saving Models](#bc-saving-models)
+
+<a name="basic-conventions"></a>
+# Basic Conventions
+
+The entire virtualbox library follows a few conventions to make sure
+things work uniformly across the entire codebase, and so that nothing
+should surprise any developers once they understand these conventions.
+
+When browsing the documentation, you'll probably notice that a lot of the
+classes inherit from {VirtualBox::AbstractModel}. This just means that all
+these classes act the same way! Every {VirtualBox::AbstractModel AbstractModel}
+shares the following behaviors:
+
+* Finding
+* Accessing
+* Modifying
+* Saving
+
+These behaviors should be similar if not the exact same across all
+virtualbox models. Each of these behaviors is covered below.
+
+<a name="bc-finding-models"></a>
+## Finding Models
+
+All data models have a `find` or `all` method (or sometimes both!) These
+methods do what you expect them to: `all` will return an array of all instances
+of that model which is typically unordered. `find` will allow you to find a
+specific instance of that model, typically by name or UUID. Below are a couple
+examples of this.
+
+### All
+
+This example uses {VirtualBox::HardDrive}. As you can see, its just an
+unmodified ruby `Array` which is returned by `all`. This can be used find,
+sort, enumerate, etc.
+
+    drives = VirtualBox::HardDrive.all
+    puts "You have #{drives.length} hard drives!"
+    
+    drives.each do |drive|
+      puts "Drive: #{drive.uuid}"
+    end
+
+In the case that `all` returns an empty array, this simply means that none
+of that model exist.
+
+### Find
+
+This example uses {VirtualBox::VM}, which will probably be the most common
+model you search for. 
+
+    vm = VirtualBox::VM.find("MyVM")
+    puts "This VM has #{vm.memory} MB of RAM allocated to it."
+
+Find can also be used with UUIDs:
+
+    vm = VirtualBox::VM.find("3d0f87b4-50f7-4fc5-ad89-93375b1b32a3")
+    puts "This VM's name is: #{vm.name}"
+
+When a find fails, it will return `nil`.
+
+<a name="bc-accessing-models"></a>
+## Accessing Models
+
+Every model has an _attribute list_ associated with it. These attributes are
+what can be accessed on the model via the typical ruby attribute accessing
+syntax with the `.` (dot) operator. Because these methods are generated
+dynamically, they don't show up as methods in the documentation. Because of this,
+attributes are listed for every model in their overviews. For examples, see the
+overviews of {VirtualBox::VM}, {VirtualBox::HardDrive}, etc.
+
+In addition to an attribute list, many models also have _relationships_. 
+Relationships are, for our purposes, similar enough to attributes that they
+can be treated the same. Relationship accessing methods are also dynamically
+generated, so they are listed within the overviews of the models as well (if they
+have any). Relationships allow two models to show that they are connected in some
+way, and can therefore be accessed through each other.
+
+### Attributes
+
+Reading attributes is simple. Let's use a {VirtualBox::VM} as an example:
+
+    vm = VirtualBox::VM.find("FooVM")
+    
+    # Accessing attributes:
+    vm.memory
+    vm.name
+    vm.boot1
+    vm.ioapic
+
+### Relationships
+
+Relationships are read the exact same way as attributes. Again using a
+{VirtualBox::VM} as an example:
+
+    vm = VirtualBox::VM.find("FooVM")
+    
+    # storage_controllers is a relationship containing an array of all the
+    # storage controllers on this VM
+    vm.storage_controllers.each do |sc|
+      puts "Storage Controller: #{sc.uuid}"
+    end
+
+The difference from an attribute is that while attributes are typically ruby
+primitives such as `String` or `Boolean`, relationship objects are always other
+virtualbox models such as {VirtualBox::StorageController}.
+
+<a name="bc-modifying-models"></a>
+## Modifying Models
+
+In addition to simply reading attributes and relationships, most can be modified
+as well. I say "most" because some attributes are `readonly` and some relationships
+simply don't support being directly modified (though their objects may, I'll get to
+this in a moment). By looking at the attribute list it is easy to spot a readonly 
+attribute, which will have the `:readonly` option set to `true`. Below is an example
+of what you might see in the overview of some model:
+
+    attribute :uuid, :readonly => true
+
+In the above case, you could read the `uuid` attribute as normal, but it wouldn't support
+modification (and you'll simply get a `NoMethodError` if you try to set it).
+
+Relationships are a little bit trickier, since when discussing modifying a relationship,
+it could either be taken to mean the items _in_ the relationship, or the relationship
+itself. A good rule of thumb, assuming there exists a relationship `foos`,is if you ever
+want to do `object.foos =` something, then you're _modifying the relationship_ and _not_
+the objects. But if you ever do `object.foos[0].destroy`, then you're _modifying the
+relationship objects_ and _not_ the relationship itself.
+
+### Attributes
+
+Attributes which support modification are modified like standard ruby attributes. The
+following example uses {VirtualBox::HardDrive}:
+
+    hd = VirtualBox::HardDrive.new
+    hd.size = 2000 # megabytes
+    hd.format = "VMDK"
+
+As you can see, there is nothing sneaky going on here, and does what you expect.
+
+### Relationships
+
+Modifying relationships, on the other hand, is a little different. If the model supports
+modifying the relationship (which it'll note in its respective documentation), then
+you can set it just like an attribute. Below, we use {VirtualBox::AttachedDevice} as
+an example:
+
+    ad = VirtualBox::AttachedDevice.new
+    
+    # Attached devices have an image relationship
+    ad.image = VirtualBox::DVD.empty_drive
+
+If a relationship doesn't support setting it, it will raise a {VirtualBox::Exceptions::NonSettableRelationshipException}.
+
+**Note**: Below is an example of modifying a relationship object, rather than a
+relationship itself. The example below uses {VirtualBox::VM}.
+
+    vm = VirtualBox::VM.find("FooVM")
+    vm.storage_controllers[0].name = "Foo Controller"
+
+<a name="bc-saving-models"></a>
+## Saving Models
+
+Saving models is _really_ easy: you simply call `save`. That's all! Well, there are
+some subtleties, but that's the basic idea. `save` will typically **also save relationships**
+so if you modify a relationship object or relationship itself, calling `save` on the 
+parent object will typically save the relationships as well. `save` always returns
+`true` or `false` depending on whether the operation was a success or not. If you'd like
+instead to know why a `save` failed, you can call the method with a `true` parameter
+which sets `raise_errors` to `true` and will raise a {VirtualBox::Exceptions::CommandFailedException}
+if there is a failure. The message on this object contains the reason.
+
+Below is an example of saving a simple {VirtualBox::VM} object:
+
+    vm = VirtualBox::VM.find("FooVM")
+    
+    # Double the memory
+    vm.memory = vm.memory.to_i * 2
+    
+    # This will return true/false depending on success
+    vm.save
+
+Below is an example where an exception will be raised if an error occurs:
+
+    vm = VirtualBox::VM.find("FooVM")
+    vm.memory = "INVALID"
+    
+    # This will raise an exception, since the memory is invalid
+    vm.save(true)

data/lib/virtualbox/abstract_model/attributable.rb

@@ -92,7 +92,21 @@ module VirtualBox
         # @option options [Symbol] :populate_key (attribute name) Specifies
         #   a custom populate key to use for {Attributable#populate_attributes}
         def attribute(name, options = {})
-          attributes[name.to_sym] = options
+          name = name.to_sym
+          attributes[name] = options
+          
+          # Create the method for reading this attribute
+          define_method(name) { read_attribute(name) }
+          
+          # Create the writer method for it unless the attribute is readonly,
+          # then remove the method if it exists
+          if !options[:readonly]
+            define_method("#{name}=") do |value|
+              write_attribute(name, value)
+            end
+          elsif method_defined?("#{name}=")
+            undef_method("#{name}=")
+          end
         end
 
         # Returns the hash of attributes and their associated options.
@@ -173,21 +187,6 @@ module VirtualBox
         name = name.to_sym
         has_attribute?(name) && self.class.attributes[name][:readonly]
       end
-      
-      # Method missing is used to add dynamic handlers for accessors and
-      # setters. Due to the general ugliness of `method_missing`, this may
-      # change in the near future, but for now it is what it is.
-      def method_missing(meth, *args)
-        meth_string = meth.to_s
-
-        if has_attribute?(meth)
-          read_attribute(meth)
-        elsif meth_string =~ /^(.+?)=$/ && has_attribute?($1) && !readonly_attribute?($1)
-          write_attribute($1.to_sym, *args)
-        else
-          super
-        end
-      end
     end
   end
 end

data/lib/virtualbox/abstract_model/dirty.rb

@@ -74,6 +74,13 @@ module VirtualBox
     #     obj.clear_dirty!(:name)
     #     obj.name_changed? # => false
     #
+    # If no specific field is speciied, `clear_dirty!` will clear the dirty
+    # status on the entire model.
+    #
+    #     obj.changed? # => assume true
+    #     obj.clear_dirty!
+    #     obj.changed? # => false
+    #
     module Dirty
       # Manages dirty state for an attribute. This method will handle
       # setting the dirty state of an attribute (or even clearing it
@@ -104,8 +111,12 @@ module VirtualBox
       # Clears dirty state for a field.
       #
       # @param [Symbol] key The field to clear dirty state.
-      def clear_dirty!(key)
-        changes.delete(key)
+      def clear_dirty!(key=nil)
+        if key.nil?
+          @changed_attributes = {}
+        else
+          changes.delete(key)
+        end
       end
 
       # Ignores any dirty changes during the duration of the block. 

data/lib/virtualbox/abstract_model/relatable.rb

@@ -39,6 +39,37 @@ module VirtualBox
     #     # Accessing through an instance "instance"
     #     instance.bacons # => whatever Bacon.populate_relationship created
     #
+    # # Settable Relationships
+    #
+    # It is often convenient that relationships become "settable." That is,
+    # for a relationship `foos`, there would exist a `foos=` method. This is
+    # possible by implementing the `set_relationship` method on the relationship
+    # class. Consider the following relationship:
+    #
+    #     relationship :foos, Foo
+    #
+    # If `Foo` has the `set_relationship` method, then it will be called by
+    # `foos=`. It is expected to return the new value for the relationship. To
+    # facilitate this need, the `set_relationship` method is given three 
+    # parameters: caller, old value, and new value. An example implementation,
+    # albeit a silly one, is below:
+    #
+    #     class Foo
+    #       def self.set_relationship(caller, old_value, new_value)
+    #         return "Changed to: #{new_value}"
+    #       end
+    #     end
+    #
+    # In this case, the following behavior would occur:
+    #
+    #     instance.foos # => assume "foo"
+    #     instance.foos = "bar"
+    #     instance.foos # => "Changed to: bar"
+    #
+    # If the relationship class _does not implement_ the `set_relationship` 
+    # method, then a {Exceptions::NonSettableRelationshipException} will be raised if
+    # a user attempts to set that relationship.
+    #
     # # Dependent Relationships
     #
     # By setting `:dependent => :destroy` on relationships, {AbstractModel}
@@ -63,8 +94,16 @@ module VirtualBox
         # @option options [Symbol] :dependent (nil) - If set to `:destroy`
         #   {AbstractModel#destroy} will propagate through to relationships.
         def relationship(name, klass, options = {})
+          name = name.to_sym
+          
           @relationships ||= {}
           @relationships[name] = { :klass => klass }.merge(options)
+          
+          # Define the method to read the relationship
+          define_method(name) { relationship_data[name] }
+          
+          # Define the method to set the relationship
+          define_method("#{name}=") { |*args| set_relationship(name, *args) }
         end
         
         # Returns a hash of all the relationships.
@@ -147,16 +186,26 @@ module VirtualBox
         self.class.relationships.has_key?(key.to_sym)
       end
       
-      # Method missing is used to add dynamic handlers for relationship
-      # accessors.
-      def method_missing(meth, *args)
-        meth_string = meth.to_s
-
-        if has_relationship?(meth)
-          relationship_data[meth.to_sym]
-        else
-          super
-        end
+      # Sets a relationship to the given value. This is not guaranteed to
+      # do anything, since "set_relationship" will be called on the class
+      # that the relationship is associated with and its expected to return
+      # the resulting relationship to set. 
+      #
+      # If the relationship class doesn't respond to the set_relationship
+      # method, then an exception {Exceptions::NonSettableRelationshipException} will
+      # be raised.
+      #
+      # This method is called by the "magic" method of `relationship=`.
+      #
+      # @param [Symbol] key Relationship key.
+      # @param [Object] value The new value of the relationship.
+      def set_relationship(key, value)
+        key = key.to_sym
+        relationship = self.class.relationships[key]
+        return unless relationship
+        
+        raise Exceptions::NonSettableRelationshipException.new unless relationship[:klass].respond_to?(:set_relationship)
+        relationship_data[key] = relationship[:klass].set_relationship(self, relationship_data[key], value)
       end
     end
   end

data/lib/virtualbox/abstract_model.rb

@@ -18,10 +18,24 @@ module VirtualBox
     # is {HardDrive#save} which will create a new hard drive if it didn't
     # previously exist, or save an old one if it did exist.
     def new_record?
-      @new_record = true if @new_record.nil?
+      new_record! if @new_record.nil?
       @new_record
     end
     
+    # Explicitly resets the model to a new record. If you're using this
+    # method outside of virtualbox library core, you should really be
+    # asking yourself "why?"
+    def new_record!
+      @new_record = true
+    end
+    
+    # Explicitly sets the model to not be a new record. If you're using
+    # this method outside of virtualbox library core, you should really
+    # be asking yourself "why?"
+    def existing_record!
+      @new_record = false
+    end
+    
     # Saves the model attributes and relationships.
     #
     # The method can be passed any arbitrary arguments, which are 
@@ -81,6 +95,14 @@ module VirtualBox
       super
     end
     
+    # Overwrites {Relatable#set_relationship} to set the dirty state of the
+    # relationship. See {Dirty#set_dirty!} as well.
+    def set_relationship(key, value)
+      existing = relationship_data[key]
+      new_value = super
+      set_dirty!(key, existing, new_value)
+    end
+    
     # Destroys the model. The exact behaviour of this method is expected to be
     # defined on the subclasses. This method on AbstractModel simply
     # propagates the destroy to the dependent relationships. For more information

data/lib/virtualbox/attached_device.rb

@@ -2,9 +2,39 @@ module VirtualBox
   # Represents an device which is attached to a storage controller. An example
   # of such a device would be a CD or hard drive attached to an IDE controller.
   #
-  # **Currently, attached devices can not be created from scratch. The only way
-  # to access them is through relationships with other models such as
-  # {StorageController}.**
+  # # Creating a New Attached Device
+  #
+  # Creating a new attached device is simple. The following is a simple example
+  # of creating a DVD with an empty drive:
+  #
+  #     ad = VirtualBox::AttachedDevice.new
+  #     ad.port = 0
+  #     ad.image = VirtualBox::DVD.empty_drive
+  #     storage_controller.devices << ad
+  #     ad.save
+  #
+  # The only quirk is that the attached device **must** be attached to a 
+  # storage controller. The above assumes that `storage_controller` exists,
+  # which adds the device.
+  #
+  # Any {Image} subclass can be set to the `image` relationship.
+  #
+  # The following is an example using {VM.find}:
+  #
+  #     # First creating the new device...
+  #     ad = VirtualBox::AttachedDevice.new
+  #     ad.port = 0
+  #     ad.image = VirtualBox::DVD.empty_drive
+  #     
+  #     # Now attaching to existing VM
+  #     vm = VirtualBox::VM.find("FooVM")
+  #     vm.storage_controllers[0].devices << ad
+  #     vm.save
+  #
+  # The interesting thing in this example is that the `save` method is called on
+  # the virtual machine rather than the AttachedDevice. This will actually work
+  # as expected! Saving a virtual machine automatically saves all it's relationships
+  # as well.
   #
   # # Attributes and Relationships
   #
@@ -40,8 +70,7 @@ module VirtualBox
   #
   class AttachedDevice < AbstractModel
     attribute :parent, :readonly => true
-    attribute :uuid
-    attribute :medium
+    attribute :uuid, :readonly => true
     attribute :port
     relationship :image, Image
     
@@ -52,7 +81,7 @@ module VirtualBox
       #
       # @return [Array<AttachedDevice>]
       def populate_relationship(caller, data)
-        relation = []
+        relation = Proxies::Collection.new(caller)
         
         counter = 0
         loop do
@@ -71,20 +100,87 @@ module VirtualBox
       def destroy_relationship(caller, data, *args)
         data.each { |v| v.destroy(*args) }
       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 |ad|
+          ad.save
+        end
+      end
     end
     
-    # Since attached devices can not be created from scratch yet, this
-    # method should never be called. Instead access attached devices
-    # through relationships from other models such as {StorageController}.
-    def initialize(index, caller, data)
+    # @overload initialize(data={})
+    #   Creates a new AttachedDevice which is a new record. This
+    #   should be attached to a storage controller and saved.
+    #   @param [Hash] data (optional) A hash which contains initial attribute
+    #     values for the AttachedDevice.
+    # @overload initialize(index, caller, data)
+    #   Creates an AttachedDevice for a relationship. **This should
+    #   never be called except internally.**
+    #   @param [Integer] index Index of the port
+    #   @param [Object] caller The parent
+    #   @param [Hash] data A hash of data which must be used
+    #     to extract the relationship data.
+    def initialize(*args)
       super()
       
-      populate_attributes({
-        :parent => caller,
-        :port => index,
-        :medium => data["#{caller.name}-#{index}-0".downcase.to_sym],
-        :uuid => data["#{caller.name}-ImageUUID-#{index}-0".downcase.to_sym]
-      })
+      if args.length == 3
+        populate_from_data(*args)
+      elsif args.length == 1
+        populate_attributes(*args)
+        new_record!
+      elsif args.empty?
+        return
+      else
+        raise NoMethodError.new
+      end
+    end
+    
+    # Saves or creates an attached device.
+    #
+    # @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)
+      raise Exceptions::NoParentException.new if parent.nil?
+      raise Exceptions::InvalidObjectException.new("Image must be set") if image.nil?
+      return true unless changed?
+      
+      # If the port changed, we have to destroy the old one, then create
+      # a new one
+      destroy({:port => port_was}, raise_errors) if port_changed? && !port_was.nil?
+
+      Command.vboxmanage("storageattach #{Command.shell_escape(parent.parent.name)} --storagectl #{Command.shell_escape(parent.name)} --port #{port} --device 0 --type #{image.image_type} --medium #{medium}")
+      existing_record!
+      clear_dirty!
+      
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
+    end
+    
+    # Medium of the attached image. This attribute will be dependent
+    # on the attached image and will return one of the following values:
+    #
+    # * **none** - There is no attached image
+    # * **emptydrive** - An image with an empty drive is attached (see
+    #     {DVD.empty_drive})
+    # * **image uuid** - The image's UUID
+    #
+    # @return [String]
+    def medium
+      if image.nil?
+        "none"
+      elsif image.empty_drive?
+        "emptydrive"
+      else
+        image.uuid
+      end
     end
     
     # Destroys the attached device. By default, this only removes any
@@ -94,11 +190,40 @@ module VirtualBox
     #
     # @option options [Boolean] :destroy_image (false) If true, will also
     #   destroy the image associated with device.
-    def destroy(options={})
+    # @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(options={}, raise_errors=false)
       # parent = storagecontroller
       # parent.parent = vm
-      Command.vboxmanage("storageattach #{Command.shell_escape(parent.parent.name)} --storagectl #{Command.shell_escape(parent.name)} --port #{port} --device 0 --medium none")      
-      image.destroy if options[:destroy_image] && image
+      destroy_port = options[:port] || port
+      Command.vboxmanage("storageattach #{Command.shell_escape(parent.parent.name)} --storagectl #{Command.shell_escape(parent.name)} --port #{destroy_port} --device 0 --medium none")      
+      image.destroy(raise_errors) if options[:destroy_image] && image
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
+    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
+    
+    protected
+    
+    # Populates the model based on data from a parsed vminfo. This
+    # method is used to create a model which already exists and is
+    # part of a relationship.
+    #
+    # **This method should never be called except internally.**
+    def populate_from_data(index, caller, data)
+      populate_attributes({
+        :parent => caller,
+        :port => index,
+        :medium => data["#{caller.name}-#{index}-0".downcase.to_sym],
+        :uuid => data["#{caller.name}-ImageUUID-#{index}-0".downcase.to_sym]
+      })
     end
   end
 end