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/04_gettinghelp.html ADDED Viewed

@@ -0,0 +1,188 @@
+<!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 | 4. Getting Help</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="03_quicktutorial.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="05_keywordconversion.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>4. Getting Help</h2>
+<p>When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the ASDictionary application, appscript's powerful built-in <code>help</code> method, and introspection.</p>
+<h3>ASDictionary</h3>
+<p>ASDictionary, available from the appscript website's <a href="http://appscript.sourceforge.net/tools.html">Tools 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>
+<h3>Built-in <code>help</code> method</h3>
+<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>
+<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>
+<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>
+<pre><code>app('TextEdit').help('-h')</code></pre>
+<p>To print a description of any class or command or view inheritance and relationships, pass the <code>help</code> method a help string containing one or more of the following options:</p>
+<dl>
+<dt>-h</dt>
+<dd>show help</dd>
+<dt>-o</dt>
+<dd>overview of all suites, classes and commands</dd>
+<dt>-k</dt>
+<dd>list all built-in keywords (type names)</dd>
+<dt>-u [suite-name]</dt>
+<dd>summary of named suite or all suites</dd>
+<dt>-t [class-or-command-name]</dt>
+<dd>terminology for named class/command or current reference</dd>
+<dt>-i [class-name]</dt>
+<dd>inheritance tree for named class or all classes</dd>
+<dt>-r [class-name]</dt>
+<dd>one-to-one and one-to-many relationships for named class or current reference</dd>
+<dt>-s [property-or-element-name]</dt>
+<dd>values of properties and elements of object(s) currently referenced</dd>
+</dl>
+<p>Arguments (shown in brackets) are optional. Additional information on usage is available via <code>help('-h')</code>.</p>
+<p>Examples:</p>
+<pre><code>app('Finder').help('-o')
+app('Finder').help('-t window')
+app('Finder').files.help # same as help('-t')
+app('Finder').help('-d item -r folder -i container')
+app('Finder').files.help('-s')</code></pre>
+<p>To print detailed information on a specific reference, call its <code>help</code> method without arguments. Examples:</p>
+<pre><code>app('TextEdit').help
+app('TextEdit').version.help
+app('TextEdit').documents.help</code></pre>
+<p>To print detailed information on a specific command, call the <code>help</code> method on an application or reference object with the <code>-t</code> option followed by the command's name. Examples:</p>
+<pre><code>app('TextEdit').help('-t open')
+app('TextEdit').documents.help('-t count -t close')</code></pre>
+<div class="hilitebox">
+<p>Tip: <code>help</code> calls can safely be inserted at any point in a reference without disrupting your script's execution:</p>
+<pre><code>c = app('TextEdit')<strong>.help.help('-o -i -s')</strong>.documents.<strong>help</strong>[1]<strong>.help</strong>.count</code></pre>
+</div>
+<h3>Introspection</h3>
+<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>
+<dl>
+<dt><code>properties</code></dt>
+<dd>Returns a list of all property names.</dd>
+<dt><code>elements</code></dt>
+<dd>Returns a list of all element names.</dd>
+<dt><code>commands</code></dt>
+<dd>Returns a list of all command names.</dd>
+<dt><code>keywords</code></dt>
+<dd>Returns a list of all class, enumerator, type and property names.</dd>
+<dt><code>parameters(commandName)</code></dt>
+<dd>Takes a command's name as string and returns the names of its parameters.</dd>
+</dl>
+<p>As with Ruby's <code>Object#methods</code>, all of these methods return a list of strings.</p>
+<p>Examples</p>
+<pre><code>te = app('TextEdit')
+p te.commands
+# ["activate", "close", "count", "delete", "duplicate", "exists", ...]
+p te.parameters('make')
+# ["at", "new", "with_data", "with_properties"]</code></pre>
+<h3>ASTranslate</h3>
+<p>ASTranslate, available from the appscript website's <a href="http://appscript.sourceforge.net/tools.html">tools page</a>, provides a simple tool for translating application commands from AppleScript to Ruby syntax - useful when help is needed in converting existing AppleScript code to Ruby. For example, the following AppleScript selects every file in the Home folder:</p>
+<pre><code>tell application "Finder"
+	select (every file of home whose name extension is in {"htm", "html"})
+end tell</code></pre>
+<p>To obtain the appscript equivalent, paste this script into ASTranslate and select <code>Execute</code> from the <code>Document</code> menu. ASTranslate will intercept any Apple events sent by AppleScript and display them appscript format:</p>
+<pre><code>app("Finder").home.files[its.name_extension.is_in(["htm", "html"])].select
+OK</code></pre>
+<p>See ASTranslate's documentation for more information.</p>
+<h3>Notes</h3>
+<p>While appscript's documentation systems try to be reasonably forgiving of flawed or faulty terminology resources, there may be a few particularly problematic applications on which they fail. Should this happen, use ASDictionary to export the application's terminology in plain text format instead.</p>
+<h3>Other sources of help</h3>
+<ul>
+<li>The <code>sample</code> folder contains example scripts demonstrating a range of common tasks.</li>
+<li>Refer to any scripting documentation and example scripts supplied by the application developer.</li>
+<li>Look for third-party scripts that provide examples of use (though many of these scripts will be written in AppleScript rather than Ruby).</li>
+<li>The <a href="http://appscript.sourceforge.net">appscript website</a> has links to mailing lists and other general resources.</li>
+</ul>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="03_quicktutorial.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="05_keywordconversion.html">Next</a>
+</div>
+</body>
+</html>

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

@@ -0,0 +1,106 @@
+<!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 | 5. Keyword Conversion</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="04_gettinghelp.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="06_classesandenums.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>5. Keyword Conversion</h2>
+<h3>Keyword conversion</h3>
+<p>Because application terminology resources specify AppleScript-style keywords for class, property, command, etc. names, appscript uses the following rules to translate these keywords to legal Ruby identifiers:</p>
+<ul>
+<li>Characters a-z, A-Z, 0-9 and underscores (_) are preserved.</li>
+<li>Spaces, hyphens (-) and forward slashes (/) are replaced with underscores.</li>
+<li>Ampersands (&amp;) are replaced by the word 'and'.</li>
+<li>All other characters are converted to 0x00-style hexadecimal representations.</li>
+<li>Names that begin with '_' or 'AS_' have an underscore appended.</li>
+<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             ignore
+after                         inspect
+and                           instance_eval
+any                           instance_variable_get
+before                        instance_variable_set
+begin_transaction             instance_variables
+beginning                     is_in
+begins_with                   is_not_in
+by_aem_app                    keywords
+by_creator                    last
+by_id                         launch
+by_name                       le
+by_pid                        lt
+by_url                        method
+class                         method_missing
+clone                         methods
+commands                      middle
+contains                      ne
+current                       next
+display                       not
+does_not_begin_with           object_id
+does_not_contain              or
+does_not_end_with             parameters
+dup                           previous
+elements                      private_methods
+end                           properties
+end_transaction               protected_methods
+ends_with                     public_methods
+eq                            result_type
+extend                        send
+first                         singleton_methods
+freeze                        taint
+ge                            timeout
+gt                            to_a
+hash                          to_s
+help                          type
+ID                            untaint
+id                            wait_reply</code></pre>
+</li>
+<li>Appscript provides default terminology for standard type classes such as <code>integer</code> and <code>unicode_text</code>, and standard commands such as <code>open</code> and <code>quit</code>. If an application-defined name matches a built-in name but has a different Apple event code, appscript will append an underscore to the application-defined name.</li>
+</ul>
+<p class="hilitebox">You can use ASDictionary or appscript's built-in <code>help</code> method to export or view application terminology in appscript format. See the <a href="04_gettinghelp.html">Getting Help</a> chapter for more information.</p>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="04_gettinghelp.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="06_classesandenums.html">Next</a>
+</div>
+</body>
+</html>

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

@@ -0,0 +1,192 @@
+<!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 | 6. Classes and Enumerated Types</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="05_keywordconversion.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="07_applicationobjects.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>6. Classes and Enumerated Types</h2>
+<h3>Appscript keywords</h3>
+<p>For your convenience, appscript represents Apple event type names and application-specific class and enumerator names as Ruby symbols. Examples:</p>
+<pre><code># AEM-defined data types:
+:boolean
+:unicode_text
+:list
+# Application-defined class names:
+:document
+:window
+:disk
+# Application-defined enumerators:
+:yes
+:no
+:ask</code></pre>
+<p>Occasionally an application dictionary defines a type or enumerator without providing it with a corresponding name name. In these cases, the value will be represented as a raw <code>AEM::AEType</code> or <code>AEM::AEEnum</code> object instead of a symbol, e.g.:</p>
+<pre><code>AEM::AEType.new('abcd')
+AEM::AEEnum.new('xyz ')</code></pre>
+<p>See the aem manual for more information on these lower-level objects, should you need to use them.</p>
+<h3>Common AE types</h3>
+<table width="100%" summary="AE-Ruby type mappings">
+<thead>
+<tr><th>AE type</th><th>appscript name</th><th>Ruby class</th></tr>
+</thead>
+<tbody>
+<tr><td><code>typeNull</code></td><td><code>:null</code></td><td><code>NilClass</code></td></tr>
+<tr><td><code>typeBoolean</code></td><td><code>:boolean</code></td><td><code>TrueClass/FalseClass</code></td></tr>
+<tr><td><code>typeInteger</code></td><td><code>:integer</code></td><td><code>Fixnum/Bignum</code></td></tr>
+<tr><td><code>typeFloat</code></td><td><code>:float</code></td><td><code>Float</code></td></tr>
+<tr><td><code>typeChar</code> *</td><td><code>:string</code></td><td><code>String</code></td></tr>
+<tr><td><code>typeStyledText</code> *</td><td><code>:styled_text</code></td><td><code>String</code></td></tr>
+<tr><td><code>typeIntlText</code> *</td><td><code>:international_text</code></td><td><code>String</code></td></tr>
+<tr><td><code>typeUnicodeText</code></td><td><code>:unicode_text</code></td><td><code>String</code></td></tr>
+<tr><td><code>typeAEList</code></td><td><code>:list</code></td><td><code>Array</code></td></tr>
+<tr><td><code>typeAERecord</code></td><td><code>:record</code></td><td><code>Hash</code></td></tr>
+<tr><td><code>typeLongDateTime</code></td><td><code>:date</code></td><td><code>Time</code></td></tr>
+<tr><td><code>typeAlias</code></td><td><code>:alias</code></td><td><code>MacTypes::Alias</code></td></tr>
+<tr><td><code>typeFileURL</code></td><td><code>:file_url</code></td><td><code>MacTypes::FileURL</code></td></tr>
+<tr><td><code>typeFSRef</code></td><td><code>:file_ref</code></td><td><code>MacTypes::FileURL</code></td></tr>
+<tr><td><code>typeFSS</code> *</td><td><code>:file_specification</code></td><td><code>MacTypes::FileURL</code></td></tr>
+<tr><td><code>typeObjectSpecifier</code></td><td><code>:reference</code></td><td><code>Appscript::Reference</code></td></tr>
+<tr><td><code>typeInsertionLoc</code></td><td><code>:location_reference</code></td><td><code>Appscript::Reference</code></td></tr>
+<tr><td><code>typeType</code></td><td><code>:type_class</code></td><td><code>Symbol</code></td></tr>
+<tr><td><code>typeEnumerated</code></td><td><code>:enumerator</code></td><td><code>Symbol</code></td></tr>
+<tr><td><small>unit types; e.g. </small> <code>typeFeet</code></td><td><small>unit names; e.g.</small> <code>:feet</code></td><td><code>MacTypes::Units</code></td></tr>
+</tbody>
+</table>
+<p>(Note that types marked with '*' are officially deprecated and/or their use discouraged in Mac OS X. They remain supported to ensure backwards compatibility with older applications that may use them.)</p>
+<h3>Type mapping notes</h3>
+<p>While AEM-Ruby type conversions generally work quite seamlessly, it is sometimes useful to know some of the details involved, particularly when troubleshooting code that deals with older or buggy applications.</p>
+<h4>Numbers</h4>
+<p>When packing a <code>Bignum</code>, appscript will pack it either as a 32-bit integer (most preferred), 64-bit integer, or 64-bit float (least preferred), depending on the value's size.</p>
+<h4>Strings (Ruby 1.8)</h4>
+<p>Because Ruby 1.8 lacks native Unicode support, appscript unpacks all text-related AE types (<code>typeChar</code>, <code>typeUnicodeText</code>, etc.) as String instances containing UTF8-encoded data.</p>
+<p>Appscript packs String instances containing UTF8-encoded data as the <code>typeUnicodeText</code> AE type. If the string does not contain valid UTF-8 data, a TypeError will be raised.</p>
+<div class="hilitebox">
+<p>You can enable a degree of UTF-8 support in Ruby's <code>String</code> class via the Jcode module (included in Ruby's standard library). To use Jcode, add the following lines to the start of your Ruby scripts, irb sessions, etc.:</p>
+<pre><code>require "jcode"
+$KCODE = "UTF8"</code></pre>
+<p>This will improve the display of non-ASCII characters in irb, amongst other things.</p>
+</div>
+<p>Note that while <code>typeUnicodeText</code> is formally deprecated in Mac OS X 10.4+ in favour of <code>typeUTF8Text</code> and <code>typeUTF16ExternalRepresentation</code>, it is still in common usage so appscript continues to use it to ensure the broadest compatibility with existing scriptable applications.</p>
+<h4>Strings (Ruby 1.9+)</h4>
+<p>Each String instance in Ruby 1.9+ contains an <code>Encoding</code> instance that identifies the character set used. By default, appscript unpacks a text descriptors as a String instance containing UTF-8 encoded data and a UTF-8 Encoding, and encodes a string as UTF-8 prior to packing its data into a text descriptor. To disable this behavior for individual <code>Application</code> instances:</p>
+<pre><code>some_app = Appscript.app('SomeApp')
+some_app.AS_app_data.use_ascii_8bit
+# Send commands here...</code></pre>
+<p>Once invoked, Strings will be treated as UTF-8 encoded data with ASCII-8BIT Encoding; this is equivalent to the Ruby 1.8 behavior.</p>
+<h4>Dates and Times</h4>
+<p>Appscript packs Ruby <code>Time</code>, <code>Date</code> and <code>DateTime</code> instances as <code>typeLongDateTime</code> descriptors. (Note that AE dates does not include locale information.)</p>
+<p>By default, <code>typeLongDateTime</code> descriptors are unpacked as Ruby <code>Time</code> instances. This is sufficient for most purposes; however, where the AEDesc contains a date value below or above the range supported by Ruby's <code>Time</code> class, an error will occur. To unpack dates as <code>DateTime</code> instances for individual <code>Application</code> instances:</p>
+<pre><code>some_app = Appscript.app('SomeApp')
+some_app.AS_app_data.use_datetime
+# Send commands here...</code></pre>
+<h4>Filesystem references</h4>
+<p>The <code>typeAlias</code> AE type represents a filesystem object, and will continue to point to that object even if it's renamed or moved to another location on the same disk. The <code>typeFSRef</code> and <code>typeFileURL</code> types represent a filesystem location. Both can represent existing locations; the <code>typeFileURL</code> type can also be used to specify locations that don't already exist.</p>
+<p>FSSpecs are also supported for sake of backwards-compatibility with older Carbon applications that sometimes still use them. They're deprecated in OS X, however, due to lack of proper Unicode and long filename support, and their use is discouraged.</p>
+<p>Note that appscript unpacks FSRefs, FileURLs and FSSpecs as <code>MacTypes::FileURL</code> objects; users do not normally need to worry about this. <code>MacTypes::FileURL</code> objects created in Ruby will always pack as type <code>:FileURL</code>, however. See the <a href="../mactypes-manual/index.html">mactypes manual</a> for more information on <code>MacTypes::Alias</code> and <code>MacTypes::FileURL</code>.</p>
+<p>When asking an application to coerce a return value into a file type you must specify the exact type (<code>:alias</code>, <code>:file_url</code>, <code>:file_ref</code>, or <code>:file_specification</code>) in the <code>get</code> command. e.g. To get a <code>MacTypes::FileURL</code> object for the current user's home folder, you would usually use:</p>
+<pre><code>app('Finder').home.get(:result_type=&gt;:file_url)</code></pre>
+<p>Also be aware that some applications may not support coercions to all AE file types; you'll need to experiment to find out which coercions are supported.</p>
+<h4>Records</h4>
+<p>The <code>typeAERecord</code> AE type is a struct-like data structure containing zero or more properties. Appscript represents AE records as Ruby hashes. The keys in this hash are usually symbols representing appscript-style property names, although they may also be <code>AEM::AEType</code> values or strings.</p>
+<p>If a hash contains a <code>:class_</code> (or <code>AEM::AEType.new('pcls')</code>) key, appscript will pack the remaining items into an AE record, then coerce it to the type specified by this 'class' property. Similarly, when unpacking an record-like AEDesc with a custom type code, appscript will unpack it as a hash with the type represented by a <code>:class_</code> entry.</p>
+<h4>Types and enumerators</h4>
+<p>The <code>typeType</code> and <code>typeEnumerated</code> AE types are unpacked as Ruby symbols when the corresponding terminology is available, otherwise they are unpacked as <code>AEM::AEType</code> and <code>AEM::AEEnum</code> respectively.</p>
+<h4>Unit types</h4>
+<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>
+<h4>Miscellaneous types</h4>
+<p>The Apple Event Manager defines many other AE types whose names and codes are defined by appscript for completeness. A few of these types are of occasional interest to users, the rest can simply be ignored. In most cases, values of these types will be represented by raw <code>AE::AEDesc</code> instances as appscript doesn't automatically convert them to native objects.</p>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="05_keywordconversion.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="07_applicationobjects.html">Next</a>
+</div>
+</body>
+</html>