virtualbox 0.4.1 → 0.4.2

data/Readme.md

@@ -1,6 +1,6 @@
 # VirtualBox Ruby Gem
 
-The VirtualBox ruby gem is a library which allows anyone to control VirtualBox 
+The VirtualBox ruby gem is a library which allows anyone to control VirtualBox
 from ruby code! Create, destroy, start, stop, suspend, and resume virtual machines.
 Also list virtual machines, list hard drives, network devices, etc.
 
@@ -19,9 +19,9 @@ the gem, you must set the path to your `VBoxManage` binary:
 ## Basic Usage
 
 The virtualbox gem is modeled after ActiveRecord. If you've used ActiveRecord, you'll
-feel very comfortable using the virtualbox gem. 
+feel very comfortable using the virtualbox gem.
 
-There is a [quick getting started guide](http://mitchellh.github.com/virtualbox/file.GettingStarted.html) to 
+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).
@@ -29,29 +29,29 @@ Complete documentation can be found at [http://mitchellh.github.com/virtualbox](
 Below are some examples:
 
     require 'virtualbox'
-    
+
     vm = VirtualBox::VM.find("my-vm")
-    
+
     # Let's first print out some basic info about the VM
     puts "Memory: #{vm.memory}"
-    
+
     vm.storage_controllers.each do |sc|
       sc.attached_devices.each do |device|
         puts "Attached Device: #{device.uuid}"
       end
     end
-    
+
     # Let's modify the memory and name...
     vm.memory = 360
     vm.name = "my-renamed-vm"
-    
+
     # Save it!
     vm.save
 
 Or here is an example of creating a hard drive:
 
     require 'virtualbox'
-    
+
     hd = VirtualBox::HardDrive.new
     hd.location = "foo.vdi"
     hd.size = 2000 # megabytes

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.2

data/docs/GettingStarted.md

@@ -43,7 +43,7 @@ sort, enumerate, etc.
 
     drives = VirtualBox::HardDrive.all
     puts "You have #{drives.length} hard drives!"
-    
+
     drives.each do |drive|
       puts "Drive: #{drive.uuid}"
     end
@@ -54,7 +54,7 @@ of that model exist.
 ### Find
 
 This example uses {VirtualBox::VM}, which will probably be the most common
-model you search for. 
+model you search for.
 
     vm = VirtualBox::VM.find("MyVM")
     puts "This VM has #{vm.memory} MB of RAM allocated to it."
@@ -76,7 +76,7 @@ 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_. 
+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
@@ -88,7 +88,7 @@ way, and can therefore be accessed through each other.
 Reading attributes is simple. Let's use a {VirtualBox::VM} as an example:
 
     vm = VirtualBox::VM.find("FooVM")
-    
+
     # Accessing attributes:
     vm.memory
     vm.name
@@ -101,7 +101,7 @@ 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|
@@ -118,7 +118,7 @@ virtualbox models such as {VirtualBox::StorageController}.
 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 
+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:
 
@@ -153,7 +153,7 @@ you can set it just like an attribute. Below, we use {VirtualBox::AttachedDevice
 an example:
 
     ad = VirtualBox::AttachedDevice.new
-    
+
     # Attached devices have an image relationship
     ad.image = VirtualBox::DVD.empty_drive
 
@@ -170,7 +170,7 @@ relationship itself. The example below uses {VirtualBox::VM}.
 
 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 
+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
@@ -180,10 +180,10 @@ 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
 
@@ -191,6 +191,6 @@ 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/docs/WhatsNew.md

@@ -31,4 +31,4 @@ Read more about port forwarding {VirtualBox::ForwardedPort here}.
 ## More Ruby Versions Supported!
 
 Previously, virtualbox only supported 1.8.7. It now supports 1.8.6 and 1.9.x thanks
-to AleksiP.
+to AlekSi.

data/lib/virtualbox.rb

@@ -12,4 +12,13 @@ require 'virtualbox/hard_drive'
 require 'virtualbox/nic'
 require 'virtualbox/shared_folder'
 require 'virtualbox/storage_controller'
-require 'virtualbox/vm'
+require 'virtualbox/vm'
+
+module VirtualBox
+  class <<self
+    # Returns installed VirtualBox version like '3.1.2r56127'.
+    def version
+      Command.vboxmanage("-v").chomp.strip
+    end
+  end
+end

data/lib/virtualbox/abstract_model.rb

@@ -13,7 +13,7 @@ module VirtualBox
     include Dirty
     include Relatable
     include Validatable
-    
+
     # Returns a boolean denoting if the record is new or existing. This
     # method is provided for subclasses to use to differentiate between
     # creating a new object or saving an existing one. An example of this
@@ -23,53 +23,53 @@ module VirtualBox
       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
-    
+
     # Returns the errors for a model.
     def errors
       error_hash = super
-      
+
       self.class.relationships.each do |name, options|
         next unless options && options[:klass].respond_to?(:errors_for_relationship)
         relationship_errors = options[:klass].errors_for_relationship(self, relationship_data[name])
-        
+
         error_hash.merge!({ :foos => relationship_errors }) if relationship_errors.length > 0
       end
-      
+
       error_hash
     end
-    
+
     # Validates the model and relationships.
     def validate(*args)
       # First clear all previous errors
       clear_errors
-      
+
       # Then do the validations
       failed = false
       self.class.relationships.each do |name, options|
         next unless options && options[:klass].respond_to?(:validate_relationship)
         failed = true if !options[:klass].validate_relationship(self, relationship_data[name], *args)
       end
-      
+
       return !failed
     end
-    
+
     # Saves the model attributes and relationships.
     #
-    # The method can be passed any arbitrary arguments, which are 
+    # The method can be passed any arbitrary arguments, which are
     # implementation specific (see {VM#save}, which does this).
     def save(*args)
       # Go through changed attributes and call save_attribute for
@@ -79,31 +79,31 @@ module VirtualBox
       end
 
       save_relationships(*args)
-      
+
       # No longer a new record
       @new_record = false
     end
-    
+
     # Saves a single attribute of the model. This method on the abstract
     # model does nothing on its own, and is expected to be overridden
-    # by any subclasses. 
+    # by any subclasses.
     #
     # This method clears the dirty status of the attribute.
     def save_attribute(key, value, *args)
       clear_dirty!(key)
     end
-    
+
     # Sets the initial attributes from a hash. This method is meant to be used
     # once to initially setup the attributes. It is **not a mass-assignment**
     # method for updating attributes.
     #
-    # This method does **not** affect dirtiness, but also does not clear it. 
-    # This means that if you call populate_attributes, the same attributes 
-    # that were dirty before the call will be dirty after the call (but no 
-    # more and no less). This distinction is important because most subclasses 
-    # of AbstractModel only save changed attributes, and ignore unchanged 
-    # attributes. Attempting to change attributes through this method will 
-    # cause them to not be saved, which is surely unexpected behaviour for 
+    # This method does **not** affect dirtiness, but also does not clear it.
+    # This means that if you call populate_attributes, the same attributes
+    # that were dirty before the call will be dirty after the call (but no
+    # more and no less). This distinction is important because most subclasses
+    # of AbstractModel only save changed attributes, and ignore unchanged
+    # attributes. Attempting to change attributes through this method will
+    # cause them to not be saved, which is surely unexpected behaviour for
     # most users.
     #
     # Calling this method will also cause the model to assume that it is not
@@ -111,21 +111,21 @@ module VirtualBox
     def populate_attributes(attribs)
       # No longer a new record
       @new_record = false
-      
+
       ignore_dirty do
         super
-        
+
         populate_relationships(attribs)
       end
-    end 
-    
+    end
+
     # Overwrites {Attributable#write_attribute} to set the dirty state of
     # the written attribute. See {Dirty#set_dirty!} as well.
     def write_attribute(name, value)
       set_dirty!(name, read_attribute(name), value)
       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)
@@ -133,7 +133,7 @@ module VirtualBox
       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
@@ -144,5 +144,23 @@ module VirtualBox
         destroy_relationship(name, *args) if options[:dependent] == :destroy
       end
     end
+
+    # Creates a human-readable format for this model. This method overrides the
+    # default `#<class>` syntax since this doesn't work well for AbstractModels.
+    # Instead, it abbreviates it, instead showing all the attributes and their
+    # values, and `...` for relationships.
+    def inspect
+      values = []
+
+      self.class.attributes.each do |name, options|
+        values.push("#{name.inspect}=#{read_attribute(name).inspect}")
+      end
+
+      self.class.relationships.each do |name, options|
+        values.push("#{name.inspect}=...")
+      end
+
+      "#<#{self.class} #{values.join(", ")}>".strip
+    end
   end
 end

data/lib/virtualbox/abstract_model/attributable.rb

@@ -9,7 +9,7 @@ module VirtualBox
     # Make sure to also see the {ClassMethods}.
     #
     # ## Defining a Basic Attribute
-    # 
+    #
     #     attribute :name
     #
     # The example above would put the "name" attribute on the class. This
@@ -27,7 +27,7 @@ module VirtualBox
     #
     # The example above allows age to be read, but not written to via the
     # `age=` method. The attribute is still able to written using
-    # {#write_attribute} but this is generally only for 
+    # {#write_attribute} but this is generally only for
     # inter-class use, and not for users of it.
     #
     # ## Defining Default Values
@@ -39,15 +39,15 @@ module VirtualBox
     #
     # ## Populating Multiple Attributes
     #
-    # Attributes can be mass populated using {#populate_attributes}. Below 
+    # Attributes can be mass populated using {#populate_attributes}. Below
     # is an example of the use.
     #
     #     class Person
     #       include Attributable
-    #     
+    #
     #       attribute :name
     #       attribute :age, :readonly => true
-    #       
+    #
     #       def initialize
     #         populate_attributes({
     #           :name => "Steven",
@@ -63,7 +63,7 @@ module VirtualBox
     # ## Custom Populate Keys
     #
     # Sometimes the attribute names don't match the keys of the hash that will be
-    # used to populate it. For this purpose, you can define a custom 
+    # used to populate it. For this purpose, you can define a custom
     # `populate_key`. Example:
     #
     #     attribute :path, :populate_key => :location
@@ -77,11 +77,11 @@ module VirtualBox
       def self.included(base)
         base.extend ClassMethods
       end
-      
+
       # Defines the class methods for the {Attributable} module. For
       # detailed overview documentation, see {Attributable}.
       module ClassMethods
-        # Defines an attribute on the model. 
+        # Defines an attribute on the model.
         #
         # @param [Symbol] name The name of the attribute, which will also be
         #   used to set the accessor methods.
@@ -94,10 +94,10 @@ module VirtualBox
         def attribute(name, 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]
@@ -113,13 +113,13 @@ module VirtualBox
         def attributes
           @attributes ||= {}
         end
-        
+
         # Used to propagate attributes to subclasses. This method makes sure that
         # subclasses of a class with {Attributable} included will inherit the
         # attributes as well, which would be the expected behaviour.
         def inherited(subclass)
           super rescue NoMethodError
-          
+
           attributes.each do |name, option|
             subclass.attribute(name, option)
           end
@@ -128,7 +128,7 @@ module VirtualBox
 
       # Does the initial population of the various attributes. It will
       # ignore attributes which are not defined or have no value in the
-      # hash. 
+      # hash.
       #
       # Population uses the attributes `populate_key` if present to
       # determine which value to take. Example:
@@ -152,7 +152,7 @@ module VirtualBox
 
       # Writes an attribute. This method ignores the `readonly` option
       # on attribute definitions. This method is mostly meant for
-      # internal use on setting attributes (including readonly 
+      # internal use on setting attributes (including readonly
       # attributes), whereas users of a class which includes this
       # module should use the accessor methods, such as `name=`.
       def write_attribute(name, value)
@@ -161,14 +161,14 @@ module VirtualBox
 
       # Reads an attribute. This method will return `nil` if the
       # attribute doesn't exist. If the attribute does exist but
-      # doesn't have a value set, it'll use the `default` value 
+      # doesn't have a value set, it'll use the `default` value
       # if specified.
       def read_attribute(name)
         if has_attribute?(name)
           attributes[name] || self.class.attributes[name][:default]
         end
       end
-      
+
       # Returns a hash of all attributes and their options.
       def attributes
         @attribute_values ||= {}