rb-appscript 0.5.1 → 0.5.2

data/rb-appscript.gemspec

@@ -2,9 +2,9 @@ require "rubygems"
 
 spec = Gem::Specification.new do |s|
 	s.name = "rb-appscript"
-	s.version = "0.5.1"
+	s.version = "0.5.2"
 	s.author = "HAS"
-	s.homepage = "http://rb-appscript.rubyforge.org/"
+	s.homepage = "http://appscript.sourceforge.net/rb-appscript"
 	s.rubyforge_project="rb-appscript"
 	s.summary="Ruby appscript (rb-appscript) is a high-level, user-friendly Apple event bridge that allows you to control scriptable Mac OS X applications using ordinary Ruby scripts."
 	s.files = Dir["**/*"].delete_if { |name| ["MakeFile", "ae.bundle", "mkmf.log", "rbae.o", "SendThreadSafe.o", "src/osx_ruby.h", "src/osx_intern.h"].include?(name) }

data/sample/TextEdit_demo.rb

@@ -111,7 +111,7 @@ p textedit.documents[1].paragraphs[its.ne("\n")].get
 
 # tell application "TextEdit" to get text of every document 
 #         whose text begins with "H"
-p textedit.documents[its.text.starts_with('H')].text.get
+p textedit.documents[its.text.begins_with('H')].text.get
 
 
 

data/src/lib/_aem/aemreference.rb

@@ -3,7 +3,7 @@
 #
 # aemreference -- an object-oriented API for constructing object specifier AEDescs
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 ######################################################################

data/src/lib/_aem/codecs.rb

@@ -3,7 +3,7 @@
 #
 # codecs -- convert native Ruby objects to AEDescs, and vice-versa
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 require "ae"
@@ -123,6 +123,12 @@ end
 
 ######################################################################
 
+module DisableObjectSpecifierCaching
+	def unpack_object_specifier(desc)
+		return fully_unpack_object_specifier(desc)
+	end
+end
+
 
 class Codecs
 	# Provides pack and unpack methods for converting data between Ruby and AE types.
@@ -135,13 +141,38 @@ class Codecs
 
 	def initialize
 		@unit_type_codecs = UnitTypeCodecs.new
+		@pack_text_as_type = KAE::TypeUnicodeText
 	end
 	
+	######################################################################
+	# Compatibility options
+	
 	def add_unit_types(type_defs)
 		# register custom unit type definitions with this Codecs instance
 		# e.g. Adobe apps define additional unit types (ciceros, pixels, etc.)
 		@unit_type_codecs.add_types(type_defs)
 	end
+	
+	def dont_cache_unpacked_specifiers
+		# When unpacking object specifiers, unlike AppleScript, appscript caches
+		# the original AEDesc for efficiency, allowing the resulting reference to
+		# be re-packed much more quickly. Occasionally this causes compatibility
+		# problems with applications that returned subtly malformed specifiers.
+		# To force a Codecs object to fully unpack and repack object specifiers,
+		# call its dont_cache_unpacked_specifiers method.
+		extend(DisableObjectSpecifierCaching)
+	end
+
+	def pack_strings_as_type(code)
+		# Some older (pre-OS X) applications may require text to be passed as 
+		# typeChar or typeIntlText rather than the usual typeUnicodeText. To force
+		# an AEM::Codecs object to pack strings as one of these older types, call 
+		# its pack_strings_as_type method, specifying the type you want used instead.
+		if not(code.is_a?(String) and code.length == 4)
+			raise ArgumentError, "Code must be a four-character string: #{code.inspect}"
+		end
+		@pack_text_as_type = code
+	end
 
 	######################################################################
 	# Subclasses could override these to provide their own reference roots if needed
@@ -193,10 +224,10 @@ class Codecs
 					# and existing applications don't choke, this code can be similarly upgraded.
 					# Note: while the BOM is optional in typeUnicodeText, it's not included by AS
 					# and some apps, e.g. iTunes 7, will handle it incorrectly, so it's omitted here.)
-					AE::AEDesc.new(KAE::TypeUTF8Text, val).coerce(KAE::TypeUnicodeText)
+					AE::AEDesc.new(KAE::TypeUTF8Text, val).coerce(@pack_text_as_type)
 				rescue AE::MacOSError => e
 					if e.to_i == -1700 # couldn't coerce to TypeUnicodeText
-						raise TypeError, "Not valid UTF8 data: #{val.inspect}"
+						raise TypeError, "Not valid UTF8 data or couldn't coerce to type %{@pack_text_as_type}: #{val.inspect}"
 					else
 						raise
 					end
@@ -362,11 +393,14 @@ class Codecs
 			when KAE::TypeRGBColor then desc.data.unpack('SSS')
 				
 			when KAE::TypeVersion
-				vers, lo = desc.data.unpack('CC')
-				subvers, patch = lo.divmod(16)
-				"#{vers}.#{subvers}.#{patch}"
-				
-			when KAE::TypeBoolean then desc.data != "\000"
+				begin
+					unpack(desc.coerce(KAE::TypeUnicodeText)) # supported in 10.4+
+				rescue
+					vers, lo = desc.data.unpack('CC')
+					subvers, patch = lo.divmod(16)
+					"#{vers}.#{subvers}.#{patch}"
+				end	
+			when KAE::TypeBoolean then desc.data[0,1] != "\000"
 			
 			when KAE::TypeUInt16 then desc.data.unpack('S')[0] # 10.5+
 			when KAE::TypeUInt64 then desc.data.unpack('Q')[0] # 10.5+

data/src/lib/_aem/connect.rb

@@ -3,7 +3,7 @@
 #
 # connect -- launch applications and create AEAddressDescs
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 module Connect
@@ -124,6 +124,7 @@ module Connect
 	def Connect.process_exists_for_url?(url)
 		# Does an application process specified by the given eppc:// URL exist?
 		# Note: this will send a 'launch' Apple event to the target application.
+		raise ArgumentError, "Invalid url: #{url}" if not url.include?(':') # workaround: process will crash if no colon in URL (OS bug)
 		return process_exists_for_desc?(AE::AEDesc.new(KAE::TypeApplicationURL, url))
 	end
 	
@@ -177,6 +178,7 @@ module Connect
 		# Make an AEAddressDesc identifying a running application on another machine.
 		#	url : string -- URL for remote application, e.g. 'eppc://user:password@0.0.0.1/TextEdit'
 		#	Result : AEAddressDesc
+		raise ArgumentError, "Invalid url: #{url}" if not url.include?(':') # workaround: process will crash if no colon in URL (OS bug)
 		return AE::AEDesc.new(KAE::TypeApplicationURL, url)
 	end
 end

data/src/lib/_aem/findapp.rb

@@ -3,7 +3,7 @@
 #
 # findapp -- locate an application by name, bundle ID or creator code
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 module FindApp

data/src/lib/_aem/mactypes.rb

@@ -3,7 +3,7 @@
 #
 # mactypes -- Ruby classes representing Alias, FileURL and unit type AEDescs
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 module MacTypes

data/src/lib/_aem/send.rb

@@ -3,7 +3,7 @@
 #
 # send -- Event class represents a packed AppleEvent that's ready to send via AESendMessage
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 module Send
@@ -15,124 +15,6 @@ module Send
 	require "kae"
 	require "_aem/codecs"
 	
-	# Most applications don't provide error description strings, so aem defines default descriptions for the common ones.
-	
-	# Following default error descriptions are cribbed from the AppleScript Language Guide/MacErrors.h:
-	
-	MacOSErrorDescriptions = {
-			# OS errors
-			-34 => "Disk is full.",
-			-35 => "Disk wasn't found.",
-			-37 => "Bad name for file.",
-			-38 => "File wasn't open.",
-			-39 => "End of file error.",
-			-42 => "Too many files open.",
-			-43 => "File wasn't found.",
-			-44 => "Disk is write protected.",
-			-45 => "File is locked.",
-			-46 => "Disk is locked.",
-			-47 => "File is busy.",
-			-48 => "Duplicate file name.",
-			-49 => "File is already open.",
-			-50 => "Parameter error.",
-			-51 => "File reference number error.",
-			-61 => "File not open with write permission.",
-			-108 => "Out of memory.",
-			-120 => "Folder wasn't found.",
-			-124 => "Disk is disconnected.",
-			-128 => "User canceled.",
-			-192 => "A resource wasn't found.",
-			-600 => "Application isn't running.",
-			-601 => "Not enough room to launch application with special requirements.",
-			-602 => "Application is not 32-bit clean.",
-			-605 => "More memory is needed than is specified in the size resource.",
-			-606 => "Application is background-only.",
-			-607 => "Buffer is too small.",
-			-608 => "No outstanding high-level event.",
-			-609 => "Connection is invalid.",
-			-904 => "Not enough system memory to connect to remote application.",
-			-905 => "Remote access is not allowed.",
-			-906 => "Application isn't running or program linking isn't enabled.",
-			-915 => "Can't find remote machine.",
-			-30720 => "Invalid date and time.",
-			# AE errors
-			-1700 => "Can't make some data into the expected type.",
-			-1701 => "Some parameter is missing for command.",
-			-1702 => "Some data could not be read.",
-			-1703 => "Some data was the wrong type.",
-			-1704 => "Some parameter was invalid.",
-			-1705 => "Operation involving a list item failed.",
-			-1706 => "Need a newer version of the Apple Event Manager.",
-			-1707 => "Event isn't an Apple event.",
-			-1708 => "Application could not handle this command.",
-			-1709 => "AEResetTimer was passed an invalid reply.",
-			-1710 => "Invalid sending mode was passed.",
-			-1711 => "User canceled out of wait loop for reply or receipt.",
-			-1712 => "Apple event timed out.",
-			-1713 => "No user interaction allowed.",
-			-1714 => "Wrong keyword for a special function.",
-			-1715 => "Some parameter wasn't understood.",
-			-1716 => "Unknown Apple event address type.",
-			-1717 => "The handler is not defined.",
-			-1718 => "Reply has not yet arrived.",
-			-1719 => "Can't get reference. Invalid index.",
-			-1720 => "Invalid range.",
-			-1721 => "Wrong number of parameters for command.",
-			-1723 => "Can't get reference. Access not allowed.",
-			-1725 => "Illegal logical operator called.",
-			-1726 => "Illegal comparison or logical.",
-			-1727 => "Expected a reference.",
-			-1728 => "Can't get reference.",
-			-1729 => "Object counting procedure returned a negative count.",
-			-1730 => "Container specified was an empty list.",
-			-1731 => "Unknown object type.",
-			-1739 => "Attempting to perform an invalid operation on a null descriptor.",
-			# Application scripting errors
-			-10000 => "Apple event handler failed.",
-			-10001 => "Type error.",
-			-10002 => "Invalid key form.",
-			-10003 => "Can't set reference to given value. Access not allowed.",
-			-10004 => "A privilege violation occurred.",
-			-10005 => "The read operation wasn't allowed.",
-			-10006 => "Can't set reference to given value.",
-			-10007 => "The index of the event is too large to be valid.",
-			-10008 => "The specified object is a property, not an element.",
-			-10009 => "Can't supply the requested descriptor type for the data.",
-			-10010 => "The Apple event handler can't handle objects of this class.",
-			-10011 => "Couldn't handle this command because it wasn't part of the current transaction.",
-			-10012 => "The transaction to which this command belonged isn't a valid transaction.",
-			-10013 => "There is no user selection.",
-			-10014 => "Handler only handles single objects.",
-			-10015 => "Can't undo the previous Apple event or user action.",
-			-10023 => "Enumerated value is not allowed for this property.",
-			-10024 => "Class can't be an element of container.",
-			-10025 => "Illegal combination of properties settings.",
-	}
-	
-	# Following Cocoa Scripting error descriptions taken from:
-	# http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSScriptCommand.html
-	# http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSScriptObjectSpecifier.html
-
-	CocoaErrorDescriptions = [
-			["NSReceiverEvaluationScriptError", "The object or objects specified by the direct parameter to a command could not be found."],
-			["NSKeySpecifierEvaluationScriptError", "The object or objects specified by a key (for commands that support key specifiers) could not be found."],
-			["NSArgumentEvaluationScriptError", "The object specified by an argument could not be found."],
-			["NSReceiversCantHandleCommandScriptError", "The receivers don't support the command sent to them."],
-			["NSRequiredArgumentsMissingScriptError", "An argument (or more than one argument) is missing."],
-			["NSArgumentsWrongScriptError", "An argument (or more than one argument) is of the wrong type or is otherwise invalid."],
-			["NSUnknownKeyScriptError", "An unidentified error occurred; indicates an error in the scripting support of the application."],
-			["NSInternalScriptError", "An unidentified internal error occurred; indicates an error in the scripting support of the application."],
-			["NSOperationNotSupportedForKeyScriptError", "The implementation of a scripting command signaled an error."],
-			["NSCannotCreateScriptCommandError", "Could not create the script command; an invalid or unrecognized Apple event was received."],
-			["NSNoSpecifierError", "No error encountered."],
-			["NSNoTopLevelContainersSpecifierError", "Someone called evaluate with nil."],
-			["NSContainerSpecifierError", "Error evaluating container specifier."],
-			["NSUnknownKeySpecifierError", "Receivers do not understand the key."],
-			["NSInvalidIndexSpecifierError", "Index out of bounds."],
-			["NSInternalSpecifierError", "Other internal error."],
-			["NSOperationNotSupportedForKeySpecifierError", "Attempt made to perform an unsupported operation on some key."]
-	]
-	
 	class Event
 		# Represents an Apple event.
 		
@@ -190,8 +72,8 @@ module Send
 			begin
 				reply_event = _send_apple_event(flags, timeout)
 			rescue AE::MacOSError => err # The Apple Event Manager raised an error.
-				if not (@_event_code == 'aevtquit' and err.to_i == -609) # Ignore invalid connection errors (-609) when quitting
-					raise CommandError.new(err.to_i, nil, err)
+				if not(@_event_code == 'aevtquit' and err.to_i == -609) # Ignore invalid connection errors (-609) when quitting
+					raise CommandError.new(err.to_i)
 				end
 			else # Decode application's reply, if any. May be a return value, error number (and optional message), or nothing.
 				if reply_event.type != KAE::TypeNull
@@ -203,12 +85,8 @@ module Send
 					if event_result.has_key?(KAE::KeyErrorNumber) # The application raised an error.
 						# Error info is unpacked using default codecs for reliability.
 						e_num = DefaultCodecs.unpack(event_result[KAE::KeyErrorNumber])
-						if e_num != 0 # Note that some apps (e.g. Finder) may return error code 0 to indicate a successful operation, so ignore this.
-							e_msg = event_result[KAE::KeyErrorString]
-							if e_msg
-								e_msg = DefaultCodecs.unpack(e_msg)
-							end
-							raise CommandError.new(e_num, e_msg, reply_event)
+						if e_num != 0 # Some apps (e.g. Finder) may return error code 0 to indicate a successful operation, so ignore this.
+							raise CommandError.new(e_num, event_result)
 						end
 					end
 					if event_result.has_key?(KAE::KeyAEResult)
@@ -228,34 +106,176 @@ module Send
 		#
 		# Methods:
 		#	number : integer -- MacOS error number
-		#	message : string | nil -- application error message if any, or default error description if available, or nil
+		#	message : string -- application error message if any, or default error description if available
+		
+		# Most applications don't provide error description strings, so define default descriptions for the common ones.
+		# Following default error descriptions are cribbed from the AppleScript Language Guide/MacErrors.h:
 		
-		attr_reader :number, :message, :raw # raw method is provided for testing/debugging use only
+		MacOSErrorDescriptions = {
+				# OS errors
+				-34 => "Disk is full.",
+				-35 => "Disk wasn't found.",
+				-37 => "Bad name for file.",
+				-38 => "File wasn't open.",
+				-39 => "End of file error.",
+				-42 => "Too many files open.",
+				-43 => "File wasn't found.",
+				-44 => "Disk is write protected.",
+				-45 => "File is locked.",
+				-46 => "Disk is locked.",
+				-47 => "File is busy.",
+				-48 => "Duplicate file name.",
+				-49 => "File is already open.",
+				-50 => "Parameter error.",
+				-51 => "File reference number error.",
+				-61 => "File not open with write permission.",
+				-108 => "Out of memory.",
+				-120 => "Folder wasn't found.",
+				-124 => "Disk is disconnected.",
+				-128 => "User canceled.",
+				-192 => "A resource wasn't found.",
+				-600 => "Application isn't running.",
+				-601 => "Not enough room to launch application with special requirements.",
+				-602 => "Application is not 32-bit clean.",
+				-605 => "More memory is needed than is specified in the size resource.",
+				-606 => "Application is background-only.",
+				-607 => "Buffer is too small.",
+				-608 => "No outstanding high-level event.",
+				-609 => "Connection is invalid.",
+				-904 => "Not enough system memory to connect to remote application.",
+				-905 => "Remote access is not allowed.",
+				-906 => "Application isn't running or program linking isn't enabled.",
+				-915 => "Can't find remote machine.",
+				-30720 => "Invalid date and time.",
+				# AE errors
+				-1700 => "Can't make some data into the expected type.",
+				-1701 => "Some parameter is missing for command.",
+				-1702 => "Some data could not be read.",
+				-1703 => "Some data was the wrong type.",
+				-1704 => "Some parameter was invalid.",
+				-1705 => "Operation involving a list item failed.",
+				-1706 => "Need a newer version of the Apple Event Manager.",
+				-1707 => "Event isn't an Apple event.",
+				-1708 => "Application could not handle this command.",
+				-1709 => "AEResetTimer was passed an invalid reply.",
+				-1710 => "Invalid sending mode was passed.",
+				-1711 => "User canceled out of wait loop for reply or receipt.",
+				-1712 => "Apple event timed out.",
+				-1713 => "No user interaction allowed.",
+				-1714 => "Wrong keyword for a special function.",
+				-1715 => "Some parameter wasn't understood.",
+				-1716 => "Unknown Apple event address type.",
+				-1717 => "The handler is not defined.",
+				-1718 => "Reply has not yet arrived.",
+				-1719 => "Can't get reference. Invalid index.",
+				-1720 => "Invalid range.",
+				-1721 => "Wrong number of parameters for command.",
+				-1723 => "Can't get reference. Access not allowed.",
+				-1725 => "Illegal logical operator called.",
+				-1726 => "Illegal comparison or logical.",
+				-1727 => "Expected a reference.",
+				-1728 => "Can't get reference.",
+				-1729 => "Object counting procedure returned a negative count.",
+				-1730 => "Container specified was an empty list.",
+				-1731 => "Unknown object type.",
+				-1739 => "Attempting to perform an invalid operation on a null descriptor.",
+				# Application scripting errors
+				-10000 => "Apple event handler failed.",
+				-10001 => "Type error.",
+				-10002 => "Invalid key form.",
+				-10003 => "Can't set reference to given value. Access not allowed.",
+				-10004 => "A privilege violation occurred.",
+				-10005 => "The read operation wasn't allowed.",
+				-10006 => "Can't set reference to given value.",
+				-10007 => "The index of the event is too large to be valid.",
+				-10008 => "The specified object is a property, not an element.",
+				-10009 => "Can't supply the requested descriptor type for the data.",
+				-10010 => "The Apple event handler can't handle objects of this class.",
+				-10011 => "Couldn't handle this command because it wasn't part of the current transaction.",
+				-10012 => "The transaction to which this command belonged isn't a valid transaction.",
+				-10013 => "There is no user selection.",
+				-10014 => "Handler only handles single objects.",
+				-10015 => "Can't undo the previous Apple event or user action.",
+				-10023 => "Enumerated value is not allowed for this property.",
+				-10024 => "Class can't be an element of container.",
+				-10025 => "Illegal combination of properties settings.",
+		}
+		
+		# Following Cocoa Scripting error descriptions taken from:
+		# http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSScriptCommand.html
+		# http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/Classes/NSScriptObjectSpecifier.html
+	
+		CocoaErrorDescriptions = [
+				["NSReceiverEvaluationScriptError", "The object or objects specified by the direct parameter to a command could not be found."],
+				["NSKeySpecifierEvaluationScriptError", "The object or objects specified by a key (for commands that support key specifiers) could not be found."],
+				["NSArgumentEvaluationScriptError", "The object specified by an argument could not be found."],
+				["NSReceiversCantHandleCommandScriptError", "The receivers don't support the command sent to them."],
+				["NSRequiredArgumentsMissingScriptError", "An argument (or more than one argument) is missing."],
+				["NSArgumentsWrongScriptError", "An argument (or more than one argument) is of the wrong type or is otherwise invalid."],
+				["NSUnknownKeyScriptError", "An unidentified error occurred; indicates an error in the scripting support of the application."],
+				["NSInternalScriptError", "An unidentified internal error occurred; indicates an error in the scripting support of the application."],
+				["NSOperationNotSupportedForKeyScriptError", "The implementation of a scripting command signaled an error."],
+				["NSCannotCreateScriptCommandError", "Could not create the script command; an invalid or unrecognized Apple event was received."],
+				["NSNoSpecifierError", "No error encountered."],
+				["NSNoTopLevelContainersSpecifierError", "Someone called evaluate with nil."],
+				["NSContainerSpecifierError", "Error evaluating container specifier."],
+				["NSUnknownKeySpecifierError", "Receivers do not understand the key."],
+				["NSInvalidIndexSpecifierError", "Index out of bounds."],
+				["NSInternalSpecifierError", "Other internal error."],
+				["NSOperationNotSupportedForKeySpecifierError", "Attempt made to perform an unsupported operation on some key."]
+		]
+		
+		attr_reader :number, :raw
 		alias_method :to_i, :number
 		
-		def initialize(number, message, raw)
-			if message == nil
-				message = MacOSErrorDescriptions[number]
-			end
-			if number > 0
-				CocoaErrorDescriptions.each do |name, description|
-					if message[0, name.length] == name
-						message += " (#{description})"
-						break
+		def initialize(number, reply_params={})
+			@number = number
+			@message = nil
+			@raw = reply_params
+		end
+		
+		def message
+			if not @message
+				desc = @raw[KAE::KeyErrorString]
+				@message = DefaultCodecs.unpack(desc) if desc
+				if @message.is_a?(String) and @number > 0
+					# add clarification to default Cocoa Scripting error messages
+					CocoaErrorDescriptions.each do |name, description|
+						if @message[0, name.length] == name
+							@message += " (#{description})"
+							break
+						end
 					end
 				end
+				# if no message supplied or is a MacOSError, use default message if one is available
+				@message = MacOSErrorDescriptions.fetch(number, '') if @message == nil
 			end
-			@number = number
-			@message = message
-			@raw = raw
+			return @message
 		end
 		
 		def to_s
-			if message
+			if message != ''
 				return "CommandError\n\t\tOSERROR: #{number}\n\t\tMESSAGE: #{message}"
 			else
 				return "CommandError\n\t\tOSERROR: #{number}"
 			end
 		end
+		
+		# extended error info (some apps may return additional error info, though most don't)
+		
+		def offending_object
+			desc = @raw[KAE::KOSAErrorOffendingObject]
+			return desc ? DefaultCodecs.unpack(desc) : nil
+		end
+		
+		def expected_type
+			desc = @raw[KAE::KOSAErrorExpectedType]
+			return desc ? DefaultCodecs.unpack(desc) : nil
+		end
+		
+		def partial_result
+			desc = @raw[KAE::KOSAErrorPartialResult]
+			return desc ? DefaultCodecs.unpack(desc) : nil
+		end
 	end
 end