RubyGems - rb-scpt - Versions diffs - 1.0.0 - Mend

rb-scpt 1.0.0

Files changed (94) hide show

checksums.yaml +7 -0
data/CHANGES +497 -0
data/doc/aem-manual/01_introduction.html +60 -0
data/doc/aem-manual/02_apioverview.html +107 -0
data/doc/aem-manual/03_packingandunpackingdata.html +135 -0
data/doc/aem-manual/04_references.html +409 -0
data/doc/aem-manual/05_targetingapplications.html +164 -0
data/doc/aem-manual/06_buildingandsendingevents.html +229 -0
data/doc/aem-manual/07_findapp.html +63 -0
data/doc/aem-manual/08_examples.html +94 -0
data/doc/aem-manual/aemreferenceinheritance.gif +0 -0
data/doc/aem-manual/index.html +56 -0
data/doc/appscript-manual/01_introduction.html +94 -0
data/doc/appscript-manual/02_aboutappscripting.html +247 -0
data/doc/appscript-manual/03_quicktutorial.html +167 -0
data/doc/appscript-manual/04_gettinghelp.html +188 -0
data/doc/appscript-manual/05_keywordconversion.html +106 -0
data/doc/appscript-manual/06_classesandenums.html +192 -0
data/doc/appscript-manual/07_applicationobjects.html +211 -0
data/doc/appscript-manual/08_realvsgenericreferences.html +96 -0
data/doc/appscript-manual/09_referenceforms.html +241 -0
data/doc/appscript-manual/10_referenceexamples.html +154 -0
data/doc/appscript-manual/11_applicationcommands.html +245 -0
data/doc/appscript-manual/12_commandexamples.html +138 -0
data/doc/appscript-manual/13_performanceissues.html +142 -0
data/doc/appscript-manual/14_notes.html +80 -0
data/doc/appscript-manual/application_architecture.gif +0 -0
data/doc/appscript-manual/application_architecture2.gif +0 -0
data/doc/appscript-manual/finder_to_textedit_event.gif +0 -0
data/doc/appscript-manual/index.html +62 -0
data/doc/appscript-manual/relationships_example.gif +0 -0
data/doc/appscript-manual/ruby_to_itunes_event.gif +0 -0
data/doc/full.css +106 -0
data/doc/index.html +45 -0
data/doc/mactypes-manual/01_introduction.html +54 -0
data/doc/mactypes-manual/02_aliasclass.html +124 -0
data/doc/mactypes-manual/03_fileurlclass.html +126 -0
data/doc/mactypes-manual/04_unitsclass.html +100 -0
data/doc/mactypes-manual/index.html +53 -0
data/doc/osax-manual/01_introduction.html +67 -0
data/doc/osax-manual/02_interface.html +147 -0
data/doc/osax-manual/03_examples.html +73 -0
data/doc/osax-manual/04_notes.html +61 -0
data/doc/osax-manual/index.html +53 -0
data/doc/rb-appscript-logo.png +0 -0
data/extconf.rb +65 -0
data/rb-scpt.gemspec +14 -0
data/sample/AB_export_vcard.rb +31 -0
data/sample/AB_list_people_with_emails.rb +13 -0
data/sample/Add_iCal_event.rb +21 -0
data/sample/Create_daily_iCal_todos.rb +75 -0
data/sample/Export_Address_Book_phone_numbers.rb +59 -0
data/sample/Hello_world.rb +21 -0
data/sample/List_iTunes_playlist_names.rb +11 -0
data/sample/Make_Mail_message.rb +33 -0
data/sample/Open_file_in_TextEdit.rb +13 -0
data/sample/Organize_Mail_messages.rb +61 -0
data/sample/Print_folder_tree.rb +16 -0
data/sample/Select_all_HTML_files.rb +14 -0
data/sample/Set_iChat_status.rb +24 -0
data/sample/Simple_Finder_GUI_Scripting.rb +18 -0
data/sample/Stagger_Finder_windows.rb +25 -0
data/sample/TextEdit_demo.rb +130 -0
data/sample/iTunes_top40_to_html.rb +71 -0
data/src/SendThreadSafe.c +380 -0
data/src/SendThreadSafe.h +139 -0
data/src/lib/_aem/aemreference.rb +1022 -0
data/src/lib/_aem/codecs.rb +662 -0
data/src/lib/_aem/connect.rb +205 -0
data/src/lib/_aem/encodingsupport.rb +77 -0
data/src/lib/_aem/findapp.rb +85 -0
data/src/lib/_aem/mactypes.rb +251 -0
data/src/lib/_aem/send.rb +279 -0
data/src/lib/_aem/typewrappers.rb +59 -0
data/src/lib/_appscript/defaultterminology.rb +277 -0
data/src/lib/_appscript/referencerenderer.rb +245 -0
data/src/lib/_appscript/reservedkeywords.rb +116 -0
data/src/lib/_appscript/safeobject.rb +249 -0
data/src/lib/_appscript/terminology.rb +471 -0
data/src/lib/aem.rb +253 -0
data/src/lib/appscript.rb +1075 -0
data/src/lib/kae.rb +1489 -0
data/src/lib/osax.rb +659 -0
data/src/rbae.c +979 -0
data/test/README +3 -0
data/test/test_aemreference.rb +118 -0
data/test/test_appscriptcommands.rb +152 -0
data/test/test_appscriptreference.rb +106 -0
data/test/test_codecs.rb +186 -0
data/test/test_findapp.rb +26 -0
data/test/test_mactypes.rb +79 -0
data/test/test_osax.rb +54 -0
data/test/testall.sh +10 -0
metadata +145 -0

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

@@ -0,0 +1,241 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>rb-appscript manual | 9. Reference Forms</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<style type="text/css" media="all"><!--@import url(../full.css);--></style>
+</head>
+<body>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
+<!-- top navigation -->
+<div class="navbar">
+<a href="08_realvsgenericreferences.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="10_referenceexamples.html">Next</a>
+<span>
+<strong><a href="../appscript-manual/index.html">appscript</a></strong> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<a href="../aem-manual/index.html">aem</a>
+</span>
+</div>
+<!-- content -->
+<div id="content">
+<h2>9. Reference Forms</h2>
+<h3>Property reference</h3>
+<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>
+<p>Syntax:</p>
+<pre><code>reference.property</code></pre>
+<p>Examples:</p>
+<pre><code>textedit.<em>name</em>
+textedit.documents[1].<em>text</em>
+finder.<em>home</em>.files.<em>name</em></code></pre>
+<h3>Element references</h3>
+<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>
+<h4>All Elements</h4>
+<p>Syntax:</p>
+<pre><code>reference.elements</code></pre>
+<p>Examples:</p>
+<pre><code>finder.home.<em>folders</em>
+textedit.<em>windows</em>
+textedit.<em>documents</em>.<em>paragraphs</em>.<em>words</em></code></pre>
+<h4>by Name</h4>
+<p>Syntax:</p>
+<pre><code>elements[selector]
+        selector : String -- name of object (as matches its 'name' property)</code></pre>
+<p>Examples:</p>
+<pre><code>disks['Macintosh HD']
+files['index.html']</code></pre>
+<p class="hilitebox">Note: applications usually treat object names as case-insensitive. Where multiple element have the same name, a by-name reference only identifies the first element found with that name. (Tip: to identify <em>all</em> elements with a particular name, use a by-filter reference instead.)</p>
+<h4>by Index</h4>
+<p>Syntax:</p>
+<pre><code>elements[selector]
+        selector : Fixnum | Bignum -- index of object</code></pre>
+<p>Examples:</p>
+<pre><code>words[3]
+items[-1]</code></pre>
+<p class="hilitebox">Note: elements are <em>one-indexed</em> (AEM-style indexing), not zero-indexed (Ruby-style indexing).</p>
+<h4>by ID</h4>
+<p>Syntax:</p>
+<pre><code>elements.ID(selector)
+        selector : anything -- object's id</code></pre>
+<p>Examples:</p>
+<pre><code>windows.ID(4321)</code></pre>
+<h4>by Absolute Position</h4>
+<p>Syntax:</p>
+<pre><code>elements.first -- first element
+elements.middle -- middle element
+elements.last -- last element
+elements.any -- random element</code></pre>
+<p>Examples:</p>
+<pre><code>documents.first
+paragraphs.last
+files.any</code></pre>
+<h4>by Relative Position</h4>
+<p>Syntax:</p>
+<pre><code>elements[selector].previous(class) -- nearest element of a given class to appear
+                                       before the specified element
+elements[selector].next(class) -- nearest element of a given class to appear
+                                   after the specified element
+        class : Symbol -- class of element (see <a href="06_classesandenums.html">Classes and Enumerated Types</a>)</code></pre>
+<p>Examples:</p>
+<pre><code>words[3].next(:word)
+paragraphs[-1].previous(:character)</code></pre>
+<h4>by Range</h4>
+<p>Range references select all elements between and including two references indicating the start and stop of the range. The start and stop references are normally declared relative to the container of the elements being selected. Appscript defines an object, <code>con</code> (short for 'container'), to indicate this container; for example, to indicate the third paragraph of the currrent container object:</p>
+<pre><code>con.paragraphs[3]</code></pre>
+<p>For convenience, the range reference also allows start and stop references to be written in shorthand form where their element class is the same as the elements being selected; thus:</p>
+<pre><code>ref.paragraphs[con.paragraphs[3], con.paragraphs[-1]]</code></pre>
+<p>can also be written as:</p>
+<pre><code>ref.paragraphs[3:-1]</code></pre>
+<p>Some applications can handle more complex range references. For example, the following will work in Tex-Edit Plus:</p>
+<pre><code>ref.words[con.characters[5], con.paragraphs[-2]]</code></pre>
+<p>Syntax:</p>
+<pre><code>elements[start, stop]
+        start : Fixnum | Bignum | String | Reference -- beginning of range
+        stop : Fixnum | Bignum | String | Reference -- end of range</code></pre>
+<p>Examples:</p>
+<pre><code>folders['Documents', 'Movies']
+documents[1, 3]
+text[con.characters[5], con.words[-2]]</code></pre>
+<p class="hilitebox">Note: ranges are specified as [start-position, <em>stop-position</em>] (AEM-style ranges), not [start-position, <em>length</em>] (Ruby-style ranges).</p>
+<h4>by Filter</h4>
+<p>A reference to each element that satisfies one or more conditions specified by a test expression:</p>
+<pre><code>elements[testExpression]</code></pre>
+<p>Test expressions consist of the following:</p>
+<ul>
+<li><p>A reference to each element being tested, represented by appscript's <code>its</code> object. This object supports all valid reference forms, allowing you to construct references to its properties and elements. For example:</p>
+<pre><code>its
+its.size
+its.words.first</code></pre></li>
+<li><p>One or more conditional tests, implemented as methods on the reference being tested. Each method takes a test reference or a value as its sole argument.</p>
+<p>Syntax:</p>
+<pre><code>reference.lt(value) # &lt;
+reference.le(value) # &lt;=
+reference.eq(value) # ==
+reference.ne(value) # !=
+reference.gt(value) # &gt;
+reference.ge(value) # &gt;=
+reference.begins_with(value)
+reference.ends_with(value)
+reference.contains(value)
+reference.is_in(value)
+reference.does_not_begin_with(value)
+reference.does_not_end_with(value)
+reference.does_not_contain(value)
+reference.is_not_in(value)
+        value : reference or value</code></pre>
+<p>Examples:</p>
+<pre><code>its.eq('')
+its.size.gt(1024)
+its.words.first.begins_with('A')
+its.characters.first.eq(its.characters.last)</code></pre>
+<li><p>Zero or more logical tests, implemented as properties/methods on conditional tests. The <code>and</code> and <code>or</code> methods take one or more conditional or logic tests as arguments.</p>
+<p>Syntax:</p>
+<pre><code>test.and(test, ...)
+test.or(test, ...)
+test.not</code></pre>
+<p>Examples:</p>
+<pre><code>its.eq('').not
+its.size.gt(1024).and(its.size.lt(10240))
+its.words[1].begins_with('A').or(
+    its.words[2].contains('ce'),
+    its.words[1].eq('Foo'))</code></pre></li>
+</ul>
+<h3>Insertion location</h3>
+<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.beginning
+elements.end
+elements[selector].before
+elements[selector].after</code></pre>
+<p>Examples:</p>
+<pre><code>documents.end
+paragraphs[1].before</code></pre>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="08_realvsgenericreferences.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="10_referenceexamples.html">Next</a>
+</div>
+</body>
+</html>

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

@@ -0,0 +1,154 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>rb-appscript manual | 10. Reference Examples</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<style type="text/css" media="all"><!--@import url(../full.css);--></style>
+</head>
+<body>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
+<!-- top navigation -->
+<div class="navbar">
+<a href="09_referenceforms.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="11_applicationcommands.html">Next</a>
+<span>
+<strong><a href="../appscript-manual/index.html">appscript</a></strong> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<a href="../aem-manual/index.html">aem</a>
+</span>
+</div>
+<!-- content -->
+<div id="content">
+<h2>10. Reference Examples</h2>
+<h3>Application objects</h3>
+<pre><code>require "appscript"
+include Appscript
+# application &quot;Finder&quot;
+app('Finder')
+# application &quot;Macintosh HD:Applications:TextEdit.app:&quot;
+app('/Applications/TextEdit.app')</code></pre>
+<h3>Property references</h3>
+<pre><code># a reference to startup disk of application &quot;Finder&quot;
+app('Finder').startup_disk
+# a reference to name of folder 1 of home of application &quot;Finder&quot;
+app('Finder').home.folders[1].name
+# a reference to name of every item of home of application &quot;Finder&quot;
+app('Finder').home.items.name
+# a reference to text of every document of application &quot;TextEdit&quot;
+app('TextEdit').documents.text
+# a reference to color of character 1 of every paragraph of text &not;
+#     of document 1 of application &quot;TextEdit&quot;
+app('TextEdit').documents[1].text.paragraphs.characters[1].color</code></pre>
+<h3>All elements references</h3>
+<pre><code># a reference to disks of application &quot;Finder&quot;
+app('Finder').disks
+# a reference to every word of every paragraph of text of every document &not;
+#     of application &quot;TextEdit&quot;
+app('TextEdit').documents.text.paragraphs.words</code></pre>
+<h3>Single element references</h3>
+<pre><code># a reference to disk 1 of application &quot;Finder&quot;
+app('Finder').disks[1]
+# a reference to file &quot;ReadMe.txt&quot; of folder &quot;Documents&quot; of home of application &quot;Finder&quot;
+app('Finder').home.folders['Documents'].files['ReadMe.txt']
+# a reference to paragraph -1 of text of document 1 of application &quot;TextEdit&quot;
+app('TextEdit').documents[1].text.paragraphs[-1]
+# a reference to middle paragraph of text of last document of application &quot;TextEdit&quot;
+app('TextEdit').documents.last.text.paragraphs.middle
+# a reference to any file of home of application &quot;Finder&quot;
+app('Finder').home.files.any</code></pre>
+<h3>Relative references</h3>
+<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)
+# a reference to paragraph after character 30 of document 1 of application &quot;Tex-Edit Plus&quot;
+app('Tex-Edit Plus').documents[1].characters[30].next(:paragraph)</code></pre>
+<h3>Element range references</h3>
+<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]
+# a reference to paragraphs 2 thru -1 of text of document 1 of application &quot;TextEdit&quot;
+app('TextEdit').documents[1].text.paragraphs[2, -1]
+# a reference to folders &quot;Documents&quot; thru &quot;Music&quot; of home of application &quot;Finder&quot;
+app('Finder').home.folders['Documents', 'Music']
+# a reference to text (word 3) thru (paragraph 7) of document 1 of application &quot;Tex-Edit Plus&quot;
+app('Tex-Edit Plus').documents[1].text[con.words[3], con.paragraphs[7]]</code></pre>
+<h3>Filter references</h3>
+<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")]
+# a reference to every paragraph of document 1 of application &quot;Tex-Edit Plus&quot; &not;
+#     whose first character is last character
+app('Tex-Edit Plus').documents[1].paragraphs[
+    its.characters.first.eq(its.characters.last)]
+# a reference to every file of folder &quot;Documents&quot; of home of application &quot;Finder&quot; &not;
+#     whose name extension is &quot;txt&quot; and size < 10240
+app('Finder').home.folders['Documents'].files[
+    its.name_extension.eq('txt').and(its.size.lt(10240))]</code></pre>
+<h3>Insertion location references</h3>
+<pre><code># a reference to end of documents of application &quot;TextEdit&quot;
+app('TextEdit').documents.end
+# a reference to before paragraph 1 of text of document 1 of application &quot;TextEdit&quot;
+app('TextEdit').documents[1].text.paragraphs[1].before</code></pre>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="09_referenceforms.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="11_applicationcommands.html">Next</a>
+</div>
+</body>
+</html>

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

@@ -0,0 +1,245 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>rb-appscript manual | 11. Application Commands</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<style type="text/css" media="all"><!--@import url(../full.css);--></style>
+</head>
+<body>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
+<!-- top navigation -->
+<div class="navbar">
+<a href="10_referenceexamples.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="12_commandexamples.html">Next</a>
+<span>
+<strong><a href="../appscript-manual/index.html">appscript</a></strong> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<a href="../osax-manual/index.html">osax</a> /
+<a href="../aem-manual/index.html">aem</a>
+</span>
+</div>
+<!-- content -->
+<div id="content">
+<h2>11. Application Commands</h2>
+<h3>Command syntax</h3>
+<p>Appscript commands have the following syntax:</p>
+<pre><code>application.command_name([direct_parameter][, keyword_parameters])</code></pre>
+<p>Both direct and keyword parameters are optional.</p>
+<p>Application commands are implemented by the application's top-level <code>application</code> object (represented by an <code>Appscript::Application</code> instance). For convenience, appscript also makes application commands available as methods on every reference. If a command is called upon a reference rather than an Application object, that reference will be taken as the application's direct parameter (with one or two caveats; see the Special Cases section below).</p>
+<p>The command's direct parameter can be any value; the application's dictionary will (usually) indicate the appropriate types. A command can have a maximum of one direct parameter; if more than one is given, an error will occur. Keyword parameters are specified as a <code>Hash</code> object whose keys are symbols representing the parameter names:</p>
+<pre><code>application.command_name(direct_parameter, {:name1 =&gt; value1, :name2 =&gt; value2, ...})</code></pre>
+<p>Note that Ruby allows the hash to be written without the enclosing <code>{</code> and <code>}</code> for appearance's sake:</p>
+<pre><code>application.command_name(direct_parameter, :name1 =&gt; value1, :name2 =&gt; value2, ...)</code></pre>
+<p>Each command can have zero or more keyword parameters as defined in the application dictionary. In addition, appscript provides the following default parameters for indicating how the command should be handled:</p>
+<table summary="Default appscript parameters">
+<thead>
+<tr><th>Name</th><th>Class</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:wait_reply</code></td><td><code>Boolean</code></td><td>Wait for application to return a result/error?</td></tr>
+<tr><td><code>:timeout</code></td><td><code>Integer</code></td><td>Number of seconds to wait for a reply (no timeout = 0)</td></tr>
+<tr><td><code>:result_type</code></td><td><code>nil</code> | <code>Symbol</code></td><td>AE type to coerce return value to (e.g. <code>:FSRef</code>)</td></tr>
+<tr><td><code>:ignore</code></td><td><code>nil</code> | <code>Array of Symbol</code></td><td>String characteristics to ignore when evaluating references. The array should contain zero or more of the following enumerators: <code>:case</code>, <code>:diacriticals</code>, <code>:expansion</code>, <code>:hyphens</code>, <code>:punctuation</code>, <code>:whitespace</code></td></tr>
+</tbody>
+</table>
+<p>(Note that most applications currently ignore the <code>:ignore</code> parameter and use the default behaviour, i.e. ignore case.)</p>
+<p>For convenience, appscript allows the direct parameter and/or keyword parameters arguments to be omitted from the method's argument list if unused. For example, a command that has no direct or keyword parameters would be written as:</p>
+<pre><code>application.command_name</code></pre>
+<p>If the command takes only keyword parameters, or the direct parameter is the reference upon which the command is called, it can be written as:</p>
+<pre><code>application.command_name(:name1 =&gt; value1, :name2 =&gt; value2, ...)</code></pre>
+<p>If the command takes only a direct parameter <em>and</em> the value given is not a hash, then it can be written as follows:
+<pre><code>application.command_name(direct_parameter)</code></pre>
+<p>If the direct parameter is a Ruby hash, you <em>must</em> provide an empty keyword parameters hash as the second argument to the call:</p>
+<pre><code>application.command_name(direct_hash_parameter, {})</code></pre>
+<p>If you forget, appscript will treat this hash value as the command's keyword parameters, resulting in an error or other unexpected behaviour.</p>
+<p>See the Special cases section below for additional rules.</p>
+<h3>Examples</h3>
+<pre><code># tell application &quot;TextEdit&quot; to activate
+app('TextEdit').activate
+# tell application &quot;TextEdit&quot; to open fileRefList
+app('TextEdit').open(fileRefList)
+# tell application &quot;Finder&quot; to get version
+app('Finder').version.get
+# tell application &quot;Finder&quot; to set name of file &quot;foo.txt&quot; of home to &quot;bar.txt&quot;
+app('Finder').home.files['foo.txt'].name.set('bar.txt')
+# tell application &quot;TextEdit&quot; to count (text of first document) each paragraph
+app('TextEdit').documents.first.text.count(:each =&gt; :paragraph)
+# tell application &quot;TextEdit&quot; to make new document at end of documents
+app('TextEdit').documents.end.make(:new =&gt; :document)
+# tell application &quot;Finder&quot; to get items of home as alias list
+app('Finder').home.items.get(:result_type =&gt; :alias)</code></pre>
+<h3>Special cases</h3>
+<p>The following special-case behaviours are implemented for convenience:</p>
+<ol>
+<li><p>Commands that take a reference to one or more application objects as a direct parameter may be written in the following form:</p>
+<pre><code>reference.command(keyword_parameters)</code></pre>
+<p>The conventional  form is also supported should you ever wish (or need) to use it:</p>
+<pre><code>application.command(reference, keyword_parameters)</code></pre>
+<p>The two forms are equivalent (appscript converts the first form to the second behind the scenes) although the first form is preferred for conciseness.</p></li>
+<li><p>If a command that already has a direct parameter is called on a reference, i.e.:</p>
+<pre><code>reference.command(direct_parameter[, keyword_parameters])</code></pre>
+<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>
+<pre><code>reference.set(value)</code></pre>
+<p>instead of:</p>
+<pre><code>reference.set(:to =&gt; value)</code></pre>
+<p>or:</p>
+<pre><code>application.set(reference, :to =&gt; value)</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>
+<h3>Command errors</h3>
+<p>The <code>Appscript::CommandError</code> exception describes an error raised by the target application or Apple Event Manager when sending a command.</p>
+<pre><code>CommandError < RuntimeError
+    Methods:
+        error_number : FixNum -- Mac OS error number
+        error_message : String -- application-supplied/generic error description
+        offending_object : anything | nil -- object that caused the error,
+                                             if given by application
+        expected_type : anything | nil -- object that caused a coercion error,
+                                          if given by application
+        partial_result : anything | nil -- part of return value constructed
+                                           before error occurred, if given
+                                           by application
+        to_i : FixNum -- equivalent to #error_number
+        to_s : String -- formatted error information</code></pre>
+<h3>Note to AppleScript users</h3>
+<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>d = app('TextEdit').documents</code></pre>
+<p>is <em>not</em> the same as:</p>
+<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 <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>
+<p>To get a single reference to all documents:</p>
+<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;
+d = app('TextEdit').documents
+print d
+--&gt; app('TextEdit').documents</code></pre>
+<p>To get a list of references to each document:</p>
+<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;}
+d = app('TextEdit').documents.get -- (explicit 'get' is required)
+print d
+--&gt; [app('TextEdit').documents[1], app('TextEdit').documents[2]]</code></pre>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="10_referenceexamples.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="12_commandexamples.html">Next</a>
+</div>
+</body>
+</html>