rb-appscript 0.2.1 → 0.3.0

data/doc/appscript-manual/05_keywordconversion.html

@@ -37,11 +37,12 @@
 
 <li>Names that match the methods already defined on appscript's Application and Reference classes have an underscore appended. The reserved method names are:
 
-<pre><code>abort_transaction             instance_variable_set
-after                         instance_variables
-and                           is_in
-any                           is_not_in
-before                        keywords
+<pre><code>abort_transaction             instance_variable_get
+after                         instance_variable_set
+and                           instance_variables
+any                           is_in
+before                        is_not_in
+by_aem_app                    keywords
 by_creator                    last
 by_id                         launch
 by_name                       le
@@ -73,8 +74,7 @@ ID                            to_a
 id                            to_s
 ignore                        type
 inspect                       untaint
-instance_eval                 wait_reply
-instance_variable_get</code></pre>
+instance_eval                 wait_reply</code></pre>
 </div>
 </li>
 </ul>

data/doc/appscript-manual/06_classesandenums.html

@@ -47,7 +47,7 @@ AEM::AEEnum.new('xyz ')</code></pre>
 
 <h2>Common AE types</h2>
 
-<table width=100% summary="AE-Ruby type mappings">
+<table width="100%" summary="AE-Ruby type mappings">
 <thead>
 <tr><th>AE type</th><th>appscript name</th><th>Ruby class</th></tr>
 </thead>
@@ -133,26 +133,7 @@ $KCODE = "UTF8"</code></pre>
 
 <h3>Unit types</h3>
 
-<p>The following unit types are defined as standard:</p>
-
-<pre><code>:centimeters                   :cubic_inches
-:meters                        :cubic_feet
-:kilometers                    :cubic_yards
-:inches                        
-:feet                          :liters
-:yards                         :quarts
-:miles                         :gallons
-                               
-:square_meters                 :grams
-:square_kilometers             :kilograms
-:square_feet                   :ounces
-:square_yards                  :pounds
-:square_miles                  
-                               :degrees_Celsius
-:cubic_centimeters             :degrees_Fahrenheit
-:cubic_meters                  :degrees_Kelvin</code></pre>
-
-<p>Values are represented by instances of the <code>MacTypes::Units</code> class, e.g. <code>MacTypes::Units.inches(3.0)</code>. See the <a href="../mactypes-manual/index.html">mactypes manual</a> for more information.</p>
+<p>Unit type values are represented by instances of the <code>MacTypes::Units</code> class, e.g. <code>MacTypes::Units.inches(3.0)</code>. See the <a href="../mactypes-manual/index.html">mactypes manual</a> for more information.</p>
 
 
 <h3>Miscellaneous types</h3>

data/doc/appscript-manual/07_applicationobjects.html

@@ -35,6 +35,8 @@ app.by_pid(pid) # Unix process id for a local process
 
 app.by_url(url) # eppc URL for a remote process
 
+app.by_aem_app(aem_app) # AEM::Application instance
+
 app.current # the host process</code></pre>
 
 <p>For convenience, the most commonly used form, <code>app.by_name(name)</code>, can be shortened to:</p>
@@ -59,6 +61,9 @@ app.current # the host process</code></pre>
 
 <dt><code>url</code></dt>
 <dd>A URL of form <code>eppc://[user[:password]@host/Application%20Name[?[uid=#]&amp;[pid=#]</code>, e.g. <code>eppc://johnsmith:foobar@office-mac.local/TextEdit?uid=501</code>. The host name/IP address and the process name (case-sensitive) are required. The username and password are optional: if omitted, the OS will obtain this information from the user's keychain or display a dialog asking the user to input one or both values. The user id and process id are also optional; if the process id is given, the process name will be ignored.</dd>
+
+<dt><code>aem_app</code></dt>
+<dd>An <code>AEM::Application</code> instance.</dd>
 </dl>
 
 
@@ -126,9 +131,13 @@ set(reference, :to =&gt; value) -- Set an object's data.
 
 <h2>Transaction support</h2>
 
-<p>Application objects implement three additional methods, <code>start_transaction</code>, <code>end_transaction</code> and <code>abort_transaction</code> that allow a sequence of related commands to be handled as a single operation by applications that support transactions, e.g. FileMaker Pro. Once the application object's <code>start_transaction</code> method is called, all subsequent commands to that application will be sent as part of the same transaction until <code>end_transaction</code> or <code>abort_transaction</code> is called.</p>
+<p>Application objects implement three additional methods, <code>start_transaction</code>, <code>end_transaction</code> and <code>abort_transaction</code> that allow a sequence of related commands to be handled as a single operation by applications that support transactions, e.g. FileMaker Pro.</p>
+
+<p>Once the application object's <code>start_transaction</code> method is called, all subsequent commands to that application will be sent as part of the same transaction until <code>end_transaction</code> or <code>abort_transaction</code> is called.</p>
+
+<p>The <code>start_transaction</code> method takes an optional <code>session</code> argument that indicates the specific transaction session to open (in applications that support this).</p>
 
-<p class="hilitebox">Remember to call <code>end_transaction</code> or <code>abort_transaction</code> at the end of every transaction. If a transaction is accidentally left open, appscript will try to end it automatically when the application object is garbage-collected, but this is not guaranteed to succeed.</p>
+<p class="hilitebox">Remember to call <code>end_transaction</code> or <code>abort_transaction</code> at the end of every transaction. (This includes transactions interrupted by a raised exception.) If a transaction is accidentally left open, appscript will try to end it automatically when the application object is garbage-collected, but this is not guaranteed to succeed.</p>
 
 
 <h2>Local application launching notes</h2>

data/doc/appscript-manual/08_realvsgenericreferences.html

@@ -83,4 +83,4 @@ puts app('Finder').home == app('Finder').home.get
 <!--footer-->
 <p class="footer">&copy; 2006 HAS</p>
 </body>
-</html>s
+</html>

data/doc/appscript-manual/09_referenceforms.html

@@ -20,7 +20,7 @@
 
 <!-- content -->
 <div id="content">
-<h2>Property Reference</h2>
+<h2>Property reference</h2>
 
 <p>A property either contains a simple value or represents a one-to-one relationship between two application objects. Properties either describe the application object (its name, class, size, color, preferences, etc.) or provide a convenient reference to other object(s) of interest to users (e.g. home, current_track).</p>
 
@@ -34,7 +34,7 @@ finder.<em>home</em>.files.<em>name</em></code></pre>
 
 
 
-<h2>Element References</h2>
+<h2>Element references</h2>
 
 <p>Elements represent a one-to-many relationship between application objects. Elements usually reflect the containment structure of the application object model and generally provide multiple ways of referencing some or all of those objects (e.g. characters/words/paragraphs of documents by index/relative-position/range/filter).</p>
 
@@ -52,8 +52,8 @@ textedit.<em>documents</em>.<em>paragraphs</em>.<em>words</em></code></pre>
 <h3>by Name</h3>
 	
 <p>Syntax:</p>
-<pre><code>elements[specifier]
-        specifier : String -- name of object (as matches its 'name' property)</code></pre>
+<pre><code>elements[selector]
+        selector : String -- name of object (as matches its 'name' property)</code></pre>
 		
 <p>Examples:</p>
 <pre><code>disks['Macintosh HD']
@@ -65,8 +65,8 @@ files['index.html']</code></pre>
 <h3>by Index</h3>
 	
 <p>Syntax:</p>
-<pre><code>elements[specifier]
-        specifier : Fixnum | Bignum -- index of object</code></pre>
+<pre><code>elements[selector]
+        selector : Fixnum | Bignum -- index of object</code></pre>
 		
 <p>Examples:</p>
 <pre><code>words[3]
@@ -78,8 +78,8 @@ items[-1]</code></pre>
 <h3>by ID</h3>
 
 <p>Syntax:</p>
-<pre><code>elements.ID(specifier)
-        specifier : anything -- object's id</code></pre>
+<pre><code>elements.ID(selector)
+        selector : anything -- object's id</code></pre>
 
 <p>Examples:</p>
 <pre><code>windows.ID(4321)</code></pre>
@@ -102,9 +102,9 @@ files.any</code></pre>
 <h3>by Relative Position</h3>
 
 <p>Syntax:</p>
-<pre><code>elements[specifier].previous(class) -- nearest element of a given class to appear 
+<pre><code>elements[selector].previous(class) -- nearest element of a given class to appear 
                                        before the specified element
-elements[specifier].next(class) -- nearest element of a given class to appear 
+elements[selector].next(class) -- nearest element of a given class to appear 
                                    after the specified element
         class : Symbol -- class of element (see <a href="4_classesandenums.html">Classes and Enumerated Types</a>)</code></pre>
 
@@ -202,15 +202,15 @@ its.words[1].starts_with('A').or(
 
 
 
-<h2>Insertion Location</h2>
+<h2>Insertion location</h2>
 
 <p>Insertion locations can be specified at the beginning or end of all elements, or before or after a specified element or element range.</p>
 
 <p>Syntax:</p>
 <pre><code>elements.start
 elements.end
-elements[specifier].before
-elements[specifier].after</code></pre>
+elements[selector].before
+elements[selector].after</code></pre>
 	
 <p>Examples:</p>
 <pre><code>documents.end

data/doc/appscript-manual/10_referenceexamples.html

@@ -32,7 +32,7 @@ app('Finder')
 app('/Applications/TextEdit.app')</code></pre>
 
 
-<h2>Property References</h2>
+<h2>Property references</h2>
 
 <pre><code># a reference to startup disk of application &quot;Finder&quot;
 app('Finder').startup_disk
@@ -51,7 +51,7 @@ app('TextEdit').documents.text
 app('TextEdit').documents[1].text.paragraphs.characters[1].color</code></pre>
 
 
-<h2>All Elements References</h2>
+<h2>All elements references</h2>
 
 <pre><code># a reference to disks of application &quot;Finder&quot;
 app('Finder').disks
@@ -61,7 +61,7 @@ app('Finder').disks
 app('TextEdit').documents.text.paragraphs.words</code></pre>
 
 
-<h2>Single Element References</h2>
+<h2>Single element references</h2>
 
 <pre><code># a reference to disk 1 of application &quot;Finder&quot;
 app('Finder').disks[1]
@@ -79,7 +79,7 @@ app('TextEdit').documents.last.text.paragraphs.middle
 app('Finder').home.files.any</code></pre>
 
 
-<h2>Relative References</h2>
+<h2>Relative references</h2>
 
 <pre><code># a reference to paragraph before paragraph 6 of text of document 1 of application &quot;TextEdit&quot;
 app('TextEdit').documents[1].text.paragraphs[6].previous(:paragraph)
@@ -88,7 +88,7 @@ app('TextEdit').documents[1].text.paragraphs[6].previous(:paragraph)
 app('Tex-Edit Plus').documents[1].characters[30].next(:paragraph)</code></pre>
 
 
-<h2>Element Range References</h2>
+<h2>Element range references</h2>
 
 <pre><code># a reference to words 1 thru 4 of text of document 1 of application &quot;TextEdit&quot;
 app('TextEdit').documents[1].text.words[1, 4]
@@ -103,7 +103,7 @@ app('Finder').home.folders['Documents', 'Music']
 app('Tex-Edit Plus').documents[1].text[con.words[3], con.paragraphs[7]]</code></pre>
 
 
-<h2>Filter References</h2>
+<h2>Filter references</h2>
 
 <pre><code># a reference to every document of application &quot;TextEdit&quot; whose text is &quot;\n&quot;
 app('TextEdit').documents[its.text.eq("\n")]
@@ -119,7 +119,7 @@ app('Finder').home.folders['Documents'].files[
     its.name_extension.eq('txt').AND(its.size.lt(10240))]</code></pre>
 
 
-<h2>Insertion Location References</h2>
+<h2>Insertion location references</h2>
 
 <pre><code># a reference to end of documents of application &quot;TextEdit&quot;
 app('TextEdit').documents.end

data/doc/appscript-manual/11_applicationcommands.html

@@ -125,13 +125,7 @@ app('Finder').home.items.get(:result_type =&gt; :alias)</code></pre>
 
 <pre><code>reference.command(direct_parameter[, keyword_parameters])</code></pre>
 
-<p>the reference upon which it is called will be packed as a 'subject' attribute. For example, if the <code>make</code> command is called on a reference, the application will use that reference as its insertion location if there is no <code>at</code> keyword parameter given; i.e.:</p>
-
-<pre><code>insertion_location.make(:new =&gt; some_class)</code></pre>
-
-<p>instead of:</p>
-
-<pre><code>application.make(:new =&gt; some_class, :at =&gt; insertion_location)</code></pre></li>
+<p>the reference upon which it is called will be packed as the Apple event's 'subject' attribute (<code>keySubjectAttr</code>).</p></li>
 
 
 <li><p>When the <code>set</code> command is called on a reference, its <code>to</code> parameter can be written as a direct parameter; i.e.:</p>
@@ -148,6 +142,17 @@ app('Finder').home.items.get(:result_type =&gt; :alias)</code></pre>
 
 <p>The first form is preferred, although all three are supported.</p></li>
 
+
+<li><p>If the <code>make</code> command is called on an insertion location reference, appscript will pack that reference as the Apple event's <code>at</code> parameter if it doesn't already have one; i.e.:</p>
+
+<pre><code>insertion_location.make(:new =&gt; some_class)</code></pre>
+
+<p>is equivalent to:</p>
+
+<pre><code>application.make(:new =&gt; some_class, :at =&gt; insertion_location)</code></pre>
+
+<p>If the <code>make</code> command is called on an object reference, appscript will pack that reference as the Apple event's 'subject' attribute. (Note that some applications may not handle the subject attribute correctly, in which case the reference should be passed as the <code>make</code> command's <code>at</code> parameter instead.)</p></li>
+
 </ol>
 
 
@@ -155,39 +160,36 @@ app('Finder').home.items.get(:result_type =&gt; :alias)</code></pre>
 
 <p>Unlike AppleScript, which implicitly sends a <code>get</code> command to any unresolved application object references at the end of evaluating an expression, appscript only resolves a reference when it receives an appropriate command. For example:</p>
 
-<pre><code>foo = app('Finder').disks</code></pre>
+<pre><code>d = app('TextEdit').documents</code></pre>
 
-<p>is <em>not</em> equivalent to:</p>
+<p>is <em>not</em> the same as:</p>
 
-<pre><code>set foo to disks of application &quot;Finder&quot;</code></pre>
+<pre><code>set d to documents of app &quot;TextEdit&quot;</code></pre>
 
-<p>even though the two may look similar. In the first case, the value assigned to variable <code>foo</code> is a reference, <code>app('Finder').disks</code>. In the second, AppleScript evaluates the <code>disks of application &quot;Finder&quot;</code> reference by performing an implicit <code>get</code> command before assigning the result, a <em>list</em> containing one or more references (one to each disk currently mounted), to variable <code>foo</code>. To assign an unresolved reference to a variable in AppleScript, the reference must be preceded by the <code>a reference to</code> operator. For example:</p>
+<p>even though the two may look similar. In the first case, the value assigned to <code>d</code> is an appscript reference: <code>app('TextEdit').documents</code>. In the second, AppleScript evaluates the <code>documents of app &quot;TextEdit&quot;</code> reference by performing an implicit <code>get</code> command and then assigning its result, a list of references to individual documents, to <code>d</code>. To obtain the original reference as an AppleScript value, the literal reference must be preceded by an <code>a reference to</code> operator as shown below.</p>
 
-<ul>
-<li><p>Getting a reference to all disks:</p>
+<p>To get a single reference to all documents:</p>
 
-<pre><code>set foo to a reference to every disk of application &quot;Finder&quot;
-return foo
---&gt; a reference to every disk of application &quot;Finder&quot;</code></pre>
+<pre><code>set d to a reference to documents of app &quot;TextEdit&quot;
+return d
+--&gt; a reference to documents of app &quot;TextEdit&quot;
 
-<pre><code>foo = app('Finder').disks
-print foo
---&gt; app('Finder').disks</code></pre></li>
 
+d = app('TextEdit').documents
+print d
+--&gt; app('TextEdit').documents</code></pre>
 
-<li><p>Getting a list of references to each disk:</p>
 
-<pre><code>set foo to get every disk of application &quot;Finder&quot; -- (the 'get' is optional here)
-return foo
---&gt; {disk &quot;Mac HD&quot; of application &quot;Finder&quot;, disk &quot;ZIP-100&quot; of application &quot;Finder&quot;}</code></pre>
+<p>To get a list of references to each document:</p>
 
-<pre><code>foo = app('Finder').disks.get
-print foo
---&gt; [app('Finder').disks['Mac HD'], app('Finder').disks['ZIP-100']]</code></pre>
+<pre><code>set d to get documents of app &quot;TextEdit&quot; -- (explicit 'get' is optional)
+return d
+--&gt; {document 1 of app &quot;TextEdit&quot;, document 2 of app &quot;TextEdit&quot;}
 
-</li>
-</ul>
 
+d = app('TextEdit').documents.get -- (explicit 'get' is required)
+print d
+--&gt; [app('TextEdit').documents[1], app('TextEdit').documents[2]]</code></pre>
 
 
 </div>

data/doc/appscript-manual/13_performanceissues.html

@@ -14,13 +14,13 @@
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="12_commandexamples.html">Previous</a> | <a href="index.html">Up</a> | <a href="14_problemapps.html">Next</a>
+	<a href="12_commandexamples.html">Previous</a> | <a href="index.html">Up</a> | <a href="14_notes.html">Next</a>
 	
 </div>
 
 <!-- content -->
 <div id="content">
-<h2>About Performance</h2>
+<h2>About performance</h2>
 
 <p>Application scripting is subject to a number of potential performance bottlenecks:</p>
 
@@ -108,7 +108,7 @@ p result</code></pre>
 
 <!-- bottom navigation -->
 <div class="navbar">
-	<a href="12_commandexamples.html">Previous</a> | <a href="index.html">Up</a> | <a href="14_problemapps.html">Next</a>
+	<a href="12_commandexamples.html">Previous</a> | <a href="index.html">Up</a> | <a href="14_notes.html">Next</a>
 	
 </div>
 

data/doc/appscript-manual/{15_notes.html → 14_notes.html}

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 
-<title>appscript | 15. Notes</title>
+<title>appscript | 14. Notes</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,17 +10,23 @@
 </head>
 <body>
 
-<h1>15. Notes</h1>
+<h1>14. Notes</h1>
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="14_problemapps.html">Previous</a> | <a href="index.html">Up</a>
+	<a href="13_performanceissues.html">Previous</a> | <a href="index.html">Up</a>
 	
 </div>
 
 <!-- content -->
 <div id="content">
-<h2>Security Issues</h2>
+
+<h2>Dealing with problem applications</h2>
+
+<p>Appscript provides a number of mechanisms for dealing with problematic applications. See the <a href="http://rb-appscript.rubyforge.org">appscript website</a> for more information.</p>
+
+
+<h2>Security issues</h2>
 
 <p>If including user names and/or passwords in remote application URLs, please note that appscript retains these URLs in both the <code>Terminology</code> module's internal cache and in the Application and Reference objects subsequently created from those URLs. Security here is the user's responsibility, as it's their code that creates and retains these objects.</p>
 
@@ -49,32 +55,31 @@
 
 <p>Many thanks to Bill Birkett, Jordan Breeding, FUJIMOTO Hisakuni, Alexander Kellett, Chris Nebel, Matt Neuburg, Laurent Sansonetti and Michelle Steiner, and to all those who have contributed comments, suggestions and bug reports to py-appscript.</p>
 
+<p>Thanks also to <a href="http://www.macosforge.org/">Mac OS Forge</a> and <a href="http://rubyforge.org/">RubyForge</a> for providing project hosting and support.</p>
+
 
 <h2>Donations</h2>
 
 <p>You can <a href="http://sourceforge.net/donate/index.php?group_id=175009">donate to the appscript project</a> via SourceForge.net. Special thanks to all those appscript users who have already contributed.</p>
 
 
-<h2>Copyright</h2>
-
-<p>(C) 2006 HAS -- hhas -at- users - sourceforge - net; <a href="http://rb-appscript.rubyforge.org">http://rb-appscript.rubyforge.org</a></p>
+<h2>Website</h2>
 
-<p>Appscript is released under the <a href="License.txt">MIT License</a>.</p>
+<p><a href="http://rb-appscript.rubyforge.org">http://rb-appscript.rubyforge.org</a></p>
 
 
-<h2>Useful Links</h2>
+<h2>Copyright</h2>
 
-<ul>
-<li><a href="http://www.cs.utexas.edu/users/wcook/papers/AppleScript/AppleScript95.pdf">The Open Scripting Architecture: Automating, Integrating, and Customizing Applications</a> (Cook &amp; Harris, 1993) -- An excellent overview of the OSA infrastructure, which includes Apple event-based application scripting. (PDF)</li>
+<p>(C) 2006 HAS -- hhas -at- users - sourceforge - net</p>
 
-</ul>
+<p>Appscript is released under the MIT License.</p>
 
 
 </div>
 
 <!-- bottom navigation -->
 <div class="navbar">
-	<a href="14_problemapps.html">Previous</a> | <a href="index.html">Up</a>
+	<a href="13_performanceissues.html">Previous</a> | <a href="index.html">Up</a>
 	
 </div>
 

data/doc/appscript-manual/full.css

@@ -17,5 +17,4 @@ th {text-align:left; font-size:0.95em; color:#225; background-color:#ccd;}
 thead {background-color:#ccd;}
 
 
-h1+.navbar {margin-top:0;
-}
+h1+.navbar {margin-top:0;}