fission 0.3.0 → 0.4.0.beta.1

data/lib/fission/metadata.rb

@@ -3,8 +3,23 @@ module Fission
 
     require 'cfpropertylist'
 
+    # Public: Gets/Sets the content (Hash).
     attr_accessor :content
 
+    # Public: Deletes the Fusion metadata related to a VM.  The VM should not be
+    # running when this method is called.  It's highly recommended to call this
+    # method without the Fusion GUI application running.  If the Fusion GUI is
+    # running this method should succeed, but it's been observed that Fusion
+    # will recreate the metadata which is deleted.  This leads to 'missing' VMs
+    # in the Fusion GUI.
+    #
+    # vm_path - The absolute path to the directory of a VM.
+    #
+    # Examples
+    #
+    #   Fission::Metadata.delete_vm_info '/vms/foo.vmwarevm'
+    #
+    # Returns nothing.
     def self.delete_vm_info(vm_path)
       metadata = new
       metadata.load
@@ -13,24 +28,62 @@ module Fission
       metadata.save
     end
 
+    # Public: Reads the configured metadata file and populates the content
+    # variable with native ruby types.
+    #
+    # Examples
+    #
+    #   metadata.load
+    #
+    # Returns nothing.
     def load
-      raw_data = CFPropertyList::List.new :file => Fission.config.attributes['plist_file']
+      raw_data = CFPropertyList::List.new :file => Fission.config['plist_file']
       @content = CFPropertyList.native_types raw_data.value
     end
 
+    # Public: Saves a new version of the metadata file with the data in the
+    # content variable.
+    #
+    # Examples
+    #
+    #   metadata.save
+    #
+    # Returns nothing.
     def save
       new_content = CFPropertyList::List.new
       new_content.value = CFPropertyList.guess @content
-      new_content.save Fission.config.attributes['plist_file'],
+      new_content.save Fission.config['plist_file'],
                        CFPropertyList::List::FORMAT_BINARY
     end
 
+    # Public: Deletes the VM information from the 'restart document path'
+    # metadata. The 'restart document path' dictates which GUI consoles to
+    # display when Fusion starts.
+    #
+    # vm_path - The absolute path to the directory of a VM.
+    #
+    # Examples
+    #
+    #   metadata.delete_vm_restart_document 'vms/foo.vmwarevm'
+    #
+    # Returns nothing.
     def delete_vm_restart_document(vm_path)
       if @content.has_key?('PLRestartDocumentPaths')
         @content['PLRestartDocumentPaths'].delete_if { |p| p == vm_path }
       end
     end
 
+    # Public: Deletes the VM information from the 'favorites list' metadata.
+    # The 'favorites list' dictates which VMs are displayed in the Fusion VM
+    # libarary.
+    #
+    # vm_path - The absolute path to the directory of a VM.
+    #
+    # Examples
+    #
+    #   metadata.delete_favorite_entry '/vms/foo.vmwarevm'
+    #
+    # Returns nothing.
     def delete_vm_favorite_entry(vm_path)
       @content['VMFavoritesListDefaults2'].delete_if { |vm| vm['path'] == vm_path }
     end

data/lib/fission/response.rb

@@ -0,0 +1,76 @@
+module Fission
+  class Response
+
+    # Public: Gets/Sets the code (Integer).
+    attr_accessor :code
+
+    # Public: Gets/Sets the message (String).
+    attr_accessor :message
+
+    # Public: Gets/Sets the data (can be any of type as needed).
+    attr_accessor :data
+
+    # Public: Initialize a Response object.
+    #
+    # args - Hash of arguments:
+    #       :code    - Integer which denotes the code of the Response.  This is
+    #                  similar in concept to command line exit codes.  The
+    #                  convention is that 0 denotes success and any other value
+    #                  is unsuccessful (default: 1).
+    #       :message - String which denotes the message of the Response.  The
+    #                  convention is that this should only be used when the
+    #                  Response is unsuccessful (default: '').
+    #       :data    - Any valid ruby object.  This is used to convey any
+    #                  data that needs to be used by a caller.  The convention
+    #                  is that this should only be used when the Response is
+    #                  successful (default nil).
+    #
+    # Examples
+    #
+    #   Response.new :code => 0, :data => [1, 2, 3, 4]
+    #
+    #   Response.new :code => 0, :data => true
+    #
+    #   Response.new :code => 5, :message => 'Something went wrong'
+    #
+    # Returns a new Response instance.
+    def initialize(args={})
+      @code = args.fetch :code, 1
+      @message = args.fetch :message, ''
+      @data = args.fetch :data, nil
+    end
+
+    # Public: Helper method to determine if a response is successful or not.
+    #
+    # Examples
+    #
+    #   response.successful?
+    #   # => true
+    #
+    #   response.successful?
+    #   # => false
+    #
+    # Returns a Boolean.
+    # Returns true if the code is 0.
+    # Returns false if the code is any other value.
+    def successful?
+      @code == 0
+    end
+
+    # Public: Helper method to create a new Response object when running a
+    # command line tool.
+    #
+    # cmd_output - This should be the output of the command.
+    #
+    # Returns a Response.
+    # The Response's code attribute will be set to the value of '$?'.  The
+    # Response's message attribute will be set to the provided command output
+    # if, and only if, the Response is unsuccessful.
+    def self.from_command(cmd_output)
+      response = new :code => $?.exitstatus
+      response.message = cmd_output unless response.successful?
+      response
+    end
+
+  end
+end

data/lib/fission/ui.rb

@@ -1,19 +1,68 @@
 module Fission
   class UI
+
+    # Internal: Returns the stdout value.
     attr_reader :stdout
 
+    # Internal: Initialize a UI object.
+    #
+    # stdout - The object to use for stdout (default: $stdout).  This provides
+    #          an easy way to capture/silence output if needed.
+    #
+    # Examples
+    #
+    #   Fission::UI.new
+    #
+    #   str_io = StringIO.new
+    #   Fission::UI.new str_io
     def initialize(stdout=$stdout)
       @stdout = stdout
     end
 
+    # Internal: Outputs the specified argument to the configured stdout object.
+    # The 'puts' method will be called on the stdout object.
+    #
+    # s - The String to output.
+    #
+    # Examples
+    #
+    #   ui.output "foo bar\n"
+    #
+    # Returns nothing.
     def output(s)
       @stdout.puts s
     end
 
+    # Internal: Outputs the specified arguments printf style.  The 'printf'
+    # method will be called on the stdout object.  Currently, this assuems there
+    # are two data items.
+    #
+    # string - The printf String.
+    # key    - The String for the first data item.
+    # value  - The String for the second data item.
+    #
+    # Examples
+    #
+    #   ui.output_printf "%s    %s\n", 'foo', bar
+    #
+    # Returns nothing.
     def output_printf(string, key, value)
       @stdout.send :printf, string, key, value
     end
 
+    # Internal: Outputs the specified argument to the configured stdout object
+    # and exits with the specified exit code.
+    #
+    # s         - The String to output.
+    # exit_code - The Integer exit code.
+    #
+    # Examples
+    #
+    #   ui.output_and_exit 'something went wrong', 99
+    #
+    #   ui.output_and_exit 'all done', 0
+    #
+    # Returns nothing.
     def output_and_exit(s, exit_code)
       output s
       exit exit_code

data/lib/fission/version.rb

@@ -1,3 +1,3 @@
 module Fission
-  VERSION = "0.3.0"
+  VERSION = "0.4.0.beta.1"
 end

data/lib/fission/vm.rb

@@ -1,158 +1,654 @@
 module Fission
   class VM
+
+    # Public: Gets the name of the VM as a String.
     attr_reader :name
 
     def initialize(name)
       @name = name
     end
 
+    # Public: Creates a snapshot for a VM.  The VM must be running in order
+    # to create a snapshot.  Snapshot names must be unique.
+    #
+    # name - The desired name of the snapshot.  The name must be unique.
+    #
+    # Examples
+    #
+    #   @vm.create_snapshot('foo_snap_1')
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
     def create_snapshot(name)
-      command = "#{Fission.config.attributes['vmrun_cmd']} snapshot #{conf_file.gsub ' ', '\ '} \"#{name}\" 2>&1"
-      output = `#{command}`
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
 
-      if $?.exitstatus == 0
-        Fission.ui.output "Snapshot '#{name}' created"
-      else
-        Fission.ui.output "There was an error creating the snapshot."
-        Fission.ui.output_and_exit "The error was:\n#{output}", 1
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      unless running_response.data
+        message = 'The VM must be running in order to take a snapshot.'
+        return Response.new :code => 1, :message => message
       end
+
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
+
+      snapshots_response = snapshots
+      return snapshots_response unless snapshots_response.successful?
+
+      if snapshots_response.data.include? name
+        message = "There is already a snapshot named '#{name}'."
+        return Response.new :code => 1, :message => message
+      end
+
+      command = "#{vmrun_cmd} snapshot "
+      command << "#{conf_file_response.data} \"#{name}\" 2>&1"
+
+      Response.from_command(`#{command}`)
     end
 
+    # Public: Reverts the VM to the specified snapshot.  The snapshot to revert
+    # to must exist and the Fusion GUI must not be running.
+    #
+    # name - The snapshot name to revert to.
+    #
+    # Examples
+    #
+    #   @vm.revert_to_snapshot('foo_snap_1')
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
     def revert_to_snapshot(name)
-      command = "#{Fission.config.attributes['vmrun_cmd']} revertToSnapshot #{conf_file.gsub ' ', '\ '} \"#{name}\" 2>&1"
-      output = `#{command}`
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
 
-      if $?.exitstatus == 0
-        Fission.ui.output "Reverted to snapshot '#{name}'"
-      else
-        Fission.ui.output "There was an error reverting to the snapshot."
-        Fission.ui.output_and_exit "The error was:\n#{output}", 1
+      if Fusion.running?
+        message = 'It looks like the Fusion GUI is currently running.  '
+        message << 'A VM cannot be reverted to a snapshot when the Fusion GUI is running.  '
+        message << 'Exit the Fusion GUI and try again.'
+        return Response.new :code => 1, :message => message
       end
+
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
+
+      snapshots_response = snapshots
+      return snapshots_response unless snapshots_response.successful?
+
+      unless snapshots_response.data.include? name
+        message = "Unable to find a snapshot named '#{name}'."
+        return Response.new :code => 1, :message => message
+      end
+
+      command = "#{vmrun_cmd} revertToSnapshot "
+      command << "#{conf_file_response.data} \"#{name}\" 2>&1"
+
+      Response.from_command(`#{command}`)
     end
 
+    # Public: List the snapshots for a VM.
+    #
+    # Examples
+    #
+    #   @vm.snapshots.data
+    #   # => ['snap 1', 'snap 2']
+    #
+    # Returns a Response with the result.
+    # If successful, the Repsonse's data attribute will be an Array of the
+    # snapshot names (String).
+    # If there is an error, an unsuccessful Response will be returned.
     def snapshots
-      command = "#{Fission.config.attributes['vmrun_cmd']} listSnapshots #{conf_file.gsub ' ', '\ '} 2>&1"
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
+
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
+
+      command = "#{vmrun_cmd} listSnapshots "
+      command << "#{conf_file_response.data} 2>&1"
       output = `#{command}`
 
-      if $?.exitstatus == 0
+      response = Response.new :code => $?.exitstatus
+
+      if response.successful?
         snaps = output.split("\n").select { |s| !s.include? 'Total snapshots:' }
-        snaps.map { |s| s.strip }
+        response.data = snaps.map { |s| s.strip }
       else
-        Fission.ui.output "There was an error getting the list of snapshots."
-        Fission.ui.output_and_exit "The error was:\n#{output}", 1
+        response.message = output
       end
+
+      response
     end
 
-    def start(args={})
-      command = "#{Fission.config.attributes['vmrun_cmd']} start #{conf_file.gsub ' ', '\ '} "
+    # Public: Starts a VM.  The VM must not be running in order to start it.
+    #
+    # options - Hash of options:
+    #           :headless - Boolean which specifies to start the VM without a
+    #                       GUI console.  The Fusion GUI must not be running in
+    #                       order to start the VM headless.
+    #                       (default: false)
+    #
+    # Examples
+    #
+    #   @vm.start
+    #
+    #   @vm.start :headless => true
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
+    def start(options={})
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
 
-      if !args[:headless].blank? && args[:headless]
-        command << "nogui 2>&1"
-      else
-        command << "gui 2>&1"
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      if running_response.data
+        return Response.new :code => 1, :message => 'VM is already running'
       end
 
-      output = `#{command}`
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
 
-      if $?.exitstatus == 0
-        Fission.ui.output "VM started"
-      else
-        Fission.ui.output "There was a problem starting the VM.  The error was:\n#{output}"
+      unless options[:headless].blank?
+        if Fusion.running?
+          message = 'It looks like the Fusion GUI is currently running.  '
+          message << 'A VM cannot be started in headless mode when the Fusion GUI is running.  '
+          message << 'Exit the Fusion GUI and try again.'
+          return Response.new :code => 1, :message => message
+        end
       end
+
+      command = "#{vmrun_cmd} start "
+      command << "#{conf_file_response.data} "
+
+      command << (options[:headless].blank? ? 'gui ' : 'nogui ')
+      command << '2>&1'
+
+      Response.from_command(`#{command}`)
     end
 
-    def stop
-      command = "#{Fission.config.attributes['vmrun_cmd']} stop #{conf_file.gsub ' ', '\ '} 2>&1"
-      output = `#{command}`
+    # Public: Stops a VM.  The VM must be running in order to stop it.
+    #
+    # options - Hash of options:
+    #           :hard - Boolean which specifies to power off the VM (instead of
+    #                   attempting to initiate a graceful shutdown).  This is
+    #                   the equivalent of passing 'hard' to the vmrun stop
+    #                   command.
+    #                   (default: false)
+    #
+    # Examples
+    #
+    #   @vm.stop
+    #
+    #   @vm.stop :hard => true
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
+    def stop(options={})
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
 
-      if $?.exitstatus == 0
-        Fission.ui.output "VM stopped"
-      else
-        Fission.ui.output "There was a problem stopping the VM.  The error was:\n#{output}"
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      unless running_response.data
+        return Response.new :code => 1, :message => 'VM is not running'
       end
+
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
+
+      command = "#{vmrun_cmd} stop "
+      command << "#{conf_file_response.data} "
+      command << 'hard ' unless options[:hard].blank?
+      command << '2>&1'
+
+      Response.from_command(`#{command}`)
     end
 
+    # Public: Suspends a VM.  The VM must be running in order to suspend it.
+    #
+    # Examples
+    #
+    #   @vm.suspend
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
     def suspend
-      command = "#{Fission.config.attributes['vmrun_cmd']} suspend #{conf_file.gsub ' ', '\ '} 2>&1"
-      output = `#{command}`
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
+
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      unless running_response.data
+        return Response.new :code => 1, :message => 'VM is not running'
+      end
+
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
+
+      command = "#{vmrun_cmd} suspend "
+      command << "#{conf_file_response.data} 2>&1"
+
+      Response.from_command(`#{command}`)
+    end
+
+    # Public: Provides the MAC addresses for a VM.
+    #
+    # Examples:
+    #
+    #   @vm.mac_addresses.data
+    #   # => ['00:0c:29:1d:6a:64', '00:0c:29:1d:6a:75']
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be an Array of the MAC
+    # addresses found.  If no MAC addresses are found, the Response's data
+    # attribute will be an empty Array.
+    # If there is an error, an unsuccessful Response will be returned.
+    def mac_addresses
+      network_response = network_info
+      return network_response unless network_response.successful?
+
+      response = Response.new :code => 0
+      response.data = network_response.data.values.collect { |n| n['mac_address'] }
+
+      response
+    end
+
+    # Public: Network information for a VM.  Includes interface name, associated
+    # MAC address, and IP address (if applicable).
+    #
+    # Examples:
+    #
+    #   # if IP addresses are found in the Fusion DHCP lease file
+    #   response = @vm.network_info.data
+    #   # => { 'ethernet0' => { 'mac_address' => '00:0c:29:1d:6a:64',
+    #                           'ip_address'  => '127.0.0.1' },
+    #          'ethernet1' => { 'mac_address' => '00:0c:29:1d:6a:75',
+    #                           'ip_address'  => '127.0.0.2' } }
+    #
+    #   # if IP addresses are not found in the Fusion DHCP lease file
+    #   response = @vm.network_info.data
+    #   # => { 'ethernet0' => { 'mac_address' => '00:0c:29:1d:6a:64',
+    #                           'ip_address'  => nil },
+    #          'ethernet1' => { 'mac_address' => '00:0c:29:1d:6a:75',
+    #                           'ip_address'  => nil } }
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be a Hash with the
+    # interface identifiers as the keys and the associated MAC address.  If an
+    # IP address was found in the Fusion DHCP lease file, then it will
+    # be included.  If an IP address was not found, then the IP address value
+    # will be nil.  If there are no network interfaces, the Response's data
+    # attribute will be an empty Hash.
+    # If there is an error, an unsuccessful Response will be returned.
+    def network_info
+      conf_file_response = conf_file
+      return conf_file_response unless conf_file_response.successful?
+
+      response = Response.new :code => 0, :data => {}
+
+      interface_pattern = /^ethernet\d+/
+      mac_pattern = /(\w\w[:-]\w\w[:-]\w\w[:-]\w\w[:-]\w\w[:-]\w\w)/
+
+      File.open conf_file_response.data, 'r' do |f|
+        f.grep(mac_pattern).each do |line|
+          int = line.scan(interface_pattern)[0]
+          mac = line.scan(mac_pattern)[0].first
+          response.data[int] = {}
+          response.data[int]['mac_address'] = mac
+
+          lease_response = Fission::Lease.find_by_mac_address mac
+          return lease_response unless lease_response.successful?
+
+          response.data[int]['ip_address'] = nil
+
+          if lease_response.data
+            response.data[int]['ip_address'] = lease_response.data.ip_address
+          end
 
-      if $?.exitstatus == 0
-        Fission.ui.output "VM suspended"
+        end
+      end
+
+      response
+    end
+
+    # Public: Provides the state of the VM.
+    #
+    # Examples
+    #
+    #   @vm.state.data
+    #   # => 'running'
+    #
+    #   @vm.state.data
+    #   # => 'not running'
+    #
+    #   @vm.state.data
+    #   # => 'suspended'
+    #
+    # Returns a Response with the result.
+    # If the Response is successful, the Response's data attribute will
+    # be a String of the state.  If the VM is currently powered on, the state
+    # will be 'running'.  If the VM is deemed to be suspended, the state will be
+    # 'suspended'.  If the VM is not running and not deemed to be suspended, the
+    # state will be 'not running'.
+    # If there is an error, an unsuccessful Response will be returned.
+    def state
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      response = Response.new :code => 0, :data => 'not running'
+
+      if running_response.data
+        response.data = 'running'
       else
-        Fission.ui.output "There was a problem suspending the VM.  The error was:\n#{output}"
+        suspended_response = suspended?
+        return suspended_response unless suspended_response.successful?
+
+        response.data = 'suspended' if suspended_response.data
+      end
+
+      response
+    end
+
+    # Public: Determines if the VM exists or not.  This method looks for the
+    # VM's conf file ('.vmx') to determine if the VM exists or not.
+    #
+    # Examples
+    #
+    #   @vm.exists?
+    #   # => true
+    #
+    # Returns a Boolean.
+    def exists?
+      conf_file.successful?
+    end
+
+    # Public: Determines if a VM is suspended.
+    #
+    # Examples
+    #
+    #   @vm.suspended?.data
+    #   # => true
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be a Boolean.  If the VM
+    # is not running, then this method will look for a '.vmem' file in the VM's
+    # directory.  If a '.vmem' file exists and it matches the name of the VM,
+    # then the VM is considered to be suspended.  If the VM is running or if a
+    # matching '.vmem' file is not found, then the VM is not considered to be
+    # suspended.
+    # If there is an error, an unsuccessful Response will be returned.
+    def suspended?
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      response = Response.new :code => 0, :data => false
+      response.data = suspend_file_exists? unless running_response.data
+
+      response
+    end
+
+    # Public: Determines if a VM has a suspend file ('.vmem') in it's directory.
+    # This only looks for a suspend file which matches the name of the VM.
+    #
+    # Examples
+    #
+    #   @vm.suspend_file_exists?
+    #   # => true
+    #
+    # Returns a Boolean.
+    def suspend_file_exists?
+      File.file? File.join(path, "#{@name}.vmem")
+    end
+
+    # Public: Determines if a VM is running.
+    #
+    # Examples
+    #
+    #   @vm.running?.data
+    #   # => true
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be a Boolean.
+    # If there is an error, an unsuccessful Response will be returned.
+    def running?
+      all_running_response = self.class.all_running
+      return all_running_response unless all_running_response.successful?
+
+      response = Response.new :code => 0, :data => false
+
+      if all_running_response.data.collect { |v| v.name }.include? @name
+        response.data = true
       end
+
+      response
     end
 
+    # Public: Determines the path to the VM's config file ('.vmx').
+    #
+    # Examples
+    #
+    #   @vm.conf_file.data
+    #   # => '/my_vms/foo/foo.vmx'
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be a String which will
+    # be escaped for spaces (' ').
+    # If there is a single '.vmx' file in the VM's directory, regardless if
+    # the name of '.vmx' file matches the VM name, the Response's data
+    # attribute will the be the path to the '.vmx' file.
+    # If there are multiple '.vmx' files found in the VM's directory, there are
+    # a couple of different possible outcomes.
+    # If one of the file names matches the VM directory name, then the
+    # Response's data attribute will be the path to the matching '.vmx' file.
+    # If none of the file names match the VM directory name, then this is deemed
+    # an error condition and an unsuccessful Response will be returned.
+    # If there is an error, an unsuccessful Response will be returned.
     def conf_file
-      vmx_path = File.join(self.class.path(@name), "*.vmx")
-      conf_files = Dir.glob(vmx_path)
+      vmx_path = File.join path, "*.vmx"
+      conf_files = Dir.glob vmx_path
+
+      response = Response.new
 
       case conf_files.count
       when 0
-        Fission.ui.output_and_exit "Unable to find a config file for VM '#{@name}' (in '#{vmx_path}')", 1
+        response.code = 1
+        response.message = "Unable to find a config file for VM '#{@name}' (in '#{vmx_path}')"
       when 1
-        conf_files.first
+        response.code = 0
+        response.data = conf_files.first
       else
         if conf_files.include?(File.join(File.dirname(vmx_path), "#{@name}.vmx"))
-          File.join(File.dirname(vmx_path), "#{@name}.vmx")
+          response.code = 0
+          response.data = File.join(File.dirname(vmx_path), "#{@name}.vmx")
         else
+          response.code = 1
           output = "Multiple config files found for VM '#{@name}' ("
           output << conf_files.sort.map { |f| "'#{File.basename(f)}'" }.join(', ')
           output << " in '#{File.dirname(vmx_path)}')"
-          Fission.ui.output_and_exit output, 1
+          response.message = output
         end
       end
+
+      response.data.gsub! ' ', '\ ' if response.successful?
+
+      response
     end
 
+    # Public: Provides the expected path to a VM's directory.  This does not
+    # imply that the VM or path exists.
+    #
+    # name - The name of the VM to provide the path for.
+    #
+    # Examples
+    #
+    #   @vm.path
+    #   # => '/vm/foo.vmwarevm'
+    #
+    # Returns the path (String) to the VM's directory.
+    def path
+      File.join Fission.config['vm_dir'], "#{@name}.vmwarevm"
+    end
+
+    # Public: Provides all of the VMs which are located in the VM directory.
+    #
+    # Examples
+    #
+    #   Fission::VM.all.data
+    #   # => [<Fission::VM:0x007fd6fa24c5d8 @name="foo">,
+    #         <Fission::VM:0x007fd6fa23c5e8 @name="bar">]
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be an Array of VM
+    # objects.  If no VMs are found, the Response's data attribute will be an
+    # empty Array.
+    # If there is an error, an unsuccessful Response will be returned.
     def self.all
-      vm_dirs = Dir[File.join Fission.config.attributes['vm_dir'], '*.vmwarevm'].select do |d|
+      vm_dirs = Dir[File.join Fission.config['vm_dir'], '*.vmwarevm'].select do |d|
         File.directory? d
       end
 
-      vm_dirs.map { |d| File.basename d, '.vmwarevm' }
+      response = Response.new :code => 0
+      response.data = vm_dirs.collect { |d| new(File.basename d, '.vmwarevm') }
+
+      response
     end
 
+    # Public: Provides all of the VMs which are currently running.
+    #
+    # Examples
+    #
+    #   Fission::VM.all_running.data
+    #   # => [<Fission::VM:0x007fd6fa24c5d8 @name="foo">,
+    #         <Fission::VM:0x007fd6fa23c5e8 @name="bar">]
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be an Array of VM
+    # objects which are running.  If no VMs are running, the Response's data
+    # attribute will be an empty Array.
+    # If there is an error, an unsuccessful Response will be returned.
     def self.all_running
-      command = "#{Fission.config.attributes['vmrun_cmd']} list"
+      command = "#{Fission.config['vmrun_cmd']} list"
 
       output = `#{command}`
 
-      if $?.exitstatus == 0
+      response = Response.new :code => $?.exitstatus
+
+      if response.successful?
         vms = output.split("\n").select do |vm|
           vm.include?('.vmx') && File.exists?(vm) && File.extname(vm) == '.vmx'
         end
 
-        vms.map { |vm| File.basename(File.dirname(vm), '.vmwarevm') }
+        response.data = vms.collect do |vm|
+          new File.basename(File.dirname(vm), '.vmwarevm')
+        end
       else
-        Fission.ui.output_and_exit "Unable to determine the list of running VMs", 1
+        response.message = output
       end
-    end
 
-    def self.exists?(vm_name)
-      File.directory? path(vm_name)
+      response
     end
 
-    def self.path(vm_name)
-      File.join Fission.config.attributes['vm_dir'], "#{vm_name}.vmwarevm"
-    end
+    # Public: Creates a new VM which is a clone of an existing VM.  As Fusion
+    # doesn't provide a native cloning mechanism, this is a best effort.  This
+    # essentially is a directory copy with updates to relevant files.  It's
+    # recommended to clone VMs which are not running.
+    #
+    # source_vm_name - The name of the VM to clone.
+    # target_vm_name - The name of the VM to be created.
+    #
+    # Examples
+    #
+    #   Fission::VM.clone 'foo', 'bar'
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
+    def self.clone(source_vm_name, target_vm_name)
+      source_vm = new source_vm_name
+      target_vm = new target_vm_name
+
+      unless source_vm.exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
+
+      if target_vm.exists?
+        return Response.new :code => 1, :message => 'VM already exists'
+      end
 
-    def self.clone(source_vm, target_vm)
-      Fission.ui.output "Cloning #{source_vm} to #{target_vm}"
-      FileUtils.cp_r path(source_vm), path(target_vm)
+      FileUtils.cp_r source_vm.path, target_vm.path
 
-      Fission.ui.output "Configuring #{target_vm}"
-      rename_vm_files source_vm, target_vm
-      update_config source_vm, target_vm
+      rename_vm_files source_vm.name, target_vm.name
+      update_config source_vm.name, target_vm.name
+
+      Response.new :code => 0
     end
 
-    def self.delete(vm_name)
-      Fission.ui.output "Deleting vm #{vm_name}"
-      FileUtils.rm_rf path(vm_name)
-      Fission::Metadata.delete_vm_info(path(vm_name))
+    # Public: Deletes a VM.  The VM must not be running in order to delete it.
+    # As there are a number issues with the Fusion command line tool for
+    # deleting VMs, this is a best effort.  The VM must not be running when this
+    # method is called.  This essentially deletes the VM directory and attempts
+    # to remove the relevant entries from the Fusion plist file.  It's highly
+    # recommended to delete VMs without the Fusion GUI running.  If the Fusion
+    # GUI is running this method should succeed, but it's been observed that
+    # Fusion will recreate the plist data which is deleted.  This leads to
+    # 'missing' VMs in the Fusion GUI.
+    #
+    # Examples
+    #
+    #   @vm.delete
+    #
+    # Returns a Response with the result.
+    # If successful, the Response's data attribute will be nil.
+    # If there is an error, an unsuccessful Response will be returned.
+    def delete
+      unless exists?
+        return Response.new :code => 1, :message => 'VM does not exist'
+      end
+
+      running_response = running?
+      return running_response unless running_response.successful?
+
+      if running_response.data
+        message = 'The VM must not be running in order to delete it.'
+        return Response.new :code => 1, :message => message
+      end
+
+      FileUtils.rm_rf path
+      Metadata.delete_vm_info path
+
+      Response.new :code => 0
     end
 
     private
+    # Internal: Renames the files of a newly cloned VM.
+    #
+    # from - The VM name that was used as the source of the clone.
+    # to   - The name of the newly cloned VM.
+    #
+    # Examples
+    #
+    #   Fission::VM.rename_vm_files 'foo', 'bar'
+    #
+    # Returns nothing.
     def self.rename_vm_files(from, to)
+      to_vm = new to
+
       files_to_rename(from, to).each do |file|
         text_to_replace = File.basename(file, File.extname(file))
 
@@ -162,18 +658,34 @@ module Fission
           end
         end
 
-        unless File.exists?(File.join(path(to), file.gsub(text_to_replace, to)))
-          FileUtils.mv File.join(path(to), file),
-                       File.join(path(to), file.gsub(text_to_replace, to))
+        unless File.exists?(File.join(to_vm.path, file.gsub(text_to_replace, to)))
+          FileUtils.mv File.join(to_vm.path, file),
+                       File.join(to_vm.path, file.gsub(text_to_replace, to))
         end
       end
     end
 
+    # Internal: Provides the list of files which need to be renamed in a newly
+    # cloned VM directory.
+    #
+    # from - The VM name that was used as the source of the clone.
+    # to   - The name of the newly cloned VM.
+    #
+    # Examples
+    #
+    #   Fission::VM.files_to_rename 'foo', 'bar'
+    #   # => ['/vms/vm1/foo.vmdk', '/vms/vm1/foo.vmx', 'vms/vm1/blah.other']
+    #
+    # Returns an Array containing the paths (String) to the files to rename.
+    # The paths which match the from name will preceed any other files found in
+    # the newly cloned VM directory.
     def self.files_to_rename(from, to)
+      to_vm = new to
+
       files_which_match_source_vm = []
       other_files = []
 
-      Dir.entries(path(to)).each do |f|
+      Dir.entries(to_vm.path).each do |f|
         unless f == '.' || f == '..'
           f.include?(from) ? files_which_match_source_vm << f : other_files << f
         end
@@ -182,19 +694,85 @@ module Fission
       files_which_match_source_vm + other_files
     end
 
+    # Internal: Provides the list of file extensions for VM related files.
+    #
+    # Examples
+    #
+    #   Fission::VM.vm_file_extension
+    #   # => ['.nvram', '.vmdk', '.vmem']
+    #
+    # Returns an Array containing the file extensions of VM realted files.
+    # The file extensions returned are Strings and include a '.'.
     def self.vm_file_extensions
       ['.nvram', '.vmdk', '.vmem', '.vmsd', '.vmss', '.vmx', '.vmxf']
     end
 
+    # Internal: Updates config files for a newly cloned VM.  This will update any
+    # files with the extension of '.vmx', '.vmxf', and '.vmdk'.  Any binary
+    # '.vmdk' files will be skipped.
+    #
+    # from - The VM name that was used as the source of the clone.
+    # to   - The name of the newly cloned VM.
+    #
+    # Examples
+    #
+    #   Fission::VM.update_config 'foo', 'bar'
+    #
+    # Returns nothing.
     def self.update_config(from, to)
+      to_vm = new to
+
       ['.vmx', '.vmxf', '.vmdk'].each do |ext|
-        file = File.join path(to), "#{to}#{ext}"
+        file = File.join to_vm.path, "#{to}#{ext}"
 
         unless File.binary?(file)
           text = (File.read file).gsub from, to
           File.open(file, 'w'){ |f| f.print text }
         end
+
+        clean_up_conf_file(file) if ext == '.vmx'
+      end
+    end
+
+    # Internal: Cleans up the conf file (*.vmx) for a newly cloned VM.  This
+    # includes removing generated MAC addresses, setting up for a new UUID, and
+    # disable VMware tools warning.
+    #
+    # conf_file_path - Aboslute path to the VM's conf file (.vmx).
+    #
+    # Examples
+    #
+    #   VM.clean_up_conf_file '/vms/foo/foo.vmx'
+    #
+    # Returns nothing.
+    def self.clean_up_conf_file(conf_file_path)
+      conf_items_patterns = [ /^tools\.remindInstall.*\n/,
+                              /^uuid\.action.*\n/,
+                              /^ethernet\.+generatedAddress.*\n/ ]
+
+      content = File.read conf_file_path
+
+      conf_items_patterns.each do |pattern|
+        content.gsub(pattern, '').strip
       end
+
+      content << "\n"
+      content << "tools.remindInstall = \"FALSE\"\n"
+      content << "uuid.action = \"create\"\n"
+
+      File.open(conf_file_path, 'w') { |f| f.print content }
+    end
+
+    # Internal: Helper for getting the configured vmrun_cmd value.
+    #
+    # Examples
+    #
+    #   @vm.vmrun_cmd
+    #   # => "/foo/bar/vmrun -T fusion"
+    #
+    # Returns a String for the configured value of Fission.config['vmrun_cmd'].
+    def vmrun_cmd
+      Fission.config['vmrun_cmd']
     end
 
   end