rb-appscript 0.5.3 → 0.6.0

data/src/lib/_aem/connect.rb

@@ -3,8 +3,6 @@
 #
 # connect -- launch applications and create AEAddressDescs
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 module Connect
 	# Creates Apple event descriptor records of typeProcessSerialNumber, typeKernelProcessID and typeApplicationURL, used to specify the target application in Send::Event constructor.
@@ -13,10 +11,28 @@ module Connect
 	require "kae"
 	require "_aem/codecs"
 	require "_aem/send"
-	
-	LaunchContinue = 0x4000
-	LaunchNoFileFlags = 0x0800
-	LaunchDontSwitch = 0x0200
+	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
@@ -65,9 +81,10 @@ module Connect
 	##
 	
 	def Connect.launch_application(path, event)
+		path = @@encoding_support.to_utf8_string(path)
 		begin
 			return AE.launch_application(path, event,
-					LaunchContinue + LaunchNoFileFlags + LaunchDontSwitch)
+					LSLaunchNoParams | LSLaunchStartClassic | LSLaunchDontSwitch)
 		rescue AE::MacOSError => err
 			raise CantLaunchApplicationError, err.to_i
 		end
@@ -75,6 +92,7 @@ module Connect
 	
 	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)
@@ -93,6 +111,7 @@ module Connect
 	##
 	
 	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
@@ -138,7 +157,7 @@ module Connect
 			# 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::CommandError => err
+		rescue Send::EventError => err
 			return (not [-600, -905].include?(err.to_i)) # not running/no network access
 		end
 		return true
@@ -154,6 +173,7 @@ module Connect
 		#	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
@@ -175,6 +195,7 @@ module Connect
 	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

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

@@ -3,8 +3,6 @@
 #
 # findapp -- locate an application by name, bundle ID or creator code
 #
-# Copyright (C) 2006-2009 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.

data/src/lib/_aem/mactypes.rb

@@ -3,8 +3,6 @@
 #
 # mactypes -- Ruby classes representing Alias, FileURL and unit type AEDescs
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 module MacTypes
 	# Defines wrapper classes for Mac OS datatypes that don't have a suitable Ruby equivalent.

data/src/lib/_aem/send.rb

@@ -3,13 +3,11 @@
 #
 # send -- Event class represents a packed AppleEvent that's ready to send via AESendMessage
 #
-# Copyright (C) 2006-2009 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.
+	# and the EventError class, which contains error information for a failed event.
 
 	require "ae"
 	require "kae"
@@ -73,7 +71,7 @@ module Send
 				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)
+					raise EventError.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
@@ -86,7 +84,7 @@ module Send
 						# Error info is unpacked using default codecs for reliability.
 						e_num = DefaultCodecs.unpack(event_result[KAE::KeyErrorNumber])
 						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)
+							raise EventError.new(e_num, event_result)
 						end
 					end
 					if event_result.has_key?(KAE::KeyAEResult)
@@ -101,7 +99,7 @@ module Send
 	end
 	
 	
-	class CommandError < RuntimeError
+	class EventError < RuntimeError
 		# Represents an error raised by the Apple Event Manager or target application when a command fails.
 		#
 		# Methods:
@@ -255,9 +253,9 @@ module Send
 		
 		def to_s
 			if message != ''
-				return "CommandError\n\t\tOSERROR: #{number}\n\t\tMESSAGE: #{message}"
+				return "EventError\n\t\tOSERROR: #{number}\n\t\tMESSAGE: #{message}"
 			else
-				return "CommandError\n\t\tOSERROR: #{number}"
+				return "EventError\n\t\tOSERROR: #{number}"
 			end
 		end
 		

data/src/lib/_aem/typewrappers.rb

@@ -3,8 +3,6 @@
 #
 # typewrappers -- Ruby classes representing type, enumerator, property and keyword AEDescs
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 module TypeWrappers
 	

data/src/lib/_appscript/defaultterminology.rb

@@ -3,8 +3,6 @@
 #
 # defaultterminology -- lookup tables for default type, enumerator and command definitions
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 module DefaultTerminology
 	# Defines built-in terminology available for any application. When constructing the terminology tables for a particular application, the Terminology module will duplicate these tables and then add application-specific terms to create the finished lookup tables.

data/src/lib/_appscript/referencerenderer.rb

@@ -3,8 +3,6 @@
 #
 # referencerenderer -- obtain an appscript-style string representation of an aem reference
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 require "_aem/aemreference"
 
@@ -21,7 +19,7 @@ class ReferenceRenderer
 	end
 	
 	def _format(val)
-		if val.is_a?(AEMReference::Base)
+		if val.is_a?(AEMReference::Query)
 			return ReferenceRenderer.render(@_app_data, val)
 		else
 			return val.inspect

data/src/lib/_appscript/reservedkeywords.rb

@@ -4,8 +4,6 @@
 # reservedkeywords -- names of methods already used by Ruby's Object class
 #    and appscript's Reference class
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 # This list is mirrored in ch.6 of the appscript manual and in py-osaterminology's makeidentifier module
 

data/src/lib/_appscript/safeobject.rb

@@ -3,7 +3,6 @@
 #
 # safeobject -- ensure Appscript::Reference#method_missing works reliably
 #
-# New code Copyright (C) 2006-2009 HAS
 # Original code Copyright (C) 2005 Thomas Sawyer, Jim Weirich; see below for original copyright
 #
 
@@ -60,14 +59,64 @@
 #
 # == Copyright (c) 2005 Thomas Sawyer, Jim Weirich
 #
-#   Ruby License
-#
-#   This module is free software. You may use, modify, and/or redistribute this
-#   software under the same terms as Ruby.
-#
-#   This program is distributed in the hope that it will be useful, but WITHOUT
-#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-#   FOR A PARTICULAR PURPOSE.
+# THE RUBY LICENSE
+# (http://www.ruby-lang.org/en/LICENSE.txt)
+# 
+#  You may redistribute this software and/or modify it under either the terms of
+#  the GPL (see below), or the conditions below:
+# 
+#   1. You may make and give away verbatim copies of the source form of the
+#      software without restriction, provided that you duplicate all of the
+#      original copyright notices and associated disclaimers.
+# 
+#   2. You may modify your copy of the software in any way, provided that
+#      you do at least ONE of the following:
+# 
+#        a) place your modifications in the Public Domain or otherwise
+#           make them Freely Available, such as by posting said
+#           modifications to Usenet or an equivalent medium, or by allowing
+#           the author to include your modifications in the software.
+# 
+#        b) use the modified software only within your corporation or
+#           organization.
+# 
+#        c) rename any non-standard executables so the names do not conflict
+#           with standard executables, which must also be provided.
+# 
+#        d) make other distribution arrangements with the author.
+# 
+#   3. You may distribute the software in object code or executable
+#      form, provided that you do at least ONE of the following:
+# 
+#        a) distribute the executables and library files of the software,
+#           together with instructions (in the manual page or equivalent)
+#           on where to get the original distribution.
+# 
+#        b) accompany the distribution with the machine-readable source of
+#           the software.
+# 
+#        c) give non-standard executables non-standard names, with
+#           instructions on where to get the original software distribution.
+# 
+#        d) make other distribution arrangements with the author.
+# 
+#   4. You may modify and include the part of the software into any other
+#      software (possibly commercial).  But some files in the distribution
+#      are not written by the author, so that they are not under these terms.
+# 
+#      For the list of those files and their copying conditions, see the
+#      file LEGAL.
+# 
+#   5. The scripts and library files supplied as input to or produced as
+#      output from the software do not automatically fall under the
+#      copyright of the software, but belong to whomever generated them,
+#      and may be sold commercially, and may be aggregated with this
+#      software.
+# 
+#   6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+#      IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+#      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#      PURPOSE.
 
 ######################################################################
 # PUBLIC

data/src/lib/_appscript/terminology.rb

@@ -3,8 +3,6 @@
 #
 # terminology -- retrieve and convert an application's terminology into lookup tables
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 ######################################################################
 # TERMINOLOGY PARSER
@@ -339,6 +337,38 @@ module Terminology
 		return reference_by_code, reference_by_name
 	end
 	
+	def Terminology.dump_tables(tables, module_name, source_path, out_path)
+		# Parse aete(s) into intermediate tables, suitable for use by Terminology#tables_for_module
+		if not(/^[A-Z][A-Za-z0-9_]*$/ === module_name)
+			raise RuntimeError, "Invalid module name."
+		end
+		# Write module
+		File.open(out_path, "w") do |f|
+			f.puts "module #{module_name}"
+			f.puts "\tVersion = 1.1"
+			f.puts "\tPath = #{source_path.inspect}"
+			f.puts
+			(["Classes", "Enumerators", "Properties", "Elements"].zip(tables[0,4])).each do |name, table|
+				f.puts "\t#{name} = ["
+				table.sort.each do |item|
+					f.puts "\t\t#{item.inspect},"
+				end
+				f.puts "\t]"
+				f.puts
+			end
+			f.puts "\tCommands = ["
+			tables[4].sort.each do |name, code, params|
+				f.puts "\t\t[#{name.inspect}, #{code.inspect}, ["
+					params.each do |item|
+						f.puts "\t\t\t#{item.inspect},"
+					end
+				f.puts "\t\t]],"
+			end
+			f.puts "\t]"
+			f.puts "end"
+		end
+	end
+	
 	#######
 	# public
 	
@@ -367,11 +397,18 @@ module Terminology
 			+ _make_reference_table(terms::Properties, terms::Elements, terms::Commands)
 	end
 	
+	def Terminology.tables_for_parsed_sdef(terms)
+		# Build terminology tables from an SdefParser instance.
+		# Result : list of hash -- [typebycode, typebyname, referencebycode, referencebyname]
+		return _make_type_table(terms.classes, terms.enumerators, terms.properties) \
+			+ _make_reference_table(terms.properties, terms.elements, terms.commands)
+	end
+	
 	def Terminology.aetes_for_app(aem_app)
 		begin
 			begin
 				aetes = aem_app.event('ascrgdte', {'----' => 0}).send(120 * 60)
-			rescue AEM::CommandError => e
+			rescue AEM::EventError => e
 				if  e.number == -192 # aete resource not found
 					aetes = []
 				else
@@ -397,58 +434,38 @@ module Terminology
 	end
 	
 	#######
+	# public
 	
 	def Terminology.dump(app_name, module_name, out_path)
-		# Export terminology tables as a Ruby module
+		# Export application terminology tables as a Ruby module
 		# app_path : string -- name or path of application
 		# module_name : string -- name of generated module (must be a valid Ruby constant)
 		# out_path : string -- module file to write
+		# 	
+		# Generates a Ruby module containing an application's basic terminology 
+		# (names and codes) as used by appscript.
+		# 
+		# Call the #dump method to dump faulty aetes to Ruby module, e.g.:
+		# 
+		# 	Terminology.dump('MyApp', 'MyAppGlue', '/path/to/ruby/modules/myappglue.rb')
+		# 
+		# Patch any errors by hand, then import the patched module into your script 
+		# and pass it to appscript's app() constructor via its 'terms' argument, e.g.:
+		# 
+		# 	require 'appscript'; include Appscript
+		# 	require 'myappglue'
+		# 	
+		# 	myapp = app('MyApp', terms => MyAppGlue)
+		# 
+		# Note that dumped terminologies aren't used by appscript's built-in help system.
+		#
 		app_path = FindApp.by_name(app_name)
-		if not(/^[A-Z][A-Za-z0-9_]*$/ === module_name)
-			raise RuntimeError, "Invalid module name."
-		end
 		# Get aete(s)
-		begin
-			begin
-				aetes = AEM::Codecs.new.unpack(AE.get_app_terminology(app_path).coerce(KAE::TypeAEList))
-			rescue NotImplementedError # get_app_terminology is unavailable on 64-bit Leopard
-				aetes = Terminology.aetes_for_app(AEM::Application.by_path(app_path))
-			end
-		rescue AE::MacOSError => e
-			if  e.to_i == -192 # aete resource not found
-				raise RuntimeError, "No terminology found."
-			else
-				raise
-			end
-		end
+		aetes = Terminology.aetes_for_app(Application.by_path(app_path))
 		aetes.delete_if { |aete| not(aete.is_a?(AE::AEDesc) and aete.type == KAE::TypeAETE) }
-		# Parse aete(s) into intermediate tables, suitable for use by Terminology#tables_for_module
 		tables = TerminologyParser.build_tables_for_aetes(aetes)
-		# Write module
-		File.open(out_path, "w") do |f|
-			f.puts "module #{module_name}"
-			f.puts "\tVersion = 1.1"
-			f.puts "\tPath = #{app_path.inspect}"
-			f.puts
-			(["Classes", "Enumerators", "Properties", "Elements"].zip(tables[0,4])).each do |name, table|
-				f.puts "\t#{name} = ["
-				table.sort.each do |item|
-					f.puts "\t\t#{item.inspect},"
-				end
-				f.puts "\t]"
-				f.puts
-			end
-			f.puts "\tCommands = ["
-			tables[4].sort.each do |name, code, params|
-				f.puts "\t\t[#{name.inspect}, #{code.inspect}, ["
-					params.each do |item|
-						f.puts "\t\t\t#{item.inspect},"
-					end
-				f.puts "\t\t]],"
-			end
-			f.puts "\t]"
-			f.puts "end"
-		end
+		Terminology.dump_tables(tables, module_name, app_path, out_path)
 	end
+	
 end