RubyGems - rb-scrpt - Versions diffs - 1.0.3 - Mend

rb-scrpt 1.0.3

Files changed (96) hide show

checksums.yaml +7 -0
data/CHANGES +497 -0
data/README.md +8 -0
data/Rakefile +32 -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 +63 -0
data/rb-scrpt.gemspec +16 -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 +69 -0
data/src/SendThreadSafe.c +380 -0
data/src/SendThreadSafe.h +139 -0
data/src/lib/_aem/aemreference.rb +1021 -0
data/src/lib/_aem/codecs.rb +661 -0
data/src/lib/_aem/connect.rb +205 -0
data/src/lib/_aem/encodingsupport.rb +74 -0
data/src/lib/_aem/findapp.rb +85 -0
data/src/lib/_aem/mactypes.rb +250 -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 +242 -0
data/src/lib/_appscript/reservedkeywords.rb +116 -0
data/src/lib/_appscript/safeobject.rb +250 -0
data/src/lib/_appscript/terminology.rb +470 -0
data/src/lib/aem.rb +253 -0
data/src/lib/kae.rb +1489 -0
data/src/lib/osax.rb +659 -0
data/src/lib/rb-scrpt.rb +1073 -0
data/src/lib/version.rb +3 -0
data/src/rbae.c +979 -0
data/test/README +3 -0
data/test/test_aemreference.rb +115 -0
data/test/test_appscriptcommands.rb +149 -0
data/test/test_appscriptreference.rb +103 -0
data/test/test_codecs.rb +181 -0
data/test/test_findapp.rb +23 -0
data/test/test_mactypes.rb +77 -0
data/test/test_osax.rb +52 -0
metadata +146 -0

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

@@ -0,0 +1,211 @@
+<!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 | 7. Application Objects</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="06_classesandenums.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="08_realvsgenericreferences.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>7. Application Objects</h2>
+<h3>Creating application objects</h3>
+<p>Before you can communicate with a scriptable application you must create an <code>Application</code> object, for example:</p>
+<pre><code>textedit = app.by_id('com.apple.textedit')</code></pre>
+<p>To target an application you must call one of the <code>app</code> object's <code>by_*</code> methods with the appropriate argument:</p>
+<dl>
+<dt><code>app.by_name(<var>name</var>)</code> / <code>app(<var>name</var>)</code></dt>
+<dd>The application's filename or POSIX path, e.g. <code>'TextEdit'</code>, <code>'TextEdit.app'</code>, <code>'/Applications/TextEdit.app'</code>. Where a filename is provided, appscript uses LaunchServices to locate the application. An <code>.app</code> suffix is optional. e.g. Given the name <code>'TextEdit'</code>, appscript first searches for an application with that exact filename; if none is found, it automatically adds an <code>.app</code> suffix (<code>'TextEdit.app'</code>) and tries again.</dd>
+<dt><code>app.by_id(<var>id</var>)</code></dt>
+<dd>The application's bundle id, e.g. <code>'com.apple.textedit'</code>. Cocoa applications often have unique bundle ids.</dd>
+<dt><code>app.by_creator(<var>creator</var>)</code></dt>
+<dd>A four-character string containing the application's creator type, e.g. <code>'ttxt'</code>. Older Carbon-based applications and some Cocoa-based applications have unique creator types.</dd>
+<dt><code>app.by_pid(<var>pid</var>)</code></dt>
+<dd>A valid Unix process id, e.g. <code>5687</code>.</dd>
+<dt><code>app.by_url(<var>url</var>)</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>app.by_aem_app(<var>aem_app</var>)</code></dt>
+<dd>An <code>AEM::Application</code> instance.</dd>
+<dt><code>app.current</code></dt>
+<dd>The host application.</dd>
+</dl>
+<p>Examples:</p>
+<pre><code>require "appscript"
+include Appscript
+ical = app('iCal')
+textedit = app('TextEdit.app')
+safari = app('/Applications/Safari')
+addressbook = app.by_id('com.apple.addressbook')
+quicktimeplayer = app.by_creator('TVOD')
+finder = app.by_url('eppc://192.168.10.1/Finder')
+itunes = app.by_url('eppc://Jan%20Smith@G4.local/iTunes')</code></pre>
+<h3>Basic commands</h3>
+<p>All applications should respond to the following commands:</p>
+<pre><code>run -- Run an application. Most applications will open an empty,
+          untitled window.
+launch -- Launch an application without sending it a 'run' event.
+          Applications that normally open a new, empty document
+          upon launch won't. [1]
+activate -- Bring the application to the front.
+reopen -- Reactivate a running application. Some applications
+          will open a new untitled window if no window is open.
+open(<var>value</var>) -- Open the specified object(s).
+    anything -- list of objects to open, typically a list of
+                MacTypes::Alias
+print(<var>value</var>) -- Print the specified object(s).
+    anything -- list of objects to print, typically a list of
+                MacTypes::Alias
+quit(saving => <var>value</var>) -- Quit an application.
+    saving : :yes | :ask | :no -- specifies whether to save
+                                  currently open documents
+</code></pre>
+<p><small>[1] The <code>launch</code> command should be used before constructing references or sending other commands, otherwise appscript will run the application normally.</small></p>
+<p>Some applications may provide their own definitions of some or all of these commands, so check their terminology before use.</p>
+<p>Appscript also defines <code>get</code> and <code>set</code> commands for any scriptable application that doesn't supply its own definitions:</p>
+<pre><code>get(<var>value</var>) -- Get the data for an object.
+    reference -- the object for the command
+    Result: anything -- the reply for the command
+set(<var>value</var>, :to =&gt; <var>value</var>) -- Set an object's data.
+    reference -- the object for the command
+    to : anything -- The new value.</code></pre>
+<p>Note that these commands are only useful in applications that define an Apple Event Object Model as part of their Apple event interface.</p>
+<h3>Transaction support</h3>
+<p>Application objects implement three additional methods, <code>begin_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>begin_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>begin_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. (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>
+<h3>Local application launching notes</h3>
+<p>Note: the following information only applies to local applications as appscript cannot directly launch applications on a remote Mac. To control a remote application, the application must be running beforehand or else launched indirectly (e.g. by using the remote Mac's Finder to open it).</p>
+<h4>How applications are identified</h4>
+<p>When you create an Application object by application name, bundle id or creator type, appscript uses LaunchServices to locate an application matching that description. If you have more than one copy of the same application installed, you can identify the one you want by providing its full path, otherwise LaunchServices will identify the newest copy for you.</p>
+<p>Appscript identifies running applications by their process ids so it's possible to control multiple versions of an application running at the same time if their Application objects are created using process ids or eppc URLs.</p>
+<h4>Checking if an application is running</h4>
+<p>You can check if the application specified by an Application object is currently running by calling its <code>#is_running?</code> method. This is useful if you don't want to perform commands on an application that isn't already running. For example:</p>
+<pre><code>te = app('TextEdit')
+# Only perform TextEdit-related commands if it's already running:
+if te.is_running?
+    # all TextEdit-related code goes here...
+end</code></pre>
+<p class="hilitebox">Remember that appscript automatically launches a non-running application the first time your script makes reference to any of its properties, elements or commands. To avoid accidental launches, <em>all</em> code relating to that application must be included in a conditional block that only executes if <code>#is_running?</code> returns <code>true</code>.</p>
+<h4>Launch errors</h4>
+<p>If the application can't be launched for some reason (e.g. if it's in the Trash), an <code>Appscript::CantLaunchApplicationError</code> error will be raised. This provides a description of the problem (if it's a standard LaunchServices error) along with the original OS error number, which you can also obtain via the <code>CantLaunchApplicationError#to_i</code> method.</p>
+<h4>Using <code>launch</code> vs <code>run</code></h4>
+<p>When appscript launches a non-running application, it normally sends it a <code>run</code> command as part of the launching process. If you wish to avoid this, you should start the application by sending it a <code>launch</code> command before doing anything else. For example:</p>
+<pre><code>te = app('TextEdit')
+te.launch
+# other TextEdit-related code goes here...</code></pre>
+<p>This is useful when you want to start an application without it going through its normal startup procedure. For example, the above script will launch TextEdit without causing it to display a new, empty document (its usual behaviour).</p>
+<p><code>launch</code> is also useful if you need to send a non-running application an <code>open</code> command as its very first instruction. For example, to send an <code>open</code> command to a non-stay-open application that batch processes one or more dropped files then quits again, you must first start it using <code>launch</code>, then send it an <code>open</code> command with the files to process. If you forget to do this, the application will first receive a <code>run</code> command and quit again before the <code>open</code> command can be handled.</p>
+<h4>Restarting applications</h4>
+<p>As soon as you start to construct a reference or command using a newly created Application objects, if the application is not already running then appscript will automatically launch it in order to obtain its terminology.</p>
+<p>If the target application has stopped running since the Application object was created, trying to send it a command using that Application object will result in an invalid connection error (-609), unless that command is <code>run</code> or <code>launch</code>. This restriction prevents appscript accidentally restarting an application that has unexpectedly quit while a script is controlling it. Scripts can restart an application by sending an explicit <code>run</code> or <code>launch</code> command, or by creating a new Application object for it.</p>
+<p>Note that you can still use Application objects to control applications that have been quit <em>and</em> restarted since the Application object was created. Appscript will automatically update the Application object's process id information as needed.</p>
+<p class="hilitebox">There is a known problem with quitting and immediately relaunching an application via appscript, where the relaunch instruction is sent to the application before it has actually quit. This timing issue appears to be the OS's fault; the current workaround for scripts that need to quit and restart applications is to insert a few seconds' delay between the <code>quit</code> and <code>run</code>/<code>launch</code> using Ruby's <code>sleep</code> function.</p>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="06_classesandenums.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="08_realvsgenericreferences.html">Next</a>
+</div>
+</body>
+</html>

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

@@ -0,0 +1,96 @@
+<!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 | 8. Real vs. Generic 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>
+</head>
+<body>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
+<!-- top navigation -->
+<div class="navbar">
+<a href="07_applicationobjects.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="09_referenceforms.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>8. Real vs. Generic References</h2>
+<h3>Real vs. generic references</h3>
+<p>References may be either 'real' or 'generic'. A real reference relates to a specific application, while a generic reference doesn't. Generic references provide a convenient shortcut for writing literal references without having to specify an application each time.</p>
+<p>A real reference begins with an <code>app</code> call, followed by a <code>by_name</code>, <code>by_id</code>, <code>by_creator</code>, <code>by_pid</code>, <code>by_url</code> call that identifies the application whose object(s) it refers to, e.g.:</p>
+<pre><code>app.by_name('TextEdit').documents.end
+app.by_url('eppc://my-mac.local/Finder').home.folders.name</code></pre>
+<p>(Remember than <code>app.by_name('TextEdit')</code> can be shortened to <code>app('TextEdit')</code> for convenience.</p>
+<p>A generic reference begins with <code>app</code>, <code>con</code> or <code>its</code> and does not identify the application to which it relates, e.g.:</p>
+<pre><code>app.documents.end
+con.word[3]
+its.name.begins_with('d')</code></pre>
+<p>Generic references are only evaluated when used used within real references, either as selectors:</p>
+<pre><code>app('Finder').home.folders[<em>its.name.begins_with('d')</em>].get
+app('Tex-Edit Plus').windows[1].text[<em>con.words[2]</em>, <em>con.words[-2]</em>].get</code></pre>
+<p>or as command parameters:</p>
+<pre><code>app('TextEdit').make(
+    :new =&gt; :word,
+    :at =&gt; <em>app.documents[1].words.end</em>,
+    :with_data =&gt; 'Hello')
+app('Finder').desktop.duplicate(
+    :to =&gt; <em>app.home.folders['Desktop Copy']</em>)</code></pre>
+<h3>Comparing and hashing references</h3>
+<p>Application references can be compared for equality and are hashable (so can be used as dictionary keys). For two real references to be considered equal, both must have the same application path or url and reference structure. Examples:</p>
+<pre><code>puts app('TextEdit').documents[1] == \
+    app.by_id('com.apple.textedit').documents[1].get
+# Result: true; both references evaluate to the same
+#     application path and reference
+puts app('Finder').home == app('Finder').home.get
+# Result: false; app('Finder').home.get returns a
+#     different reference to the same location</code></pre>
+<p>For two generic references to be equal, both must have the same reference structure. Note that comparing generic references to real references will always return a false result.</p>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="07_applicationobjects.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="09_referenceforms.html">Next</a>
+</div>
+</body>
+</html>

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

@@ -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>