melomel 0.3.1 → 0.4.0

data/lib/melomel/bridge/messaging.rb

@@ -3,70 +3,116 @@ require 'nokogiri'
 # These add-on methods enable the message encoding and decoding.
 module Melomel
   class Bridge
+    ###########################################################################
+    #
+    # Basic Messages
+    #
+    ###########################################################################
+
     # Creates an object in the Flash virtual machine and returns the reference
     # to it.
+    #
+    # class_name - The name of the class to instantiate.
+    #
+    # Returns an instance of the class if the class is found. Otherwise, nil.
     def create_object(class_name)
-      send("<create class=\"#{class_name}\"/>")
-      parse_message_value(Nokogiri::XML(receive()).root)
+      send_create_object(class_name, false)
+    end
+
+    # Same as `create_object` except that an error is thrown if the class is
+    # not found.
+    def create_object!(class_name)
+      send_create_object(class_name, true)
     end
 
     # Retrieves a reference to a class in the Flash virtual machine.
+    #
+    # class_name - The name of the class to retrieve a reference to.
+    #
+    # Returns a reference to the class if it exists. Otherwise, nil.
     def get_class(class_name)
-      send("<get-class name=\"#{class_name}\"/>")
-      parse_message_value(Nokogiri::XML(receive()).root)
+      send_get_class(class_name, false)
+    end
+
+    # Same as `get_class` except that an error is thrown if the class is not
+    # found.
+    def get_class!(class_name)
+      send_get_class(class_name, true)
     end
 
     # Retrieves a property of an object in the Flash virtual machine
+    #
+    # proxy_id - The identifier for the object proxy.
+    # property - The name of the property to access.
+    # 
+    # Returns the value of the property if it exists. Otherwise, nil.
     def get_property(proxy_id, property)
-      send("<get object=\"#{proxy_id}\" property=\"#{property}\"/>")
-      parse_message_value(Nokogiri::XML(receive()).root)
+      send_get_property(proxy_id, property, false)
+    end
+
+    # Same as `get_property` except that an error is thrown if the property
+    # does not exist.
+    def get_property!(proxy_id, property)
+      send_get_property(proxy_id, property, true)
     end
 
     # Sets a property on an object in the Flash virtual machine
+    #
+    # proxy_id - The identifier of the object proxy.
+    # property - The name of the property to mutate.
+    # value    - The value to set the property to.
+    #
+    # Returns the value of the property after being set.
     def set_property(proxy_id, property, value)
-      # Create message and format value to set
-      xml = Nokogiri::XML("<set object=\"#{proxy_id}\" property=\"#{property}\"><arg/></set>")
-      format_message_value(xml.at_xpath('/set/arg'), value)
-      
-      # Send & Receive
-      send(xml.root.to_xml(:indent => 0))
-      parse_message_value(Nokogiri::XML(receive()).root)
+      send_set_property(proxy_id, property, value, false)
+    end
+
+    # Same as `set_property` except that an error is thrown if the property
+    # does not exist.
+    def set_property!(proxy_id, property, value)
+      send_set_property(proxy_id, property, value, true)
     end
 
     # Invokes a method on an object in the Flash virtual machine
+    #
+    # proxy_id    - The identifier of the object proxy.
+    # method_name - The name of the method to invoke.
+    # *args       - List of arguments passed to the method.
+    #
+    # Returns the value returned from the Flash method.
     def invoke_method(proxy_id, method_name, *args)
-      xml = Nokogiri::XML("<invoke object=\"#{proxy_id}\" method=\"#{method_name}\"><args/></invoke>")
-      
-      # Loop over and add arguments to call
-      args_node = xml.at_xpath('invoke/args')
-      args.each do |arg|
-        arg_node = Nokogiri::XML::Node.new('arg', xml)
-        format_message_value(arg_node, arg)
-        args_node.add_child(arg_node)
-      end
-      
-      # Send and receive
-      send(xml.root.to_xml(:indent => 0))
-      parse_message_value(Nokogiri::XML(receive()).root)
+      send_invoke_method(proxy_id, method_name, args, false)
+    end
+    
+    # Same as `invoke_method` except that an error is thrown if the method
+    # does not exist.
+    def invoke_method!(proxy_id, method_name, *args)
+      send_invoke_method(proxy_id, method_name, args, true)
     end
     
     # Invokes a package level function in the Flash virtual machine
-    def invoke_function(function, *args)
-       xml = Nokogiri::XML("<invoke-function name=\"#{function}\"><args/></invoke>")
-
-        # Loop over and add arguments to call
-        args_node = xml.at_xpath('invoke-function/args')
-        args.each do |arg|
-          arg_node = Nokogiri::XML::Node.new('arg', xml)
-          format_message_value(arg_node, arg)
-          args_node.add_child(arg_node)
-        end
+    # 
+    # function_name - The fully qualified name of the function to invoke.
+    # *args         - List of arguments passed to the function.
+    #
+    # Returns the return value of the Flash function.
+    def invoke_function(function_name, *args)
+      send_invoke_function(function_name, args, false)
+    end
 
-        # Send and receive
-        send(xml.root.to_xml(:indent => 0))
-        parse_message_value(Nokogiri::XML(receive()).root)
+    # Same as `invoke_function` except that an error is thrown if the method
+    # does not exist.
+    def invoke_function!(function_name, *args)
+      send_invoke_function(function_name, args, true)
     end
 
+
+    ###########################################################################
+    #
+    # Utility Methods
+    #
+    ###########################################################################
+
     # Creates an object proxy from a hash
     def create_hash(hash)
       proxy = create_object('Object')
@@ -106,24 +152,113 @@ module Melomel
 
     # Parses a return message and converts it into an appropriate type
     def parse_message_value(xml)
-      value = xml['value']
-      data_type = xml['dataType']
+      name = xml.name()
       
-      if data_type == 'null'
-        return nil
-      elsif data_type == 'int'
-        return value.to_i
-      elsif data_type == 'float'
-        return value.to_f
-      elsif data_type == 'boolean'
-        return value == 'true'
-      elsif data_type == 'object'
-        return Melomel::ObjectProxy.new(self, value.to_i)
-      elsif data_type == 'string' || data_type.nil?
-        return value
+      # If we receive an error back then raise it in the Ruby VM.
+      if name == 'error'
+        stack_trace_xml = xml.at_xpath('stack-trace')
+        object      = Melomel::ObjectProxy.new(self, xml['proxyId'].to_i)
+        error_id    = xml['errorId'].to_i
+        message     = xml['message']
+        name        = xml['name']
+        stack_trace = stack_trace_xml ? stack_trace_xml.to_str : nil
+        $stderr.puts(stack_trace)
+        raise Melomel::Error.new(object, error_id, message, name, stack_trace), message
+
+      # Otherwise we have a return value so we should parse it.
       else
-        raise UnrecognizedTypeError, "Unknown type: #{data_type}"
+        value = xml['value']
+        data_type = xml['dataType']
+      
+        if data_type == 'null'
+          return nil
+        elsif data_type == 'int'
+          return value.to_i
+        elsif data_type == 'float'
+          return value.to_f
+        elsif data_type == 'boolean'
+          return value == 'true'
+        elsif data_type == 'object'
+          return Melomel::ObjectProxy.new(self, value.to_i)
+        elsif data_type == 'string' || data_type.nil?
+          return value
+        else
+          raise UnrecognizedTypeError, "Unknown type: #{data_type}"
+        end
       end
     end
+    
+
+    ###########################################################################
+    #
+    # Private Methods
+    #
+    ###########################################################################
+
+    private
+    
+    # Creates an object in the Flash virtual machine and returns the reference
+    # to it.
+    def send_create_object(class_name, throwable=true)
+      send("<create class=\"#{class_name}\" throwable=\"#{throwable}\"/>")
+      parse_message_value(Nokogiri::XML(receive()).root)
+    end
+
+    # Retrieves a reference to a class in the Flash virtual machine.
+    def send_get_class(class_name, throwable=true)
+      send("<get-class name=\"#{class_name}\" throwable=\"#{throwable}\"/>")
+      parse_message_value(Nokogiri::XML(receive()).root)
+    end
+
+    # Retrieves a property of an object in the Flash virtual machine
+    def send_get_property(proxy_id, property, throwable)
+      send("<get object=\"#{proxy_id}\" property=\"#{property}\" throwable=\"#{throwable}\"/>")
+      parse_message_value(Nokogiri::XML(receive()).root)
+    end
+
+    # Sets a property on an object in the Flash virtual machine
+    def send_set_property(proxy_id, property, value, throwable)
+      # Create message and format value to set
+      xml = Nokogiri::XML("<set object=\"#{proxy_id}\" property=\"#{property}\" throwable=\"#{throwable}\"><arg/></set>")
+      format_message_value(xml.at_xpath('/set/arg'), value)
+      
+      # Send & Receive
+      send(xml.root.to_xml(:indent => 0))
+      parse_message_value(Nokogiri::XML(receive()).root)
+    end
+
+    # Invokes a method on an object in the Flash virtual machine
+    def send_invoke_method(proxy_id, method_name, args, throwable)
+      xml = Nokogiri::XML("<invoke object=\"#{proxy_id}\" method=\"#{method_name}\" throwable=\"#{throwable}\"><args/></invoke>")
+      
+      # Loop over and add arguments to call
+      args_node = xml.at_xpath('invoke/args')
+      args.each do |arg|
+        arg_node = Nokogiri::XML::Node.new('arg', xml)
+        format_message_value(arg_node, arg)
+        args_node.add_child(arg_node)
+      end
+      
+      # Send and receive
+      send(xml.root.to_xml(:indent => 0))
+      parse_message_value(Nokogiri::XML(receive()).root)
+    end
+    
+    # Invokes a package level function in the Flash virtual machine
+    def send_invoke_function(function_name, args, throwable)
+      xml = Nokogiri::XML("<invoke-function name=\"#{function_name}\" throwable=\"#{throwable}\"><args/></invoke>")
+
+      # Loop over and add arguments to call
+      args_node = xml.at_xpath('invoke-function/args')
+      args.each do |arg|
+        arg_node = Nokogiri::XML::Node.new('arg', xml)
+        format_message_value(arg_node, arg)
+        args_node.add_child(arg_node)
+      end
+
+      # Send and receive
+      send(xml.root.to_xml(:indent => 0))
+      parse_message_value(Nokogiri::XML(receive()).root)
+    end
   end
 end

data/lib/melomel/error.rb

@@ -0,0 +1,43 @@
+# This class is used for all errors returned from the Flash virtual machine.
+module Melomel
+  class Error < StandardError
+    ############################################################################
+    #
+    # Constructor
+    #
+    ############################################################################
+
+    def initialize(object, error_id, message, name, stack_trace)
+      @object   = object
+      @error_id = error_id
+      @message  = message
+      @name     = name
+      @stack_trace = stack_trace
+    end
+    
+
+    ############################################################################
+    #
+    # Public Properties
+    #
+    ############################################################################
+
+    # A proxied reference to the original Flash error object.
+    #
+    # Returns a Melomel::ObjectProxy.
+    attr_reader :object
+
+    # The error identifier of the Flash error.
+    attr_reader :error_id
+
+    # The Flash error message.
+    attr_reader :message
+
+    # The name of the Flash error.
+    attr_reader :name
+
+    # The Flash stack trace. This is only available when using the Flash debug
+    # player or the AIR Debug Launcher (ADL).
+    attr_reader :stack_trace
+  end
+end

data/lib/melomel/object_proxy.rb

@@ -22,16 +22,29 @@ module Melomel
       @bridge.get_property(@proxy_id, name)
     end
     
+    def get_property!(name)
+      @bridge.get_property!(@proxy_id, name)
+    end
+    
     # Sets the value of a property for the proxied object.
     def set_property(name, value)
       @bridge.set_property(@proxy_id, name, value)
     end
+
+    # Sets the value of a property for the proxied object.
+    def set_property!(name, value)
+      @bridge.set_property!(@proxy_id, name, value)
+    end
     
     # Invokes a method on the proxied object. Arguments passed into the method
     # are passed through to the invoked method
     def invoke_method(method_name, *args)
       @bridge.invoke_method(@proxy_id, method_name, *args)
     end
+
+    def invoke_method!(method_name, *args)
+      @bridge.invoke_method!(@proxy_id, method_name, *args)
+    end
     
     alias :invoke :invoke_method
     
@@ -45,10 +58,18 @@ module Melomel
         return set_property(method_name.chop, *args)
       # Methods with arguments are methods
       elsif args.length > 0
-        return invoke_method(method_name, *args)
+        if last_char == '!'
+          return invoke_method!(method_name.chop, *args)
+        else
+          return invoke_method(method_name, *args)
+        end
       # Methods with no arguments are aliased to get_property
       else
-        return get_property(method_name)
+        if last_char == '!'
+          return get_property!(method_name.chop)
+        else
+          return get_property(method_name)
+        end
       end
     end
   end

data/lib/melomel/version.rb

@@ -1,3 +1,3 @@
 module Melomel
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/melomel.rb

@@ -1,4 +1,7 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.index(File.dirname(__FILE__))
+
 require 'melomel/bridge'
+require 'melomel/error'
 require 'melomel/object_proxy'
 require 'melomel/ui'
 require 'melomel/version'

data/test/sandbox.rb

@@ -0,0 +1,14 @@
+require File.join(File.dirname(File.expand_path(__FILE__)), *%w[helper])
+
+class SandboxTestCase < RunnerTestCase
+  def setup
+    start_runner
+    Melomel.connect()
+  end
+
+  def teardown
+    stop_runner
+  end
+
+  # Add tests here.
+end

data/test/test_integration.rb

@@ -20,6 +20,25 @@ class IntegrationTestCase < RunnerTestCase
     assert_equal 'bar', runner.foo
   end
 
+  def test_should_get_missing_property_as_nil
+    app = Melomel.get_class('mx.core.FlexGlobals').topLevelApplication
+    assert_nil app.no_such_property
+  end
+
+  def test_should_throw_error_when_getting_missing_instance_property!
+    app = Melomel.get_class('mx.core.FlexGlobals').topLevelApplication
+    assert_raises Melomel::Error do
+      app.no_such_property!
+    end
+  end
+
+  def test_should_throw_error_when_getting_missing_static_property!
+    runner = Melomel.get_class('MelomelRunner')
+    assert_raises Melomel::Error do
+      runner.no_such_property!
+    end
+  end
+
   # Tests the ability for a get_property to call a no-arg method if unavailable.
   def test_should_get_property_passthrough
     app = Melomel.get_class('mx.core.FlexGlobals').topLevelApplication
@@ -30,7 +49,7 @@ class IntegrationTestCase < RunnerTestCase
     runner = Melomel.get_class('MelomelRunner')
     runner.name = 'Susy'
     assert_equal 'Susy', runner.name
-    runner.name = 'John' # TODO: Do not make other tests dependent on this
+    runner.name = 'John'
   end
 
   def test_should_invoke_method

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: melomel
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 3
-  - 1
-  version: 0.3.1
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Ben Johnson
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-27 00:00:00 -06:00
+date: 2010-09-29 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -79,6 +79,7 @@ files:
 - lib/melomel/bridge/messaging.rb
 - lib/melomel/bridge/ui.rb
 - lib/melomel/bridge.rb
+- lib/melomel/error.rb
 - lib/melomel/object_proxy.rb
 - lib/melomel/ui.rb
 - lib/melomel/version.rb
@@ -86,6 +87,7 @@ files:
 - README.md
 - CHANGELOG.md
 - test/helper.rb
+- test/sandbox.rb
 - test/test_bridge.rb
 - test/test_integration.rb
 - test/test_messaging.rb
@@ -127,6 +129,7 @@ specification_version: 3
 summary: A Ruby interface to Melomel
 test_files: 
 - test/helper.rb
+- test/sandbox.rb
 - test/test_bridge.rb
 - test/test_integration.rb
 - test/test_messaging.rb