rubyosa 0.2.0 → 0.3.0

data/AUTHORS

@@ -5,5 +5,9 @@ Contributors:
 Aaron Patterson <aaron.patterson@gmail.com>
 James MacAulay <jmacaulay@gmail.com>
 Michael Pruett <michael@68k.org>
+Michail Pishchagin <mblsha@gmail.com>
 Sebastian Delmont <sd@notso.net>
+Stefan Saasen <s@juretta.com>
+Terry Donoghue <donoghue@apple.com>
 Vincent Isambart <vincent.isambart@gmail.com>
+Wes Rogers <wesrog@gmail.com>

data/COPYRIGHT

@@ -1,4 +1,4 @@
-Copyright (c) 2006, Apple Computer, Inc. All rights reserved.
+Copyright (c) 2006-2007, Apple Inc. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
@@ -8,7 +8,7 @@ are met:
 2.  Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution. 
-3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
+3.  Neither the name of Apple Inc. ("Apple") nor the names of
     its contributors may be used to endorse or promote products derived
     from this software without specific prior written permission. 
 

data/README

@@ -24,9 +24,16 @@ libxml-ruby 0.3.8 or greater
 $ ruby extconf.rb
 $ make
 $ sudo make install
+$ sudo make install-extras
+
+`make install' will only install the core of the bridge, while 
+`make install-extras' will install some additional tools such as the rdoc-osa
+utility.
 
 == Support ==
 
+A tutorial is available online at http://rubyosa.rubyforge.org/tutorial.html.
+
 Sample code is available in the `sample' sub-directory.
 
 The rdoc-osa tool can be used to generate API reference documentation

data/bin/rdoc-osa

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
-# RDoc frontend for RubyOSA. Generate API referene documentation for the 
+# RDoc frontend for RubyOSA. Generate API reference documentation for the
 # given application, based on the descriptions in the sdef(5).
 #
-# Copyright (c) 2006, Apple Computer, Inc. All rights reserved.
+# Copyright (c) 2006-2007, Apple Inc. All rights reserved.
 # 
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -12,7 +12,7 @@
 # 2.  Redistributions in binary form must reproduce the above copyright
 #     notice, this list of conditions and the following disclaimer in the
 #     documentation and/or other materials provided with the distribution. 
-# 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
+# 3.  Neither the name of Apple Inc. ("Apple") nor the names of
 #     its contributors may be used to endorse or promote products derived
 #     from this software without specific prior written permission. 
 # 
@@ -30,6 +30,7 @@
 
 require 'rbosa'
 require 'tmpdir'
+require 'rbconfig'
 
 def usage
     STDERR.puts <<-EOS
@@ -55,20 +56,22 @@ end
 
 usage unless ARGV.length >= 2 
 
-msg = case ARGV.first
+key = case ARGV.first
     when '--name'
-        :app_with_name
+        :name
     when '--path'
-        :app_with_path
+        :path
     when '--bundle_id'
-        :app_with_bundle_id
+        :bundle_id
     when '--signature'
-        :app_with_signature
+        :signature
     else
         usage
 end
 
-app = OSA.send(msg, ARGV[1])
+DOC_NOT_AVAILABLE = 'Documentation not available.'
+
+app = OSA.app(key => ARGV[1])
 mod = OSA.const_get(app.class.name.scan(/^OSA::(.+)::Application$/).to_s)
 fake_ruby_src = mod.constants.map do |const_name|
     obj = mod.const_get(const_name)
@@ -76,20 +79,37 @@ fake_ruby_src = mod.constants.map do |const_name|
     when Class
         # Class.
         methods_desc = obj.const_get('METHODS_DESCRIPTION').map do |method|
-            args_doc, args_def = '', ''
+            args_doc, args_def, args_def_opt = '', '', ''
             if method.args and !method.args.empty?
-                args_doc = method.args.map do |x| 
-                    arg = x.name.dup
-                    optional = arg.sub!(/=.+$/, '') != nil
-                    "  # #{arg}::\n  #    #{x.description}" + (optional ? ' Optional.' : '')
-                end.join("\n")
-                args_def = '(' + method.args.map { |x| x.name }.join(', ') + ')'
+                args_doc_ary, args_def_ary, args_def_opt_ary = [], [], []
+                method.args.each do |x| 
+                    arg = x.name
+                    desc = x.description
+                    desc = DOC_NOT_AVAILABLE if desc.empty?
+                    args_doc_ary << "  # #{arg}::\n  #    #{desc}" + (x.optional? ? ' Optional. Can be passed as a Hash key/value.' : '')
+                    if x.optional?
+                        args_def_ary << x.name + '=nil'
+                        args_def_opt_ary << ':' + x.name + ' => nil'
+                    else
+                        args_def_ary << x.name
+                        args_def_opt_ary << x.name
+                    end
+                end
+                args_doc = args_doc_ary.join("\n")
+                args_def = '(' + args_def_ary.join(', ') + ')'
+                args_def_opt = '(' + args_def_opt_ary.join(', ') + ')'
             end
             if method.result
                 args_doc << "\n" unless args_doc.empty?
-                args_doc << "  # Returns::\n  #    #{method.result.description}\n"
+                desc = method.result.description
+                desc = DOC_NOT_AVAILABLE if desc.empty?
+                args_doc << "  # Returns::\n  #    #{desc}\n"
             end
             <<EOS
+  # call-seq:
+  #    #{method.name + args_def}
+  #    #{args_def_opt != args_def ? method.name + args_def_opt : ''}
+  #
   # #{method.description}
 #{args_doc}
   def #{method.name}#{args_def}; end
@@ -134,9 +154,18 @@ module OSA; end
 module #{mod.name}; end
 EOS
 
+rdoc_flags = ''
+template = File.join(Config.datadir('rubyosa'), 'rdoc_html.rb')
+if File.exists?(template)
+    rdoc_flags << " --template '#{template}' "
+end
+rdoc_flags << " --title '#{app.name} RubyOSA API' "
+rdoc_flags << ' --main OSA '
+rdoc_flags << ARGV[2..-1].join(' ')
+
 path = unique_tmp_path(app.name, '.rb')
 File.open(path, 'w') { |io| io.puts fake_ruby_src }
-line = "rdoc #{ARGV[2..-1].join(' ')} \"#{path}\""
+line = "rdoc #{rdoc_flags} \"#{path}\""
 unless system(line)
     STDERR.puts "Error when executing `#{line}' : #{$?}"
     exit 1

data/extconf.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2006, Apple Computer, Inc. All rights reserved.
+# Copyright (c) 2006-2007, Apple Inc. All rights reserved.
 # 
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -8,7 +8,7 @@
 # 2.  Redistributions in binary form must reproduce the above copyright
 #     notice, this list of conditions and the following disclaimer in the
 #     documentation and/or other materials provided with the distribution. 
-# 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
+# 3.  Neither the name of Apple Inc. ("Apple") nor the names of
 #     its contributors may be used to endorse or promote products derived
 #     from this software without specific prior written permission. 
 # 
@@ -50,4 +50,10 @@ new_filename_prefix = 'osx_'
     end
 end
 
+# Generate the Makefile
 create_makefile('osa', 'src')
+
+# Tweak the Makefile to add an extra install task.
+text = File.read('Makefile')
+text << "\n\ninstall-extras: post-install.rb\n\t@$(RUBY) post-install.rb\n\n"
+File.open('Makefile', 'w') { |io| io.write(text) }

data/sample/AddressBook/inspect.rb

@@ -0,0 +1,31 @@
+# Print all the contacts your Address Book contains.
+# Thanks to Stefan Saasen.
+
+begin require 'rubygems'; rescue LoadError; end
+require 'rbosa'
+
+OSA.utf8_strings = true
+
+def print_person(pe)                 
+  puts pe.name
+  unless pe.emails.size < 1
+    puts "\tE-Mail: " + pe.emails.map { |email| 
+      email.value 
+    }.join(', ')
+  end
+  formatted_addresses = pe.addresses.map { |a|
+    # Some malformed addresses can't be formatted and the address book
+    # will therefore return an application-level error, that we handle there.
+    ('(' + a.label + ') ' + a.formatted_address rescue nil)
+  }.compact.map { |a|
+    "\t\t" + a.gsub(/\n/, ' ').strip.squeeze(' ')
+  }
+  unless formatted_addresses.size < 1
+    puts "\tAddresses:\n" + formatted_addresses.join("\n")
+  end
+end                          
+
+ab = OSA.app('Address Book')
+ab.people.each do |pe|
+  print_person pe
+end 

data/sample/Mail/get_selected_mail.rb

@@ -0,0 +1,14 @@
+# Retrieve and show every selected message content in Mail into new TextEdit documents. 
+
+begin require 'rubygems'; rescue LoadError; end
+require 'rbosa'
+
+OSA.utf8_strings = true
+textedit = OSA.app('TextEdit')
+mailApp = OSA.app('Mail')
+viewers = mailApp.message_viewers
+viewers.each do |viewer|
+  viewer.selected_messages.each do |message|
+    textedit.make(OSA::TextEdit::Document).text = message.content
+  end
+end

data/sample/{TextEdit_hello_world.rb → TextEdit/hello_world.rb}

@@ -6,7 +6,7 @@ require 'rbosa'
 textedit = OSA.app('TextEdit')
 
 # Complex way.
-textedit.make(OSA::TextEdit::Document, nil, nil, {:ctxt => 'Hello World #1'})
+textedit.make(OSA::TextEdit::Document, :with_properties => {:text => 'Hello World #1'})
 
 # Easier way.
 textedit.make(OSA::TextEdit::Document).text = 'Hello World #2'

data/sample/iTunes/tag_genre_lastfm.rb

@@ -0,0 +1,20 @@
+# For each selected track in iTunes, retrieve the genre from Last.fm and accordingly tag the track.
+
+begin require 'rubygems'; rescue LoadError; end
+require 'rbosa'
+require 'net/http'
+require 'cgi'
+require 'rexml/document'
+include REXML
+
+itunes = OSA.app('iTunes')
+selection = itunes.selection.get
+if selection.empty?
+  $stderr.puts "Please select some tracks."
+  exit 1
+end
+selection.each do |track|
+  feed = "http://ws.audioscrobbler.com/1.0/artist/#{CGI::escape(track.artist)}/toptags.xml"
+  doc = Document.new(Net::HTTP.get(URI(feed)))
+  track.genre = doc.root[1][1].text
+end

data/sample/{sdef.rb → misc/sdef.rb}

@@ -18,20 +18,20 @@ end
 
 usage unless ARGV.length == 2 
 
-msg = case ARGV.first
+key = case ARGV.first
     when '--name'
-        :app_with_name
+        :name
     when '--path'
-        :app_with_path
+        :path
     when '--bundle_id'
-        :app_with_bundle_id
+        :bundle_id
     when '--signature'
-        :app_with_signature
+        :signature
     else
         usage
 end
 
-app = OSA.send(msg, ARGV.last)
+app = OSA.app(key => ARGV.last)
 doc = REXML::Document.new(app.sdef)
 doc.write(STDOUT, 0)
 puts ""

data/src/lib/rbosa.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2006, Apple Computer, Inc. All rights reserved.
+# Copyright (c) 2006-2007, Apple Inc. All rights reserved.
 # 
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -8,7 +8,7 @@
 # 2.  Redistributions in binary form must reproduce the above copyright
 #     notice, this list of conditions and the following disclaimer in the
 #     documentation and/or other materials provided with the distribution. 
-# 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
+# 3.  Neither the name of Apple Inc. ("Apple") nor the names of
 #     its contributors may be used to endorse or promote products derived
 #     from this software without specific prior written permission. 
 # 
@@ -116,8 +116,8 @@ class OSA::Element
     end
     
     def self.from_rbobj(requested_type, value, enum_group_codes)
-      obj = OSA.convert_to_osa(requested_type, value, enum_group_codes)
-      obj.is_a?(OSA::Element) ? obj : self.__new__(*obj)
+        obj = OSA.convert_to_osa(requested_type, value, enum_group_codes)
+        obj.is_a?(OSA::Element) ? obj : self.__new__(*obj)
     end
 end
 
@@ -129,16 +129,37 @@ class OSA::ElementList
 end
 
 class OSA::ElementRecord
+    def self.from_hash(hash)
+        value = {}
+        hash.each do |code, val| 
+            key = OSA.sym_to_code(code)
+            if key.nil?
+                raise ArgumentError, "invalid key `#{code}'" if code.to_s.length != 4
+                key = code
+            end
+            value[key] = OSA::Element.from_rbobj(nil, val, nil)
+        end
+        OSA::ElementRecord.__new__(value)
+    end
+
     def to_hash
         h = {}
-        self.to_a.each { |key, val| h[key] = val.to_rbobj }
+        self.to_a.each do |code, val|
+            key = (OSA.code_to_sym(code) or code)
+            h[key] = val.to_rbobj
+        end 
         return h
     end
 end
 
 module OSA::ObjectSpecifier
     def get
-        @app.__send_event__('core', 'getd', [['----', self]], true).to_rbobj
+        new_obj = @app.__send_event__('core', 'getd', [['----', self]], true).to_rbobj
+        if !new_obj.is_a?(self.class) and new_obj.is_a?(OSA::Element) and self.respond_to?(:properties) and (klass = self.properties[:class])
+            klass.__duplicate__(new_obj)
+        else
+            new_obj
+        end
     end
 end
 
@@ -150,7 +171,7 @@ class OSA::ObjectSpecifierList
     end
    
     def length
-        @length ||= @app.__send_event__(
+        @app.__send_event__(
             'core', 'cnte', 
             [['----', @container], ['kocl', OSA::Element.__new__('type', @desired_class::CODE.to_4cc)]], 
             true).to_rbobj
@@ -186,6 +207,10 @@ class OSA::ObjectSpecifierList
         and (0..other.length).all? { |i| other[i] == self[i] }
     end
 
+    def inspect
+        super.scan(/^([^ ]+)/).to_s << " desired_class=#{@desired_class}>"
+    end
+
     #######
     private
     #######
@@ -196,25 +221,87 @@ class OSA::ObjectSpecifierList
     end
 end
 
+module OSA::EventDispatcher
+
+    SCRIPTING_ADDITIONS_DIR = [
+        '/System/Library/ScriptingAdditions',
+        '/Library/ScriptingAdditions'
+    ]
+    if home = ENV['HOME']
+        SCRIPTING_ADDITIONS_DIR << File.join(home, '/Library/ScriptingAdditions')
+    end
+
+    def merge(args)
+        args = { :name => args } if args.is_a?(String)
+        by_name = args[:name]
+        begin
+            name, target, sdef = OSA.__scripting_info__(args)
+        rescue RuntimeError => excp
+            # If an sdef bundle can't be find by name, let's be clever and look in the ScriptingAdditions locations.
+            if by_name 
+                args = SCRIPTING_ADDITIONS_DIR.each do |dir|
+                    path = ['.app', '.osax'].map { |e| File.join(dir, by_name + e) }.find { |p| File.exists?(p) }
+                    if path
+                        break { :path => path }
+                    end
+                end 
+                if args.is_a?(Hash)
+                    by_name = nil
+                    retry
+                end
+            end
+            raise excp
+        end
+        app_module_name = self.class.name.scan(/^OSA::(.+)::.+$/).flatten.first
+        app_module = OSA.const_get(app_module_name) 
+        OSA.__load_sdef__(sdef, target, app_module, true, self.class)
+        (self.__send_event__('ascr', 'gdut', [], true) rescue nil) # Don't ask me why...
+        return self 
+    end
+end
+
 module OSA
     def self.app_with_name(name)
-        self.__app__(*OSA.__scripting_info__(:by_name, name))
+        STDERR.puts "OSA.app_with_name() has been deprecated and its usage is now discouraged. Please use OSA.app('name') instead."
+        self.__app__(*OSA.__scripting_info__(:name => name))
     end
 
     def self.app_with_path(path)
-        self.__app__(*OSA.__scripting_info__(:by_path, path))
+        STDERR.puts "OSA.app_by_path() has been deprecated and its usage is now discouraged. Please use OSA.app(:path => 'path') instead."
+        self.__app__(*OSA.__scripting_info__(:path => path))
     end
 
-    def self.app_with_bundle_id(bundle_id)
-        self.__app__(*OSA.__scripting_info__(:by_bundle_id, bundle_id))
+    def self.app_by_bundle_id(bundle_id)
+        STDERR.puts "OSA.app_by_bundle_id() has been deprecated and its usage is now discouraged. Please use OSA.app(:bundle_id => 'bundle_id') instead."
+        self.__app__(*OSA.__scripting_info__(:bundle_id => bundle_id))
     end
 
-    def self.app_with_signature(signature)
-        self.__app__(*OSA.__scripting_info__(:by_signature, signature))
+    def self.app_by_signature(signature)
+        STDERR.puts "OSA.app_by_signature() has been deprecated and its usage is now discouraged. Please use OSA.app(:signature => 'signature') instead."
+        self.__app__(*OSA.__scripting_info__(:signature => signature))
     end
 
-    def self.app(name)
-        self.app_with_name(name)
+    def self.app(*args)
+        if args.size == 2
+            if args.first.is_a?(String) and args.last.is_a?(Hash)
+                hash = args.last
+                if hash.has_key?(:name)
+                    warn "Given Hash argument already has a :name key, ignoring the first String argument `#{args.first}'"
+                else
+                    hash[:name] = args.first
+                end
+                args = hash
+            else
+                raise ArgumentError, "when called with 2 arguments, the first is supposed to be a String and the second a Hash"
+            end
+        else
+            if args.size != 1
+                raise ArgumentError, "wrong number of arguments (#{args.size} for at least 1)"
+            end
+            args = args.first
+        end
+        args = { :name => args } if args.is_a?(String)
+        self.__app__(*OSA.__scripting_info__(args))
     end
 
     @conversions_to_ruby = {}
@@ -253,47 +340,49 @@ module OSA
         end
     end
 
-    def self.convert_to_osa(requested_type, value, enum_group_codes=nil)
-        if requested_type.nil?
-            case value
-            when OSA::Element
-                return value
-            when String
-                requested_type = 'text'
-            when Array
-                requested_type = 'list'
-            when Hash
-                requested_type = 'record'
-            when Integer
-                requested_type = 'integer'
-            else
-                STDERR.puts "can't determine OSA type for #{value}" if $VERBOSE
-                ['null', nil]
-            end
-        end
-
+    def self.__convert_to_osa__(requested_type, value, enum_group_codes=nil)
+        return value if value.is_a?(OSA::Element)
         if conversion = @conversions_to_osa[requested_type]
             args = [value, requested_type]
             conversion.call(*args[0..(conversion.arity - 1)])
         elsif enum_group_codes and enum_group_codes.include?(requested_type)
             ['enum', value.code.to_4cc]
         elsif md = /^list_of_(.+)$/.match(requested_type)
-            ary = value.to_a.map { |x| convert_to_osa(md[1], x, enum_group_codes) }
+            ary = value.to_a.map do |elem| 
+                obj = convert_to_osa(md[1], elem, enum_group_codes) 
+                obj.is_a?(OSA::Element) ? obj : OSA::Element.__new__(*obj)
+            end
             ElementList.__new__(ary)
         else
             STDERR.puts "unrecognized type #{requested_type}" if $VERBOSE
             ['null', nil]
         end
     end
+
+    def self.convert_to_osa(requested_type, value, enum_group_codes=nil)
+        ary = __convert_to_osa__(requested_type, value, enum_group_codes)
+        if ary == ['null', nil]
+            new_type = case value
+                when String then 'text'
+                when Array then 'list'
+                when Hash then 'record'
+                when Integer then 'integer'
+            end
+            if new_type
+                ary = __convert_to_osa__(new_type, value, enum_group_codes)
+            end
+        end
+        ary
+    end
     
     def self.set_params(hash)
         previous_values = {}
         hash.each do |key, val|
-            ivar_key = '@' + key.to_s
-            previous_val = self.instance_variable_get(ivar_key)
-            if previous_val.nil?
+            unless OSA.respond_to?(key)
                 raise ArgumentError, "Invalid key value (no parameter named #{key} was found)"
             end
+            ivar_key = '@' + key.to_s
+            previous_val = self.instance_variable_get(ivar_key)
             previous_values[ivar_key] = previous_val;
             self.instance_variable_set(ivar_key, hash[key])
         end
@@ -310,9 +399,13 @@ module OSA
 
     class DocItem
         attr_reader :name, :description
-        def initialize(name, description)
+        def initialize(name, description, optional=false)
             @name = name
             @description = description
+            @optional = optional
+        end
+        def optional?
+            @optional
         end
     end
 
@@ -328,10 +421,20 @@ module OSA
         end
     end
  
-    def self.__app__(name, signature, sdef)
+    def self.__app__(name, target, sdef)
         @apps ||= {}
-        app = @apps[signature]
+        app = @apps[target]
         return app if app
+
+        # Creates a module for this app, we will define the scripting interface within it.
+        app_module = Module.new
+        self.const_set(rubyfy_constant_string(name), app_module)
+
+        @apps[target] = __load_sdef__(sdef, target, app_module)
+    end
+
+    def self.__load_sdef__(sdef, target, app_module, merge_only=false, app_class=nil)
+        # Load the sdef.
         doc = if USE_LIBXML
             parser = XML::Parser.new
             parser.string = sdef
@@ -340,10 +443,6 @@ module OSA
             REXML::Document.new(sdef)
         end
 
-        # Creates a module for this app, we will define the scripting interface within it.
-        app_module = Module.new
-        self.const_set(rubyfy_constant_string(name), app_module)
-
         # Retrieves and creates enumerations.
         enum_group_codes = {} 
         doc.find('/dictionary/suite/enumeration').each do |element|
@@ -367,14 +466,15 @@ module OSA
                 documentation << DocItem.new(enum_name, englishify_sentence(element['description']))
             end
  
-            app_module.const_set(enum_module_name, enum_module)
+            app_module.const_set(enum_module_name, enum_module) unless app_module.const_defined?(enum_module_name)
         end
 
         # Retrieves and creates classes.
         classes = {}
         class_elements = {}
         doc.find('/dictionary/suite/class').each do |element|
-            (class_elements[element['name']] ||= []) << element
+            key = (element['id'] or element['name'])
+            (class_elements[key] ||= []) << element
         end
         class_elements.values.flatten.each do |element| 
             klass = add_class_from_xml_element(element, class_elements, classes, app_module)
@@ -396,7 +496,7 @@ module OSA
             # Add basic properties that might be missing to the Item class (if any).
             props = {}
             element.find('property').each do |x| 
-                props[x['name']] = [x['code'], x['type'], x['access'], x['description']]
+                props[x['name']] = [x['code'], type_of_parameter(x), x['access'], x['description']]
             end
             if klass.name[-6..-1] == '::Item'
                 unless props.has_key?('id')
@@ -422,60 +522,54 @@ module OSA
                 # Implicit 'get' if the property class is primitive (not defined in the sdef),
                 # otherwise just return an object specifier.
                 method_name = rubyfy_method(name, klass, type)
-                method_code = if pklass.nil?
-                    <<EOC
-def #{method_name}
-    @app.__send_event__('core', 'getd', 
-        [['----', Element.__new_object_specifier__('prop', @app == self ? Element.__new__('null', nil) : self, 
-                                                   'prop', Element.__new__('type', '#{code}'.to_4cc))]],
-        true).to_rbobj
-end
-EOC
+                method_proc = if pklass.nil?
+                    proc do 
+                        @app.__send_event__('core', 'getd', 
+                            [['----', Element.__new_object_specifier__('prop', @app == self ? Element.__new__('null', nil) : self, 
+                            'prop', Element.__new__('type', code.to_4cc))]],
+                            true).to_rbobj
+                    end
                 else
-                    <<EOC
-def #{method_name}
-    o = #{pklass.name}.__new_object_specifier__('prop', @app == self ? Element.__new__('null', nil) : self, 
-                                                'prop', Element.__new__('type', '#{code}'.to_4cc))
-    unless OSA.lazy_events?
-        @app.__send_event__('core', 'getd', [['----', o]], true).to_rbobj
-    else
-        o.instance_variable_set(:@app, @app)
-        o.extend(OSA::ObjectSpecifier)
-    end
-end
-EOC
+                    proc do  
+                        o = pklass.__new_object_specifier__('prop', @app == self ? Element.__new__('null', nil) : self, 
+                                                                    'prop', Element.__new__('type', code.to_4cc))
+                        unless OSA.lazy_events?
+                            @app.__send_event__('core', 'getd', [['----', o]], true).to_rbobj
+                        else
+                            o.instance_variable_set(:@app, @app)
+                            o.extend(OSA::ObjectSpecifier)
+                        end
+                    end
                 end
 
-                klass.class_eval(method_code)
+                klass.class_eval { define_method(method_name, method_proc) }
                 ptypedoc = if pklass.nil?
-                    if mod = enum_group_codes[type]
-                        "a #{mod} enumeration"
-                    else
-                        type
-                    end
+                    type_doc(type, enum_group_codes, app_module)
                 else
                     "a #{pklass} object"
                 end
-                description[0] = description[0].chr.downcase if description
-                methods_doc << DocMethod.new(method_name, englishify_sentence("Gets the #{name} property -- #{description}"), DocItem.new('result', englishify_sentence("the property value, as #{ptypedoc}")), nil)
+                if description
+                    description[0] = description[0].chr.downcase
+                    description = '-- ' << description
+                end 
+                methods_doc << DocMethod.new(method_name, englishify_sentence("Gets the #{name} property #{description}"), DocItem.new('result', englishify_sentence("the property value, as #{ptypedoc}")), nil)
 
                 # For the setter, always send an event.
                 if setter
                     method_name = rubyfy_method(name, klass, type, true)
-                    method_code = <<EOC
-def #{method_name}(val)
-    @app.__send_event__('core', 'setd', 
-        [['----', Element.__new_object_specifier__('prop', @app == self ? Element.__new__('null', nil) : self, 
-                                                   'prop', Element.__new__('type', '#{code}'.to_4cc))],
-         ['data', #{new_element_code(type, 'val', enum_group_codes)}]],
-        true)
-    return nil
-end
-EOC
-
-                    klass.class_eval(method_code)
-                    methods_doc << DocMethod.new(method_name, englishify_sentence("Sets the #{name} property -- #{description}"), nil, [DocItem.new('val', englishify_sentence("the value to be set, as #{ptypedoc}"))])
+                    method_proc = proc do |val|
+                        @app.__send_event__('core', 'setd', 
+                            [['----', Element.__new_object_specifier__('prop', @app == self ? Element.__new__('null', nil) : self, 
+                                                                       'prop', Element.__new__('type', code.to_4cc))],
+                             ['data', val.is_a?(OSA::Element) ? val : Element.from_rbobj(type, val, enum_group_codes.keys)]],
+                            true)
+                        return nil
+                    end
+                    klass.class_eval { define_method(method_name, method_proc) }
+                    methods_doc << DocMethod.new(method_name, englishify_sentence("Sets the #{name} property #{description}"), nil, [DocItem.new('val', englishify_sentence("the value to be set, as #{ptypedoc}"))])
                 end 
+
+                OSA.add_property(name.intern, code)
             end
 
             # Creates elements.
@@ -496,39 +590,49 @@ EOC
                 end
 
                 method_name = rubyfy_method(eklass::PLURAL, klass)
-                method_code = <<EOC
-def #{method_name}
-    unless OSA.lazy_events?
-        @app.__send_event__('core', 'getd', 
-            [['----', Element.__new_object_specifier__(
-                '#{eklass::CODE}'.to_4cc, @app == self ? Element.__new__('null', nil) : self,
-                'indx', Element.__new__('abso', 'all '.to_4cc))]],
-            true).to_rbobj
-    else
-        ObjectSpecifierList.new(@app, #{eklass}, @app == self ? Element.__new__('null', nil) : self)
-    end
-end
-EOC
-
-                klass.class_eval(method_code)
+                method_proc = proc do
+                    unless OSA.lazy_events?
+                        @app.__send_event__('core', 'getd', 
+                            [['----', Element.__new_object_specifier__(
+                                eklass::CODE.to_4cc, @app == self ? Element.__new__('null', nil) : self,
+                                'indx', Element.__new__('abso', 'all '.to_4cc))]],
+                            true).to_rbobj
+                    else
+                        ObjectSpecifierList.new(@app, eklass, @app == self ? Element.__new__('null', nil) : self)
+                    end
+                end
+                klass.class_eval { define_method(method_name, method_proc) }
                 methods_doc << DocMethod.new(method_name, englishify_sentence("Gets the #{eklass::PLURAL} associated with this object"), DocItem.new('result', englishify_sentence("an Array of #{eklass} objects")), nil)
             end
         end
 
-        # Having an 'application' class is required.
-        app_class = classes['application']
-        raise "No application class defined." if app_class.nil?
+        unless merge_only
+            # Having an 'application' class is required.
+            app_class = classes['application']
+            raise "No application class defined." if app_class.nil?
+            all_classes_but_app = classes.values.reject { |x| x.ancestors.include?(OSA::EventDispatcher) }
+        else
+            all_classes_but_app = classes.values
+        end
 
         # Maps commands to the right classes.
-        all_classes_but_app = classes.values.reject { |x| x.ancestors.include?(OSA::EventDispatcher) }
         doc.find('/dictionary/suite/command').each do |element|
             name = element['name']
             next if /NOT AVAILABLE/.match(name) # Finder's sdef (Tiger) names some commands with this 'tag'.
             description = element['description']
-            code = element['code']
             direct_parameter = element.find_first('direct-parameter')
             result = element.find_first('result')           
+            has_result = result != nil
  
+            code = element['code']
+            begin
+                code = Iconv.iconv('MACROMAN', 'UTF-8', code).to_s
+            rescue Iconv::IllegalSequence
+                # We can't do more...
+                STDERR.puts "unrecognized command code encoding '#{code}', skipping..." if $DEBUG
+                next
+            end
+
             classes_to_define = []
             forget_direct_parameter = true
             direct_parameter_optional = false
@@ -567,53 +671,79 @@ EOC
             end
 
             params = []
+            params_doc = []
             unless direct_parameter.nil?
-                params << ['direct', 
-                           '----',
-                           direct_parameter['description'], 
-                           direct_parameter_optional,
-                           type_of_parameter(direct_parameter)]
+                pdesc = direct_parameter['description']
+                params << [
+                    'direct',
+                    '----',
+                    direct_parameter_optional,
+                    type_of_parameter(direct_parameter)
+                ]
+                unless forget_direct_parameter
+                    params_doc << DocItem.new('direct', englishify_sentence(pdesc))
+                end
             end 
 
-            params.concat(element.find('parameter').to_a.map do |element|
-                [rubyfy_string(element['name'], true),
-                 element['code'],
-                 element['description'],
-                 parameter_optional?(element),
-                 type_of_parameter(element)]
-            end)
- 
-            p_dec, p_def, p_args_doc = [], [], []
-            already_has_optional_args = false # Once an argument is optional, all following arguments should be optional.
-            params.each do |pname, pcode, pdesc, optional, ptype|
-                decl = pname
-                self_direct = (pcode == '----' and forget_direct_parameter)
-                defi = if self_direct
-                    forget_direct_parameter ? "(self.is_a?(OSA::EventDispatcher) ? [] : ['----', self])" : "['----', self]"
-                else
-                    "['#{pcode}', #{new_element_code(ptype, pname, enum_group_codes)}]"
+            element.find('parameter').to_a.each do |element|
+                poptional = parameter_optional?(element) 
+                params << [
+                    rubyfy_string(element['name']),
+                    element['code'],
+                    poptional,
+                    type_of_parameter(element)
+                ]
+                params_doc << DocItem.new(rubyfy_string(element['name'], true), englishify_sentence(element['description']), poptional) 
+            end
+
+            method_proc = proc do |*args_ary|
+                args = []
+                min_argc = i = 0
+                already_has_optional_args = false # Once an argument is optional, all following arguments should be optional.
+                optional_hash = nil 
+                params.each do |pname, pcode, optional, ptype|
+                    self_direct = (pcode == '----' and forget_direct_parameter)
+                    if already_has_optional_args or (optional and !self_direct)
+                        already_has_optional_args = true
+                    else
+                        if args_ary.size < i
+                            raise ArgumentError, "wrong number of arguments (#{args_ary.size} for #{i})"
+                        end
+                    end
+                    val = if self_direct
+                        self.is_a?(OSA::EventDispatcher) ? [] : ['----', self]
+                    else
+                        arg = args_ary[i]
+                        min_argc += 1 unless already_has_optional_args
+                        i += 1
+                        if arg.is_a?(Hash) and already_has_optional_args and i >= args_ary.size and min_argc + 1 == i
+                            optional_hash = arg
+                        end
+                        if optional_hash
+                            arg = optional_hash.delete(pname.intern)
+                        end 
+                        if arg.nil?
+                            if already_has_optional_args
+                                []
+                            end
+                        else
+                            [pcode, arg.is_a?(OSA::Element) ? arg : OSA::Element.from_rbobj(ptype, arg, enum_group_codes.keys)]
+                        end
+                    end
+                    args << val
                 end
-                if already_has_optional_args or (optional and !self_direct)
-                    decl += '=nil'
-                    defi = "(#{pname} == nil ? [] : #{defi})"
-                    already_has_optional_args = true
-                end 
-                unless self_direct
-                    p_dec << decl 
-                    p_args_doc << DocItem.new(decl, englishify_sentence(pdesc)) 
+                if args_ary.size > params.size or args_ary.size < min_argc
+                    raise ArgumentError, "wrong number of arguments (#{args_ary.size} for #{min_argc})"
+                end
+                if optional_hash and !optional_hash.empty?
+                    raise ArgumentError, "inappropriate optional argument(s): #{optional_hash.keys.join(', ')}"
                 end
-                p_def << defi
+                wait_reply = (OSA.wait_reply != nil ? OSA.wait_reply : (has_result or @app.remote?)) 
+                ret = @app.__send_event__(code[0..3], code[4..-1], args, wait_reply)
+                wait_reply ? ret.to_rbobj : ret
             end
 
-            code = Iconv.iconv('MACROMAN', 'UTF-8', code).to_s
-
-            method_code = <<EOC
-def %METHOD_NAME%(#{p_dec.join(', ')})
-  @app.__send_event__('#{code[0..3]}', '#{code[4..-1]}', [#{p_def.join(', ')}], #{result != nil})#{result != nil ? '.to_rbobj' : ''}
-end
-EOC
-
-            if result.nil?
+            unless has_result
                 result_type = result_doc = nil
             else
                 result_type = type_of_parameter(result)
@@ -623,22 +753,27 @@ EOC
 
             classes_to_define.each do |klass|
                 method_name = rubyfy_method(name, klass, result_type)
-                code = method_code.sub(/%METHOD_NAME%/, method_name)
-                klass.class_eval(code)
+                klass.class_eval { define_method(method_name, method_proc) }
                 methods_doc = klass.const_get(:METHODS_DESCRIPTION)
-                methods_doc << DocMethod.new(method_name, englishify_sentence(description), result_doc, p_args_doc)
+                methods_doc << DocMethod.new(method_name, englishify_sentence(description), result_doc, params_doc)
             end
         end
 
-        # Returns an application instance, that's all folks!
-        hash = {}
-        classes.each_value { |klass| hash[klass::CODE] = klass } 
-        app = app_class.__new__('sign', signature.to_4cc)
-        app.instance_variable_set(:@sdef, sdef)
-        app.instance_variable_set(:@classes, hash)
-        app.instance_eval 'def sdef; @sdef; end'
-        app.extend OSA::EventDispatcher
-        @apps[signature] = app
+        unless merge_only
+            # Returns an application instance, that's all folks!
+            hash = {}
+            classes.each_value { |klass| hash[klass::CODE] = klass } 
+            app_class.class_eval do 
+                attr_reader :sdef
+                define_method(:remote?) { @is_remote == true }
+            end
+            is_remote = target.length > 4
+            app = is_remote ? app_class.__new__('aprl', target) : app_class.__new__('sign', target.to_4cc)
+            app.instance_variable_set(:@is_remote, is_remote)
+            app.instance_variable_set(:@sdef, sdef)
+            app.instance_variable_set(:@classes, hash)
+            app.extend OSA::EventDispatcher
+        end
     end
 
     def self.parameter_optional?(element)
@@ -647,7 +782,8 @@ EOC
 
     def self.add_class_from_xml_element(element, class_elements, repository, app_module)
         real_name = element['name']
-        klass = repository[real_name]
+        key = (element['id'] or real_name)
+        klass = repository[key]
         if klass.nil?
             code = element['code']
             inherits = element['inherits']
@@ -674,7 +810,7 @@ EOC
                 end
             end
 
-            klass.class_eval 'include OSA::EventDispatcher' if real_name == 'application'
+            klass.class_eval { include OSA::EventDispatcher } if real_name == 'application'
 
             klass.const_set(:REAL_NAME, real_name) unless klass.const_defined?(:REAL_NAME)
             klass.const_set(:PLURAL, plural == nil ? real_name + 's' : plural) unless klass.const_defined?(:PLURAL)
@@ -682,30 +818,45 @@ EOC
             
             app_module.const_set(rubyfy_constant_string(real_name), klass)
 
-            repository[real_name] = klass
+            repository[key] = klass
         end 
 
         return klass
     end
     
+    def self.type_doc(type, enum_group_codes, app_module)
+        if mod = enum_group_codes[type]
+            mod.to_s 
+        elsif md = /^list_of_(.+)$/.match(type)
+            "list of #{type_doc(md[1], enum_group_codes, app_module)}"
+        else
+            up_type = type.upcase
+            begin
+                app_module.const_get(up_type).to_s
+            rescue 
+                type
+            end
+        end
+    end
+
     def self.type_of_parameter(element)
         type = element['type']
         if type.nil?
             etype = element.find_first('type')
-            if etype.nil? or (type = etype['type']).nil?
-                raise "Parameter #{element} has no type."
+            if etype
+                type = etype['type']
+                if type.nil? and (etype2 = etype.find_first('type')) != nil
+                    type = etype2['type']
+                end
+                type = "list_of_#{type}" if etype['list'] == 'yes'
             end
-            type = "list_of_#{type}" if etype['list'] == 'yes'
         end
+        raise "Parameter #{element} has no type." if type.nil?
         return type
     end
 
-    def self.new_element_code(type, varname, enum_group_codes)
-        "#{varname}.is_a?(OSA::Element) ? #{varname} : Element.from_rbobj('#{type}', #{varname}, #{enum_group_codes.keys.inspect})" 
-    end
-
     def self.escape_string(string)
-        string.gsub(/[\s\-\.\/]/, '_').gsub(/&/, 'and')
+        string.gsub(/[\$\=\s\-\.\/]/, '_').gsub(/&/, 'and')
     end
 
     def self.rubyfy_constant_string(string, upcase=false)
@@ -751,6 +902,7 @@ EOC
     def self.englishify_sentence(string)
         return '' if string.nil?
         string[0] = string[0].chr.upcase
+        string.strip!
         last = string[-1].chr
         string << '.' if last != '.' and last != '?' and last != '!'
         return string
@@ -766,7 +918,7 @@ OSA.add_conversion_to_osa('Unicode text') { |value| [OSA.utf8_strings ? 'utf8' :
 # Signed/unsigned integer. 
 OSA.add_conversion_to_ruby('shor', 'long') { |value| value.unpack('l').first }
 OSA.add_conversion_to_ruby('comp') { |value| value.unpack('q').first }
-OSA.add_conversion_to_ruby('magn') { |value| value.unpack('d').first }
+OSA.add_conversion_to_ruby('magn', 'doub') { |value| value.unpack('d').first }
 OSA.add_conversion_to_osa('integer', 'double integer') { |value| ['magn', [value].pack('l')] }
 
 # Float
@@ -791,14 +943,15 @@ OSA.add_conversion_to_ruby('list') { |value, type, object|
 # File name.
 # Let's use the 'furl' type here instead of 'alis', as we don't have a way to produce an alias for a file that does not exist yet.
 OSA.add_conversion_to_osa('alias', 'file') { |value| ['furl', value.to_s] }
-OSA.add_conversion_to_ruby('alis') { |value, type, object| URI.parse(object.__data__('furl')).path } 
+OSA.add_conversion_to_ruby('alis') do |value, type, object| 
+  URI.unescape(URI.parse(object.__data__('furl')).path)
+end 
 
 # Hash.
 OSA.add_conversion_to_ruby('reco') { |value, type, object| object.is_a?(OSA::ElementRecord) ? object.to_hash : value }
 OSA.add_conversion_to_osa('record') do |value| 
     if value.is_a?(Hash)
-        value.each { |key, val| value[key] = OSA::Element.from_rbobj(nil, val, nil) } 
-        OSA::ElementRecord.__new__(value)
+        OSA::ElementRecord.from_hash(value)
     else
         value 
     end 
@@ -808,7 +961,7 @@ end
 OSA.add_conversion_to_ruby('enum') { |value, type, object| OSA::Enumerator.enum_for_code(object.__data__('TEXT')) or object }
 
 # Class.
-OSA.add_conversion_to_osa('type class') { |value| value.is_a?(Class) and value.ancestors.include?(OSA::Element) ? ['type', value::CODE.to_4cc] : value } 
+OSA.add_conversion_to_osa('type class', 'type') { |value| value.is_a?(Class) and value.ancestors.include?(OSA::Element) ? ['type', value::CODE.to_4cc] : value } 
 OSA.add_conversion_to_ruby('type') do |value, type, object| 
   if value == 'msng' 
     # Missing values.
@@ -827,5 +980,8 @@ OSA.add_conversion_to_osa('bounding rectangle') { |value| ['qdrt', value.pack('S
 OSA.add_conversion_to_ruby('PICT') { |value, type, object| value[222..-1] } # Removing trailing garbage.
 OSA.add_conversion_to_osa('picture') { |value| ['PICT', value.to_s] }
 OSA.add_conversion_to_ruby('imaA') { |value, type, object| value }
+OSA.add_conversion_to_ruby('TIFF') { |value, type, object| value }
 OSA.add_conversion_to_osa('Image') { |value| ['imaA', value.to_s] }
 OSA.add_conversion_to_osa('TIFF picture') { |value| ['TIFF', value.to_s] }
+
+require 'rbosa_properties'