rb-appscript 0.2.1 → 0.3.0

data/src/lib/_appscript/terminology.rb

@@ -14,26 +14,43 @@ module TerminologyParser
 		@@_name_cache = {}
 		LegalFirst = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_'
 		LegalRest = LegalFirst + '0123456789'
+		@@_reserved_keywords = {} # ersatz set
+		ReservedKeywords.each { |name| @@_reserved_keywords[name] = nil }
 		
 		def initialize
-			@enumerators = {}
-			@properties = {}
+			# terminology tables; order is significant where synonym definitions occur
 			@commands = {}
-			@_plural_class_names = {}
-			@_singular_class_names = {}
+			@properties = []
+			@elements = []
+			@classes = []
+			@enumerators = []
+			# use ersatz sets to record previously found definitions, and avoid adding duplicates to lists
+			# (i.e. 'name+code not in <set>' is quicker than using 'name+code not in <list>')
+			@_found_properties = {} # set
+			@_found_elements = {} # set
+			@_found_classes = {} # set
+			@_found_enumerators = {} # set
+			# ideally, aetes should define both singular and plural names for each class, but
+			# some define only one or the other so we need to fill in any missing ones afterwards
+			@_spare_class_names = {} # names by code
+			@_found_class_codes = {} # set
+			@_found_element_codes = {} # set
 		end
 		
 		def _integer
+			# Read a 2-byte integer.
 			@_ptr += 2
 			return @_str[@_ptr - 2, 2].unpack('S')[0]
 		end
 		
 		def _word
+			# Read a 4-byte string (really a long, but represented as an 4-character 8-bit string for readability).
 			@_ptr += 4
-			return @_str[@_ptr - 4, 4]
+			return @_str[@_ptr - 4, 4] # big-endian
 		end
 		
 		def _name
+			# Read a MacRoman-encoded Pascal keyword string.
 			count = @_str[@_ptr]
 			@_ptr += 1 + count
 			s = @_str[@_ptr - count, count]
@@ -58,7 +75,7 @@ module TerminologyParser
 					end
 					legal = LegalRest
 				end
-				if res[0, 3] == 'AS_' or ReservedKeywords.include?(res) or res[0, 1] == '_'
+				if res[0, 3] == 'AS_' or @@_reserved_keywords.has_key?(res) or res[0, 1] == '_'
 					res += '_'
 				end
 				@@_name_cache[s] = res
@@ -70,96 +87,115 @@ module TerminologyParser
 		
 		def parse_command
 			name = _name
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
-			code = _word + _word
+			@_ptr += 1 + @_str[@_ptr] # description string
+			@_ptr += @_ptr & 1 # align
+			code = _word + _word # event class + event id
 			# skip result
-			@_ptr += 4
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
-			@_ptr += 2
-			# skip direct
-			@_ptr += 4
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
-			@_ptr += 2
+			@_ptr += 4 # datatype word
+			@_ptr += 1 + @_str[@_ptr] # description string
+			@_ptr += @_ptr & 1 # align
+			@_ptr += 2 # flags integer
+			# skip direct parameter
+			@_ptr += 4 # datatype word
+			@_ptr += 1 + @_str[@_ptr] # description string
+			@_ptr += @_ptr & 1 # align
+			@_ptr += 2 # flags integer
 			#
 			current_command_args = []
-			@commands[code] = [name, code, current_command_args]
-			# args
+			# Note: overlapping command definitions (e.g. InDesign) should be processed as follows:
+			# - If their names and codes are the same, only the last definition is used; other definitions are ignored and will not compile.
+			# - If their names are the same but their codes are different, only the first definition is used; other definitions are ignored and will not compile.
+			# - If a dictionary-defined command has the same name but different code to a built-in definition, escape its name so it doesn't conflict with the default built-in definition.
+			if not @commands.has_key?(name) or @commands[name][1] == code
+				@commands[name] = [name, code, current_command_args]
+			end
+			# add labelled parameters
 			_integer.times do
 				parameter_name = _name
-				@_ptr += @_ptr & 1
+				@_ptr += @_ptr & 1 # align
 				parameter_code = _word
-				@_ptr += 4
-				@_ptr += 1 + @_str[@_ptr]
-				@_ptr += @_ptr & 1
-				@_ptr += 2
+				@_ptr += 4 # datatype word
+				@_ptr += 1 + @_str[@_ptr] # description string
+				@_ptr += @_ptr & 1 # align
+				@_ptr += 2 # flags integer
 				current_command_args.push([parameter_name, parameter_code])
 			end
 		end
 		
 		def parse_class
 			name = _name
-			@_ptr += @_ptr & 1
+			@_ptr += @_ptr & 1 # align
 			code = _word
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
+			@_ptr += 1 + @_str[@_ptr] # description string
+			@_ptr += @_ptr & 1 # align
 			is_plural = false
-			_integer.times do
+			_integer.times do # properties
 				propname = _name
-				@_ptr += @_ptr & 1
+				@_ptr += @_ptr & 1 # align
 				propcode = _word
-				@_ptr += 4
-				@_ptr += 1 + @_str[@_ptr]
-				@_ptr += @_ptr & 1
+				@_ptr += 4 # datatype word
+				@_ptr += 1 + @_str[@_ptr] # description string
+				@_ptr += @_ptr & 1 # align
 				flags = _integer
-				if propcode != 'c@#^'
-					if flags & 1 == 1
+				if propcode != 'c@#^' # not a superclass definition (see kAEInheritedProperties)
+					if flags & 1 == 1 # indicates class name is plural (see kAESpecialClassProperties)
 						is_plural = true
-					else
-						@properties[propcode] = [propname, propcode]
+					elsif not @_found_properties.has_key?(propname + propcode)
+						@properties.push([propname, propcode]) # preserve ordering
+						@_found_properties[propname + propcode] = nil # add to found set
 					end
 				end
 			end
-			_integer.times do
-				@_ptr += 4
+			_integer.times do # skip elements
+				@_ptr += 4 # code word
 				count = _integer
-				@_ptr += 4 * count
+				@_ptr += 4 * count # reference forms
 			end
 			if is_plural
-				@_plural_class_names[code] = [name, code]
+				if not @_found_elements.has_key?(name + code)
+					@elements.push([name, code])
+					@_found_elements[name + code] = nil # add to found set
+					@_found_element_codes[code] = nil # add to found set
+				end
 			else
-				@_singular_class_names[code] = [name, code]
+				if not @_found_classes.has_key?(name + code)
+					@classes.push([name, code])
+					@_found_classes[name + code] = nil # add to found set
+					@_found_class_codes[code] = nil # add to found set
+				end
 			end
+			@_spare_class_names[code] = name
 		end
 		
-		def parse_comparison
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
-			@_ptr += 4
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
+		def parse_comparison # comparison info isn't used
+			@_ptr += 1 + @_str[@_ptr] # name string
+			@_ptr += @_ptr & 1 # align
+			@_ptr += 4 # code word
+			@_ptr += 1 + @_str[@_ptr] # description string
+			@_ptr += @_ptr & 1 # align
 		end
 		
 		def parse_enumeration
-			@_ptr += 4
-			_integer.times do
+			@_ptr += 4 # code word
+			_integer.times do # enumerators
 				name = _name
-				@_ptr += @_ptr & 1
+				@_ptr += @_ptr & 1 # align
 				code = _word
-				@_ptr += 1 + @_str[@_ptr]
-				@_ptr += @_ptr & 1
-				@enumerators[code + name] = [name, code]
+				@_ptr += 1 + @_str[@_ptr] # description string
+				@_ptr += @_ptr & 1 # align
+				if not @_found_enumerators.has_key?(name + code)
+					@enumerators.push([name, code])
+					@_found_enumerators[name + code] = nil # add to found set
+				end
 			end
 		end
 		
 		def parse_suite
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += 1 + @_str[@_ptr]
-			@_ptr += @_ptr & 1
-			@_ptr += 4
-			@_ptr += 4
+			@_ptr += 1 + @_str[@_ptr] # name string
+			@_ptr += 1 + @_str[@_ptr] # description string
+			@_ptr += @_ptr & 1 # align
+			@_ptr += 4 # code word
+			@_ptr += 4 # level, version integers
 			_integer.times { parse_command }
 			_integer.times { parse_class }
 			_integer.times { parse_comparison }
@@ -169,24 +205,30 @@ module TerminologyParser
 		def parse(aetes)
 			aetes.each do |aete|
 				@_str = aete.data
-				@_ptr = 6
+				@_ptr = 6 # version, language, script integers
 				_integer.times { parse_suite }
 				if not @_ptr == @_str.length
 					raise RuntimeError, "aete was not fully parsed."
 				end
 			end
-			classes = @_plural_class_names.clone
-			classes.update(@_singular_class_names)
-			elements = @_singular_class_names.clone
-			elements.update(@_plural_class_names)
-			return [classes, @enumerators, @properties, elements, @commands].map! { |d| d.values }
+			# singular names are normally used in the classes table and plural names in the elements table. However, if an aete defines a singular name but not a plural name then the missing plural name is substituted with the singular name; and vice-versa if there's no singular equivalent for a plural name.
+			missing_elements = @_found_class_codes.keys - @_found_element_codes.keys
+			missing_classes = @_found_element_codes.keys - @_found_class_codes.keys
+			missing_elements.each do |code|
+				@elements.push([@_spare_class_names[code], code])
+			end
+			missing_classes.each do |code|
+				@classes.push([@_spare_class_names[code], code])
+			end
+			return [@classes, @enumerators, @properties, @elements, @commands.values]
 		end
 	end
 	
 	
 	class LittleEndianParser < BigEndianParser
 		def _word
-			return super.reverse
+			# Read a 4-byte string (really a long, but represented as an 4-character 8-bit string for readability).
+			return super.reverse # little-endian
 		end
 	end
 	
@@ -195,7 +237,7 @@ module TerminologyParser
 	# Public
 	
 	def TerminologyParser.build_tables_for_aetes(aetes)
-		if [1].pack('S') == "\000\001"
+		if [1].pack('S') == "\000\001" # is it big-endian?
 			return BigEndianParser.new.parse(aetes)
 		else
 			return LittleEndianParser.new.parse(aetes)
@@ -217,35 +259,47 @@ module Terminology
 	@@_terminology_cache = {}
 	
 	def Terminology._make_type_table(classes, enums, properties)
+		# builds tables used for converting symbols to/from AEType, AEEnums
 		type_by_code = DefaultTerminology::TypeByCode.clone
 		type_by_name = DefaultTerminology::TypeByName.clone
 		[[AEM::AEType, properties], [AEM::AEEnum, enums], [AEM::AEType, classes]].each do |klass, table|
-			table.each do |name, code|
+			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 += '_'
+				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 += '_'
 				end
-				type_by_code[code] = name.intern
-				type_by_name[name.intern] = klass.new(code)
+				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]
 	end
 	
 	def Terminology._make_reference_table(properties, elements, commands)
+		# builds tables used for constructing references and commands
 		reference_by_code = DefaultTerminology::ReferenceByCode.clone
 		reference_by_name = DefaultTerminology::ReferenceByName.clone
 		[[:element, elements, 'e'], [:property, properties, 'p']].each do |kind, table, prefix|
 			# 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 do |name, code|
-				reference_by_code[prefix + code] = name
-				reference_by_name[name.intern] = [kind, code]
+			table.each_with_index do |item, i|
+				name, code = item
+				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
 			end
 		end
 		if reference_by_name.has_key?(:text) # special case: AppleScript always packs 'text of...' as all-elements specifier
 			reference_by_name[:text][0] = :element
 		end
-		commands.reverse.each do |name, code, args|
+		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 += '_'
@@ -261,17 +315,22 @@ module Terminology
 	# public
 	
 	def Terminology.default_tables
+		# [typebycode, typebyname, referencebycode, referencebyname]
 		return _make_type_table([], [], []) + _make_reference_table([], [], [])
 	end
 	
 	def Terminology.tables_for_aetes(aetes)
-		classes, enums, properties, elements, commands = TerminologyParser.build_tables_for_aetes(aetes.delete_if { |aete| not (aete.is_a?(AE::AEDesc) and aete.type == 'aete') })
+		# Build terminology tables from a list of unpacked aete byte strings.
+		# Result : list of hash -- [typebycode, typebyname, referencebycode, referencebyname]
+		classes, enums, properties, elements, commands = TerminologyParser.build_tables_for_aetes(aetes.delete_if { |aete| not (aete.is_a?(AE::AEDesc) and aete.type == KAE::TypeAETE) })
 		return _make_type_table(classes, enums, properties) + _make_reference_table(properties, elements, commands)
 	end
 	
 	##
 	
 	def Terminology.tables_for_module(terms)
+		# Build terminology tables from a dumped terminology module.
+		# Result : list of hash -- [typebycode, typebyname, referencebycode, referencebyname]
 		if terms::Version != 1.1
 			raise RuntimeError, "Unsupported terminology module version: #{terms::Version} (requires version 1.1)."
 		end
@@ -279,20 +338,14 @@ module Terminology
 			+ _make_reference_table(terms::Properties, terms::Elements, terms::Commands)
 	end
 	
-	def Terminology.tables_for_app(path, pid, url)
-		if not @@_terminology_cache.has_key?([path, pid, url])
+	def Terminology.tables_for_app(aem_app)
+		# Build terminology tables for an application.
+		# app : AEM::Application
+		# Result : list of hash -- [typebycode, typebyname, referencebycode, referencebyname]
+		if not @@_terminology_cache.has_key?(aem_app.identity)
 			begin
-				if path
-					app = AEM::Application.by_path(path)
-				elsif pid
-					app = AEM::Application.by_pid(pid)
-				elsif url
-					app = AEM::Application.by_url(url)
-				else
-					app = AEM::Application.current
-				end
 				begin
-					aetes = app.event('ascrgdte', {'----' => 0}).send(30 * 60)
+					aetes = aem_app.event('ascrgdte', {'----' => 0}).send(60 * 60)
 				rescue AEM::CommandError => e
 					if  e.number == -192 # aete resource not found
 						aetes = []
@@ -304,11 +357,63 @@ module Terminology
 					aetes = [aetes]
 				end
 			rescue => err
-				raise RuntimeError, "Can't get terminology for application (#{path or pid or url}): #{err}"
+				raise RuntimeError, "Can't get terminology for application (#{aem_app}): #{err}"
+			end
+			@@_terminology_cache[aem_app.identity] = Terminology.tables_for_aetes(aetes)
+		end
+		return @@_terminology_cache[aem_app.identity]
+	end
+	
+	#######
+	
+	def Terminology.dump(app_name, module_name, out_path)
+		# Export 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
+		app_path = FindApp.by_name(app_name)
+		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|
+			# Get aete(s)
+			begin
+				aetes = AEM::Codecs.new.unpack(AE.get_app_terminology(app_path).coerce(KAE::TypeAEList))
+			rescue AE::MacOSError => e
+				if  e.to_i == -192 # aete resource not found
+					raise RuntimeError, "No terminology found."
+				else
+					raise
+				end
+			end
+			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 code
+			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
-			@@_terminology_cache[[path, pid, url]] = Terminology.tables_for_aetes(aetes)
+			f.puts "\t]"
+			f.puts "end"
 		end
-		return @@_terminology_cache[[path, pid, url]]
 	end
 end
 

data/src/lib/aem.rb

@@ -58,8 +58,7 @@ module AEM
 		require "weakref"
 		
 		private_class_method :new
-		attr_reader :hash, :identity
-		protected :identity
+		attr_reader :hash, :identity, :address_desc
 		
 		#######
 		# Workaround for lack of proper destructors in Ruby; see #initialize method.
@@ -80,7 +79,7 @@ module AEM
 			# identity is used by #inspect, #hash, #==
 			@_transaction = KAE::KAnyTransactionID
 			@_path = path
-			@_address = address_desc
+			@address_desc = address_desc
 			@identity = identity
 			@hash = identity.hash
 			# workaround for lack of proper destructors; if a transaction is still open when Application instance is garbage collected, the following finalizer will automatically close it. Note: object IDs were different for some reason, so class maintains its own unique ids.
@@ -89,7 +88,7 @@ module AEM
 			ObjectSpace.define_finalizer(WeakRef.new(self), proc do
 				transaction_id = @@_transaction_ids_by_app_no.delete(app_number)
 				if transaction_id != KAE::KAnyTransactionID
-					self.class::Event.new(@_address, 'miscendt', {}, {}, transaction_id).send(60, KAE::KAENoReply)
+					self.class::Event.new(@address_desc, 'miscendt', {}, {}, transaction_id).send(60, KAE::KAENoReply)
 				end
 			end)
 		end
@@ -166,7 +165,7 @@ module AEM
 			# Note that this only works for Application objects created via the by_path constructor. 
 			# Also note that any Event objects created prior to calling #reconnect will still be invalid.
 			if @_path
-				@_address = Connect.local_app(@_path)
+				@address_desc = Connect.local_app(@_path)
 			end
 			return
 		end
@@ -178,7 +177,7 @@ module AEM
 			#	atts : hash -- a dict of form {AE_code:anything,...} containing zero or more event attributes (event info)
 			#	return_id : integer  -- reply event's ID
 			#	codecs : Codecs -- codecs object to use when packing/unpacking this event
-			return self.class::Event.new(@_address, event, params, atts, @_transaction, return_id, codecs)
+			return self.class::Event.new(@address_desc, event, params, atts, @_transaction, return_id, codecs)
 		end
 		
 		def start_transaction(session=nil)
@@ -186,7 +185,7 @@ module AEM
 			if @_transaction != KAE::KAnyTransactionID
 				raise RuntimeError, "Transaction is already active."
 			end
-			@_transaction = self.class::Event.new(@_address, 'miscbegi', session != nil ? {'----' => session} : {}).send
+			@_transaction = self.class::Event.new(@address_desc, 'miscbegi', session != nil ? {'----' => session} : {}).send
 			@@_transaction_ids_by_app_no[@app_number] = @_transaction
 			return
 		end
@@ -196,7 +195,7 @@ module AEM
 			if @_transaction == KAE::KAnyTransactionID
 				raise RuntimeError, "No transaction is active."
 			end
-			self.class::Event.new(@_address, 'miscttrm', {}, {}, @_transaction).send
+			self.class::Event.new(@address_desc, 'miscttrm', {}, {}, @_transaction).send
 			@_transaction = KAE::KAnyTransactionID
 			@@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
 			return
@@ -207,7 +206,7 @@ module AEM
 			if @_transaction == KAE::KAnyTransactionID
 				raise RuntimeError, "No transaction is active."
 			end
-			self.class::Event.new(@_address, 'miscendt', {}, {}, @_transaction).send
+			self.class::Event.new(@address_desc, 'miscendt', {}, {}, @_transaction).send
 			@_transaction = KAE::KAnyTransactionID
 			@@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
 			return