rb-appscript 0.4.0 → 0.5.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (48) hide show
  1. data/CHANGES +37 -0
  2. data/LICENSE +6 -2
  3. data/README +7 -4
  4. data/TODO +6 -2
  5. data/doc/aem-manual/01_introduction.html +1 -1
  6. data/doc/aem-manual/02_apioverview.html +1 -1
  7. data/doc/aem-manual/03_packingandunpackingdata.html +3 -3
  8. data/doc/aem-manual/04_references.html +18 -13
  9. data/doc/aem-manual/05_targettingapplications.html +33 -13
  10. data/doc/aem-manual/06_buildingandsendingevents.html +1 -1
  11. data/doc/aem-manual/07_findapp.html +1 -1
  12. data/doc/aem-manual/08_examples.html +1 -1
  13. data/doc/aem-manual/index.html +1 -1
  14. data/doc/appscript-manual/01_introduction.html +1 -1
  15. data/doc/appscript-manual/02_aboutappscripting.html +4 -4
  16. data/doc/appscript-manual/03_quicktutorial.html +1 -1
  17. data/doc/appscript-manual/04_gettinghelp.html +13 -42
  18. data/doc/appscript-manual/05_keywordconversion.html +1 -1
  19. data/doc/appscript-manual/06_classesandenums.html +1 -1
  20. data/doc/appscript-manual/07_applicationobjects.html +19 -1
  21. data/doc/appscript-manual/08_realvsgenericreferences.html +1 -1
  22. data/doc/appscript-manual/09_referenceforms.html +1 -1
  23. data/doc/appscript-manual/10_referenceexamples.html +1 -1
  24. data/doc/appscript-manual/11_applicationcommands.html +1 -1
  25. data/doc/appscript-manual/12_commandexamples.html +1 -1
  26. data/doc/appscript-manual/13_performanceissues.html +1 -1
  27. data/doc/appscript-manual/14_notes.html +1 -1
  28. data/doc/appscript-manual/index.html +1 -1
  29. data/doc/index.html +1 -1
  30. data/doc/mactypes-manual/index.html +13 -1
  31. data/doc/osax-manual/index.html +37 -6
  32. data/extconf.rb +2 -2
  33. data/rb-appscript.gemspec +1 -1
  34. data/sample/AB_export_vcard.rb +31 -0
  35. data/sample/Add_iCal_event.rb +4 -4
  36. data/src/lib/_aem/connect.rb +88 -8
  37. data/src/lib/_aem/mactypes.rb +27 -21
  38. data/src/lib/_appscript/reservedkeywords.rb +1 -0
  39. data/src/lib/aem.rb +40 -5
  40. data/src/lib/appscript.rb +104 -30
  41. data/src/lib/kae.rb +1 -0
  42. data/src/lib/osax.rb +35 -19
  43. data/src/rbae.c +115 -1
  44. data/test/README +3 -1
  45. data/test/test_appscriptcommands.rb +5 -4
  46. data/test/test_codecs.rb +7 -1
  47. data/test/testall.sh +1 -1
  48. metadata +24 -23
data/CHANGES CHANGED
@@ -1,3 +1,40 @@
1
+ 2007-12-18 -- 0.5.0 (beta 2)
2
+
3
+ - OSAX module no longer errors on import in 10.5 if a ScriptingAdditions folder (e.g. ~/Library/ScriptingAdditions) doesn't exist
4
+
5
+ - added Appscript::Application#is_running? method
6
+
7
+ - added hfs_path, #hfs_path methods to MacTypes::Alias, MacTypes::FileURL; existing path, #path methods now use CFURL functions to convert between POSIX paths and URLs
8
+
9
+ - aem/appscript now raises Connect::CantLaunchApplicationError instead of AE::MacOSError if unable to launch an application. Users should update existing code as necessary.
10
+
11
+ - fixed extconf.rb so that universal binaries build correctly
12
+
13
+ - built-in help system now uses ASDictionary 0.9.0+ instead of AppscriptHelpAgent. (AppscriptHelpAgent is no longer used as-of rb-appscript 0.5.0 and may be removed if previously installed.)
14
+
15
+ - #help method now writes messages to stderr instead of stdout
16
+
17
+ - Appscript::Reference#respond_to? now has identical signature to Object#respond_to? (optional second argument was previously missing)
18
+
19
+ - fixed bug in AE.convert_long_date_time_to_unix_seconds (used to unpack AEDescs of typeLongDateTime) where it would crash if passed a FixNum instead of a BigNum
20
+
21
+ - now allow methods that have been added to Object class at runtime (e.g. importing the 'pp' module adds #pretty_print and #pretty_inspect) to be invoked on Appscript::Reference and Appscript::Application instances, assuming that the reference object doesn't already have a property/element/command by the same name. In other words, instances of these classes now behave more or less the same as instances of ordinary subclasses that use bound methods rather than #method_missing to handle incoming messages. Previously, calling (e.g.) #pretty_inspect on an appscript reference would result in a 'property/element/command not found' error.
22
+
23
+ - improved behaviour of Appscript::Application#AS_new_reference when argument is nil (now returns a new reference to the root application object)
24
+
25
+ - OSAX::Application initialiser now optionally accepts static terminology 'glue' module as its second argument. This is partly to provide scripts that need to run in 64-bit processes with a workaround for accessing the OSAX module, which can't yet automatically obtain osax terminology under 64-bit (see TODO file).
26
+
27
+ - added process_exists_for_path?, process_exists_for_pid?, process_exists_for_url?, process_exists_for_desc? class methods to AEM::Application
28
+
29
+ - deprecated AEM::Application.is_running? (will be removed in 1.0.0); any existing code that uses this method should be updated to use AEM::Application.process_exists_for_path? instead
30
+
31
+ - fixed minor formatting flaw in generic references' #to_s method
32
+
33
+ - AEM::Application is now a subclass of AEMReference::Base, allowing aem Codecs instances to pack it
34
+
35
+ - added AB_export_vcard.rb sample script
36
+
37
+
1
38
  2007-08-17 -- 0.4.0 (beta 1)
2
39
 
3
40
  - renamed the following aem/appscript methods to be consistent with AppleScript:
data/LICENSE CHANGED
@@ -1,9 +1,13 @@
1
- (All modules are released under the MIT License, except safeobject.rb which is a modified version of basicobject <http://facets.rubyforge.org> released under the Ruby License.)
1
+ All code is released under the MIT License, except for the following:
2
+
3
+ - safeobject.rb which is a modified version of basicobject <http://facets.rubyforge.org> released under the Ruby License (see below)
4
+
5
+ - SendThreadSafe.h/SendThreadSafe.m, which are modified versions of Apple code (http://developer.apple.com/samplecode/AESendThreadSafe/); see SendThreadSafe.h for the original Apple license
2
6
 
3
7
  ======================================================================
4
8
  MIT LICENSE
5
9
 
6
- Copyright (C) 2006 HAS
10
+ Copyright (C) 2006 - 2007 HAS
7
11
 
8
12
  ======================================================================
9
13
  THE RUBY LICENSE
data/README CHANGED
@@ -27,11 +27,14 @@ Please note that the version of Ruby included with Mac OS X 10.4 is missing the
27
27
  ======================================================================
28
28
  NOTES
29
29
 
30
- - rb-appscript 0.4.0 is the first beta release. Except for bug fixes, no further changes are planned prior to the 1.0 release.
30
+ - rb-appscript 0.5.0 is the second beta release. Please file bug reports if you encounter any problems.
31
31
 
32
- - rb-appscript 0.4.0 contains a couple of API changes from earlier versions; see the CHANGES file and documentation for details
32
+ - rb-appscript 0.5.0 contains bug fixes, minor API changes and requested enhancements; see the CHANGES file and documentation for details.
33
+
34
+ - rb-appscript 0.5.0 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.
35
+
36
+ - 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.
33
37
 
34
- - rb-appscript 0.4.0 provides preliminary 64-bit support for OS X 10.5 in the following modules: AE, AEM, Appscript. Note that the OSAX module currently remains 32-bit only; this will be addressed after OS X 10.5 is released.
35
38
 
36
39
  ======================================================================
37
40
  AUTHOR
@@ -41,6 +44,6 @@ AUTHOR
41
44
  ======================================================================
42
45
  COPYRIGHT
43
46
 
44
- Copyright (C) 2006 HAS
47
+ Copyright (C) 2006 - 2007 HAS
45
48
 
46
49
  Appscript is released under the MIT License. See the LICENSE file for more information.
data/TODO CHANGED
@@ -1,7 +1,11 @@
1
1
  TO DO
2
2
 
3
- - Add a libxml2-based sdef parser for use by Terminology.dump, OSAX::ScriptingAddition in 64-bit Leopard as OSAGetAppTerminology is not available there. Also use weak binding for OSAGetAppTerminology, OSACopyScriptingDefinition in rbae.c
3
+ - Add a libxml2-based sdef parser for use by OSAX::ScriptingAddition in 64-bit Leopard as OSAGetAppTerminology is not available there. (note: OSAGetAppTerminology, OSACopyScriptingDefinition should be weakly bound in rbae.c)
4
4
 
5
5
  - can numbers in range (2**63)..(2**64 - 1) safely be packed as typeUInt64 on 10.5+? Or stick with packing those as lossy 64-bit floating point for compatibility?
6
6
 
7
- - _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.
7
+ - unpack support for typeISO8601DateTime (10.1+), typeCFAbsoluteTime (10.5+)?
8
+
9
+ - _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.
10
+
11
+ - #== 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.)
@@ -43,6 +43,6 @@
43
43
  </div>
44
44
 
45
45
  <!--footer-->
46
- <p class="footer">&copy; 2006 HAS</p>
46
+ <p class="footer">&copy; 2007 HAS</p>
47
47
  </body>
48
48
  </html>
@@ -84,6 +84,6 @@
84
84
  </div>
85
85
 
86
86
  <!--footer-->
87
- <p class="footer">&copy; 2006 HAS</p>
87
+ <p class="footer">&copy; 2007 HAS</p>
88
88
  </body>
89
89
  </html>
@@ -23,7 +23,7 @@
23
23
 
24
24
  <h2>Codecs</h2>
25
25
 
26
- <p>The <code>AEM::Codecs</code> class provides methods for converting Python data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
26
+ <p>The <code>AEM::Codecs</code> class provides methods for converting Ruby data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
27
27
 
28
28
  <pre><code>Codecs
29
29
 
@@ -59,7 +59,7 @@ TO DO: customisation options: subclassing and extending pack/unpack, overriding
59
59
 
60
60
  <h2>AE types</h2>
61
61
 
62
- <p>The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Python. Accordingly, aem defines several classes to represent these types on the Python side. All share a common abstract base class, <code>AETypeBase</code>:</p>
62
+ <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>
63
63
 
64
64
  <pre><code>AETypeBase -- Abstract base class
65
65
 
@@ -93,6 +93,6 @@ AEKey &lt; AETypeBase -- represents an AE object of typeKeyword</code></pre>
93
93
  </div>
94
94
 
95
95
  <!--footer-->
96
- <p class="footer">&copy; 2006 HAS</p>
96
+ <p class="footer">&copy; 2007 HAS</p>
97
97
  </body>
98
98
  </html>
@@ -39,7 +39,7 @@
39
39
  <dd>selector data (e.g. in a by-name specifier, this would be a string)</dd>
40
40
  </dl>
41
41
 
42
- <p>The Apple Event Manager (and, in turn, the ae extension) 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>
42
+ <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>
43
43
 
44
44
  <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>
45
45
 
@@ -62,25 +62,25 @@ ref = OSX::AEDesc.record({
62
62
  p ref
63
63
  #&lt;AEDesc:0x57594 type='obj '&gt;</code></pre>
64
64
 
65
- <p>(The ae extension is even lower-level and more verbose.)</p>
65
+ <p>(The equivalent C code is even lower-level and more verbose.)</p>
66
66
 
67
67
  <p>This code works by creating each AEDesc of <code>typeAERecord</code> in turn, populating it, then coercing it to <code>typeObjectSpecifier</code>. Each AEDesc is nested within the next to form a linked list of object specifier records; the last (innermost) descriptor in the finished list indicates the reference's root object in the AEOM (in this case, the <code>application</code> object, which is represented by a null descriptor).</p>
68
68
 
69
- <p>Now, compare the above with the aem equivalent:</p>
69
+ <p>Now, compare the above with the AEM equivalent:</p>
70
70
 
71
- <pre><code>AEM.app.elements('docu').by_index(1).property('ctxt')</code></pre>
71
+ <pre><code>[[[AEMApp elements: 'docu'] at: 1] property: 'ctxt']</code></pre>
72
72
 
73
- <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>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>
73
+ <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>
74
74
 
75
- <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>[1]</code>).</p>
75
+ <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>
76
76
 
77
- <p>Note that <code>AEM.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>
77
+ <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>
78
78
 
79
- <pre><code>AEM.app.elements('docu').by_filter(...).first</code></pre>
79
+ <pre><code>[[[AEMApp elements: 'docu'] byTest: ...] first]</code></pre>
80
80
 
81
81
  <p>is equivalent to writing:</p>
82
82
 
83
- <pre><code>AEM.app.elements('docu').by_filter(...).elements('docu').first</code></pre>
83
+ <pre><code>[[[[AEMApp elements: 'docu'] byTest: ...] elements: 'docu'] first]</code></pre>
84
84
 
85
85
  <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>
86
86
 
@@ -109,15 +109,20 @@ p ref
109
109
  <li>elements by test</li>
110
110
  </ul>
111
111
 
112
- <p>(Actually, there's nine forms if you count the 'user property' reference form, although this is only used by OSA applets to identify script properties. Aem supports this extra form more for sake of completeness than usefulness.)</p>
112
+ <p>(Actually, there's nine forms if you count the 'user property' reference form, although this is only used by OSA (e.g. Script Editor) applets to identify script properties. AEM supports this extra form more for sake of completeness than usefulness.)</p>
113
113
 
114
- <p>Each of these reference forms is represented by a different aem specifier class, apart from the absolute position form which is represented by three different classes according to the kind of selector used: a numerical index (e.g. <code>1</code>, <code>-3</code>), a named ordinal identifying a single element (<code>first</code>, <code>middle</code>, <code>last</code>, <code>any</code>), or a named ordinal identifying all elements (<code>all</code>).</p>
114
+ <p>Each of these reference forms is represented by a different AEM specifier class, apart from the absolute position form which is represented by three different classes according to the kind of selector used: a numerical index (e.g. <code>1</code>, <code>-3</code>), a named ordinal identifying a single element (<code>first</code>, <code>middle</code>, <code>last</code>, <code>any</code>), or a named ordinal identifying all elements (<code>all</code>).</p>
115
115
 
116
116
  <p>The following diagram shows the aem reference class hierarchy (slightly simplified for legibility); concrete classes are shown in bold:</p>
117
117
 
118
118
  <p><img src="aemreferenceinheritance.gif" title="aem reference class hierarchy" />
119
119
 
120
- <p>Note that the user shouldn't instantiate these classes directly; instead, aem will instantiate them as appropriate when the client calls the methods of other aem reference objects, starting with the <code>app</code>, <code>con</code> and <code>its</code> objects that form the root of all aem references.</p>
120
+ <p>Note that the user shouldn't instantiate these classes directly; instead, AEM will instantiate them as appropriate when the client calls the methods of other AEM specifier objects, starting with the <code>app</code>, <code>con</code> and <code>its</code> objects that form the root of all aem references.</p>
121
+
122
+
123
+
124
+ TO DO: finish
125
+
121
126
 
122
127
  <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>
123
128
 
@@ -396,6 +401,6 @@ ObjectBeingExamined &lt; PropertySpecifier -- AEM.its returns an instance
396
401
  </div>
397
402
 
398
403
  <!--footer-->
399
- <p class="footer">&copy; 2006 HAS</p>
404
+ <p class="footer">&copy; 2007 HAS</p>
400
405
  </body>
401
406
  </html>
@@ -25,19 +25,39 @@
25
25
 
26
26
  <h2>The <code>Application</code> class</h2>
27
27
 
28
- <p>The <code>Application</code> class represents an application to which Apple events will be sent. Its constructor allows applications to be identified in one of four ways: by full path, by eppc URL, by custom <code>AEAddressDesc</code>, or the host application if no other value is given. Its main method, <code>event</code>, is used to construct the Apple events to send. Several utility methods are also provided.</p>
28
+ <p>The <code>Application</code> class represents an application to which Apple events will be sent. Its constructor allows applications to be identified in one of four ways: by full path, by eppc URL, by custom <code>AEAddressDesc</code>, or the host application if no other value is given. Its main method, <code>#event</code>, is used to construct the Apple events to send. Several utility methods are also provided.</p>
29
29
 
30
30
  <pre><code>Application -- the target application
31
31
 
32
32
  Class methods:
33
33
 
34
- launch(path) -- launch an application in background if not
35
- already running, and send it a 'ascrnoop' event
34
+ process_exists_for_path?(path) -- Does a local process launched
35
+ from the specified application file exist?
36
36
  path : string -- application's path, e.g. '/Applications/iCal.app'
37
+ Result : boolean -- Note: if path is invalid, an AE::MacOSError
38
+ is raised.
37
39
 
38
- is_running?(path) -- Is an application currently running?
39
- path : string -- application's path, e.g. '/Applications/iCal.app'
40
+ process_exists_for_pid?(pid) -- Is there a local application process
41
+ with the given Unix process id?
42
+ pid : integer
40
43
  Result : boolean
44
+
45
+ process_exists_for_url?(url) -- Does an application process specified
46
+ by the given eppc:// URL exist?
47
+ url : string -- url for remote process
48
+ (e.g. 'eppc://user:pass@0.0.0.1/TextEdit')
49
+ Result : boolean -- Returns false if process doesn't exist, or if
50
+ access isn't allowed.
51
+
52
+ process_exists_for_desc?(desc) -- Does an application process specified
53
+ by the given AEAddressDesc exist?
54
+ desc : AE::AEDesc -- AEAddressDesc for application
55
+ Result : boolean -- Returns false if process doesn't exist, or if
56
+ access isn't allowed.
57
+
58
+ launch(path) -- launch an application in background if not
59
+ already running, and send it a 'ascrnoop' event
60
+ path : string -- application's path, e.g. '/Applications/iCal.app'
41
61
 
42
62
  Constructors:
43
63
 
@@ -81,7 +101,7 @@
81
101
 
82
102
  <h2>Creating <code>Application</code> objects</h2>
83
103
 
84
- <p>When targetting a local application by path, the full path to the application (or application bundle) must be given, including a <code>.app</code> suffix if present. Note that aem identifies local applications by process serial number for reliability. If the target application is not already running when a new <code>Application</code> instance is created, it will be started automatically so that a PSN can be acquired.</p>
104
+ <p>When targetting a local application by path, the full path to the application (or application bundle) must be given, including a <code>.app</code> suffix if present. Note that aem identifies local applications by process serial number for reliability. If the target application is not already running when a new <code>Application</code> instance is created, it will be started automatically so that a PSN can be acquired. If the application can't be launched for some reason (e.g. if it's in the Trash), an <code>AEM::CantLaunchApplicationError</code> error will be raised.</p>
85
105
 
86
106
  <p>If the <code>by_url</code> constructor is used, its <code>url</code> argument should be an eppc URL string. Aem will pack this as an <code>AEDesc</code> of <code>typeApplSignature</code>. The target machine must have Remote Apple Events enabled in its Sharing preferences.</p>
87
107
 
@@ -104,22 +124,22 @@ KAE::TypeProcessSerialNumber</code></pre>
104
124
 
105
125
  <h2>Transactions</h2>
106
126
 
107
- <p>The <code>begin_transaction</code> and <code>end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
127
+ <p>The <code>#begin_transaction</code> and <code>#end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
108
128
 
109
129
  <p>Note that during a transaction, sending the application an event not created during that transaction will cause an error. Similarly, sending the application an event created during a transaction after that transaction has ended will cause an error.</p>
110
130
 
111
- <p>The <code>end_transaction</code> method must be called to close both successful and failed transactions on completion. If a transaction session is accidentally left open, aem will attempt to close it when the <code>Application</code> object is garbage-collected, although this cannot be guaranteed to succeed.</p>
131
+ <p>The <code>#end_transaction</code> method must be called to close both successful and failed transactions on completion. If a transaction session is accidentally left open, aem will attempt to close it when the <code>Application</code> object is garbage-collected, although this cannot be guaranteed to succeed.</p>
112
132
 
113
133
 
114
134
  <h2>Reconnecting to local applications</h2>
115
135
 
116
- <p>Because local applications are identified by process serial number, an existing <code>Application</code> object created using the <code>path</code> argument will no longer hold a valid <code>AEAddressDesc</code> if the target application quits. Sending events to an invalid address will cause a <code>CommandError</code> -600 ("application isn't running") or -609 ("connection is invalid") to be raised.</p>
136
+ <p>Because local applications are identified by process serial number, an existing <code>Application</code> object created using the <code>by_path</code> constructor will no longer hold a valid <code>AEAddressDesc</code> if the target application subsequently quits. Sending events to an invalid address will cause a <code>CommandError</code> -600 ("application isn't running") or -609 ("connection is invalid") to be raised.</p>
117
137
 
118
- <p>The <code>is_running?</code> class method can be used to check if a local application is running or not, given its full path.</p>
138
+ <p>The <code>process_exists_for_path?</code> class method can be used to check if a local application is running or not, given its full path.</p>
119
139
 
120
- <p>Calling the <code>reconnect</code> method will create a new <code>AEAddressDesc</code> for an existing <code>Application</code> object. If the application is not running at the time, it will be started automatically.</p>
140
+ <p>Calling the <code>#reconnect</code> method will create a new <code>AEAddressDesc</code> for an existing <code>Application</code> object that was originally created via the <code>by_path</code> constructor. If the application is not running at the time, it will be started automatically.</p>
121
141
 
122
- <p>Note that only <code>Event</code> instances created after <code>reconnect</code> is called will receive the new <code>AEAddressDesc</code>. Any <code>Event</code> instances created before <code>reconnect</code> is called will still contain the old <code>AEAddressDesc</code>. Also note that the <code>reconnect</code> method will only work for <code>Application</code> objects created using the <code>by_path</code> constructor.</p>
142
+ <p>Note that only <code>Event</code> instances created after <code>#reconnect</code> is called will receive the new <code>AEAddressDesc</code>. Any <code>Event</code> instances created before <code>reconnect</code> is called will still contain the old <code>AEAddressDesc</code>.</p>
123
143
 
124
144
 
125
145
  </div>
@@ -130,6 +150,6 @@ KAE::TypeProcessSerialNumber</code></pre>
130
150
  </div>
131
151
 
132
152
  <!--footer-->
133
- <p class="footer">&copy; 2006 HAS</p>
153
+ <p class="footer">&copy; 2007 HAS</p>
134
154
  </body>
135
155
  </html>
@@ -170,6 +170,6 @@ KAE::KAECanSwitchLayer</code></pre>
170
170
  </div>
171
171
 
172
172
  <!--footer-->
173
- <p class="footer">&copy; 2006 HAS</p>
173
+ <p class="footer">&copy; 2007 HAS</p>
174
174
  </body>
175
175
  </html>
@@ -49,6 +49,6 @@ by_creator(creator) -- Find the application with the given creator type.
49
49
  </div>
50
50
 
51
51
  <!--footer-->
52
- <p class="footer">&copy; 2006 HAS</p>
52
+ <p class="footer">&copy; 2007 HAS</p>
53
53
  </body>
54
54
  </html>
@@ -80,6 +80,6 @@ textedit.event('corecrel', {
80
80
  </div>
81
81
 
82
82
  <!--footer-->
83
- <p class="footer">&copy; 2006 HAS</p>
83
+ <p class="footer">&copy; 2007 HAS</p>
84
84
  </body>
85
85
  </html>
@@ -37,6 +37,6 @@
37
37
  </div>
38
38
 
39
39
  <!--footer-->
40
- <p class="footer">&copy; 2006 HAS</p>
40
+ <p class="footer">&copy; 2007 HAS</p>
41
41
  </body>
42
42
  </html>
@@ -78,6 +78,6 @@ app('TextEdit').documents.end.make(
78
78
  </div>
79
79
 
80
80
  <!--footer-->
81
- <p class="footer">&copy; 2006 HAS</p>
81
+ <p class="footer">&copy; 2007 HAS</p>
82
82
  </body>
83
83
  </html>
@@ -67,12 +67,12 @@
67
67
 
68
68
  <p><img src="application_architecture.gif" alt="Application with Graphical and Apple event interfaces." /></p>
69
69
 
70
- <p>A scriptable application also contains a built-in definition of its scripting interface in the form of an <code>aete</code> or <code>sdef</code> resource. This resource can be obtained programmatically and used:</p>
70
+ <p>A scriptable application also contains a built-in definition of its scripting interface in the form of an <code>aete</code> or <code>sdef</code> resource. This resource can be obtained programmatically and used to:</p>
71
71
 
72
72
  <ul>
73
- <li>to support automatic translation of human-readable terminology to four-letter codes in high-level bridges such as AppleScript and appscript</li>
73
+ <li>support automatic translation of human-readable terminology to four-letter codes in high-level bridges such as AppleScript and appscript</li>
74
74
 
75
- <li>to generate basic human-readable documentation by applications such as Script Editor and HTMLDictionary.</li>
75
+ <li>generate basic human-readable documentation by applications such as Script Editor and HTMLDictionary.</li>
76
76
  </ul>
77
77
 
78
78
  <p>(Note that the <code>aete</code> and <code>sdef</code> formats do not provide an exhaustive description of the application's scripting interface, and additional documentation is usually required - if not always provided - to form a complete understanding of that interface and how to use it effectively.)</p>
@@ -231,6 +231,6 @@ app('TextEdit').documents[1].text.paragraphs</code></pre>
231
231
  </div>
232
232
 
233
233
  <!--footer-->
234
- <p class="footer">&copy; 2006 HAS</p>
234
+ <p class="footer">&copy; 2007 HAS</p>
235
235
  </body>
236
236
  </html>
@@ -151,6 +151,6 @@ irb&gt; te.documents.text.get
151
151
  </div>
152
152
 
153
153
  <!--footer-->
154
- <p class="footer">&copy; 2006 HAS</p>
154
+ <p class="footer">&copy; 2007 HAS</p>
155
155
  </body>
156
156
  </html>
@@ -20,7 +20,15 @@
20
20
 
21
21
  <!-- content -->
22
22
  <div id="content">
23
- <p>When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the built-in <code>help</code> method, the ASDictionary and <code>osadict</code> tools, and introspection.</p>
23
+ <p>When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the ASDictionary application and its bundled <code>asdict</code> command-line tool, appscript's powerful built-in <code>help</code> method, and introspection.</p>
24
+
25
+
26
+
27
+ <h2>ASDictionary</h2>
28
+
29
+ <p>ASDictionary, available from the appscript website's <a href="http://rb-appscript.rubyforge.org/downloads.html">Downloads page</a>, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file format and a frame-based format similar to rdoc's.</p>
30
+
31
+ <p>In addition, the <code>asdict</code> tool bundled with ASDictionary can be used to export application dictionaries in HTML format, or browse them interactively from the command line. See ASDictionary's documentation for more information.</p>
24
32
 
25
33
 
26
34
 
@@ -28,13 +36,9 @@
28
36
 
29
37
  <p>Appscript's <code>Application</code> and <code>Reference</code> classes include a powerful interactive help system that allows you to explore applications' scripting interfaces from within running scripts and Ruby's interactive <code>irb</code> interpreter. The <code>help</code> method can provide information on any suite, class, command or reference, and display the inheritance and relationships for a selected class or the entire application.</p>
30
38
 
31
- <div class="hilitebox">
32
- <p>Rb-appscript's built-in <code>help</code> method relies on the AppscriptHelpAgent application, available separately from the <a href="http://rb-appscript.rubyforge.org">appscript website</a>. See the AppscriptHelpAgent Read Me for installation instructions.</p>
39
+ <div class="hilitebox">Note that rb-appscript's built-in help system is only available when ASDictionary 0.9.0 or later is installed. If ASDictionary isn't available or is too old, invoking <code>help</code> will simply result in a "No help available" message and the script will continue to run as normal.</div>
33
40
 
34
- <p>Note that AppscriptHelpAgent is <em>not</em> required to access any other feature of rb-appscript, and its installation it is entirely optional. If AppscriptHelpAgent is not installed, invoking <code>help</code> will simply result in a "No help available" message being displayed and the script will continue to run as normal.</p>
35
- </div>
36
-
37
- <p>Built-in help is invoked by calling an <code>app</code> object's <code>help</code> method, optionally passing it a string indicating the type of information you want. For example, to view the help system's own help, call the <code>help</code> method with <code>'-h'</code> as its argument:</p>
41
+ <p>Built-in help is invoked by calling an <code>app</code> object's <code>help</code> method, optionally passing it a string indicating the type of information you want. The resulting help message is printed to <code>stderr</code> and script execution continues as normal. For example, to view the help system's own help, call the <code>help</code> method with <code>'-h'</code> as its argument:</p>
38
42
 
39
43
  <pre><code>app('TextEdit').help('-h')</code></pre>
40
44
 
@@ -90,42 +94,9 @@ app('TextEdit').documents.help('-t count -t close')</code></pre>
90
94
 
91
95
 
92
96
 
93
- <h2>ASDictionary</h2>
94
-
95
- <p>ASDictionary, available from the <a href="http://sourceforge.net/projects/appscript"> py-appscript website</a>, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file format and a frame-based format similar to rdoc's.</p>
96
-
97
-
98
-
99
- <h2>osadict</h2>
100
-
101
- <p>The <code>osadict</code> tool, bundled with the <a href="http://sourceforge.net/projects/appscript">py-appscript package</a>, can be used to export application dictionaries in HTML format, or browse them interactively from the command line.</p>
102
-
103
- <p>To view osadict's full documentation:</p>
104
-
105
- <pre><code>osadict -h</code></pre>
106
-
107
- <p>Use osadict's <code>-s</code> option or <code>default</code> command to set the formatting style for rb-appscript.</p>
108
-
109
- <p>Examples:</p>
110
-
111
- <pre><code># Export TextEdit's dictionary to HTML:
112
- osadict -Hs rb TextEdit.app > TextEdit.html
113
-
114
- # Browse iCal's dictionary:
115
- osadict -s rb eppc://remote-mac.local/iCal
116
- iCal&gt; -u
117
- iCal&gt; -t view_calendar
118
- iCal&gt; -t calendar -i calendar -r calendar
119
- iCal&gt; exit
120
-
121
- # View a Standard Additions command:
122
- osadict -Ns rb StandardAdditions -t display dialog</code></pre>
123
-
124
-
125
-
126
97
  <h2>Introspection</h2>
127
98
 
128
- <p>Appscript's <code>Application</code> and <code>Reference</code> classes define several instance methods for obtaining information on the target application: </p>
99
+ <p>In addition to supporting Ruby's standard <code>#methods</code> and <code>#respond_to?</code> methods, appscript's <code>Application</code> and <code>Reference</code> classes also define several instance methods for obtaining information on the target application: </p>
129
100
 
130
101
  <dl>
131
102
  <dt><code>properties</code></dt>
@@ -184,6 +155,6 @@ p te.parameters('make')
184
155
  </div>
185
156
 
186
157
  <!--footer-->
187
- <p class="footer">&copy; 2006 HAS</p>
158
+ <p class="footer">&copy; 2007 HAS</p>
188
159
  </body>
189
160
  </html>