rb-appscript 0.2.0

data/src/lib/_appscript/terminology.rb

@@ -0,0 +1,314 @@
+#!/usr/local/bin/ruby
+# Copyright (C) 2006 HAS. 
+# Released under MIT License.
+
+######################################################################
+# TERMINOLOGY PARSER
+######################################################################
+
+module TerminologyParser
+	
+	require "_appscript/reservedkeywords" # names of all existing methods on ASReference::Application
+	
+	class BigEndianParser
+		@@_name_cache = {}
+		LegalFirst = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_'
+		LegalRest = LegalFirst + '0123456789'
+		
+		def initialize
+			@enumerators = {}
+			@properties = {}
+			@commands = {}
+			@_plural_class_names = {}
+			@_singular_class_names = {}
+		end
+		
+		def _integer
+			@_ptr += 2
+			return @_str[@_ptr - 2, 2].unpack('S')[0]
+		end
+		
+		def _word
+			@_ptr += 4
+			return @_str[@_ptr - 4, 4]
+		end
+		
+		def _name
+			count = @_str[@_ptr]
+			@_ptr += 1 + count
+			s = @_str[@_ptr - count, count]
+			if not @@_name_cache.has_key?(s)
+				legal = LegalFirst
+				res = ''
+				s.split(//).each do |c|
+					if legal[c]
+						res += c
+					else
+						case c
+							when ' ', '-', '/'
+								res += '_'
+							when '&'
+								res += 'and'
+						else
+							if res == ''
+								res = '_'
+							end
+							res += "0x#{c.unpack('HXh')}"
+						end
+					end
+					legal = LegalRest
+				end
+				if res[0, 3] == 'AS_' or ReservedKeywords.include?(res) or res[0, 1] == '_'
+					res += '_'
+				end
+				@@_name_cache[s] = res
+			end
+			return @@_name_cache[s]
+		end
+		
+		##
+		
+		def parse_command
+			name = _name
+			@_ptr += 1 + @_str[@_ptr]
+			@_ptr += @_ptr & 1
+			code = _word + _word
+			# 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
+			#
+			current_command_args = []
+			@commands[code] = [name, code, current_command_args]
+			# args
+			_integer.times do
+				parameter_name = _name
+				@_ptr += @_ptr & 1
+				parameter_code = _word
+				@_ptr += 4
+				@_ptr += 1 + @_str[@_ptr]
+				@_ptr += @_ptr & 1
+				@_ptr += 2
+				current_command_args.push([parameter_name, parameter_code])
+			end
+		end
+		
+		def parse_class
+			name = _name
+			@_ptr += @_ptr & 1
+			code = _word
+			@_ptr += 1 + @_str[@_ptr]
+			@_ptr += @_ptr & 1
+			is_plural = false
+			_integer.times do
+				propname = _name
+				@_ptr += @_ptr & 1
+				propcode = _word
+				@_ptr += 4
+				@_ptr += 1 + @_str[@_ptr]
+				@_ptr += @_ptr & 1
+				flags = _integer
+				if propcode != 'c@#^'
+					if flags & 1 == 1
+						is_plural = true
+					else
+						@properties[propcode] = [propname, propcode]
+					end
+				end
+			end
+			_integer.times do
+				@_ptr += 4
+				count = _integer
+				@_ptr += 4 * count
+			end
+			if is_plural
+				@_plural_class_names[code] = [name, code]
+			else
+				@_singular_class_names[code] = [name, code]
+			end
+		end
+		
+		def parse_comparison
+			@_ptr += 1 + @_str[@_ptr]
+			@_ptr += @_ptr & 1
+			@_ptr += 4
+			@_ptr += 1 + @_str[@_ptr]
+			@_ptr += @_ptr & 1
+		end
+		
+		def parse_enumeration
+			@_ptr += 4
+			_integer.times do
+				name = _name
+				@_ptr += @_ptr & 1
+				code = _word
+				@_ptr += 1 + @_str[@_ptr]
+				@_ptr += @_ptr & 1
+				@enumerators[code + name] = [name, code]
+			end
+		end
+		
+		def parse_suite
+			@_ptr += 1 + @_str[@_ptr]
+			@_ptr += 1 + @_str[@_ptr]
+			@_ptr += @_ptr & 1
+			@_ptr += 4
+			@_ptr += 4
+			_integer.times { parse_command }
+			_integer.times { parse_class }
+			_integer.times { parse_comparison }
+			_integer.times { parse_enumeration }
+		end
+		
+		def parse(aetes)
+			aetes.each do |aete|
+				@_str = aete.data
+				@_ptr = 6
+				_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 }
+		end
+	end
+	
+	
+	class LittleEndianParser < BigEndianParser
+		def _word
+			return super.reverse
+		end
+	end
+	
+	
+	#######
+	# Public
+	
+	def TerminologyParser.build_tables_for_aetes(aetes)
+		if [1].pack('S') == "\000\001"
+			return BigEndianParser.new.parse(aetes)
+		else
+			return LittleEndianParser.new.parse(aetes)
+		end
+	end
+
+end
+
+
+######################################################################
+# TERMINOLOGY TABLES BUILDER
+######################################################################
+
+module Terminology
+
+	require "aem"
+	require "_appscript/defaultterminology"
+
+	@@_terminology_cache = {}
+	
+	def Terminology._make_type_table(classes, enums, properties)
+		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|
+				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)
+			end
+		end
+		return [type_by_code, type_by_name]
+	end
+	
+	def Terminology._make_reference_table(properties, elements, 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]
+			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|
+			if DefaultTerminology::DefaultCommands.has_key?(name) and \
+					code != DefaultTerminology::DefaultCommands[name]
+						name += '_'
+			end
+			dct = {}
+			args.each { |arg_name, arg_code| dct[arg_name.intern] = arg_code }
+			reference_by_name[name.intern] = [:command, [code, dct]]
+		end
+		return reference_by_code, reference_by_name
+	end
+	
+	#######
+	# public
+	
+	def Terminology.default_tables
+		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') })
+		return _make_type_table(classes, enums, properties) + _make_reference_table(properties, elements, commands)
+	end
+	
+	##
+	
+	def Terminology.tables_for_module(terms)
+		if terms::Version != 1.1
+			raise RuntimeError, "Unsupported terminology module version: #{terms::Version} (requires version 1.1)."
+		end
+		return _make_type_table(terms::Classes, terms::Enumerators, terms::Properties) \
+			+ _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])
+			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)
+				rescue AEM::CommandError => e
+					if  e.number == -192 # aete resource not found
+						aetes = []
+					else
+						raise
+					end
+				end
+				if not aetes.is_a?(Array)
+					aetes = [aetes]
+				end
+			rescue => err
+				raise RuntimeError, "Can't get terminology for application (#{path or pid or url}): #{err}"
+			end
+			@@_terminology_cache[[path, pid, url]] = Terminology.tables_for_aetes(aetes)
+		end
+		return @@_terminology_cache[[path, pid, url]]
+	end
+end
+

data/src/lib/aem.rb

@@ -0,0 +1,216 @@
+#!/usr/local/bin/ruby
+# Copyright (C) 2006 HAS. 
+# Released under MIT License.
+
+require "ae"
+require "kae"
+require "_aem/findapp"
+require "_aem/mactypes"
+
+module AEM
+
+	# Mid-level wrapper for building and sending Apple events to local and remote applications.
+	
+	require "_aem/codecs"
+	require "_aem/aemreference"
+	require "_aem/typewrappers"
+	require "_aem/connect"
+	require "_aem/send"
+	
+	#######
+	# Constants
+	
+	Codecs = Codecs
+	DefaultCodecs = DefaultCodecs
+	MacOSError = AE::MacOSError
+	
+	AEDesc = AE::AEDesc
+	
+	AETypeBase = TypeWrappers::AETypeBase
+	AEType = TypeWrappers::AEType
+	AEEnum = TypeWrappers::AEEnum
+	AEProp = TypeWrappers::AEProp
+	AEKey = TypeWrappers::AEKey
+	
+	CommandError = Send::CommandError
+	
+	#######
+	# Reference roots
+	
+	def AEM.app
+		return AEMReference::App
+	end
+	
+	def AEM.con
+		return AEMReference::Con
+	end
+	
+	def AEM.its
+		return AEMReference::Its
+	end
+	
+	#######
+	# Application class
+	
+	class Application
+		# Identifies an application and provides an #event method for constructing Apple events targetted at it.
+	
+		require "weakref"
+		
+		private_class_method :new
+		attr_reader :hash, :identity
+		protected :identity
+		
+		#######
+		# Workaround for lack of proper destructors in Ruby; see #initialize method.
+		
+		@@_app_number_count = 0
+		@@_transaction_ids_by_app_no = {}
+
+		#######
+	
+		Event = Send::Event # Application subclasses can override this class constant (usually with a subclass of Send::Event) to modify how Apple events are created and/or sent.
+		
+		#######
+		
+		def initialize(path, address_desc, identity)
+			# called by constructor method
+			# path is used by #reconnect
+			# address_desc is an AEAddressDesc identifying the target application
+			# identity is used by #inspect, #hash, #==
+			@_transaction = KAE::KAnyTransactionID
+			@_path = path
+			@_address = 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.
+			@app_number = app_number = (@@_app_number_count += 1)
+			@@_transaction_ids_by_app_no[app_number] = @_transaction
+			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)
+				end
+			end)
+		end
+	
+		#######
+		# utility class methods; placed here for convenience
+		
+		def Application.launch(path)
+			# Launches a local application without sending it the usual 'run' event (aevtoapp).
+			Connect.launch_app(path)
+		end
+		
+		def Application.is_running?(path)
+			# Checks if a local application is running.
+			return Connect.is_running?(path)
+		end
+		
+		#######
+		# constructors
+		
+		def Application.by_path(path)
+			# path : string  -- full path to local application
+			#
+			# Note: application will be launched if not already running.
+			return new(path, Connect.local_app(path), [:path, path])
+		end
+		
+		def Application.by_url(url)
+			# url : string -- eppc URL for remote process
+			return new(nil, Connect.remote_app(url), [:url, url])
+		end
+		
+		def Application.by_pid(pid)
+			# pid : integer -- Unix process id
+			return new(nil, Connect.local_app_by_pid(pid), [:pid, pid])
+		end
+		
+		def Application.by_desc(desc)
+			# desc : AEDesc -- an AEAddressDesc
+			return new(nil, desc, [:desc, desc.type, desc.data])
+		end
+		
+		def Application.current
+			return new(nil, Connect::CurrentApp, [:current])
+		end
+		
+		#######
+		# methods
+		
+		def inspect
+			if @identity[0] == :current
+				return 'AEM::Application.current'
+			else
+				con_name = {:path => 'by_path', :url => 'by_url', :pid => 'by_pid', :desc => 'by_desc'}[@identity[0]]
+				return "AEM::Application.#{con_name}(#{@identity[1].inspect})"
+			end
+		end
+		
+		alias_method :to_s, :inspect
+		
+		def ==(val)
+			return (self.class == val.class and @identity == val.identity)
+		end
+		
+		alias_method :eql?, :== 
+		
+		# (hash method is provided by attr_reader :hash)
+		
+		def reconnect
+			# If application has quit since this Application object was created, its AEAddressDesc
+			# is no longer valid so this Application object will not work even when application is restarted.
+			# #reconnect will update this Application object's AEAddressDesc so it's valid again.
+			#
+			# 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)
+			end
+			return
+		end
+		
+		def event(event, params={}, atts={}, return_id=KAE::KAutoGenerateReturnID, codecs=DefaultCodecs)
+			# Construct an Apple event targetted at this application.
+			#	event  : string -- 8-letter code indicating event's class, e.g. 'coregetd'
+			#	params : hash -- a dict of form {AE_code:anything,...} containing zero or more event parameters (message arguments)
+			#	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)
+		end
+		
+		def start_transaction(session=nil)
+			# Start a new transaction.
+			if @_transaction != KAE::KAnyTransactionID
+				raise RuntimeError, "Transaction is already active."
+			end
+			@_transaction = self.class::Event.new(@_address, 'miscbegi', session != nil ? {'----' => session} : {}).send
+			@@_transaction_ids_by_app_no[@app_number] = @_transaction
+			return
+		end
+		
+		def abort_transaction
+			# Abort the current transaction.
+			if @_transaction == KAE::KAnyTransactionID
+				raise RuntimeError, "No transaction is active."
+			end
+			self.class::Event.new(@_address, 'miscttrm', {}, {}, @_transaction).send
+			@_transaction = KAE::KAnyTransactionID
+			@@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
+			return
+		end
+		
+		def end_transaction
+			# End the current transaction.
+			if @_transaction == KAE::KAnyTransactionID
+				raise RuntimeError, "No transaction is active."
+			end
+			self.class::Event.new(@_address, 'miscendt', {}, {}, @_transaction).send
+			@_transaction = KAE::KAnyTransactionID
+			@@_transaction_ids_by_app_no[@app_number] = KAE::KAnyTransactionID
+			return
+		end
+	end
+end