rb-appscript 0.2.1 → 0.3.0

data/CHANGES

@@ -1,3 +1,62 @@
+2007-01-18 -- 0.3.0
+
+- removed 'AS' alias; client scripts should refer to Appscript module, e.g.:
+
+	textedit = AS.app('TextEdit')
+
+should be changed to:
+
+	textedit = Appscript.app('TextEdit')
+
+- added 'p' prefixes to 'pcls' and 'ID  ' keys in DefaultTerminology::ReferenceByCode (minor bugfix)
+
+- in AE::AEDesc, renamed #get to #get_item and added #get_param and #get_attr methods
+
+- improved unpacking of object specifiers and other reference-related AEDescs (10-20% faster)
+
+- adjusted ordering of case blocks in Codecs#pack, #unpack to improve performance when packing/unpacking more commonly used types
+
+- added Appscript::Application#AS_new_reference; this takes a generic/aem reference and returns an appscript reference
+
+- referencerenderer now displays accurate representation of an appscript reference when appscript-style representation is unavailable (previously rendered the appscript reference as an aem-style reference string, which was misleading)
+
+- tweaked APIs for UnitTypeCodecs' pack/unpack procs
+
+- moved problem apps chapter to website
+
+- added information on osadict to getting help chapter
+
+- renamed aem's #userproperty method to #user_property
+
+- modified AEM_resolve to dispatch method calls via #send. Client objects should now either implement all aem reference methods OR a send(name, *args) method. Clients should avoid using method_missing as that can cause problems if client code includes methods into Object, as those injected methods may then be called instead of method_missing.
+
+- appscript now unpacks AEAddressDescs as Appscript::Application instances (note: as with AppleScript, this behaviour is asymmetrical since application objects always pack as null descs, i.e. they're treated as references when packing)
+
+- added Appscript::Application#by_aem_app method for converting AEM::Application instances to appscript application objects
+
+- iTunes_top40_to_html.rb sample script now opens resulting HTML file in user's default web browser
+
+- removed MacTypes::Units.method_missing
+
+- Appscript::Reference and Appscript::GenericReference now inherit from SafeObject class (based on BasicObject class <http://facets.rubyforge.org>) to prevent any third-party methods added to base classes from showing up in Reference/GenericReference and interfering with method_missing's behaviour. Note that _appscript/safeobject.rb installs traps on Module#method_added and Module#included in order to detect any changes during runtime.
+
+- added OSAX#osax and OSAX#scripting_addition to allow these methods to be included for convenience
+
+- FindApp.by_name now always raises ApplicationNotFoundError when application not found (previously sometimes raised RuntimeError
+
+- added more tests
+
+- fixed bug in MacTypes::FileBase#== where comparing two Alias/FileURL objects with different paths would return true, not false, and generally improved its behaviour
+
+- added default value ('StandardAdditions') for OSAX.osax's name argument
+
+- added Add_iCal_event.rb, Export_Address_Book_phone_numbers.rb examples; updated Hello_World.rb example to also demonstrate OSAX usage; made Select_all_HTML_files.rb example clearer
+
+- improved handling of synonyms in Terminology, TerminologyParser modules (definitions with same codes but different names are now retained; previously only the last-found definition was retained). Still doesn't mimic AS's behaviour 100%, but it's difficult to get any closer without studying the original AS source code.
+
+- added Terminology.dump method; removed misc/dump.rb file
+
+
 2006-11-29 -- 0.2.1
 
 - renamed AS module to Appscript. An 'AS' alias is temporarily provided for backwards compatibility but this will be removed in a future release. Users should update their scripts accordingly.

data/LICENSE

@@ -1 +1,66 @@
+(All modules are released under the MIT License, except safeobject.rb which is a modified version of basicobject <http://facets.rubyforge.org> released under the Ruby License.)
+
+======================================================================
+MIT LICENSE
+
 Copyright (C) 2006 HAS
+
+======================================================================
+THE RUBY LICENSE
+(http://www.ruby-lang.org/en/LICENSE.txt)
+
+ You may redistribute this software and/or modify it under either the terms of
+ the GPL (see below), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+          with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+          together with instructions (in the manual page or equivalent)
+          on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+          the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them,
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README

@@ -27,7 +27,7 @@ Please note that the version of Ruby included with Mac OS X 10.4 is missing the
 ======================================================================
 NOTES
 
-- rb-appscript 0.2.x contains a number of API changes from rb-appscript 0.1.x; see the CHANGES file and documentation for details
+- rb-appscript 0.3.0 contains a couple of API changes from rb-appscript 0.2.x; see the CHANGES file and documentation for details
 
 ======================================================================
 AUTHOR

data/TODO

@@ -1,27 +1,27 @@
 TO DO
 
-- pack/unpack support for application types (note: packing would be a bit tricky, since app('foo') could also indicate a reference, in which case it should be packed as a null desc; unpacking might be a bit clumsy, and would (at least in theory) require a by_desc/by_aem_application method to be added to AS::Application to handle typeMachPort, other types could be converted to paths/creator codes/urls/etc. ok though)
+- see if there's a way to provide a SafeObject base class for Appscript::Reference and Appscript::GenericReference that doesn't depend on inserting callbacks into Module (or are Rubyists fine with the current approach?)
 
-- allow users to extract a generic ref from a real ref (to_generic) for comparison purposes. Or vice-versa?
+- see if it's possible to work better with irb's autocomplete (autocomplete support is currently limited to start of a reference; not sure why)
 
-- implement built-in help system by bridging to py-appscript
+- ae/aem/appscript-defined exception classes aren't quite idiomatic Ruby
 
-- see if it's possible to work better with irb's autocomplete (autocomplete support is currently limited to start of a reference)
+- any additional tests
 
-- ae/aem/appscript-defined exception classes aren't quite idiomatic Ruby
+- improve/polish documentation
 
-- would be nice if MacFile::FileNotFoundError always showed the failed path (this'd need a bit of Alias Manager glue added to the ae extension)
+- see also TO DO comments in rbae.c
 
-- include an example project (or source for) that uses ruby2exe to build a standalone 'applet'
+-------
 
-- profiling
+- _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.
 
-- finish writing tests
+- support sending and receiving events on non-main threads
 
-- improve and polish documentation
+- provide an example project (or source for) that uses ruby2exe to build a standalone 'applet'
 
-- finish problem apps chapter (see comments in HTML file)
+- any more built-in Ruby class<->AE type converters needed?
 
-- see also TO DO items in source files
+- in AEM::CommandError, extract and report any kOSA... error parameters, if present
 
-- see also py-appscript's todo.txt file
+- implement built-in help by bridging to osadict

data/doc/aem-manual/04_references.html

@@ -166,24 +166,24 @@ p ref
         after
             Result : InsertionSpecifier
 
-        property(property_code)
-            property_code : str -- four-char code
+        property(code)
+            code : str -- four-char property code, e.g. 'pnam'
             Result : Property
 
         user_property(name)
             name : str
             Result : UserProperty
 
-        elements(class_code)
-            class_code : str -- four-char code
+        elements(ccode)
+            code : str -- four-char class code, e.g. 'docu'
             Result : AllElements
 
-        previous(class_code)
-            class_code : str -- four-char code
+        previous(code)
+            code : str -- four-char class code
             Result : Element
 
-        next(class_code)
-            class_code : str -- four-char code
+        next(code)
+            code : str -- four-char class code
             Result : Element
         
         -- Note: following methods are for use on
@@ -273,13 +273,13 @@ p ref
             key : anything -- the object's unique id
             Result : ElementByID
 
-        by_range(start_ref, end_ref)
-            start_ref : Element -- an app- or con-based reference
-            end_ref : Element -- an app- or con-based reference
+        by_range(start, stop)
+            start : Element -- an app- or con-based reference
+            stop : Element -- an app- or con-based reference
             Result : ElementByRange
 
-        by_filter(testref)
-            test_ref : Test -- an its-based reference
+        by_filter(test)
+            test : Test -- an its-based reference
             Result : ElementsByFilter</code></pre>
 
 

data/doc/aem-manual/05_targettingapplications.html

@@ -37,7 +37,7 @@
 
         is_running?(path) -- Is an application currently running?
             path : string -- application's path, e.g. '/Applications/iCal.app'
-            Result : bool
+            Result : boolean
     
     Constructors:
 
@@ -61,10 +61,12 @@
 
         event(...) -- construct an Apple event (see next chapter for details)
 
-        start_transaction -- start a new transaction; all Events
-                constructed after start_transaction is called will
-                belong to the same transaction until end_transaction
-                or abort_transaction is called
+        start_transaction(session=nil) -- start a new transaction;
+                all Events constructed after start_transaction is
+                called will belong to the same transaction until
+                end_transaction or abort_transaction is called
+            session : anything -- optional value identifying the 
+                    specific session (where supported)
 
         end_transaction -- end the current transaction
 

data/doc/aem-manual/06_buildingandsendingevents.html

@@ -30,7 +30,7 @@
 <pre><code>Application -- the target application
         ...
 
-        event(event_code, params={}, atts={}, return_id=KAE.KAutoGenerateReturnID,
+        event(event_code, params={}, atts={}, return_id=KAE::KAutoGenerateReturnID,
                 codecs=DefaultCodecs) -- construct an Apple event
             event_code : string -- 8-letter code indicating event's class and id,
                     e.g. 'coregetd'

data/doc/aem-manual/08_examples.html

@@ -14,14 +14,14 @@
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a> | <a href="09_notes.html">Next</a>
+	<a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a>
 </div>
 
 <!-- content -->
 <div id="content">
 
 
-<h2>Identifying Applications</h2>
+<h2>Identifying applications</h2>
 
 <pre><code># application "Macintosh HD:Applications:TextEdit.app"
 textedit = AEM::Application.by_path('/Applications/TextEdit.app')
@@ -33,7 +33,7 @@ textedit = AEM::Application.by_path(FindApp.by_name('TextEdit'))
 textedit = AEM::Application.by_url('eppc://my-mac.local/TextEdit')</code></pre>
 
 
-<h2>Building References</h2>
+<h2>Building references</h2>
 
 <pre><code># name (of application)
 AEM.app.property('pnam')
@@ -44,7 +44,7 @@ AEM.app.elements('docu').property('ctxt')
 # end of every paragraph of text of document 1
 AEM.app.elements('docu').by_index(1).property('ctxt').elements('cpar').end
 
-#�paragraphs 2 thru last of first document
+# paragraphs 2 thru last of first document
 AEM.app.elements('docu').first.elements('cpar').by_range(
         AEM.con.elements('cpar').by_index(2), 
         AEM.con.elements('cpar').last)
@@ -53,7 +53,7 @@ AEM.app.elements('docu').first.elements('cpar').by_range(
 AEM.app.elements('docu').by_index(1).elements('cpar').by_filter(AEM.its.ne("\n"))</code></pre>
 
 
-<h2>Sending Events</h2>
+<h2>Sending events</h2>
 
 <pre><code># quit TextEdit
 textedit.event('corequit').send
@@ -76,7 +76,7 @@ textedit.event('corecrel', {
 
 <!-- bottom navigation -->
 <div class="navbar">
-	<a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a> | <a href="09_notes.html">Next</a>
+	<a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a>
 </div>
 
 <!--footer-->

data/doc/aem-manual/index.html

@@ -14,7 +14,7 @@
 
 <!-- top navigation -->
 <div class="navbar">
-	<a href="01_introduction.html">Next</a>
+	<a href="../index.html">Up</a> | <a href="01_introduction.html">Next</a>
 	
 </div>
 
@@ -28,16 +28,15 @@
 	<li><a href="06_buildingandsendingevents.html">Building and sending events</a></li>
 	<li><a href="07_findapp.html">Locating applications</a></li>
 	<li><a href="08_examples.html">Examples</a></li>
-	<li><a href="09_notes.html">Notes</a></li>
 </ol></div>
 
 <!-- bottom navigation -->
 <div class="navbar">
-	<a href="01_introduction.html">Next</a>
+	<a href="../index.html">Up</a> | <a href="01_introduction.html">Next</a>
 	
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2004 HAS</p>
+<p class="footer">&copy; 2006 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/02_aboutappscripting.html

@@ -212,17 +212,9 @@ app('TextEdit').documents[1].text.paragraphs</code></pre>
 
 
 
-<h2>Additional Resources</h2>
+<h2>Additional resources</h2>
 
-<ul>
-
-<li><a href="http://www.cs.utexas.edu/users/wcook/papers/AppleScript/AppleScript95.pdf">The Open Scripting Architecture: Automating, Integrating, and Customizing Applications</a> (PDF; Cook &amp; Harris, 1993) -- A very good technical overview of the OSA infrastructure, which includes Apple event-based application scripting. Recommended reading.</li>
-
-<li><a href="http://developer.apple.com/documentation/AppleScript/Conceptual/AppleEvents/index.html">Apple Events Programming Guide</a> -- Technical introduction to Apple events. See also the <a href="http://developer.apple.com/documentation/AppleScript/index-date.html">AppleScript Documentation List</a>.</li>
-
-<li><a href="http://developer.apple.com/technotes/tn2002/tn2106.html">Scripting Interface Guidelines</a> -- Intended for developers of scriptable applications, but provides some useful insight for scripters as well.</li>
-
-</ul>
+<p>Background information links can be found on the <a href="http://rb-appscript.rubyforge.org">rb-appscript website</a>.</p>
 
 <hr />
 

data/doc/appscript-manual/04_gettinghelp.html

@@ -20,16 +20,43 @@
 
 <!-- content -->
 <div id="content">
-<p>There are two ways to get information about applications' scripting interfaces: the ASDictionary application and introspection.</p>
+<p>There are several ways to get information about applications' scripting interfaces: the <code>osadict</code> command-line tool, the ASDictionary application, and introspection.</p>
+
+
+<h2>osadict</h2>
+
+<p>The <code>osadict</code> tool, bundled with the <a href="http://sourceforge.net/projects/appscript">py-appscript package</a>, can be used to export application dictionaries in HTML format, or browse them interactively from the command line.</p>
+
+<p>To view osadict's full documentation:</p>
+
+<pre><code>osadict -h</code></pre>
+
+<p>Use osadict's <code>-s</code> option or <code>default</code> command to set the formatting style for rb-appscript.</p>
+
+<p>Examples:</p>
+
+<pre><code># Export TextEdit's dictionary to HTML:
+osadict -Hs rb TextEdit.app > TextEdit.html
+
+# Browse iCal's dictionary:
+osadict -s rb eppc://remote-mac.local/iCal
+iCal&gt; -u
+iCal&gt; -t view_calendar
+iCal&gt; -t calendar -i calendar -r calendar
+iCal&gt; exit
+
+# View a Standard Additions command:
+osadict -Ns rb StandardAdditions -t display dialog</code></pre>
 
 
 <h2>ASDictionary</h2>
 
-<p>ASDictionary 0.7.1+ renders application terminology resources in plain text and HTML formats. You can obtain the latest version from the py-appscript project site (<a href="http://sourceforge.net/projects/appscript">http://sourceforge.net/projects/appscript</a>).</p>
+<p>ASDictionary, available from the <a href="http://sourceforge.net/projects/appscript"> py-appscript website</a>, renders application terminology resources in plain text and HTML formats. It provides a convenient drag-n-drop alternative to using the <code>osadict -H ...</code> command.</p>
+
 
 <h2>Introspection</h2>
 
-<p>Appscript Application and Reference objects provide several methods for obtaining information on the target application: </p>
+<p>Appscript's <code>Application</code> and <code>Reference</code> classes define several methods for obtaining information on the target application: </p>
 
 <dl>
 <dt><code>properties</code></dt>
@@ -60,30 +87,17 @@ p te.commands
 p te.parameters('make')
 # ["at", "new", "with_data", "with_properties"]</code></pre>
 
-<h2>Other sources of help</h2>
 
-<p>For advice and assistance with using rb-appscript:</p>
+<h2>Other sources of help</h2>
 
 <ul>
-<li>Support forums for rb-appscript are available at <a href="http://rubyforge.org/forum/?group_id=2346"> http://rubyforge.org/forum/?group_id=2346</a></li>
-
 <li>The <code>sample</code> folder contains example scripts demonstrating a range of common tasks.</li>
-</ul>
 
-<p>For information on scripting specific applications:</p>
-
-<ul>
 <li>Refer to any scripting documentation and example scripts supplied by the application developer.</li>
 
-<li>The <a href="http://pythonmac.org/wiki/AppscriptModule">appscript entry at the pythonmac.org wiki</a> links to pages that discuss scripting specific applications.</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://listserv.dartmouth.edu/scripts/wa.exe?A0=macscrpt">MacScrpt mailing list</a> at Dartmouth College discusses application scripting but extends to all Mac scripting languages.</li>
-
-<li><a href="http://www.macscripter.net">MacScripter.net</a> is the main hub for AppleScript-based application scripters, providing file archives, forums and links to other related sites.</li>
-
-<li>Apple's website provides a <a href="http://www.apple.com/applescript/developers/">developer section</a> and <a href="http://lists.apple.com/index.html">mailing lists</a> relating to application scripting and AppleScript.</li>
+<li>The <a href="http://rb-appscript.rubyforge.org">rb-appscript website</a> has links to mailing lists and other general resources.</li>
 </ul>