RubyGems - rb-appscript - Versions diffs - 0.5.1 → 0.5.2 - Mend

rb-appscript 0.5.1 → 0.5.2

Files changed (61) hide show

data/CHANGES +30 -0
data/LICENSE +1 -1
data/README +7 -3
data/TODO +7 -1
data/doc/aem-manual/01_introduction.html +23 -9
data/doc/aem-manual/02_apioverview.html +25 -11
data/doc/aem-manual/03_packingandunpackingdata.html +22 -17
data/doc/aem-manual/04_references.html +49 -36
data/doc/aem-manual/05_targettingapplications.html +25 -14
data/doc/aem-manual/06_buildingandsendingevents.html +47 -21
data/doc/aem-manual/07_findapp.html +22 -11
data/doc/aem-manual/08_examples.html +21 -10
data/doc/aem-manual/index.html +28 -12
data/doc/appscript-manual/01_introduction.html +40 -27
data/doc/appscript-manual/02_aboutappscripting.html +28 -15
data/doc/appscript-manual/03_quicktutorial.html +29 -16
data/doc/appscript-manual/04_gettinghelp.html +31 -16
data/doc/appscript-manual/05_keywordconversion.html +23 -10
data/doc/appscript-manual/06_classesandenums.html +32 -19
data/doc/appscript-manual/07_applicationobjects.html +31 -18
data/doc/appscript-manual/08_realvsgenericreferences.html +23 -11
data/doc/appscript-manual/09_referenceforms.html +33 -20
data/doc/appscript-manual/10_referenceexamples.html +30 -17
data/doc/appscript-manual/11_applicationcommands.html +25 -13
data/doc/appscript-manual/12_commandexamples.html +26 -15
data/doc/appscript-manual/13_performanceissues.html +46 -20
data/doc/appscript-manual/14_notes.html +29 -19
data/doc/appscript-manual/index.html +27 -11
data/doc/full.css +95 -9
data/doc/index.html +27 -10
data/doc/mactypes-manual/01_introduction.html +56 -0
data/doc/mactypes-manual/02_aliasclass.html +134 -0
data/doc/mactypes-manual/03_fileurlclass.html +136 -0
data/doc/mactypes-manual/04_unitsclass.html +102 -0
data/doc/mactypes-manual/index.html +26 -227
data/doc/osax-manual/01_introduction.html +69 -0
data/doc/osax-manual/02_interface.html +149 -0
data/doc/osax-manual/03_examples.html +75 -0
data/doc/osax-manual/04_notes.html +80 -0
data/doc/osax-manual/index.html +26 -195
data/doc/rb-appscript-logo.png +0 -0
data/rb-appscript.gemspec +2 -2
data/sample/TextEdit_demo.rb +1 -1
data/src/lib/_aem/aemreference.rb +1 -1
data/src/lib/_aem/codecs.rb +42 -8
data/src/lib/_aem/connect.rb +3 -1
data/src/lib/_aem/findapp.rb +1 -1
data/src/lib/_aem/mactypes.rb +1 -1
data/src/lib/_aem/send.rb +162 -142
data/src/lib/_aem/typewrappers.rb +2 -2
data/src/lib/_appscript/defaultterminology.rb +76 -46
data/src/lib/_appscript/referencerenderer.rb +1 -1
data/src/lib/_appscript/reservedkeywords.rb +2 -2
data/src/lib/_appscript/safeobject.rb +1 -1
data/src/lib/_appscript/terminology.rb +30 -19
data/src/lib/aem.rb +1 -6
data/src/lib/appscript.rb +65 -20
data/src/lib/osax.rb +21 -18
data/src/rbae.c +1 -1
data/test/test_appscriptcommands.rb +1 -1
metadata +12 -3

data/doc/mactypes-manual/04_unitsclass.html ADDED

@@ -0,0 +1,102 @@
+<!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-mactypes manual | 4. Units class</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_fileurlclass.html">Previous</a> &bull;
+<a href="index.html">Up</a>
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<strong><a href="../mactypes-manual/index.html">mactypes</a></strong> /
+<a href="../osax-manual/index.html">osax</a> /
+<a href="../aem-manual/index.html">aem</a>
+</span>
+</div>
+<!-- content -->
+<div id="content">
+<h2>4. The <code>MacTypes::Units</code> class</h2>
+<p>The <code>Units</code> class represents a measurement of some sort, e.g. 3 inches, 98.5 degrees Fahrenheit.</p>
+<pre><code>class Units
+    Constructor:
+        Units.new(value, type)
+            value : Fixnum | Bignum | Float -- the amount, e.g. 3.5
+            type : Symbol -- the unit of measurement, e.g. :centimeters
+    Methods:
+        ==
+        hash
+        inspect
+        value -- returns the amount
+        type -- returns the unit of measurement
+        to_i -- returns the amount as an integer
+        to_f -- returns the amount as a float
+        to_s -- returns the measurement as a string, e.g. "3.5 centimeters"</code></pre>
+<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>Additional application-specific unit types can be added if needed.</p>
+<h3>Examples</h3>
+<pre><code>MacTypes::Units.new(14, :inches)
+MacTypes::Units.new(3.5, :square_meters)</code></pre>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="03_fileurlclass.html">Previous</a> &bull;
+<a href="index.html">Up</a>
+<span>&copy; 2006-2008 HAS</span>
+</div>
+</body>
+</html>

data/doc/mactypes-manual/index.html CHANGED

@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
-<title>mactypes</title>
+<title>rb-mactypes manual</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,247 +10,46 @@
 </head>
 <body>
-<h1>mactypes</h1>
+<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
 <!-- top navigation -->
 <div class="navbar">
-    <a href="../index.html">Up</a>
+<a href="../index.html">Previous</a> &bull;
+<a href="../index.html">Up</a> &bull;
+<a href="01_introduction.html">Next</a>
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<strong><a href="../mactypes-manual/index.html">mactypes</a></strong> /
+<a href="../osax-manual/index.html">osax</a> /
+<a href="../aem-manual/index.html">aem</a>
+</span>
 </div>
 <!-- content -->
 <div id="content">
-<h2>What is mactypes?</h2>
-<p>The mactypes module provides user-friendly wrappers for OS X Alias and FileURL objects, commonly used by scriptable applications to identify filesystem objects and locations, and for unit type values used by some applications to represent lengths, etc. It is automatically imported when requiring appscript, aem or osax.</p>
+<h2>Contents</h2>
-<p class="hilitebox">Note that most scriptable applications do not use or understand POSIX paths, and while the Apple Event Manager does provide some built-in coercions for converting between path strings and alias/file objects, these work with HFS paths only. Therefore, when specifying files and folders to scriptable applications, use <code>MacTypes::Alias</code> and <code>MacTypes::FileURL</code> objects - not path strings - unless otherwise indicated.</p>
-<h2><code>MacTypes::Alias</code></h2>
-<p>The <code>Alias</code> class represents a persistent reference to a filesystem object. Aliases keep track of filesystem objects even if they're renamed or moved to another location on the same disk.</p>
-<h3>Methods</h3>
-<pre><code>Alias -- a persistent reference to a filesystem object
-    Constructors:
-        Alias.path(path) -- make Alias object from POSIX path string
-        Alias.hfs_path(path) -- make Alias object from HFS path string
-        Alias.url(url) -- make Alias object from a local file:// URL string
-        Alias.desc(desc) -- make Alias object from an AE::AEDesc
-                            of TypeAlias
-    Methods:
-        ==
-        hash
-        inspect
-        path -- returns POSIX path string to the object's current location
-        hfs_path -- returns HFS path string to the object's current location
-        url -- returns file:// URL string to the object's current location
-        desc -- returns AE::AEDesc of TypeAlias
-        to_s -- synonym for #path
-        to_alias -- returns self
-        to_file_url -- returns a MacTypes::FileURL object</code></pre>
-<h3>Examples</h3>
-<pre><code>require "appscript"
-f = MacTypes::Alias.path('/Users/foo/some file')
-puts f.to_s
-# /Users/foo/some file
-puts f.url
-# file://localhost/Users/foo/some%20file
-puts f.inspect
-# MacTypes::Alias.path("/Users/foo/some file")
-Appscript.app('TextEdit').open(f)
-# opens document in TextEdit</code></pre>
-<h3>Notes</h3>
-<p>Comparing an <code>Alias</code> object against a <code>FileURL</code> object always returns false, even if both point to the same location.</p>
-<p>Remember that aliases can change when the corresponding filesystem object is moved, so take care when using <code>Alias</code> objects in situations that involve comparing or hashing them (e.g. <code>Hash</code> keys).</p>
-<h2><code>MacTypes::FileURL</code></h2>
-<p>The <code>FileURL</code> class represents a fixed filesystem location. This may be deterministic (i.e. existing locations only) or non-deterministic depending on how the object is created.</p>
-<h3>Methods</h3>
-<pre><code>FileURL -- identifies a fixed filesystem location
-    Constructors:
-        FileURL.path(path) -- make FileURL object from POSIX path string
-        FileURL.hfs_path(path) -- make FileURL object from HFS path string
-        FileURL.url(url) -- make FileURL object from a local file:// URL string
-        FileURL.desc(desc) -- make FileURL object from an AE::AEDesc
-                              of TypeFSS, TypeFSRef or TypeFileURL
-    Methods:
-        ==
-        hash
-        inspect
-        path -- returns POSIX path string
-        hfs_path -- returns HFS path string
-        url -- returns file:// URL string
-        desc -- returns AE::AEDesc of TypeFSRef, TypeFSS or TypeFileURL
-        to_s -- synonym for #path
-        to_alias -- returns a MacTypes::Alias object
-        to_file_url -- returns a new MacTypes::FileURL object</code></pre>
-<h3>Examples</h3>
-<pre><code>require "appscript"
-f = MacTypes::FileURL.path('/Users/foo/new file')
-puts f.to_s
-# /Users/foo/new file
-puts f.url
-# file://localhost/Users/foo/some%20file
-puts f.inspect
-# MacTypes::FileURL.path("/Users/foo/new file")
-Appscript.app('TextEdit').documents[1].save(:in => f)
-# saves front TextEdit document at the given location</code></pre>
-<h3>Notes</h3>
-<p>Unlike the <code>Alias</code> class which wraps <code>TypeAlias</code> values only, the <code>FileURL</code> class provides a uniform wrapper for several file-related types that may be returned by applications: <code>TypeFSS</code>, <code>TypeFSRef</code> and <code>TypeFileURL</code>. When passing <code>FileURL</code> values to applications, you should not normally need to worry about which value type a <code>FileURL</code> object contains as well-designed applications will ask the Apple Event Manager to coerce the given value to the desired type as necessary.</p>
-<p>When dealing with less well-behaved applications, however, you may need to pass an AEDesc of a specific type. In this case you should use the <code>desc</code> method to obtain an <code>AE::AEDesc</code> object, then call its <code>coerce</code> method to obtain an AEDesc of the desired type. For example, if an older Carbon application refuses to accept a FileURL identifying a non-existing file location, you may need to provide a FSSpec insteaf:</p>
-<pre><code>require "appscript"
-file_url = MacTypes::FileURL.path('/Users/foo/new file')
-fs_spec = file_url.desc.coerce(KAE::TypeFSS)
-Appscript.app('older app').documents[1].save(:in => fs_spec)</code></pre>
-<p>When used in an application command, a <code>FileURL</code> object returned by appscript will always pack into the same <code>TypeFSRef</code>, <code>TypeFileURL</code> or <code>TypeFSS</code> AEDesc it was created from. A <code>FileURL</code> object returned by <code>FileURL.path</code>, <code>Alias#to_file_url</code> or <code>FileURL#to_file_url</code> will always pack into an AEDesc of <code>TypeFileURL</code>.</p>
-<p>When comparing <code>FileURL</code> objects for equality, be aware that <code>FileURL#==</code> always performs case-sensitive comparisons, regardless of how the underlying filesystem handles case-[in]sensitivity.</p>
-<p>Note that AEDescs of <code>TypeFSRef</code> can represent existing filesystem locations only. AEDescs of <code>TypeFileURL</code> can represent both existing and non-existing locations. AEDescs of <code>TypeFSS</code> (FSSpecs) are deprecated on Mac OS X due to lack of proper Unicode and long filename support, and are retained for backwards compatibility with older applications only.</p>
-<p>Be aware that <code>FileURL#==</code> does not normalize file URLs; thus minor differences in capitalization, etc. can result in <code>FileURL#==</code> returning <code>false</code> even if both objects happen to identify the same filesystem location.</p>
-<h2><code>MacTypes::FileNotFoundError</code></h2>
-<p><code>FileNotFoundError</code> is a subclass of <code>RuntimeError</code>. It is raised by <code>Alias</code> and <code>FileURL</code> objects when an operation that only works for existing filesystem objects/locations fails. For example:</p>
-<pre><code>require "appscript"
-MacTypes::Alias.path('/some/non/existent/location')
-# raises FileNotFoundError</code></pre>
-<h2><code>MacTypes::Units</code></h2>
-<p>The <code>Units</code> class represents a measurement of some sort, e.g. 3 inches, 98.5 degrees Fahrenheit.</p>
-<pre><code>class Units
-    Constructor:
-        Units.new(value, type)
-            value : Fixnum | Bignum | Float -- the amount, e.g. 3.5
-            type : Symbol -- the unit of measurement, e.g. :centimeters
-    Methods:
-        ==
-        hash
-        inspect
-        value -- returns the amount
-        type -- returns the unit of measurement
-        to_i -- returns the amount as an integer
-        to_f -- returns the amount as a float
-        to_s -- returns the measurement as a string, e.g. "3.5 centimeters"</code></pre>
-<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>Additional application-specific unit types can be added if needed.</p>
+<ol>
+	<li><a href="01_introduction.html">Introduction</a></li>
+	<li><a href="02_aliasclass.html">Alias class</a></li>
+	<li><a href="03_fileurlclass.html">FileURL class</a></li>
+	<li><a href="04_unitsclass.html">Units class</a></li>
+</ol>
 </div>
 <!-- bottom navigation -->
-<div class="navbar">
-    <a href="../index.html">Up</a>
+<div class="footer">
+<a href="../index.html">Previous</a> &bull;
+<a href="../index.html">Up</a> &bull;
+<a href="01_introduction.html">Next</a>
+<span>&copy; 2006-2008 HAS</span>
 </div>
-<!--footer-->
-<p class="footer">&copy; 2006-2008 HAS</p>
 </body>
 </html>

data/doc/osax-manual/01_introduction.html ADDED

@@ -0,0 +1,69 @@
+<!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-osax manual | 1. Introduction</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="index.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="02_interface.html">Next</a>
+<span>
+<a href="../appscript-manual/index.html">appscript</a> /
+<a href="../mactypes-manual/index.html">mactypes</a> /
+<strong><a href="../osax-manual/index.html">osax</a></strong> /
+<a href="../aem-manual/index.html">aem</a>
+</span>
+</div>
+<!-- content -->
+<div id="content">
+<h2>1. Introduction</h2>
+<h3>About osax</h3>
+<p>The <code>OSAX</code> module provides an easy way to call scripting additions (a.k.a. OSAXen) from Ruby. It exports a single public class, <code>ScriptingAddition</code>, and two functions, <code>osax</code> and <code>scripting_additions</code>.</p>
+<p>The <code>ScriptingAddition</code> class represents a single scripting addition. It is similar to an appscript application object, except that it defines commands for the specified scripting addition instead of the application's normal commands. </p>
+<p>Once you've created a <code>ScriptingAddition</code> instance, you can invoke its commands in exactly the same way as you would call a scriptable application's commands in appscript.</p>
+<p>For example:</p>
+<pre><code>require "osax"
+sa = OSAX::ScriptingAddition.new("StandardAdditions")
+sa.say("Hello world", :using=&gt;"Victoria")</code></pre>
+<p>The default application commands (<code>run</code>, <code>activate</code>, <code>quit</code>, etc.) are also available; see the appscript manual for details on those.</p>
+<p>By default, <code>ScriptingAddition</code> objects are targeted at the current application. You can obtain a <code>ScriptingAddition</code> object targeted at another application by calling one of its <code>by...</code> methods.</p>
+</div>
+<!-- bottom navigation -->
+<div class="footer">
+<a href="index.html">Previous</a> &bull;
+<a href="index.html">Up</a> &bull;
+<a href="02_interface.html">Next</a>
+<span>&copy; 2006-2008 HAS</span>
+</div>
+</body>
+</html>