rb-scpt 1.0.1 → 1.0.2

data/src/lib/aem.rb

@@ -12,242 +12,242 @@ require "_aem/mactypes"
 
 module AEM
 
-	# Mid-level wrapper for building and sending Apple events to local and remote applications.
-	
-	require "_aem/codecs"
-	require "_aem/aemreference"
-	require "_aem/typewrappers"
-	require "_aem/connect"
-	require "_aem/send"
-	
-	#######
-	# Constants
-	
-	Codecs = Codecs
-	DefaultCodecs = DefaultCodecs
-	MacOSError = AE::MacOSError
-	CantLaunchApplicationError = Connect::CantLaunchApplicationError
-	
-	
-	AEDesc = AE::AEDesc
-	
-	AETypeBase = TypeWrappers::AETypeBase
-	AEType = TypeWrappers::AEType
-	AEEnum = TypeWrappers::AEEnum
-	AEProp = TypeWrappers::AEProp
-	AEKey = TypeWrappers::AEKey
-	
-	EventError = Send::EventError	
-	CommandError = Send::EventError # deprecated class name; kept for backwards compatibility
-	
-	#######
-	# Reference roots
-	
-	def AEM.app
-		return AEMReference::App
-	end
-	
-	def AEM.con
-		return AEMReference::Con
-	end
-	
-	def AEM.its
-		return AEMReference::Its
-	end
-	
-	def AEM.custom_root(value)
-		return AEMReference::CustomRoot.new(value)
-	end
-	
-	#######
-	# Application class
-	
-	class Application < AEMReference::Query
-		# Identifies an application and provides an #event method for constructing Apple events targetted at it.
-	
-		require "weakref"
-		
-		private_class_method :new
-		attr_reader :hash, :identity, :address_desc
-		
-		#######
-		# Workaround for lack of proper destructors in Ruby; see #initialize method.
-		
-		@@_app_number_count = 0
-		@@_transaction_ids_by_app_no = {}
-
-		#######
-	
-		Event = Send::Event # Application subclasses can override this class constant (usually with a subclass of Send::Event) to modify how Apple events are created and/or sent.
-		
-		#######
-		
-		def initialize(path, address_desc, identity)
-			# called by constructor method
-			# path is used by #reconnect
-			# address_desc is an AEAddressDesc identifying the target application
-			# identity is used by #inspect, #hash, #==
-			@_transaction = KAE::KAnyTransactionID
-			@_path = path
-			@address_desc = address_desc
-			@identity = identity
-			@hash = identity.hash
-			# workaround for lack of proper destructors; if a transaction is still open when Application instance is garbage collected, the following finalizer will automatically close it. Note: object IDs were different for some reason, so class maintains its own unique ids.
-			@app_number = app_number = (@@_app_number_count += 1)
-			@@_transaction_ids_by_app_no[app_number] = @_transaction
-			ObjectSpace.define_finalizer(WeakRef.new(self), proc do
-				transaction_id = @@_transaction_ids_by_app_no.delete(app_number)
-				if transaction_id != KAE::KAnyTransactionID
-					self.class::Event.new(@address_desc, 'miscendt', {}, {}, transaction_id).send(60, KAE::KAENoReply)
-				end
-			end)
-		end
-	
-		#######
-		# utility class methods; placed here for convenience
-		
-		def Application.launch(path)
-			# Launches a local application without sending it the usual 'run' event (aevtoapp).
-			Connect.launch_app_with_launch_event(path)
-		end
-		
-		def Application.process_exists_for_path?(path)
-			# Does a local process launched from the specified application file exist?
-			# Note: if path is invalid, an AE::MacOSError is raised.
-			return Connect.process_exists_for_path?(path)
-		end
-	
-		def Application.process_exists_for_pid?(pid)
-			# Is there a local application process with the given unix process id?
-			return Connect.process_exists_for_pid?(pid)
-		end
-		
-		def Application.process_exists_for_url?(url)
-			# Does an application process specified by the given eppc:// URL exist?
-			# Returns false if process doesn't exist or if access to it isn't allowed.
-			# (Implementation note: this method sends an Apple event to the specified process and checks for errors.)
-			return Connect.process_exists_for_url?(url)
-		end
-		
-		def Application.process_exists_for_desc?(desc)
-			# Does an application process specified by the given AEAddressDesc exist?
-			# Returns false if process doesn't exist or if access to it isn't allowed.
-			# (Implementation note: this method sends an Apple event to the specified process and checks for errors.)
-			return Connect.process_exists_for_desc?(desc)
-		end
-		
-		#######
-		# constructors
-		
-		def Application.by_path(path)
-			# path : string  -- full path to local application
-			#
-			# Note: application will be launched if not already running.
-			return new(path, Connect.local_app(path), [:path, path])
-		end
-		
-		def Application.by_url(url)
-			# url : string -- eppc URL for remote process
-			return new(nil, Connect.remote_app(url), [:url, url])
-		end
-		
-		def Application.by_pid(pid)
-			# pid : integer -- Unix process id
-			return new(nil, Connect.local_app_by_pid(pid), [:pid, pid])
-		end
-		
-		def Application.by_desc(desc)
-			# desc : AEDesc -- an AEAddressDesc
-			return new(nil, desc, [:desc, desc.type, desc.data])
-		end
-		
-		def Application.current
-			return new(nil, Connect::CurrentApp, [:current])
-		end
-		
-		#######
-		# methods
-		
-		def inspect
-			if @identity[0] == :current
-				return "#{self.class}.current"
-			else
-				con_name = {:path => 'by_path', :url => 'by_url', :pid => 'by_pid', :desc => 'by_desc'}[@identity[0]]
-				return "#{self.class}.#{con_name}(#{@identity[1].inspect})"
-			end
-		end
-		
-		alias_method :to_s, :inspect
-		
-		def ==(val)
-			return (self.class == val.class and @identity == val.identity)
-		end
-		
-		alias_method :eql?, :== 
-		
-		# (hash method is provided by attr_reader :hash)
-		
-		def AEM_comparable
-			return ['AEMApplication', @identity]
-		end
-		
-		def AEM_pack_self(codecs)
-			return @address_desc
-		end
-		
-		def reconnect
-			# If application has quit since this Application object was created, its AEAddressDesc
-			# is no longer valid so this Application object will not work even when application is restarted.
-			# #reconnect will update this Application object's AEAddressDesc so it's valid again.
-			#
-			# Note that this only works for Application objects created via the by_path constructor. 
-			# Also note that any Event objects created prior to calling #reconnect will still be invalid.
-			if @_path
-				@address_desc = Connect.local_app(@_path)
-			end
-			return
-		end
-		
-		def event(event, params={}, atts={}, return_id=KAE::KAutoGenerateReturnID, codecs=DefaultCodecs)
-			# Construct an Apple event targetted at this application.
-			#	event  : string -- 8-letter code indicating event's class, e.g. 'coregetd'
-			#	params : hash -- a dict of form {AE_code:anything,...} containing zero or more event parameters (message arguments)
-			#	atts : hash -- a dict of form {AE_code:anything,...} containing zero or more event attributes (event info)
-			#	return_id : integer  -- reply event's ID
-			#	codecs : Codecs -- codecs object to use when packing/unpacking this event
-			return self.class::Event.new(@address_desc, event, params, atts, @_transaction, return_id, codecs)
-		end
-		
-		def begin_transaction(session=nil)
-			# Begin a new transaction.
-			if @_transaction != KAE::KAnyTransactionID
-				raise RuntimeError, "Transaction is already active."
-			end
-			@_transaction = self.class::Event.new(@address_desc, 'miscbegi', session != nil ? {'----' => session} : {}).send
-			@@_transaction_ids_by_app_no[@app_number] = @_transaction
-			return
-		end
-		
-		def abort_transaction
-			# Abort the current transaction.
-			if @_transaction == KAE::KAnyTransactionID
-				raise RuntimeError, "No transaction is active."
-			end
-			self.class::Event.new(@address_desc, 'miscttrm', {}, {}, @_transaction).send
-			@_transaction = KAE::KAnyTransactionID
-			@@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
-			return
-		end
-		
-		def end_transaction
-			# End the current transaction.
-			if @_transaction == KAE::KAnyTransactionID
-				raise RuntimeError, "No transaction is active."
-			end
-			self.class::Event.new(@address_desc, 'miscendt', {}, {}, @_transaction).send
-			@_transaction = KAE::KAnyTransactionID
-			@@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
-			return
-		end
-	end
+  # Mid-level wrapper for building and sending Apple events to local and remote applications.
+
+  require "_aem/codecs"
+  require "_aem/aemreference"
+  require "_aem/typewrappers"
+  require "_aem/connect"
+  require "_aem/send"
+
+  #######
+  # Constants
+
+  Codecs = Codecs
+  DefaultCodecs = DefaultCodecs
+  MacOSError = AE::MacOSError
+  CantLaunchApplicationError = Connect::CantLaunchApplicationError
+
+
+  AEDesc = AE::AEDesc
+
+  AETypeBase = TypeWrappers::AETypeBase
+  AEType = TypeWrappers::AEType
+  AEEnum = TypeWrappers::AEEnum
+  AEProp = TypeWrappers::AEProp
+  AEKey = TypeWrappers::AEKey
+
+  EventError = Send::EventError
+  CommandError = Send::EventError # deprecated class name; kept for backwards compatibility
+
+  #######
+  # Reference roots
+
+  def AEM.app
+    return AEMReference::App
+  end
+
+  def AEM.con
+    return AEMReference::Con
+  end
+
+  def AEM.its
+    return AEMReference::Its
+  end
+
+  def AEM.custom_root(value)
+    return AEMReference::CustomRoot.new(value)
+  end
+
+  #######
+  # Application class
+
+  class Application < AEMReference::Query
+    # Identifies an application and provides an #event method for constructing Apple events targetted at it.
+
+    require "weakref"
+
+    private_class_method :new
+    attr_reader :hash, :identity, :address_desc
+
+    #######
+    # Workaround for lack of proper destructors in Ruby; see #initialize method.
+
+    @@_app_number_count = 0
+    @@_transaction_ids_by_app_no = {}
+
+    #######
+
+    Event = Send::Event # Application subclasses can override this class constant (usually with a subclass of Send::Event) to modify how Apple events are created and/or sent.
+
+    #######
+
+    def initialize(path, address_desc, identity)
+      # called by constructor method
+      # path is used by #reconnect
+      # address_desc is an AEAddressDesc identifying the target application
+      # identity is used by #inspect, #hash, #==
+      @_transaction = KAE::KAnyTransactionID
+      @_path = path
+      @address_desc = address_desc
+      @identity = identity
+      @hash = identity.hash
+      # workaround for lack of proper destructors; if a transaction is still open when Application instance is garbage collected, the following finalizer will automatically close it. Note: object IDs were different for some reason, so class maintains its own unique ids.
+      @app_number = app_number = (@@_app_number_count += 1)
+      @@_transaction_ids_by_app_no[app_number] = @_transaction
+      ObjectSpace.define_finalizer(WeakRef.new(self), proc do
+                                     transaction_id = @@_transaction_ids_by_app_no.delete(app_number)
+                                     if transaction_id != KAE::KAnyTransactionID
+                                       self.class::Event.new(@address_desc, 'miscendt', {}, {}, transaction_id).send(60, KAE::KAENoReply)
+                                     end
+                                   end)
+    end
+
+    #######
+    # utility class methods; placed here for convenience
+
+    def Application.launch(path)
+      # Launches a local application without sending it the usual 'run' event (aevtoapp).
+      Connect.launch_app_with_launch_event(path)
+    end
+
+    def Application.process_exists_for_path?(path)
+      # Does a local process launched from the specified application file exist?
+      # Note: if path is invalid, an AE::MacOSError is raised.
+      return Connect.process_exists_for_path?(path)
+    end
+
+    def Application.process_exists_for_pid?(pid)
+      # Is there a local application process with the given unix process id?
+      return Connect.process_exists_for_pid?(pid)
+    end
+
+    def Application.process_exists_for_url?(url)
+      # Does an application process specified by the given eppc:// URL exist?
+      # Returns false if process doesn't exist or if access to it isn't allowed.
+      # (Implementation note: this method sends an Apple event to the specified process and checks for errors.)
+      return Connect.process_exists_for_url?(url)
+    end
+
+    def Application.process_exists_for_desc?(desc)
+      # Does an application process specified by the given AEAddressDesc exist?
+      # Returns false if process doesn't exist or if access to it isn't allowed.
+      # (Implementation note: this method sends an Apple event to the specified process and checks for errors.)
+      return Connect.process_exists_for_desc?(desc)
+    end
+
+    #######
+    # constructors
+
+    def Application.by_path(path)
+      # path : string  -- full path to local application
+      #
+      # Note: application will be launched if not already running.
+      return new(path, Connect.local_app(path), [:path, path])
+    end
+
+    def Application.by_url(url)
+      # url : string -- eppc URL for remote process
+      return new(nil, Connect.remote_app(url), [:url, url])
+    end
+
+    def Application.by_pid(pid)
+      # pid : integer -- Unix process id
+      return new(nil, Connect.local_app_by_pid(pid), [:pid, pid])
+    end
+
+    def Application.by_desc(desc)
+      # desc : AEDesc -- an AEAddressDesc
+      return new(nil, desc, [:desc, desc.type, desc.data])
+    end
+
+    def Application.current
+      return new(nil, Connect::CurrentApp, [:current])
+    end
+
+    #######
+    # methods
+
+    def inspect
+      if @identity[0] == :current
+        return "#{self.class}.current"
+      else
+        con_name = {:path => 'by_path', :url => 'by_url', :pid => 'by_pid', :desc => 'by_desc'}[@identity[0]]
+        return "#{self.class}.#{con_name}(#{@identity[1].inspect})"
+      end
+    end
+
+    alias_method :to_s, :inspect
+
+    def ==(val)
+      return (self.class == val.class and @identity == val.identity)
+    end
+
+    alias_method :eql?, :==
+
+    # (hash method is provided by attr_reader :hash)
+
+    def AEM_comparable
+      return ['AEMApplication', @identity]
+    end
+
+    def AEM_pack_self(codecs)
+      return @address_desc
+    end
+
+    def reconnect
+      # If application has quit since this Application object was created, its AEAddressDesc
+      # is no longer valid so this Application object will not work even when application is restarted.
+      # #reconnect will update this Application object's AEAddressDesc so it's valid again.
+      #
+      # Note that this only works for Application objects created via the by_path constructor.
+      # Also note that any Event objects created prior to calling #reconnect will still be invalid.
+      if @_path
+        @address_desc = Connect.local_app(@_path)
+      end
+      return
+    end
+
+    def event(event, params={}, atts={}, return_id=KAE::KAutoGenerateReturnID, codecs=DefaultCodecs)
+      # Construct an Apple event targetted at this application.
+      #	event  : string -- 8-letter code indicating event's class, e.g. 'coregetd'
+      #	params : hash -- a dict of form {AE_code:anything,...} containing zero or more event parameters (message arguments)
+      #	atts : hash -- a dict of form {AE_code:anything,...} containing zero or more event attributes (event info)
+      #	return_id : integer  -- reply event's ID
+      #	codecs : Codecs -- codecs object to use when packing/unpacking this event
+      return self.class::Event.new(@address_desc, event, params, atts, @_transaction, return_id, codecs)
+    end
+
+    def begin_transaction(session=nil)
+      # Begin a new transaction.
+      if @_transaction != KAE::KAnyTransactionID
+        raise RuntimeError, "Transaction is already active."
+      end
+      @_transaction = self.class::Event.new(@address_desc, 'miscbegi', session != nil ? {'----' => session} : {}).send
+      @@_transaction_ids_by_app_no[@app_number] = @_transaction
+      return
+    end
+
+    def abort_transaction
+      # Abort the current transaction.
+      if @_transaction == KAE::KAnyTransactionID
+        raise RuntimeError, "No transaction is active."
+      end
+      self.class::Event.new(@address_desc, 'miscttrm', {}, {}, @_transaction).send
+      @_transaction = KAE::KAnyTransactionID
+      @@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
+      return
+    end
+
+    def end_transaction
+      # End the current transaction.
+      if @_transaction == KAE::KAnyTransactionID
+        raise RuntimeError, "No transaction is active."
+      end
+      self.class::Event.new(@address_desc, 'miscendt', {}, {}, @_transaction).send
+      @_transaction = KAE::KAnyTransactionID
+      @@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
+      return
+    end
+  end
 end