rb-scpt 1.0.0

data/src/lib/_aem/connect.rb

@@ -0,0 +1,205 @@
+#
+# rb-appscript
+#
+# connect -- launch applications and create AEAddressDescs
+#
+
+module Connect
+	# Creates Apple event descriptor records of typeProcessSerialNumber, typeKernelProcessID and typeApplicationURL, used to specify the target application in Send::Event constructor.
+	
+	require "ae"
+	require "kae"
+	require "_aem/codecs"
+	require "_aem/send"
+	require "_aem/encodingsupport"
+	
+	@@encoding_support = AEMEncodingSupport.encoding_support
+	
+	LSLaunchDefaults = 0x00000001
+	LSLaunchAndPrint = 0x00000002
+	LSLaunchReserved2 = 0x00000004
+	LSLaunchReserved3 = 0x00000008
+	LSLaunchReserved4 = 0x00000010
+	LSLaunchReserved5 = 0x00000020
+	LSLaunchAndDisplayErrors = 0x00000040
+	LSLaunchInhibitBGOnly = 0x00000080
+	LSLaunchDontAddToRecents = 0x00000100
+	LSLaunchDontSwitch = 0x00000200
+	LSLaunchNoParams = 0x00000800
+	LSLaunchAsync = 0x00010000
+	LSLaunchStartClassic = 0x00020000
+	LSLaunchInClassic = 0x00040000
+	LSLaunchNewInstance = 0x00080000
+	LSLaunchAndHide = 0x00100000
+	LSLaunchAndHideOthers = 0x00200000
+	LSLaunchHasUntrustedContents = 0x00400000
+	
+	KNoProcess = 0
+	KCurrentProcess = 2
+	
+	def Connect.make_address_desc(psn)
+		return AE::AEDesc.new(KAE::TypeProcessSerialNumber, psn.pack('LL'))
+	end
+	
+	NullAddress = make_address_desc([0,KNoProcess])
+	LaunchEvent = Send::Event.new(Connect::NullAddress, 'ascrnoop').AEM_event
+	RunEvent = Send::Event.new(Connect::NullAddress, 'aevtoapp').AEM_event
+	
+	#######
+	# public
+	
+	class CantLaunchApplicationError < RuntimeError
+	
+		# Taken from <http://developer.apple.com/documentation/Carbon/Reference/LaunchServicesReference>:
+		LSErrors = {
+			-10660 => "The application cannot be run because it is inside a Trash folder.",
+			-10810 => "An unknown error has occurred.",
+			-10811 => "The item to be registered is not an application.",
+			-10813 => "Data of the desired type is not available (for example, there is no kind string).",
+			-10814 => "No application in the Launch Services database matches the input criteria.",
+			-10817 => "Data is structured improperly (for example, an item's information property list is malformed).",
+			-10818 => "A launch of the application is already in progress.",
+			-10822 => "There is a problem communicating with the server process that maintains the Launch Services database.",
+			-10823 => "The filename extension to be hidden cannot be hidden.",
+			-10825 => "The application to be launched cannot run on the current Mac OS version.",
+			-10826 => "The user does not have permission to launch the application (on a managed network).",
+			-10827 => "The executable file is missing or has an unusable format.",
+			-10828 => "The Classic emulation environment was required but is not available.",
+			-10829 => "The application to be launched cannot run simultaneously in two different user sessions.",
+		}
+	
+		def initialize(error_number)
+			@error_number = error_number
+			super("#{ LSErrors.fetch(@error_number, 'OS error') } (#{ @error_number })")
+		end
+		
+		def to_i
+			return @error_number
+		end
+	end
+	
+	##
+	
+	def Connect.launch_application(path, event)
+		path = @@encoding_support.to_utf8_string(path)
+		begin
+			return AE.launch_application(path, event,
+					LSLaunchNoParams | LSLaunchStartClassic | LSLaunchDontSwitch)
+		rescue AE::MacOSError => err
+			raise CantLaunchApplicationError, err.to_i
+		end
+	end
+	
+	def Connect.launch_app_with_launch_event(path)
+		# Send a 'launch' event to an application. If application is not already running, it will be launched in background first.
+		path = @@encoding_support.to_utf8_string(path)
+		begin
+			# If app is already running, calling AE.launch_application will send a 'reopen' event, so need to check for this first:
+			psn = AE.psn_for_application_path(path)
+		rescue AE::MacOSError => err
+			if err.to_i == -600 # Application isn't running, so launch it and send it a 'launch' event
+				sleep(1)
+				launch_application(path, LaunchEvent)
+			else
+				raise
+			end
+		else # App is already running, so send it a 'launch' event
+			Send::Event.new(make_address_desc(psn), 'ascrnoop').send(60, KAE::KAENoReply)
+		end
+	end
+	
+	##
+	
+	def Connect.process_exists_for_path?(path)
+		path = @@encoding_support.to_utf8_string(path)
+		# Does a local process launched from the specified application file exist?
+		# Note: if path is invalid, an AE::MacOSError is raised.
+		begin
+			AE.psn_for_application_path(path)
+			return true
+		rescue AE::MacOSError => err
+			if err.to_i == -600
+				return false
+			else
+				raise
+			end
+		end
+	end
+
+	def Connect.process_exists_for_pid?(pid)
+		# Is there a local application process with the given unix process id?
+		begin
+			AE.psn_for_process_id(pid)
+			return true
+		rescue AE::MacOSError => err
+			if err.to_i == -600
+				return false
+			else
+				raise
+			end
+		end
+	end
+	
+	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
+	
+	def Connect.process_exists_for_desc?(desc)
+		# Does an application process specified by the given AEAddressDesc exist?
+		# Returns false if process doesn't exist OR remote Apple events aren't allowed.
+		# Note: this will send a 'launch' Apple event to the target application.
+		begin
+			# This will usually raise error -1708 if process is running, and various errors
+			# if the process doesn't exist/can't be reached. If app is running but busy,
+			# AESendMessage may return a timeout error (this should be -1712, but
+			# -609 is often returned instead for some reason).
+			Send::Event.new(desc, 'ascrnoop').send
+		rescue Send::EventError => err
+			return (not [-600, -905].include?(err.to_i)) # not running/no network access
+		end
+		return true
+	end
+	
+	##
+	
+	CurrentApp = make_address_desc([0, KCurrentProcess])
+	
+	def Connect.local_app(path)
+		# Make an AEAddressDesc identifying a local application. (Application will be launched if not already running.)
+		#	path : string -- full path to application, e.g. '/Applications/TextEdit.app'
+		#	Result : AEAddressDesc
+		#
+		# Always creates AEAddressDesc by process serial number; that way there's no confusion if multiple versions of the same app are running.
+		path = @@encoding_support.to_utf8_string(path)
+		begin
+			psn = AE.psn_for_application_path(path)
+		rescue AE::MacOSError => err
+			if err.to_i == -600 # Application isn't running, so launch it in background and send it a standard 'run' event.
+				sleep(1)
+				psn = launch_application(path, RunEvent)
+			else
+				raise
+			end
+		end
+		return make_address_desc(psn)
+	end
+	
+	def Connect.local_app_by_pid(pid)
+		# Make an AEAddressDesc identifying a running application by Unix process id.
+		#	pid : integer -- unsigned 32-bit integer
+		#	Result : AEAddressDesc
+		return AE::AEDesc.new(KAE::TypeKernelProcessID, [pid].pack('L'))
+	end
+	
+	def Connect.remote_app(url)
+		url = @@encoding_support.to_utf8_string(url)
+		# 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/encodingsupport.rb

@@ -0,0 +1,77 @@
+#
+# rb-appscript
+#
+# encodingsupport -- support string encodings in Ruby 1.9+
+#
+
+
+module AEMEncodingSupport
+
+	module EnableStringEncodings
+		# AE extension methods consume and return Strings containing UTF-8 encoded data, ignoring
+		# any attached encoding information. This module provides wrappers for AE interactions that
+		# take care of any encoding issues in Ruby 1.9+.
+		
+		def EnableStringEncodings.to_utf8_string(s)
+			# Call before passing a string to an AE method that expects it to contain UTF-8 encoded data.
+			return s if [Encoding::ASCII_8BIT, Encoding::UTF_8].include?(s.encoding)
+			return s.encode('UTF-8')
+		end
+		
+		def EnableStringEncodings.pack_string(s, as_type)
+			begin
+				return AE::AEDesc.new(KAE::TypeUTF8Text, EnableStringEncodings.to_utf8_string(s)).coerce(as_type)
+			rescue AE::MacOSError => e
+				if e.to_i == -1700 # couldn't coerce to TypeUnicodeText
+					raise TypeError, "Not valid UTF8 data or couldn't coerce to type %{as_type}: #{s.inspect}"
+				else
+					raise
+				end
+			end
+		end
+		
+		def EnableStringEncodings.unpack_string(desc)
+			# String instances returned by AE methods contain UTF-8 data and ASCII-8BIT encoding,
+			# so change the encoding to match the data
+			return desc.coerce(KAE::TypeUTF8Text).data.force_encoding('UTF-8')
+		end
+	end
+	
+	
+	module DisableStringEncodings
+		# Support for Ruby 1.8 Strings, which do not contain encoding information. User is responsible
+		# for ensuring String instances passed to AE APIs contain UTF-8 encoded data; String instances
+		# returned by unpack_string will always contain contain UTF-8 encoded data.
+		
+		def DisableStringEncodings.to_utf8_string(s)
+			return s
+		end
+		
+		def DisableStringEncodings.pack_string(s, as_type)
+			begin
+				# 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.)
+				return AE::AEDesc.new(KAE::TypeUTF8Text, s).coerce(as_type)
+			rescue AE::MacOSError => e
+				if e.to_i == -1700 # couldn't coerce to TypeUnicodeText
+					raise TypeError, "Not valid UTF8 data or couldn't coerce to type %{as_type}: #{s.inspect}"
+				else
+					raise
+				end
+			end
+		end
+		
+		def DisableStringEncodings.unpack_string(desc)
+			return desc.coerce(KAE::TypeUTF8Text).data
+		end
+		
+	end
+	
+	
+	def AEMEncodingSupport.encoding_support
+		# get the appropriate module for the Ruby version used
+		version, sub_version = RUBY_VERSION.split('.').collect {|n| n.to_i} [0, 2]
+		return (version >= 1 and sub_version >= 9) ? AEMEncodingSupport::EnableStringEncodings : AEMEncodingSupport::DisableStringEncodings
+	end
+
+end

data/src/lib/_aem/findapp.rb

@@ -0,0 +1,85 @@
+#
+# rb-appscript
+#
+# findapp -- locate an application by name, bundle ID or creator code
+#
+
+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 ApplicationNotFoundError.new(nil, nil, name), "Application #{name.inspect} not found."
+		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,251 @@
+#
+# rb-appscript
+#
+# mactypes -- Ruby classes representing Alias, FileURL and unit type AEDescs
+#
+
+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"
+	
+	KCFURLPOSIXPathStyle = 0
+	KCFURLHFSPathStyle = 1
+	KCFURLWindowsPathStyle = 2
+	
+	class FileBase
+		
+		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.url == val.url))
+		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).
+		
+		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, AE.convert_path_to_url(path, KCFURLPOSIXPathStyle)),
+					KAE::TypeAlias, path))
+		end
+		
+		def Alias.hfs_path(path)
+			# Make Alias object from HFS path.
+			return new(FileBase._coerce(
+					AE::AEDesc.new(KAE::TypeFileURL, AE.convert_path_to_url(path, KCFURLHFSPathStyle)),
+					KAE::TypeAlias, path))
+		end
+		
+		def Alias.url(url)
+			# Make Alias object from file URL. Note: only the path portion of the URL is used; the domain will always be localhost.
+			return Alias.path(AE.convert_url_to_path(url, KCFURLPOSIXPathStyle))
+		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
+		
+		attr_reader :desc # Return AEDesc of typeAlias. If clients want a different type, they can subsequently call this AEDesc's coerce method.
+		
+		def url
+			# Get as URL string.
+			return desc.coerce(KAE::TypeFileURL).data
+		end
+		
+		def path
+			# Get as POSIX path.
+			return AE.convert_url_to_path(FileBase._coerce(@desc, KAE::TypeFileURL).data, KCFURLPOSIXPathStyle)
+		end
+		
+		def hfs_path
+			# Get as HFS path.
+			return AE.convert_url_to_path(FileBase._coerce(@desc, KAE::TypeFileURL).data, KCFURLHFSPathStyle)
+		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.hfs_path(path)
+			# Make FileURL object from HFS path.
+			return new(AE.convert_url_to_path(AE.convert_path_to_url(path, KCFURLHFSPathStyle), KCFURLPOSIXPathStyle), nil)
+		end
+		
+		def FileURL.url(url)
+			# Make FileURL object from file URL. Note: only the path portion of the URL is used; the domain will always be localhost.
+			return FileURL.path(AE.convert_url_to_path(url, KCFURLPOSIXPathStyle))
+		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 may be typeFSS, typeFSRef or typeFileURL.
+			if not @desc
+				@desc = AE::AEDesc.new(KAE::TypeFileURL, AE.convert_path_to_url(@path, KCFURLPOSIXPathStyle))
+			end
+			return @desc
+		end
+		
+		def url
+			# Get as URL string.
+			return desc.coerce(KAE::TypeFileURL).data
+		end
+		
+		def path
+			# Get as POSIX path.
+			if not @path
+				@path = AE.convert_url_to_path(FileBase._coerce(@desc, KAE::TypeFileURL).data, KCFURLPOSIXPathStyle)
+			end
+			return @path
+		end
+		
+		def hfs_path
+			return AE.convert_url_to_path(AE.convert_path_to_url(path, KCFURLPOSIXPathStyle), KCFURLHFSPathStyle)
+		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 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
+