rb-appscript 0.2.0

data/src/lib/_aem/findapp.rb

@@ -0,0 +1,83 @@
+#!/usr/local/bin/ruby
+# Copyright (C) 2006 HAS. 
+# Released under MIT License.
+
+module FindApp
+	# Support module for obtaining the full path to a local application given its name, bundle id or creator type. If application isn't found, an ApplicationNotFoundError exception is raised.
+
+	require "ae"
+	
+	class ApplicationNotFoundError < RuntimeError
+	
+		attr_reader :creator_type, :bundle_id, :application_name
+		
+		def initialize(creator, id, name)
+			@creator_type, @bundle_id, @application_name  = creator, id, name 
+			super()
+		end
+	end
+	
+	#######
+	
+	def FindApp._find_app(creator, id, name)
+		begin
+			return AE.find_application(creator, id, name)
+		rescue AE::MacOSError => err
+			if err.to_i == -10814
+				ident = [creator, id, name].compact.to_s.inspect
+				raise ApplicationNotFoundError.new(creator, id, name), "Application #{ident} not found."
+			else
+				raise
+			end
+		end
+	end
+	
+	#######
+
+	def FindApp.by_name(name)		
+		# Find the application with the given name and return its full path. 
+		#
+		# Absolute paths are also accepted. An '.app' suffix is optional.
+		#
+		# Examples: 
+		#	FindApp.by_name('TextEdit')
+		#	FindApp.by_name('Finder.app')
+		#
+		if name[0, 1] != '/' # application name only, not its full path
+			begin
+				new_name = _find_app(nil, nil, name)
+			rescue ApplicationNotFoundError
+				if ('----' + name)[-4, 4].downcase == '.app'
+					raise ApplicationNotFoundError.new(nil, nil, name), "Application #{name.inspect} not found."
+				end
+				new_name = _find_app(nil, nil, name + '.app')
+			end
+			name = new_name
+		end
+		if not FileTest.exist?(name) and name[-4, 4].downcase != '.app' and not FileTest.exist?(name+ '.app')
+			name += '.app'
+		end
+		if not FileTest.exist?(name)
+			raise RuntimeError, name
+		end
+		return name
+	end
+	
+	def FindApp.by_id(id)
+		# Find the application with the given bundle id and return its full path.
+		#
+		# Examples:
+		#	FindApp.by_id('com.apple.textedit')
+		#
+		return _find_app(nil, id, nil)
+	end
+	
+	def FindApp.by_creator(creator)
+		# Find the application with the given creator type and return its full path.
+		#
+		# Examples:
+		#	FindApp.by_creator('ttxt')
+		#
+		return _find_app(creator, nil, nil)
+	end
+end

data/src/lib/_aem/mactypes.rb

@@ -0,0 +1,228 @@
+#!/usr/local/bin/ruby
+# Copyright (C) 2006 HAS. 
+# Released under MIT License.
+
+module MacTypes
+	# Defines wrapper classes for Mac OS datatypes that don't have a suitable Ruby equivalent.
+	#
+	# Note: all path strings are/must be valid UTF8.
+
+	require "ae"
+	require "kae"
+	
+	class FileBase
+	
+		URLPrefix = 'file://localhost'
+	
+		def FileBase._path_to_url(path)
+			return URLPrefix + path.gsub(/[^a-zA-Z0-9_.-\/]/) { |c| "%%%02x" % c[0] }
+		end
+	
+		def FileBase._url_to_path(url)
+			if url[0, URLPrefix.length] != URLPrefix
+				raise ArgumentError, "Not a file:// URL."
+			end
+			return url[URLPrefix.length, url.length].gsub(/%../) { |s| "%c" % s[1,2].hex }
+		end
+		
+		def FileBase._coerce(desc, type, path=nil)
+			begin
+				return desc.coerce(type)
+			rescue AE::MacOSError => e
+				if [-35, -43, -120, -1700].include?(e.to_i) # disk/file/folder not found, or coercion error
+					if path != nil
+						raise FileNotFoundError, "File #{path.inspect} not found."
+					else
+						raise FileNotFoundError, "File not found."
+					end
+				else
+					raise
+				end
+			end
+		end
+		
+		def ==(val)
+			return (self.equal?(val) or (
+					self.class == val.class and 
+					self.desc.type == val.desc.type and
+					self.desc.data == self.desc.data))
+		end
+		
+		alias_method :eql?, :==
+		
+		def hash
+			return [desc.type, desc.data].hash
+		end
+	end
+	
+	# public
+	
+	class Alias < FileBase
+		# Wraps AEDescs of typeAlias. Alias objects keep track of filesystem objects as they're moved around the disk or renamed.
+		#
+		# Since Ruby doesn't already bridge the Mac OS's Alias Manager, simplest solution is to always store data internally as an AEDesc of typeAlias, and convert this to other forms on demand (e.g. when casting to string).
+		
+		attr_reader :desc
+		private_class_method :new
+		
+		def initialize(desc)
+			@desc = desc
+		end
+		
+		# Constructors
+		
+		def Alias.path(path)
+			# Make Alias object from POSIX path.
+			return new(FileBase._coerce(
+					AE::AEDesc.new(KAE::TypeFileURL, FileBase._path_to_url(path)),
+					KAE::TypeAlias, path))
+		end
+		
+		def Alias.desc(desc)
+			# Make Alias object from CarbonX.AE.AEDesc of typeAlias. Note: descriptor type is not checked; clients are responsible for passing the correct type as other types will cause unexpected problems/errors.
+			return new(desc)
+		end
+		
+		# Methods
+		
+		def desc
+			# Return AEDesc of typeAlias. If clients want a different type, they can subsequently call this AEDesc's coerce method.
+			return @desc
+		end
+		
+		def path
+			# Get as POSIX path.
+			return FileBase._url_to_path(FileBase._coerce(@desc, KAE::TypeFileURL).data)
+		end
+		
+		alias_method :to_s, :path
+		
+		def inspect
+			return "MacTypes::Alias.path(#{to_s.inspect})"
+		end
+		
+		def to_alias
+			# Get as MacTypes::Alias.
+			return self
+		end
+		
+		def to_file_url
+			# Get as MacTypes::FileURL; note that the resulting FileURL object will always pack as an AEDesc of typeFileURL.
+			return MacTypes::FileURL.desc(FileBase._coerce(@desc, KAE::TypeFileURL))
+		end
+	end
+	
+	##
+	
+	class FileURL < FileBase
+		# Wraps AEDescs of typeFSRef/typeFSS/typeFileURL to save user from having to deal with them directly. FileURL objects refer to specific locations on the filesystem which may or may not already exist.
+		
+		private_class_method :new
+		
+		def initialize(path, desc)
+			@path = path
+			@desc = desc
+		end
+		
+		# Constructors
+		
+		def FileURL.path(path)
+			# Make FileURL object from POSIX path.
+			return new(path, nil)
+		end
+		
+		def FileURL.desc(desc)
+			# Make FileURL object from AEDesc of typeFSS, typeFSRef, typeFileURL. Note: descriptor type is not checked; clients are responsible for passing the correct type as other types will cause unexpected problems/errors.
+			return new(nil, desc)
+		end
+		
+		# Methods
+		
+		def desc
+			# Get as AEDesc. If constructed from Ruby, descriptor's type is always typeFileURL; if returned by aem, its type mat be typeFSS, typeFSRef or typeFileURL.
+			if not @desc
+				@desc = AE::AEDesc.new(KAE::TypeFileURL, FileBase._path_to_url(@path))
+			end
+			return @desc
+		end
+		
+		def path
+			# Get as POSIX path.
+			if not @path
+				@path = FileBase._url_to_path(FileBase._coerce(@desc, KAE::TypeFileURL).data)
+			end
+			return @path
+		end
+		
+		alias_method :to_s, :path
+		
+		def inspect
+			return "MacTypes::FileURL.path(#{to_s.inspect})"
+		end
+		
+		def to_alias
+			# Get as MacTypes::Alias.
+			return MacTypes::Alias.desc(FileBase._coerce(desc, KAE::TypeAlias, to_s))
+		end
+		
+		def to_file_url
+			# Get as MacTypes::FileURL; note that the resulting FileURL object will always pack as an AEDesc of typeFileURL.
+			return MacTypes::FileURL.desc(FileBase._coerce(desc, KAE::TypeFileURL, to_s))
+		end
+	end
+	
+	##
+	
+	class FileNotFoundError < RuntimeError
+		# Raised when an operation that only works for an existing filesystem object/location is performed on an Alias/FileURL object that identifies a non-existent object/location.
+	end
+	
+	#######
+		
+	class Units
+		# Represents a measurement; e.g. 3 inches, 98.5 degrees Fahrenheit.
+		#
+		# The AEM defines a standard set of unit types; some applications may define additional types for their own use. This wrapper stores the raw unit type and value data; aem/appscript Codecs objects will convert this to/from an AEDesc, or raise an error if the unit type is unrecognised.
+	
+		attr_reader :value, :type
+	
+		def Units.method_missing(name, value)
+			return new(value, name)
+		end
+		
+		def initialize(value, type)
+			@value = value
+			@type = type
+		end
+		
+		def ==(val)
+			return (self.equal?(val) or (
+					self.class == val.class and 
+					@value == val.value and @type == val.type))
+		end
+		
+		alias_method :eql?, :==
+		
+		def hash
+			return [@value, @type].hash
+		end
+		
+		def to_i
+			return @value.to_i
+		end
+		
+		def to_f
+			return @value.to_f
+		end
+		
+		def to_s
+			return "#{@value.inspect} #{@type.tr('_', ' ')}"
+		end
+		
+		def inspect
+			return "MacTypes::Units.new(#{@value.inspect}, #{@type.inspect})"
+		end
+	end
+
+end
+

data/src/lib/_aem/send.rb

@@ -0,0 +1,257 @@
+#!/usr/local/bin/ruby
+# Copyright (C) 2006 HAS. 
+# Released under MIT License.
+
+module Send
+
+	# Defines the Event class, which represents an Apple event that's packed and ready to send, 
+	# and the CommandError class, which contains error information for a failed event.
+
+	require "ae"
+	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.
+		
+		# Clients don't instantiate this class directly; instead, new instances are returned by AEM::Application#event.
+		
+		attr_reader :AEM_event
+	
+		def initialize(address, event_code, params={}, atts={}, transaction=KAE::KAnyTransactionID, 
+				return_id= KAE::KAutoGenerateReturnID, codecs=DefaultCodecs)
+			# Create and pack a new Apple event ready for sending.
+			# address : AEAddressDesc -- the target application, identified by PSN, URL, etc.
+			# event_code : string -- 8-letter code indicating event's class and id, e.g. 'coregetd'
+			# params : hash -- a hash of form {AE_code=>anything,...} containing zero or more event parameters (message arguments)
+			# atts : hash -- a hash of form {AE_code=>anything,...} containing zero or more event attributes (event info)
+			# transaction : integer -- transaction number; AEM::Application takes care of this value
+			# return_id : integer  -- reply event's ID
+			# codecs : Codecs -- clients can provide custom Codecs object for packing parameters and unpacking result of this event
+			@_event_code = event_code
+			@_codecs = codecs
+			@AEM_event = _create_apple_event(event_code[0, 4], event_code[-4, 4], address, return_id, transaction)
+			atts.each {|key, value| @AEM_event.put_attr(key, codecs.pack(value))}
+			params.each {|key, value| @AEM_event.put_param(key, codecs.pack(value))}
+		end
+		
+		def _create_apple_event(event_class, event_id, target, return_id, transaction_id)
+			# Hook method; may be overridden to customise how AppleEvent descriptors are created.
+			return AE::AEDesc.new_apple_event(event_class, event_id, target, return_id, transaction_id)
+		end
+		
+		def _send_apple_event(flags, timeout)
+			#�Hook method; may be overridden to customise how events are sent.
+			return @AEM_event.send(flags, timeout)
+		end
+		
+		def inspect
+			return "#<AEM::Event @code=#{@_event_code}>"
+		end
+		
+		alias_method :to_s, :inspect
+		
+		def send(timeout=KAE::KAEDefaultTimeout, flags=KAE::KAECanSwitchLayer + KAE::KAEWaitReply)
+			# Send this Apple event (may be called any number of times).
+			# timeout : int | KAEDefaultTimeout | KNoTimeOut -- number of ticks to wait for target process to reply before raising timeout error
+			# flags : integer -- bitwise flags [1] indicating how target process should handle event
+			# Result : anything -- value returned by application, if any
+			#
+			# [1] Should be the sum of zero or more of the following kae module constants:
+			#
+			#	KAENoReply | KAEQueueReply | KAEWaitReply
+			#	KAEDontReconnect
+			#	KAEWantReceipt
+			#	KAENeverInteract | KAECanInteract | KAEAlwaysInteract
+			#	KAECanSwitchLayer
+
+			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)
+				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
+					event_result = {}
+					reply_event.length.times do |i|
+						key, value = reply_event.get(i + 1, KAE::TypeWildCard)
+						event_result[key] = value
+					end
+					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)
+						end
+					end
+					if event_result.has_key?(KAE::KeyAEResult)
+						# Return values are unpacked using [optionally] client-supplied codecs.
+						# This allows aem clients such as appscript to customise how values are unpacked
+						# (e.g. to unpack object specifier descs as appscript references instead of aem references).
+						return @_codecs.unpack(event_result[KAE::KeyAEResult])
+					end
+				end
+			end
+		end
+	end
+	
+	
+	class CommandError < RuntimeError
+		# Represents an error raised by the Apple Event Manager or target application when a command fails.
+		#
+		# Methods:
+		#	number : integer -- MacOS error number
+		#	message : string | nil -- application error message if any, or default error description if available, or nil
+		
+		attr_reader :number, :message, :raw # raw method is provided for testing/debugging use only
+		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
+					end
+				end
+			end
+			@number = number
+			@message = message
+			@raw = raw
+		end
+		
+		def to_s
+			if message
+				return "CommandError\n\t\tOSERROR: #{number}\n\t\tMESSAGE: #{message}"
+			else
+				return "CommandError\n\t\tOSERROR: #{number}"
+			end
+		end
+	end
+end

data/src/lib/_aem/typewrappers.rb

@@ -0,0 +1,57 @@
+#!/usr/local/bin/ruby
+# Copyright (C) 2006 HAS. 
+# Released under MIT License.
+
+module TypeWrappers
+	
+	class AETypeBase
+		
+		attr_reader :code
+		
+		def initialize(code)
+			if not (code.is_a?(String) and code.length == 4)
+				raise ArgumentError, "Code must be a four-character string: #{code}"
+			end
+			@code = code
+		end
+		
+		def hash 
+			return @code.hash
+		end
+		
+		def ==(val)
+			return (self.equal?(val) or (val.class == self.class and val.code == @code))
+		end
+		
+		alias_method :eql?, :== 
+			
+		def to_s
+			return "AEM::#{self.class::Name}.new(#{@code.dump})"
+		end
+		
+		def inspect
+			return to_s
+		end
+	end
+	
+	
+	class AEType < AETypeBase
+		Name = 'AEType'
+	end
+	
+	
+	class AEEnum < AETypeBase
+		Name = 'AEEnum'
+	end
+	
+	
+	class AEProp < AETypeBase
+		Name = 'AEProp'
+	end
+	
+	
+	class AEKey < AETypeBase
+		Name = 'AEKey'
+	end
+
+end