rb-appscript 0.2.1 → 0.3.0

data/src/lib/appscript.rb

@@ -13,6 +13,7 @@ module Appscript
 	require "aem"
 	require "_appscript/referencerenderer"
 	require "_appscript/terminology"
+	require "_appscript/safeobject"
 	
 	######################################################################
 	# APPDATA
@@ -24,34 +25,36 @@ module Appscript
 	
 	class AppData < AEM::Codecs
 	
-		attr_reader :path, :pid, :url
+		attr_reader :constructor, :identifier, :reference_codecs
+		attr_writer :reference_codecs
 	
-		def initialize(aem_application_class, path, pid, url, terms)
+		def initialize(aem_application_class, constructor, identifier, terms)
 			super()
-			@_aem_application_class = aem_application_class
-			@_terms = terms
-			@path = path
-			@pid = pid
-			@url = url
-		end
-		
-		def _connect # initialize AEM::Application instance and terminology tables the first time they are needed
-			if @path
-				@target = @_aem_application_class.by_path(@path)
-			elsif @pid
-				@target = @_aem_application_class.by_pid(@pid)
-			elsif @url
-				@target = @_aem_application_class.by_url(@url)
+			@_aem_application_class = aem_application_class # AEM::Application class or subclass to use when constructing target
+			@_terms = terms # user-supplied terminology tables/true/false
+			@constructor = constructor # name of AEM::Application constructor to use/:by_aem_app
+			@identifier = identifier # argument for AEM::Application constructor
+			@reference_codecs = AEM::Codecs.new # low-level Codecs object used to unpack references; used by AppData#unpack_object_specifier, AppData#unpack_insertion_loc. Note: this is a bit kludgy, and it's be better to use AppData for all unpacking, but it should be 'good enough' in practice.
+		end
+		
+		def connect # initialize AEM::Application instance and terminology tables the first time they are needed
+			case @constructor
+				when :by_aem_app
+					@target = @identifier
+				when :current
+					@target = @_aem_application_class.current
 			else
-				@target = @_aem_application_class.current
+				@target = @_aem_application_class.send(@constructor, @identifier)
 			end
 			case @_terms
 				when true # obtain terminology from application
-					@type_by_code, @type_by_name, @reference_by_code, @reference_by_name = Terminology.tables_for_app(@path, @pid, @url)
+					@type_by_code, @type_by_name, @reference_by_code, @reference_by_name = Terminology.tables_for_app(@target)
 				when false # use built-in terminology only (e.g. use this when running AppleScript applets)
 					@type_by_code, @type_by_name, @reference_by_code, @reference_by_name = Terminology.default_tables
 				when nil # [developer-only] make Application#methods return names of built-in methods only (needed to generate reservedkeywords.rb file)
 					@type_by_code, @type_by_name, @reference_by_code, @reference_by_name = {}, {}, {}, {}
+				when Array # ready-to-use terminology tables
+					@type_by_code, @type_by_name, @reference_by_code, @reference_by_name = @_terms
 			else # @_terms is [assumed to be] a module containing dumped terminology, so use that
 				@type_by_code, @type_by_name, @reference_by_code, @reference_by_name = Terminology.tables_for_module(@_terms)
 			end
@@ -61,27 +64,27 @@ module Appscript
 		#######
 		
 		def target
-			_connect
+			connect
 			return @target
 		end
 		
 		def type_by_name
-			_connect
+			connect
 			return @type_by_name
 		end
 		
 		def type_by_code
-			_connect
+			connect
 			return @type_by_code
 		end
 		
 		def reference_by_name
-			_connect
+			connect
 			return @reference_by_name
 		end
 		
 		def reference_by_code
-			_connect
+			connect
 			return @reference_by_code
 		end
 		
@@ -101,7 +104,7 @@ module Appscript
 		
 		##
 		
-		ClassType = AEM::AEType.new('pcls')
+		ClassType = AEM::AEType.new(KAE::PClass)
 		
 		def pack_hash(val)
 			record = AE::AEDesc.new_list(true)
@@ -137,7 +140,7 @@ module Appscript
 				end
 			end
 			if usrf
-				record.put_param('usrf', usrf)
+				record.put_param(KAE::KeyASUserRecordFields, usrf)
 			end
 			return record
 		end
@@ -160,8 +163,8 @@ module Appscript
 		def unpack_aerecord(desc)
 			dct = {}
 			desc.length().times do |i|
-				key, value = desc.get(i + 1, KAE::TypeWildCard)
-				if key == 'usrf'
+				key, value = desc.get_item(i + 1, KAE::TypeWildCard)
+				if key == KAE::KeyASUserRecordFields
 					lst = unpack_aelist(value)
 					(lst.length / 2).times do |i|
 						dct[lst[i * 2]] = lst[i * 2 + 1]
@@ -174,20 +177,41 @@ module Appscript
 		end
 		
 		def unpack_object_specifier(desc)
-			return Reference.new(self, DefaultCodecs.unpack_object_specifier(desc))
+			return Reference.new(self, @reference_codecs.unpack(desc))
 		end
 		
 		def unpack_insertion_loc(desc)
-			return Reference.new(self, DefaultCodecs.unpack_insertion_loc(desc))
+			return Reference.new(self, @reference_codecs.unpack(desc))
 		end
 				
-		def unpack_contains_comp_descriptor(op1, op2)
+		def unpack_contains_comp_descriptor(op1, op2) # TO DO: is this needed?
 			if op1.is_a?(Appscript::Reference) and op1.AS_aem_reference.AEM_root == AEMReference::Its
 				return op1.contains(op2)
 			else
 				return super
 			end
 		end
+		
+		def unpack_unknown(desc)
+			return case desc.type
+				when KAE::TypeApplicationBundleID
+					Appscript.app.by_id(desc.data)
+				when KAE::TypeApplicationURL
+					if desc.data[0, 4] == 'file' # workaround for converting AEAddressDescs containing file:// URLs to application paths, since AEAddressDescs containing file URLs don't seem to work correctly
+						Appscript.app(MacTypes::FileURL.url(desc.data).path)
+					else # presumably contains an eppc:// URL
+						Appscript.app.by_url(desc.data)
+					end
+				when KAE::TypeApplSignature
+					Appscript.app.by_creator(AEM::Codecs.four_char_code(desc.data))
+				when KAE::TypeKernelProcessID
+					Appscript.app.by_pid(desc.data.unpack('L')[0])
+				when KAE::TypeMachPort, KAE::TypeProcessSerialNumber
+					Appscript.app.by_aem_app(AEM::Application.by_desc(desc))
+			else
+				super
+			end
+		end
 	end
 	
 	
@@ -195,7 +219,7 @@ module Appscript
 	# GENERIC REFERENCE
 	######################################################################
 	
-	class GenericReference
+	class GenericReference < AS_SafeObject
 	
 		attr_reader :_call
 		protected :_call
@@ -215,7 +239,7 @@ module Appscript
 		end
 		
 		def method_missing(name, *args)
-			return AS::GenericReference.new(@_call + [[name, args]])
+			return Appscript::GenericReference.new(@_call + [[name, args]])
 		end
 	
 		def to_s
@@ -255,11 +279,11 @@ module Appscript
 	# REFERENCE
 	######################################################################
 	
-	class Reference
+	class Reference < AS_SafeObject
 	
 		# users may occasionally require access to the following for creating workarounds to problem apps
 		# note: calling #AS_app_data on a newly created application object will return an AppData instance
-		# that is not yet fully initialised, so remember to call its #_connect method before use
+		# that is not yet fully initialised, so remember to call its #connect method before use
 		attr_reader :AS_aem_reference, :AS_app_data
 		attr_writer :AS_aem_reference, :AS_app_data
 	
@@ -302,117 +326,112 @@ module Appscript
 		
 		# default cons, csig attributes
 		
-		DefaultConsiderations =  AEM::DefaultCodecs.pack([AEM::AEType.new('case')])
+		DefaultConsiderations =  AEM::DefaultCodecs.pack([AEM::AEEnum.new(KAE::KAECase)])
 		DefaultConsidersAndIgnores = _pack_uint32(KAE::KAECaseIgnoreMask)
 		
 		##
 		
 		def _send_command(args, name, code, labelled_arg_terms)
-	#		puts "Calling command #{name} \n\twith args #{args.inspect},\n\treference #{self}\n\tinfo #{code.inspect}, #{labelled_arg_terms.inspect}\n\n"
-#			begin # TO DO: enable error handling block once debugging is completed
-				atts = {'subj' => nil}
-				params = {}
-				case args.length
-					when 0
+			atts = {KAE::KeySubjectAttr => nil}
+			params = {}
+			case args.length
+				when 0
+					keyword_args = {}
+				when 1 # note: if a command takes a hash as its direct parameter, user must pass {} as a second arg otherwise hash will be assumed to be keyword parameters
+					if args[0].is_a?(Hash)
+						keyword_args = args[0]
+					else
+						params[KAE::KeyDirectObject] = args[0]
 						keyword_args = {}
-					when 1 # note: if a command takes a hash as its direct parameter, user must pass {} as a second arg otherwise hash will be assumed to be keyword parameters
-						if args[0].is_a?(Hash)
-							keyword_args = args[0]
-						else
-							params['----'] = args[0]
-							keyword_args = {}
-						end
-					when 2
-						params['----'], keyword_args = args
-				else
-					raise ArgumentError, "Too many direct parameters."
-				end
-				if not keyword_args.is_a?(Hash)
-					raise ArgumentError, "Second argument must be a Hash containing zero or more keyword parameters."
-				end
-				# get user-specified timeout, if any
-				timeout = (keyword_args.delete(:timeout) {60}).to_i
-				if timeout <= 0
-					timeout = KAE::KNoTimeOut
-				else
-					timeout *= 60
-				end
-				# default send flags
-				send_flags = KAE::KAECanSwitchLayer
-				# ignore application's reply?
-				send_flags += keyword_args.delete(:wait_reply) == false ? KAE::KAENoReply : KAE::KAEWaitReply
-				# add considering/ignoring attributes
-				ignore_options = keyword_args.delete(:ignore)
-				if ignore_options == nil
-					atts['cons'] = DefaultConsiderations
-					atts['csig'] = DefaultConsidersAndIgnores
-				else
-					atts['cons'] = ignore_options
-					csig = 0
-					IgnoreEnums.each do |option, consider_mask, ignore_mask|
-						csig += ignore_options.include?(option) ? ignore_mask : consider_mask
 					end
-					atts['csig'] = Reference._pack_uint32(csig)
-				end
-				# optionally specify return value type
-				if keyword_args.has_key?(:result_type)
-					params['rtyp'] = keyword_args.delete(:result_type)
+				when 2
+					params[KAE::KeyDirectObject], keyword_args = args
+			else
+				raise ArgumentError, "Too many direct parameters."
+			end
+			if not keyword_args.is_a?(Hash)
+				raise ArgumentError, "Second argument must be a Hash containing zero or more keyword parameters."
+			end
+			# get user-specified timeout, if any
+			timeout = (keyword_args.delete(:timeout) {60}).to_i
+			if timeout <= 0
+				timeout = KAE::KNoTimeOut
+			else
+				timeout *= 60
+			end
+			# default send flags
+			send_flags = KAE::KAECanSwitchLayer
+			# ignore application's reply?
+			send_flags += keyword_args.delete(:wait_reply) == false ? KAE::KAENoReply : KAE::KAEWaitReply
+			# add considering/ignoring attributes
+			ignore_options = keyword_args.delete(:ignore)
+			if ignore_options == nil
+				atts[KAE::EnumConsiderations] = DefaultConsiderations
+				atts[KAE::EnumConsidsAndIgnores] = DefaultConsidersAndIgnores
+			else
+				atts[KAE::EnumConsiderations] = ignore_options
+				csig = 0
+				IgnoreEnums.each do |option, consider_mask, ignore_mask|
+					csig += ignore_options.include?(option) ? ignore_mask : consider_mask
 				end
-				# extract labelled parameters, if any
-				keyword_args.each do |param_name, param_value|
-					param_code = labelled_arg_terms[param_name]
-					if param_code == nil
-						raise ArgumentError, "Unknown keyword parameter: #{param_name.inspect}"
-					end
-					params[param_code] = param_value
+				atts[KAE::EnumConsidsAndIgnores] = Reference._pack_uint32(csig)
+			end
+			# optionally specify return value type
+			if keyword_args.has_key?(:result_type)
+				params[KAE::KeyAERequestedType] = keyword_args.delete(:result_type)
+			end
+			# extract labelled parameters, if any
+			keyword_args.each do |param_name, param_value|
+				param_code = labelled_arg_terms[param_name]
+				if param_code == nil
+					raise ArgumentError, "Unknown keyword parameter: #{param_name.inspect}"
 				end
-				# apply special cases
-				# Note: appscript does not replicate every little AppleScript quirk when packing event attributes and parameters (e.g. AS always packs a make command's tell block as the subject attribute, and always includes an each parameter in count commands), but should provide sufficient consistency with AS's habits and give good usability in their own right.
-				if @AS_aem_reference != AEM.app # If command is called on a Reference, rather than an Application...
-					if code == 'coresetd'
-						#  if ref.set(...) contains no 'to' argument, use direct argument for 'to' parameter and target reference for direct parameter
-						if params.has_key?('----') and not params.has_key?('data')
-							params['data'] = params['----']
-							params['----'] = @AS_aem_reference
-						elsif not params.has_key?('----')
-							params['----'] = @AS_aem_reference
-						else
-							atts['subj'] = @AS_aem_reference
-						end
-					elsif code == 'corecrel'
-						# this next bit is a bit tricky: 
-						# - While it should be possible to pack the target reference as a subject attribute, when the target is of typeInsertionLoc, CocoaScripting stupidly tries to coerce it to typeObjectSpecifier, which causes a coercion error.
-						# - While it should be possible to pack the target reference as the 'at' parameter, some less-well-designed applications won't accept this and require it to be supplied as a subject attribute (i.e. how AppleScript supplies it).
-						# One option is to follow the AppleScript approach and force users to always supply subject attributes as target references and 'at' parameters as 'at' parameters, but the syntax for the latter is clumsy and not backwards-compatible with a lot of existing appscript code (since earlier versions allowed the 'at' parameter to be given as the target reference). So for now we split the difference when deciding what to do with a target reference: if it's an insertion location then pack it as the 'at' parameter (where possible), otherwise pack it as the subject attribute (and if the application doesn't like that then it's up to the client to pack it as an 'at' parameter themselves).
-						#
-						# if ref.make(...) contains no 'at' argument and target is an insertion reference, use target reference for 'at' parameter...
-						if @AS_aem_reference.is_a?(AEMReference::InsertionSpecifier) and not params.has_key?('insh')
-							params['insh'] = @AS_aem_reference
-						else # ...otherwise pack the target reference as the subject attribute
-							atts['subj'] = @AS_aem_reference
-						end
-					elsif params.has_key?('----')
-						# if user has already supplied a direct parameter, pack that reference as the subject attribute
-						atts['subj'] = @AS_aem_reference
+				params[param_code] = param_value
+			end
+			# apply special cases
+			# Note: appscript does not replicate every little AppleScript quirk when packing event attributes and parameters (e.g. AS always packs a make command's tell block as the subject attribute, and always includes an each parameter in count commands), but should provide sufficient consistency with AS's habits and give good usability in their own right.
+			if @AS_aem_reference != AEM.app # If command is called on a Reference, rather than an Application...
+				if code == 'coresetd'
+					#  if ref.set(...) contains no 'to' argument, use direct argument for 'to' parameter and target reference for direct parameter
+					if params.has_key?(KAE::KeyDirectObject) and not params.has_key?(KAE::KeyAEData)
+						params[KAE::KeyAEData] = params[KAE::KeyDirectObject]
+						params[KAE::KeyDirectObject] = @AS_aem_reference
+					elsif not params.has_key?(KAE::KeyDirectObject)
+						params[KAE::KeyDirectObject] = @AS_aem_reference
 					else
-						# pack that reference as the direct parameter
-						params['----'] = @AS_aem_reference
+						atts[KAE::KeySubjectAttr] = @AS_aem_reference
+					end
+				elsif code == 'corecrel'
+					# this next bit is a bit tricky: 
+					# - While it should be possible to pack the target reference as a subject attribute, when the target is of typeInsertionLoc, CocoaScripting stupidly tries to coerce it to typeObjectSpecifier, which causes a coercion error.
+					# - While it should be possible to pack the target reference as the 'at' parameter, some less-well-designed applications won't accept this and require it to be supplied as a subject attribute (i.e. how AppleScript supplies it).
+					# One option is to follow the AppleScript approach and force users to always supply subject attributes as target references and 'at' parameters as 'at' parameters, but the syntax for the latter is clumsy and not backwards-compatible with a lot of existing appscript code (since earlier versions allowed the 'at' parameter to be given as the target reference). So for now we split the difference when deciding what to do with a target reference: if it's an insertion location then pack it as the 'at' parameter (where possible), otherwise pack it as the subject attribute (and if the application doesn't like that then it's up to the client to pack it as an 'at' parameter themselves).
+					#
+					# if ref.make(...) contains no 'at' argument and target is an insertion reference, use target reference for 'at' parameter...
+					if @AS_aem_reference.is_a?(AEMReference::InsertionSpecifier) \
+							and not params.has_key?(KAE::KeyAEInsertHere)
+						params[KAE::KeyAEInsertHere] = @AS_aem_reference
+					else # ...otherwise pack the target reference as the subject attribute
+						atts[KAE::KeySubjectAttr] = @AS_aem_reference
 					end
+				elsif params.has_key?(KAE::KeyDirectObject)
+					# if user has already supplied a direct parameter, pack that reference as the subject attribute
+					atts[KAE::KeySubjectAttr] = @AS_aem_reference
+				else
+					# pack that reference as the direct parameter
+					params[KAE::KeyDirectObject] = @AS_aem_reference
 				end
-#			rescue => e
-#				raise Appscript::CommandError.new(self, name, args, e)
-#			end
+			end
 			# build and send the Apple event, returning its result, if any
 			begin
-				# puts 'SENDING EVENT: ' + [code, params, atts, timeout, send_flags].inspect
 				return @AS_app_data.target.event(code, params, atts, 
 						KAE::KAutoGenerateReturnID, @AS_app_data).send(timeout, send_flags)
 			rescue => e
 				if e.is_a?(AEM::CommandError)
-					if [-600, -609].include?(e.number) and @AS_app_data.path
-						if not AEM::Application.is_running?(@AS_app_data.path)
+					if [-600, -609].include?(e.number) and @AS_app_data.constructor == :by_path
+						if not AEM::Application.is_running?(@AS_app_data.identifier)
 							if code == 'ascrnoop'
-								AEM::Application.launch(@AS_app_data.path)
+								AEM::Application.launch(@AS_app_data.identifier)
 							elsif code != 'aevtoapp'
 								raise CommandError.new(self, name, args, e)
 							end
@@ -503,29 +522,12 @@ module Appscript
 			selector_type, code = @AS_app_data.reference_by_name[name]
 			case selector_type
 				when :property
-					return Reference.new(self.AS_app_data, self.AS_aem_reference.property(code))
+					return Reference.new(@AS_app_data, @AS_aem_reference.property(code))
 				when :element
-					return Reference.new(self.AS_app_data, self.AS_aem_reference.elements(code))
+					return Reference.new(@AS_app_data, @AS_aem_reference.elements(code))
 				when :command
 					return _send_command(args, name, code[0], code[1])
 			else
-				# convenience shortcuts # TO DO: decide if these should be kept or not; note: if enabled, reserved keywords list will need to be expanded to include methods whose names end in '?' and '='
-				# - if name ends with '?', remove that and look up again; if property/element found, make new reference and send it a 'get' event, else raise 'unknown' error
-				# - if name ends with '=', remove that and look up again; if property/element found, make new reference and send it a 'set' event, else raise 'unknown' error
-				#name_str = name.to_s
-				#modifier = name_str[-1, 1]
-				#if modifier == '?' or modifier == '=' and name_str.length > 0
-				#	new_name = name_str.chop.intern
-				#	selector_type, code = @AS_app_data.reference_by_name[new_name]
-				#	if [:property, :element].include?(selector_type) and
-				#		case modifier
-				#			when '?'
-				#				return self.send(new_name, *args).get
-				#			when '='
-				#				return self.send(new_name, *args).set(*args)
-				#		end
-				#	end
-				#end
 				msg = "Unknown property, element or command: '#{name}'"
 				if @AS_app_data.reference_by_name.has_key?("#{name}_".intern)
 					msg += " (Did you mean '#{name}_'?)"
@@ -536,7 +538,7 @@ module Appscript
 		
 		def [](selector, end_range_selector=nil)
 			if end_range_selector != nil
-				new_ref = self.AS_aem_reference.by_range(
+				new_ref = @AS_aem_reference.by_range(
 						self._resolve_range_boundary(selector, 1),
 						self._resolve_range_boundary(end_range_selector, -1))
 			elsif selector.is_a?(String)
@@ -547,7 +549,7 @@ module Appscript
 			else
 				new_ref = @AS_aem_reference.by_index(selector)
 			end
-			return Reference.new(self.AS_app_data, new_ref)
+			return Reference.new(@AS_app_data, new_ref)
 		end
 		
 		def first
@@ -681,38 +683,50 @@ module Appscript
 			return AEM::Application
 		end
 		
-		def initialize(path, pid, url, terms)
-			super(AppData.new(_aem_application_class, path, pid, url, terms), AEM.app)
+		def initialize(constructor, identifier, terms)
+			super(AppData.new(_aem_application_class, constructor, identifier, terms), AEM.app)
 		end
 		
 		# constructors
 		
 		def Application.by_name(name, terms=true)
-			return new(FindApp.by_name(name), nil, nil, terms)
+			return new(:by_path, FindApp.by_name(name), terms)
 		end
 		
 		def Application.by_id(id, terms=true)
-			return new(FindApp.by_id(id), nil, nil, terms)
+			return new(:by_path, FindApp.by_id(id), terms)
 		end
 		
 		def Application.by_creator(creator, terms=true)
-			return new(FindApp.by_creator(creator), nil, nil, terms)
+			return new(:by_path, FindApp.by_creator(creator), terms)
 		end
 		
 		def Application.by_pid(pid, terms=true)
-			return new(nil, pid, nil, terms)
+			return new(:by_pid, pid, terms)
 		end
 		
 		def Application.by_url(url, terms=true)
-			return new(nil, nil, url, terms)
+			return new(:by_url, url, terms)
+		end
+		
+		def Application.by_aem_app(aem_app, terms=true)
+			return new(:by_aem_app, aem_app, terms)
 		end
 		
 		def Application.current(terms=true)
-			return new(nil, nil, nil, terms)
+			return new(:current, nil, terms)
 		end
 		
 		#
 		
+		def AS_new_reference(ref)
+			if ref.is_a?(Appscript::GenericReference)
+				return ref.AS_resolve(@AS_app_data)
+			else
+				return Reference.new(@AS_app_data, ref)
+			end
+		end
+		
 		def start_transaction(session=nil)
 			@AS_app_data.target.start_transaction(session)
 		end
@@ -726,8 +740,8 @@ module Appscript
 		end
 		
 		def launch
-			if @AS_app_data.path
-				AEM::Application.launch(@AS_app_data.path)
+			if @AS_app_data.constructor == :by_path
+				AEM::Application.launch(@AS_app_data.identifier)
 				@AS_app_data.target.reconnect
 			else
 				@AS_app_data.target.event('ascrnoop').send # will send launch event to app if already running; else will error
@@ -764,6 +778,10 @@ module Appscript
 			return @_app_class.by_url(url, terms)
 		end
 		
+		def by_aem_app(aem_app, terms=true)
+			return @_app_class.by_aem_app(aem_app, terms)
+		end
+		
 		def current(terms=true)
 			return @_app_class.current(terms)
 		end
@@ -846,5 +864,3 @@ module Appscript
 	
 	ApplicationNotFoundError = FindApp::ApplicationNotFoundError
 end
-
-AS = Appscript # backwards compatibility # TO DO: remove in 0.3.0