virtualbox 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+bin/*
+vendor/gems/*
+doc/*
+.yardoc/*

data/Gemfile

@@ -0,0 +1,11 @@
+# Gems required for testing only. To install run
+# gem bundle test
+only :test do
+  gem "contest", ">= 0.1.2"
+  gem "mocha"
+  gem "ruby-debug", ">= 0.10.3" if RUBY_VERSION < '1.9'
+end
+
+# Makes sure that our code doesn't request gems outside
+# of our dependency list.
+disable_system_gems

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "virtualbox"
+    gemspec.summary = "Create and modify virtual machines in VirtualBox using pure ruby."
+    gemspec.description = "Create and modify virtual machines in VirtualBox using pure ruby."
+    gemspec.email = "mitchell.hashimoto@gmail.com"
+    gemspec.homepage = "http://github.com/mitchellh/virtualbox"
+    gemspec.authors = ["Mitchell Hashimoto"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = 'test/**/*_test.rb'
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ['--main', 'Readme.md', '--markup', 'markdown', '--files', 'TODO']
+  end
+rescue LoadError
+  puts "Yard not available. Install it with: gem install yard"
+end

data/Readme.md

@@ -0,0 +1,75 @@
+# VirtualBox Ruby Gem
+
+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.
+
+## Installation and Requirements
+
+First you need to install [VirtualBox](http://www.virtualbox.org/) which is available for
+Windows, Linux, and OS X. After installation, install the gem:
+
+    sudo gem install virtualbox
+
+The gem assumes that `VBoxManage` will be available on the `PATH`. If not, before using
+the gem, you must set the path to your `VBoxManage` binary:
+
+    VirtualBox::Command.vboxmanage = "/path/to/my/VBoxManage"
+
+## Basic Usage
+
+The virtualbox gem is modeled after ActiveRecord. If you've used ActiveRecord, you'll
+feel very comfortable using the virtualbox gem. 
+
+Complete documentation can be found at [http://mitchellh.github.com/virtualbox](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
+    hd.save
+
+## Known Issues or Uncompleted Features
+
+VirtualBox has a _ton_ of features! As such, this gem is still not totally complete.
+You can see the features that are still left to do in the TODO file.
+
+## Reporting Bugs or Feature Requests
+
+Please use the [issue tracker](https://github.com/mitchellh/virtualbox/issues).
+
+## Contributing
+
+If you'd like to contribute to VirtualBox, the first step to developing is to
+clone this repo, get [wycat's bundler](http://github.com/wycats/bundler) if you
+don't have it already, and do the following:
+
+    gem bundle test
+    rake
+
+This will run the test suite, which should come back all green! Then you're good to go!

data/TODO

@@ -0,0 +1,13 @@
+# TODO
+
+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
+* Getting/Setting guest properties

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/virtualbox.rb

@@ -0,0 +1,11 @@
+$:.unshift(File.expand_path(File.dirname(__FILE__)))
+require 'virtualbox/errors'
+require 'virtualbox/command'
+require 'virtualbox/abstract_model'
+require 'virtualbox/image'
+require 'virtualbox/attached_device'
+require 'virtualbox/dvd'
+require 'virtualbox/hard_drive'
+require 'virtualbox/nic'
+require 'virtualbox/storage_controller'
+require 'virtualbox/vm'

data/lib/virtualbox/abstract_model.rb

@@ -0,0 +1,95 @@
+require 'virtualbox/abstract_model/attributable'
+require 'virtualbox/abstract_model/dirty'
+require 'virtualbox/abstract_model/relatable'
+
+module VirtualBox
+  # AbstractModel is the base class used for most of virtualbox's classes.
+  # It provides convenient ActiveRecord-style model behavior to subclasses.
+  #
+  # @abstract
+  class AbstractModel
+    include Attributable
+    include Dirty
+    include Relatable
+    
+    # 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
+    # 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
+    end
+    
+    # Saves the model attributes and relationships.
+    #
+    # 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
+      # those only
+      changes.each do |key, values|
+        save_attribute(key, values[1], *args)
+      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. 
+    #
+    # 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 
+    # most users.
+    #
+    # Calling this method will also cause the model to assume that it is not
+    # a new record (see {#new_record?}).
+    def populate_attributes(attribs)
+      # No longer a new record
+      @new_record = false
+      
+      ignore_dirty do
+        super
+        
+        populate_relationships(attribs)
+      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
+    
+    # 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
+    # on relationships, see {Relatable}.
+    def destroy(*args)
+      # Destroy dependent relationships
+      self.class.relationships.each do |name, options|
+        destroy_relationship(name, *args) if options[:dependent] == :destroy
+      end
+    end
+  end
+end

data/lib/virtualbox/abstract_model/attributable.rb

@@ -0,0 +1,193 @@
+module VirtualBox
+  class AbstractModel
+    # Module which can be included into any other class which allows
+    # that class to have attributes using the "attribute" class method.
+    # This creates the reader/writer for the attribute but also provides
+    # other useful options such as readonly attributes, default values,
+    # and more.
+    #
+    # 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
+    # would give the class the following abilities
+    #
+    #     instance.name = "Harry!"
+    #     puts instance.name # => "Harry!"
+    #
+    # Basic attributes alone are not different than ruby's built-in
+    # `attr_*` methods.
+    #
+    # ## Defining a Readonly Attribute
+    #
+    #     attribute :age, :readonly => true
+    #
+    # 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 
+    # inter-class use, and not for users of it.
+    #
+    # ## Defining Default Values
+    #
+    #     attribute :format, :default => "VDI"
+    #
+    # The example above applies a default value to format. So if no value
+    # is ever given to it, `format` would return `VDI`.
+    #
+    # ## Populating Multiple Attributes
+    #
+    # 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",
+    #           :age => 27
+    #         })
+    #       end
+    #     end
+    #
+    # **Note:** Populating attributes is not the same as mass-updating attributes.
+    # {#populate_attributes} is meant to do initial population only. There is
+    # currently no method for mass assignment for updating.
+    #
+    # ## 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 
+    # `populate_key`. Example:
+    #
+    #     attribute :path, :populate_key => :location
+    #
+    #     def initialize
+    #       populate_attributes(:location => "Home")
+    #       puts path # => "Home"
+    #     end
+    #
+    module Attributable
+      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. 
+        #
+        # @param [Symbol] name The name of the attribute, which will also be
+        #   used to set the accessor methods.
+        # @option options [Boolean] :readonly (false) If true, attribute will be readonly.
+        #   More specifically, the `attribute=` method won't be defined for it.
+        # @option options [Object] :default (nil) Specifies a default value for the
+        #   attribute.
+        # @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
+        end
+
+        # Returns the hash of attributes and their associated options.
+        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
+        end
+      end
+
+      # Does the initial population of the various attributes. It will
+      # ignore attributes which are not defined or have no value in the
+      # hash. 
+      #
+      # Population uses the attributes `populate_key` if present to
+      # determine which value to take. Example:
+      #
+      #     attribute :name, :populate_key => :namae
+      #     attribute :age
+      #
+      #     def initialize
+      #       populate_attributes(:namae => "Henry", :age => 27)
+      #     end
+      #
+      # The above example would set `name` to `Henry` since that is
+      # the `populate_key`. If a `populate_key` is not present, the
+      # attribute name is used.
+      def populate_attributes(attribs)
+        self.class.attributes.each do |key, options|
+          value_key = options[:populate_key] || key
+          write_attribute(key, attribs[value_key])
+        end
+      end
+
+      # 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 
+      # attributes), whereas users of a class which includes this
+      # module should use the accessor methods, such as `name=`.
+      def write_attribute(name, value)
+        attributes[name] = value
+      end
+
+      # 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 
+      # 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 ||= {}
+      end
+
+      # Returns boolean value denoting if an attribute exists.
+      def has_attribute?(name)
+        self.class.attributes.has_key?(name.to_sym)
+      end
+
+      # Returns a boolean value denoting if an attribute is readonly.
+      # This method also returns false for **nonexistent attributes**
+      # so it should be used in conjunction with {#has_attribute?} if
+      # existence is important.
+      def readonly_attribute?(name)
+        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