rb-appscript 0.5.1 → 0.5.2

data/CHANGES

@@ -1,3 +1,33 @@
+2009-07-05 -- 0.5.2
+
+- removed deprecated AEM::Application.is_running? method
+
+- added #dont_cache_unpacked_specifiers, #pack_strings_as_type compatibility options to AEM::Codecs
+
+- added default definitions for 'item' type, 'items' elements, 'properties' property as Apple have removed the 'item' class definition from skeleton.sdef (the default terminology for Cocoa apps)
+
+- property and elements methods now raise ArgumentError if passed arguments; previously, malformed elements selectors, e.g. app('TextEdit').documents(1).text, would be silently ignored, resulting in unexpected behaviour
+
+- Codecs#unpack now tries to coerce descriptors of typeVersion to unicode text (works on 10.4+) c.f. AppleScript (note: itunes.version.get returns the wrong version number otherwise; this appears to be an iTunes bug, but is masked by current AppleScript behaviour)
+
+- #process_exists_for_url?, #remote_app in connect.rb now raise error if URL string doesn't contain a colon (process will crash otherwise due to an OS bug)
+
+- improved error reporting in Reference#[] when a malformed generic reference containing a command expands to a non-reference value. e.g. its.name.get() would previously expand the the value of the object's 'name' property, typically a string, resulting in a cryptic NoMethodError; this now raises a descriptive ArgumentError.
+
+- fixed bug where Terminology module would error on zero-length keywords in problem dictionaries (e.g. MS Word 12.1.7)
+
+- AEM::Codecs now correctly unpacks AEDescs of typeBoolean whose data >1 byte
+
+- fixed inconsistent escaping of application-defined property/element names that overlap built-in type/enum/property names but uses different codes. e.g. Adobe Illustrator defines 'rotation' as 'SxRx' - this overlaps built-in definition ('rotation' = 'trot'), so is escaped as 'rotation_'. Previously only the Keyword was escaped (i.e. :rotation_ but ref.rotation) now both are escaped (i.e. :rotation_, ref.rotation_). Users should update existing code as needed.
+
+- restructured defaultterminology.rb to make it easier to maintain
+
+- changed default terminology mapping for :data from KAE::CRawData ('rdat') to KAE::TypeData ('tdta')
+
+- the OSAX module now obtains list of installed scripting additions on first use instead of import (the .osax scanning code uses System Events via AEM, and sending Apple events in event loop-based application before the event loop is started can disrupt the process's handling of incoming Apple events)
+
+
+
 2008-02-18 -- 0.5.1
 
 - fixed bug in Appscript::Application#launch where calling it on an application specified by_pid/by_url/by_aem_app would raise error -1708

data/LICENSE

@@ -7,7 +7,7 @@ All code is released under the MIT License, except for the following:
 ======================================================================
 MIT LICENSE
 
-Copyright (C) 2006-2008 HAS
+Copyright (C) 2006-2009 HAS
 
 ======================================================================
 THE RUBY LICENSE

data/README

@@ -27,13 +27,17 @@ Please note that the version of Ruby included with Mac OS X 10.4 (Tiger) is miss
 ======================================================================
 NOTES
 
+- Developer tools for exporting application dictionaries (ASDictionary) and converting application commands from AppleScript to appscript syntax (ASTranslate) are available separately:
+
+	http://appscript.sourceforge.net/tools.html
+
 - This is a beta release. Please file bug reports if you encounter any problems.
 
-- rb-appscript 0.5.1 contains bug and compatibility fixes; see the CHANGES file and documentation for details.
+- rb-appscript 0.5.2 contains bug and compatibility fixes; see the CHANGES file and documentation for details.
 
 - rb-appscript currently provides 64-bit support for OS X 10.5 in the following modules: AE, AEM, Appscript. The OSAX module provides partial 64-bit support; see the osax manual for details.
 
-- ASDictionary 0.9.0 or later is required to use rb-appscript's built-in #help method. If ASDictionary isn't installed, interactive help won't be available but appscript will continue to operate as normal.
+- ASDictionary 0.11.3 or later is required to use rb-appscript's built-in #help method. If ASDictionary isn't installed, interactive help won't be available but appscript will continue to operate as normal.
 
 
 ======================================================================
@@ -44,6 +48,6 @@ AUTHOR
 ======================================================================
 COPYRIGHT
 
-Copyright (C) 2006-2008 HAS 
+Copyright (C) 2006-2009 HAS 
 
 Appscript is released under the MIT License. See the LICENSE file for more information.

data/TODO

@@ -10,4 +10,10 @@ TO DO
 
 - #== and #hash methods in MacTypes::Alias, MacTypes::FileURL lack robustness; see notes in mactypes manual for details. Could these be improved? (Note: some mactypes unit tests may fail in some situations due to 'dumb' nature of these methods.)
 
-- support string encodings in Ruby 1.9
+- support string encodings in Ruby 1.9
+
+- document extended error info methods
+
+- add compatibility flag to AppData for unpacking typeLongDateTime descs as Date instead of Time instances (the latter has limited range)
+
+- fix strict warnings in Ruby 1.9.1

data/doc/aem-manual/01_introduction.html

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 
-<title>aem | 1. Introduction</title>
+<title>rb-aem manual | 1. Introduction</title>
 
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
 <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,23 +10,34 @@
 </head>
 <body>
 
-<h1>1. Introduction</h1>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_apioverview.html">Next</a>
+<a href="index.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="02_apioverview.html">Next</a>
+
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<strong><a href="../aem-manual/index.html">aem</a></strong>
+</span>
 </div>
 
 <!-- content -->
 <div id="content">
 
-<h2>What is aem?</h2>
+<h2>1. Introduction</h2>
+
+<h3>What is aem?</h3>
 
 <p>The aem package provides a mid-level object-oriented wrapper around the low-level ae extension. It provides the following services:</p>
 
 <ul>
 <li>an object-oriented API for constructing Apple Event Object Model queries ("references")</li>
-<li>data conversion between common Ruby and AEM types</li>
+<li>data conversion between common Ruby and Apple event types</li>
 <li>AEAddressDesc creation</li>
 <li>Apple event construction and dispatch.</li>
 </ul>
@@ -38,11 +49,14 @@
 </div>
 
 <!-- bottom navigation -->
-<div class="navbar">
-	<a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_apioverview.html">Next</a>
+
+<div class="footer">
+<a href="index.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="02_apioverview.html">Next</a>
+
+<span>&copy; 2006-2008 HAS</span>
 </div>
 
-<!--footer-->
-<p class="footer">&copy; 2006-2008 HAS</p>
 </body>
 </html>

data/doc/aem-manual/02_apioverview.html

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 
-<title>aem | 2. API overview</title>
+<title>rb-aem manual | 2. API overview</title>
 
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
 <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,19 +10,30 @@
 </head>
 <body>
 
-<h1>2. API overview</h1>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="01_introduction.html">Previous</a> | <a href="index.html">Up</a> | <a href="03_packingandunpackingdata.html">Next</a>
+<a href="01_introduction.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="03_packingandunpackingdata.html">Next</a>
+
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<strong><a href="../aem-manual/index.html">aem</a></strong>
+</span>
 </div>
 
 <!-- content -->
 <div id="content">
 
-<h2>Classes</h2>
+<h2>2. API overview</h2>
 
-<p>The main aem classes are as follows:</p>
+<h3>Classes</h3>
+
+<p>The main AEM classes are as follows:</p>
 
 <dl>
 <dt>Application</dt>
@@ -45,7 +56,7 @@
 <p>In addition, there are a number of classes used to represent application references, although the user does not instantiate these directly.</p>
 
 
-<h2>Attributes</h2>
+<h3>Methods</h3>
 
 <p>The AEM module exports three top-level methods for use in constructing application references:</p>
 
@@ -64,7 +75,7 @@
 <p>References are constructed from these base objects using chained property/method calls.</p>
 
 
-<h2>Modules</h2>
+<h3>Modules</h3> <!-- TO DO: improve; move to top -->
 
 <p>The aem package also exports the following support module:</p>
 
@@ -79,11 +90,14 @@
 </div>
 
 <!-- bottom navigation -->
-<div class="navbar">
-	<a href="01_introduction.html">Previous</a> | <a href="index.html">Up</a> | <a href="03_packingandunpackingdata.html">Next</a>
+
+<div class="footer">
+<a href="01_introduction.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="03_packingandunpackingdata.html">Next</a>
+
+<span>&copy; 2006-2008 HAS</span>
 </div>
 
-<!--footer-->
-<p class="footer">&copy; 2006-2008 HAS</p>
 </body>
 </html>

data/doc/aem-manual/03_packingandunpackingdata.html

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 
-<title>aem | 3. Packing and unpacking data</title>
+<title>rb-aem manual | 3. Packing and unpacking data</title>
 
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
 <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,18 +10,28 @@
 </head>
 <body>
 
-<h1>3. Packing and unpacking data</h1>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="02_apioverview.html">Previous</a> | <a href="index.html">Up</a> | <a href="04_references.html">Next</a>
+<a href="02_apioverview.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="04_references.html">Next</a>
+
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<strong><a href="../aem-manual/index.html">aem</a></strong>
+</span>
 </div>
 
 <!-- content -->
 <div id="content">
 
+<h2>3. Packing and unpacking data</h2>
 
-<h2>Codecs</h2>
+<h3>Codecs</h3>
 
 <p>The <code>AEM::Codecs</code> class provides methods for converting Ruby data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
 
@@ -49,15 +59,7 @@
 
 
 
-<!-- <h3>Notes</h3>
-
-TO DO: customisation options: subclassing and extending pack/unpack, overriding individual encoder/decoder methods and packUnknown/unpackUnknown; when to instantiate/when to modify; notes on appscript integration; notes on differences to py-appscript Codecs? notes on add_unit_types
-
--->
-
-
-
-<h2>AE types</h2>
+<h3>AE types</h3>
 
 <p>The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Ruby. Accordingly, aem defines several classes to represent these types on the Ruby side. All share a common abstract base class, <code>AETypeBase</code>:</p>
 
@@ -88,11 +90,14 @@ AEKey &lt; AETypeBase -- represents an AE object of typeKeyword</code></pre>
 </div>
 
 <!-- bottom navigation -->
-<div class="navbar">
-	<a href="02_apioverview.html">Previous</a> | <a href="index.html">Up</a> | <a href="04_references.html">Next</a>
+
+<div class="footer">
+<a href="02_apioverview.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="04_references.html">Next</a>
+
+<span>&copy; 2006-2008 HAS</span>
 </div>
 
-<!--footer-->
-<p class="footer">&copy; 2006-2008 HAS</p>
 </body>
 </html>

data/doc/aem-manual/04_references.html

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 
-<title>aem | 4. References</title>
+<title>rb-aem manual | 4. References</title>
 
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
 <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,18 +10,28 @@
 </head>
 <body>
 
-<h1>4. References</h1>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="03_packingandunpackingdata.html">Previous</a> | <a href="index.html">Up</a> | <a href="05_targettingapplications.html">Next</a>
+<a href="03_packingandunpackingdata.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="05_targettingapplications.html">Next</a>
+
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<strong><a href="../aem-manual/index.html">aem</a></strong>
+</span>
 </div>
 
 <!-- content -->
 <div id="content">
 
+<h2>4. References</h2>
 
-<h2>About references</h2>
+<h3>About references</h3>
 
 <p>An Apple Event Object Model query (a.k.a. "reference") essentially consists of a linked list made up of one or more Apple event descriptors (AEDescs) of, for the most part, <code>typeObjectSpecifier</code>. Object specifiers are used to identify properties and elements in the application's AEOM. Each object specifer contains four fields:</p>
 
@@ -39,7 +49,7 @@
 <dd>selector data (e.g. in a by-name specifier, this would be a string)</dd>
 </dl>
 
-<p>The Apple Event Manager provides several ways to construct object specifiers and assemble them into a complete reference, but these are all rather verbose and low-level. Aem hides all these details behind an object-oriented wrapper that uses chained property and method calls to gather the data needed to create object specifiers and assemble them into linked lists.</p>
+<p>The Apple Event Manager provides several ways to construct object specifiers and assemble them into a complete reference, but these are all rather verbose and low-level. AEM hides all these details behind an object-oriented wrapper that uses chained property and method calls to gather the data needed to create object specifiers and assemble them into linked lists.</p>
 
 <p>For example, consider the reference <code>text of document 1</code>. The code for constructing this reference using a relatively low-level bridge, in this case RubyAEOSA, would be:</p>
 
@@ -68,19 +78,19 @@ p ref
 
 <p>Now, compare the above with the AEM equivalent:</p>
 
-<pre><code>[[[AEMApp elements: 'docu'] at: 1] property: 'ctxt']</code></pre>
+<pre><code>app.elements('docu').by_index(1).property('ctxt')</code></pre>
 
-<p>As you can see, AEM still uses low-level four-character codes to identify the <code>text</code> property and <code>document</code> class, but is otherwise a high-level object-oriented API. Once again, each reference begins with a root object, in this case <code>AEMApp</code>. New AEM specifiers are constructed by method calls; each call returning a new specifier object whose own methods can be called, and so on. This allows clients to build up a chain of AEM specifier objects that aem can later pack into AEDescs for sending to applications.</p>
+<p>As you can see, AEM still uses low-level four-character codes to identify the <code>text</code> property and <code>document</code> class, but is otherwise a high-level object-oriented API. Once again, each reference begins with a root object, in this case <code>AEM.app</code>. New AEM specifiers are constructed by method calls; each call returning a new specifier object whose own methods can be called, and so on. This allows clients to build up a chain of AEM specifier objects that aem can later pack into AEDescs for sending to applications.</p>
 
-<p>One more thing to notice: in AEM, specifying a class of elements and indicating which of those elements should be selected are performed by separate method calls, although the information provided will eventually be packed into a single AEDesc of <code>typeObjectSpecifier</code>. This two-step approach makes it easier to integrate aem with the higher-level appscript bridge, which also uses two calls to construct element specifiers (one to specify the element class, e.g. <code>-document</code>, and another to specify the selection, e.g. <code>-at:</code>).</p>
+<p>One more thing to notice: in AEM, specifying a class of elements and indicating which of those elements should be selected are performed by separate method calls, although the information provided will eventually be packed into a single AEDesc of <code>typeObjectSpecifier</code>. This two-step approach makes it easier to integrate aem with the higher-level appscript bridge, which also uses two calls to construct element specifiers (one to specify the element class, e.g. <code>#document</code>, and another to specify the selection, e.g. <code>#by_index</code>).</p>
 
-<p>Note that <code>[AEMApp elements: 'docu']</code> is itself a valid reference, identifying <em>all</em> the document elements of the application class. You do not have to call an explicit <code>all</code> selector (indeed, none is provided) as AEM automatically handles the details for you. AEM even allows for some convenient shorthand, e.g. writing:</p>
+<p>Note that <code>app.elements('docu')</code> is itself a valid reference, identifying <em>all</em> the document elements of the application class. You do not have to call an explicit <code>#all</code> selector (indeed, none is provided) as AEM automatically handles the details for you. AEM even allows for some convenient shorthand, e.g. writing:</p>
 
-<pre><code>[[[AEMApp elements: 'docu'] byTest: ...] first]</code></pre>
+<pre><code>app.elements('docu')by_filter(...).first</code></pre>
 
 <p>is equivalent to writing:</p>
 
-<pre><code>[[[[AEMApp elements: 'docu'] byTest: ...] elements: 'docu'] first]</code></pre>
+<pre><code>app.elements('docu')by_filter(...).elements('docu').first</code></pre>
 
 <p>This allows clients to specify the first document that matches the given condition without having to specify the element class a second time. In AppleScript, the equivalent to this is:</p>
 
@@ -94,9 +104,9 @@ p ref
 
 
 
-<h2>Reference forms</h2>
+<h3>Reference forms</h3>
 
-<p>Aem defines a number of classes representing each of the AEOM reference forms. There are eight AEOM reference forms:</p>
+<p>AEM defines a number of classes representing each of the AEOM reference forms. There are eight AEOM reference forms:</p>
 
 <ul>
 <li>insertion location</li>
@@ -121,7 +131,7 @@ p ref
 
 
 
-TO DO: finish
+<!-- TO DO: finish -->
 
 
 <p>In fact, it really isn't necessary to remember the reference class hierarchy at all, only to know which concrete classes implement which methods. All user-accessible properties and methods are defined by just four superclasses:</p>
@@ -142,9 +152,9 @@ TO DO: finish
 
 
 
-<h2>Base classes</h2>
+<h3>Base classes</h3>
 
-<h3>Basic methods</h3>
+<h4>Basic methods</h4>
 
 <pre><code>BASE -- Base class for all reference form and test clause classes.
     hash -- aem references can be used as dictionary keys
@@ -152,7 +162,7 @@ TO DO: finish
     ==(value) -- aem references can be compared for equality</code></pre>
 
 
-<h3>Methods for all position specifiers</h3>
+<h4>Methods for all position specifiers</h4>
 
 <pre><code>PositionSpecifier &lt; Specifier -- base class for all property and element
         reference forms (i.e. all forms except insertion location)
@@ -235,7 +245,7 @@ TO DO: finish
             Result : Test</code></pre>
 
 
-<h3>Methods for all multi-element specifiers</h3>
+<h4>Methods for all multi-element specifiers</h4>
 
 <pre><code>MultipleElements &lt; PositionSpecifier -- base class for all multi-
         element reference forms
@@ -277,7 +287,7 @@ TO DO: finish
             Result : ElementsByFilter</code></pre>
 
 
-<h3>Methods for all test clause classes</h3>
+<h4>Methods for all test clause classes</h4>
 
 <pre><code>Test &lt; BASE -- represents a comparison/logic test
 
@@ -300,14 +310,14 @@ TO DO: finish
 
 
 
-<h2>Concrete classes</h2>
+<h3>Concrete classes</h3>
 
-<h3>Insertion location reference form</h3>
+<h4>Insertion location reference form</h4>
 
 <pre><code>InsertionSpecifier &lt; Specifier -- refers to insertion point before or after/at
         beginning or end of element(s); e.g. ref.before</code></pre>
 
-<h3>Property reference forms</h3>
+<h4>Property reference forms</h4>
 
 <pre><code>Property &lt; PositionSpecifier -- refers to a property (whose value
         may be a basic type, application object or reference);
@@ -318,7 +328,7 @@ UserProperty &lt; PositionSpecifier -- refers to a user-defined property
         (typically in an OSA applet); e.g. ref.user_property('myVar')</code></pre>
 
 
-<h3>Single element reference forms</h3>
+<h4>Single element reference forms</h4>
 
 
 <pre><code>ElementByIndex &lt; SingleElement -- refers to a single element in the referenced 
@@ -341,7 +351,7 @@ ElementByRelativePosition &lt; SingleElement -- refers to the previous or next e
         e.g. ref.next('cpar')</code></pre>
 
 
-<h3>Multiple element reference forms</h3>
+<h4>Multiple element reference forms</h4>
 
 <pre><code>ElementsByRange &lt; MultipleElements -- refers to a range of elements
         in the referenced container object(s) (including beginning and 
@@ -358,23 +368,23 @@ AllElements &lt; MultipleElements -- refers to all elements of the given class
         in the referenced container object(s); e.g. ref.elements('docu')</code></pre>
 
 
-<h3>Tests</h3>
+<h4>Tests</h4>
 
 <p>The <code>Test</code> class represents a comparison test or logical test, and defines methods for composing additional logical tests on top of these. Each kind of test clause is represented by a different subclass of the main <code>Test</code> class. The details are not that important, however, so they're not listed here.</p>
 
 
 
 
-<h3>Reference Roots</h3>
+<h4>Reference Roots</h4>
 
-<pre><code>ApplicationRoot &lt; PositionSpecifier -- AEM.app returns an instance of
-       this class
+<pre><code>ApplicationRoot &lt; PositionSpecifier
+       -- AEM.app returns an instance of this class
 
-CurrentContainer &lt; PositionSpecifier -- AEM.con returns an instance of
-       this class
+CurrentContainer &lt; PositionSpecifier
+       -- AEM.con returns an instance of this class
 
-ObjectBeingExamined &lt; PositionSpecifier -- AEM.its returns an instance
-       of this class</code></pre>
+ObjectBeingExamined &lt; PositionSpecifier
+       -- AEM.its returns an instance of this class</code></pre>
 
 
 
@@ -384,11 +394,14 @@ ObjectBeingExamined &lt; PositionSpecifier -- AEM.its returns an instance
 </div>
 
 <!-- bottom navigation -->
-<div class="navbar">
-	<a href="03_packingandunpackingdata.html">Previous</a> | <a href="index.html">Up</a> | <a href="05_targettingapplications.html">Next</a>
+
+<div class="footer">
+<a href="03_packingandunpackingdata.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="05_targettingapplications.html">Next</a>
+
+<span>&copy; 2006-2008 HAS</span>
 </div>
 
-<!--footer-->
-<p class="footer">&copy; 2006-2008 HAS</p>
 </body>
 </html>