rb-appscript 0.5.1 → 0.5.2

data/src/lib/_aem/typewrappers.rb

@@ -3,7 +3,7 @@
 #
 # typewrappers -- Ruby classes representing type, enumerator, property and keyword AEDescs
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 module TypeWrappers
@@ -13,7 +13,7 @@ module TypeWrappers
 		attr_reader :code
 		
 		def initialize(code)
-			if not (code.is_a?(String) and code.length == 4)
+			if not(code.is_a?(String) and code.length == 4)
 				raise ArgumentError, "Code must be a four-character string: #{code.inspect}"
 			end
 			@code = code

data/src/lib/_appscript/defaultterminology.rb

@@ -3,7 +3,7 @@
 #
 # defaultterminology -- lookup tables for default type, enumerator and command definitions
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 module DefaultTerminology
@@ -64,7 +64,7 @@ module DefaultTerminology
 		'ldt ' => :date,
 		'list' => :list,
 		'reco' => :record,
-		'rdat' => :data,
+		'tdta' => :data,
 		'scpt' => :script,
 		
 		'insl' => :location_reference,
@@ -114,7 +114,7 @@ module DefaultTerminology
 		
 		'msng' => :missing_value,
 		
-		'pcls' => :class_,
+		'cobj' => :item,
 		
 		'null' => :null,
 		
@@ -190,60 +190,90 @@ module DefaultTerminology
 		'sat ' => :Saturday,
 	}
 	
-	#######
-	# TypeByCode and TypeByName tables are used to convert Ruby Symbols to and from AEDescs of typeType, typeEnum and typeProperty.
-	
-	TypeByCode = Types.clone.update(Enums)
-
-	TypeByName = {}
-	Types.each { |code, name| TypeByName[name] = AEM::AEType.new(code) }
-	Enums.each { |code, name| TypeByName[name] = AEM::AEEnum.new(code) }
-	
-	#######
-	# ReferenceByCode tables is used by ReferenceRenderer module to convert property and element four-char codes to human readable names
-	#
-	# ReferenceByName table is used to convert appscript-style references and commands to their aem equivalents
+	Properties = {
+		'pcls' => :class_,
+		'pAll' => :properties_,
+		'ID  ' => :id_,
+	}
 	
-	ReferenceByCode = {
-		'ppcls' => 'class_',
-		'pID  ' => 'id_',
+	Elements = {
+		'cobj' => :items,
 	}
 	
-	ReferenceByName = {
-		:quit => [:command, ['aevtquit', {
+	Commands = {
+		:quit => ['aevtquit', {
 				:saving => 'savo',
-				}]],
-		:activate => [:command, ['miscactv', {
-				}]],
-		:run => [:command, ['aevtoapp', {
-				}]],
-		:launch => [:command, ['ascrnoop', {
-				}]],
-		:open => [:command, ['aevtodoc', {
-				}]],
-		:get => [:command, ['coregetd', {
-				}]],
-		:print => [:command, ['aevtpdoc', {
-				}]],
-		:class_ => [:property, 'pcls'],
-		:set => [:command, ['coresetd', {
+				}],
+		:activate => ['miscactv', {
+				}],
+		:run => ['aevtoapp', {
+				}],
+		:launch => ['ascrnoop', {
+				}],
+		:open => ['aevtodoc', {
+				}],
+		:get => ['coregetd', {
+				}],
+		:print => ['aevtpdoc', {
+				}],
+		:set => ['coresetd', {
 				:to => 'data',
-				}]],
-		:reopen => [:command, ['aevtrapp', {
-				}]],
-		:id_ => [:property, 'ID  '],
-		:open_location => [:command, ['GURLGURL', {
+				}],
+		:reopen => ['aevtrapp', {
+				}],
+		:open_location => ['GURLGURL', {
 				:window => 'WIND',
-				}]],
+				}],
 	}
-
+	
+	#######
+	# TypeByCode and TypeByName tables are used to convert Ruby Symbols to and from AEDescs of typeType, typeEnum and typeProperty.
+	
+	TypeByCode = {} # used to decode class (typeType) and enumerator (typeEnum) descriptors
+	TypeByName = {} # used to encode class and enumerator keywords
+	TypeCodeByName = {} # used to check for name collisions
+	
+	Enums.each do |code, name|
+		TypeByCode[code] = name
+		TypeByName[name] = AEM::AEEnum.new(code)
+		TypeCodeByName[name.to_s] = code
+	end
+	
+	[Types, Properties].each do |table|
+		table.each do |code, name|
+			TypeByCode[code] = name
+			TypeByName[name] = AEM::AEType.new(code)
+			TypeCodeByName[name.to_s] = code
+		end
+	end
+	
+	#######
+	# ReferenceByCode and ReferenceByName tables are used to convert between appscript- and aem-style references
+	
+	ReferenceByCode = {} # used by ReferenceRenderer module to convert property and element four-char codes to human readable names
+	ReferenceByName = {} # used to convert appscript-style references and commands to their aem equivalents
+	
+	Properties.each do |code, name|
+		ReferenceByCode['p' + code] = name.to_s
+		ReferenceByName[name] = [:property, code]
+	end
+	
+	Elements.each do |code, name|
+		ReferenceByCode['e' + code] = name.to_s
+		ReferenceByName[name] = [:element, code]
+	end
+	
+	Commands.each do |name, info|
+		ReferenceByName[name] = [:command, info]
+	end
+	
 	#######
-	# DefaultCommands; used by Terminology._make_reference_table to check for any collisions between standard and application-defined commands where the command names are the same but the codes are different
+	# CommandCodeByName; used by Terminology._make_reference_table to check for any collisions between standard and application-defined commands where the command names are the same but the codes are different
 	
-	DefaultCommands = {} # {'quit' => 'aevtquit', 'activate' => 'miscactv',...}
+	CommandCodeByName = {} # {'quit' => 'aevtquit', 'activate' => 'miscactv',...}
 	ReferenceByName.each do |name, info|
 		if info[0] == :command
-			DefaultCommands[name.to_s] = info[1][0]
+			CommandCodeByName[name.to_s] = info[1][0]
 		end
 	end
 end

data/src/lib/_appscript/referencerenderer.rb

@@ -3,7 +3,7 @@
 #
 # referencerenderer -- obtain an appscript-style string representation of an aem reference
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 require "_aem/aemreference"

data/src/lib/_appscript/reservedkeywords.rb

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

data/src/lib/_appscript/safeobject.rb

@@ -3,7 +3,7 @@
 #
 # safeobject -- ensure Appscript::Reference#method_missing works reliably
 #
-# New code Copyright (C) 2006-2008 HAS
+# New code Copyright (C) 2006-2009 HAS
 # Original code Copyright (C) 2005 Thomas Sawyer, Jim Weirich; see below for original copyright
 #
 

data/src/lib/_appscript/terminology.rb

@@ -3,7 +3,7 @@
 #
 # terminology -- retrieve and convert an application's terminology into lookup tables
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 ######################################################################
@@ -283,17 +283,17 @@ module Terminology
 			table.each_with_index do |item, i|
 				name, code = item
 				# If an application-defined name overlaps an existing type name but has a different code, append '_' to avoid collision:
-				if DefaultTerminology::TypeByName.has_key?(name) and \
-						DefaultTerminology::TypeByName[name].code != code
-					name += '_'
+				name += '_' if DefaultTerminology::TypeCodeByName.fetch(name, code) != code
+				begin
+					type_by_code[code] = name.intern # to handle synonyms, if same code appears more than once then use name from last definition in list
+				rescue ArgumentError # ignore #intern error if name is empty string
 				end
-				type_by_code[code] = name.intern # to handle synonyms, if same code appears more than once then use name from last definition in list
 				name, code = table[-i - 1]
-				if DefaultTerminology::TypeByName.has_key?(name) and \
-						DefaultTerminology::TypeByName[name].code != code
-					name += '_'
+				name += '_' if DefaultTerminology::TypeCodeByName.fetch(name, code) != code
+				begin
+					type_by_name[name.intern] = klass.new(code) # to handle synonyms, if same name appears more than once then use code from first definition in list
+				rescue ArgumentError # ignore #intern error if name is empty string
 				end
-				type_by_name[name.intern] = klass.new(code) # to handle synonyms, if same name appears more than once then use code from first definition in list
 			end
 		end
 		return [type_by_code, type_by_name]
@@ -307,9 +307,15 @@ module Terminology
 			# note: if property and element names are same (e.g. 'file' in BBEdit), will pack as property specifier unless it's a special case (i.e. see :text below). Note that there is currently no way to override this, i.e. to force appscript to pack it as an all-elements specifier instead (in AS, this would be done by prepending the 'every' keyword), so clients would need to use aem for that (but could add an 'all' method to Reference class if there was demand for a built-in workaround)
 			table.each_with_index do |item, i|
 				name, code = item
+				# If an application-defined name overlaps an existing type name but has a different code, append '_' to avoid collision:
+				name += '_' if DefaultTerminology::TypeCodeByName.fetch(name, code) != code
 				reference_by_code[prefix + code] = name # to handle synonyms, if same code appears more than once then use name from last definition in list
 				name, code = table[-i - 1]
-				reference_by_name[name.intern] = [kind, code] # to handle synonyms, if same name appears more than once then use code from first definition in list
+				name += '_' if DefaultTerminology::TypeCodeByName.fetch(name, code) != code
+				begin
+					reference_by_name[name.intern] = [kind, code] # to handle synonyms, if same name appears more than once then use code from first definition in list
+				rescue ArgumentError # ignore #intern error if name is empty string
+				end
 			end
 		end
 		if reference_by_name.has_key?(:text) # special case: AppleScript always packs 'text of...' as all-elements specifier
@@ -317,13 +323,18 @@ module Terminology
 		end
 		commands.reverse.each do |name, code, args| # to handle synonyms, if two commands have same name but different codes, only the first definition should be used (iterating over the commands list in reverse ensures this)
 			# Avoid collisions between default commands and application-defined commands with same name but different code (e.g. 'get' and 'set' in InDesign CS2):
-			if DefaultTerminology::DefaultCommands.has_key?(name) and \
-					code != DefaultTerminology::DefaultCommands[name]
-						name += '_'
-			end
+			name += '_' if DefaultTerminology::CommandCodeByName.fetch(name, code) != code
 			dct = {}
-			args.each { |arg_name, arg_code| dct[arg_name.intern] = arg_code }
-			reference_by_name[name.intern] = [:command, [code, dct]]
+			args.each do |arg_name, arg_code|
+				begin
+					dct[arg_name.intern] = arg_code
+				rescue ArgumentError # ignore #intern error if name is empty string
+				end
+			end
+			begin
+				reference_by_name[name.intern] = [:command, [code, dct]]
+			rescue ArgumentError # ignore #intern error if name is empty string
+			end
 		end
 		return reference_by_code, reference_by_name
 	end
@@ -339,7 +350,7 @@ module Terminology
 	def Terminology.tables_for_aetes(aetes)
 		# Build terminology tables from a list of unpacked aete byte strings.
 		# Result : list of hash -- [typebycode, typebyname, referencebycode, referencebyname]
-		aetes = aetes.reject { |aete| not (aete.is_a?(AE::AEDesc) and aete.type == KAE::TypeAETE and aete.data != '') }
+		aetes = aetes.reject { |aete| not(aete.is_a?(AE::AEDesc) and aete.type == KAE::TypeAETE and aete.data != '') }
 		classes, enums, properties, elements, commands = TerminologyParser.build_tables_for_aetes(aetes)
 		return _make_type_table(classes, enums, properties) + _make_reference_table(properties, elements, commands)
 	end
@@ -393,7 +404,7 @@ module Terminology
 		# module_name : string -- name of generated module (must be a valid Ruby constant)
 		# out_path : string -- module file to write
 		app_path = FindApp.by_name(app_name)
-		if not /^[A-Z][A-Za-z0-9_]*$/ === module_name
+		if not(/^[A-Z][A-Za-z0-9_]*$/ === module_name)
 			raise RuntimeError, "Invalid module name."
 		end
 		# Get aete(s)
@@ -410,7 +421,7 @@ module Terminology
 				raise
 			end
 		end
-		aetes.delete_if { |aete| not (aete.is_a?(AE::AEDesc) and aete.type == KAE::TypeAETE) }
+		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

data/src/lib/aem.rb

@@ -4,7 +4,7 @@
 # aem -- a mid-level object-oriented API for creating and sending Apple events
 #    using raw AE codes; may be used directly or via high-level appscript wrapper
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 require "ae"
@@ -112,11 +112,6 @@ module AEM
 			Connect.launch_app_with_launch_event(path)
 		end
 		
-		def Application.is_running?(path) # TO DO: delete
-			$stderr.puts('Warning! AEM::Application.is_running? is deprecated; use process_exists_for_path? instead.')
-			return Connect.process_exists_for_path?(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.

data/src/lib/appscript.rb

@@ -4,14 +4,14 @@
 # appscript -- syntactically sugared wrapper around the mid-level aem API;
 #    provides a high-level, easy-to-use API for creating and sending Apple events
 #
-# Copyright (C) 2006-2008 HAS. Released under MIT License.
+# Copyright (C) 2006-2009 HAS. Released under MIT License.
 #
 
 require "_aem/mactypes"
 
 module Appscript
 
-	Version = '0.5.0'
+	Version = '0.5.2'
 
 	# The following methods and classes are of interest to end users:
 	# app, con, its, CommandError, ApplicationNotFoundError, CantLaunchApplicationError
@@ -75,6 +75,12 @@ module Appscript
 		
 		#######
 		
+		def dont_cache_unpacked_specifiers
+			@reference_codecs.dont_cache_unpacked_specifiers
+		end
+		
+		#######
+		
 		Constructors = {
 			:by_path => 'path',
 			:by_pid => 'pid',
@@ -88,11 +94,10 @@ module Appscript
 				apppath = FindApp.by_id(ASDictionaryBundleID)
 				asdictionary_is_running = AEM::Application.process_exists_for_path?(apppath)
 				@_help_agent = AEM::Application.by_path(apppath)
-				if not asdictionary_is_running # hide ASDictionary after launching it # TO DO: something less kludgy
+				if not asdictionary_is_running # hide ASDictionary after launching it
 					AEM::Application.by_path(FindApp.by_id('com.apple.systemevents')).event('coresetd', {
 							'----' => AEM.app.elements('prcs').by_name('ASDictionary').property('pvis'), 
 							'data' => false}).send
-					sleep(1) # KLUDGE: need a short delay here to workaround ASDictionary 0.9.0's event handling glitches # TO DO: delete after ASDictionary is fixed
 				end
 				return true
 			rescue FindApp::ApplicationNotFoundError => e
@@ -128,13 +133,7 @@ module Appscript
 					return ref if not _init_help_agent
 					e = _display_help(flags, ref)
 				end
-				if e
-					if e.number == -1708 # event wasn't handled, presumably because available ASDictionary is too old
-						$stderr.puts("No help available: ASDictionary 0.9.0 or later required.")
-					else
-						$stderr.puts("No help available: ASDictionary raised an error: #{e}.")
-					end
-				end
+				$stderr.puts("No help available: ASDictionary raised an error: #{e}.") if e
 			rescue => err
 				$stderr.puts("No help available: unknown error: #{err}")
 			end
@@ -527,7 +526,7 @@ module Appscript
 						if code == 'ascrnoop'
 							AEM::Application.launch(@AS_app_data.identifier)
 						elsif code != 'aevtoapp'
-							raise CommandError.new(self, name, args, e)
+							raise CommandError.new(self, name, args, e, @AS_app_data)
 						end
 					end
 					# update AEMApplication object's AEAddressDesc
@@ -537,11 +536,11 @@ module Appscript
 						return @AS_app_data.target.event(code, params, atts, 
 								KAE::KAutoGenerateReturnID, @AS_app_data).send(timeout, send_flags)
 					rescue AEM::CommandError => e
-						raise CommandError.new(self, name, args, e)
+						raise CommandError.new(self, name, args, e, @AS_app_data)
 					end
 				end
 			end
-			raise CommandError.new(self, name, args, e)
+			raise CommandError.new(self, name, args, e, @AS_app_data)
 		end
 		
 		
@@ -635,8 +634,10 @@ module Appscript
 			selector_type, code = @AS_app_data.reference_by_name[name]
 			case selector_type # check if name is a property/element/command name, and if it is handle accordingly
 				when :property
+					raise ArgumentError, "wrong number of arguments for '#{name}' property (1 for 0)" if args != []
 					return Reference.new(@AS_app_data, @AS_aem_reference.property(code))
 				when :element
+					raise ArgumentError, "wrong number of arguments for '#{name}' elements (1 for 0)" if args != []
 					return Reference.new(@AS_app_data, @AS_aem_reference.elements(code))
 				when :command
 					return _send_command(args, name, code[0], code[1])
@@ -692,7 +693,12 @@ module Appscript
 					when Appscript::GenericReference, Appscript::Reference, AEMReference::Test
 						case selector
 							when Appscript::GenericReference
-								test_clause = selector.AS_resolve(@AS_app_data).AS_aem_reference
+								test_clause = selector.AS_resolve(@AS_app_data)
+								begin
+									test_clause = test_clause.AS_aem_reference
+								rescue NoMethodError
+									raise ArgumentError, "Not a valid its-based test: #{selector}"
+								end
 							when Appscript::Reference
 								test_clause = selector.AS_aem_reference
 						else
@@ -1008,12 +1014,31 @@ module Appscript
 		
 		attr_reader :reference, :name, :parameters, :real_error
 		
-		def initialize(reference, command_name, parameters, real_error)
-			@reference, @command_name, @parameters, @real_error = reference, command_name, parameters, real_error
+		def initialize(reference, command_name, parameters, real_error, codecs)
+			@reference, @command_name, @parameters = reference, command_name, parameters
+			@real_error, @codecs = real_error, codecs
 			super()
 		end
 		
-		def to_i
+		def to_s
+			if @real_error.is_a?(AEM::CommandError)
+				err = "CommandError\n\t\tOSERROR: #{error_number}"
+				err += "\n\t\tMESSAGE: #{error_message}" if error_message != ''
+				[
+					["\n\t\tOFFENDING OBJECT", KAE::KOSAErrorOffendingObject],
+					["\n\t\tEXPECTED TYPE", KAE::KOSAErrorExpectedType],
+					["\n\t\tPARTIAL RESULT", KAE::KOSAErrorPartialResult],
+				].each do |label, key|
+					desc = @real_error.raw[key]
+					err += "#{label}: #{@codecs.unpack(desc).inspect}" if desc
+				end
+			else
+				err = @real_error
+			end
+			return "#{err}\n\t\tCOMMAND: #{@reference}.#{@command_name}(#{(@parameters.collect { |item| item.inspect }).join(', ')})\n"
+		end
+		
+		def error_number
 			if @real_error.is_a?(AE::MacOSError) or @real_error.is_a?(AEM::CommandError)
 				return @real_error.to_i
 			else
@@ -1021,8 +1046,28 @@ module Appscript
 			end
 		end
 		
-		def to_s
-			return "#{@real_error}\n\t\tCOMMAND: #{@reference}.#{@command_name}(#{(@parameters.collect { |item| item.inspect }).join(', ')})\n"
+		alias_method :to_i, :error_number
+		
+		def error_message
+			return @real_error.message
+		end
+		
+		def offending_object
+			return nil if not @real_error.is_a?(AEM::CommandError)
+			desc = @real_error.raw[KAE::KOSAErrorOffendingObject]
+			return desc ? @codecs.unpack(desc) : nil
+		end
+		
+		def expected_type
+			return nil if not @real_error.is_a?(AEM::CommandError)
+			desc = @real_error.raw[KAE::KOSAErrorExpectedType]
+			return desc ? @codecs.unpack(desc) : nil
+		end
+		
+		def partial_result
+			return nil if not @real_error.is_a?(AEM::CommandError)
+			desc = @real_error.raw[KAE::KOSAErrorPartialResult]
+			return desc ? @codecs.unpack(desc) : nil
 		end
 	end