rb-appscript 0.2.0

data/CHANGES

@@ -0,0 +1,243 @@
+2006-11-20 -- 0.2.0
+
+- removed path expansion in FindApp#byName, MacFile::Alias#at, MacFile::FileURL#at
+
+- changed default send flags to KAE::KAECanSwitchLayer + KAE::KAEWaitReply (same as AppleScript)
+
+- aliased AE::MacOSError#number to #to_i; added #to_s and #inspect methods
+
+- added #to_s and #inspect methods to AE::AEDesc
+
+- fixed undefined variable bug in FindApp#byName when raising an ApplicationNotFoundError
+
+- added osax module and documentation
+
+- added event handling code to rbae.c (not yet fully tested)
+
+- added gemspec for source-based gem
+
+- made Reference class's AS_appdata and AS_aemreference instance variables writeable as well as readable - this'll make it easier to inject workarounds (e.g. modified pack/unpack routines) for occasional application flaws
+
+- added sample scripts: Organize_Mail_messages.rb, Create_daily_iCal_todos.rb, Simple_Finder_GUI_Scripting.rb, Set_iChat_status.rb
+
+- now always packs a subject attribute (KAE::TypeSubjectAttr); this is normally a null descriptor. (Note: AS includes a subject attribute for commands whose direct parameter isn't a reference, e.g. make. Photoshop CS2's make command requires either an 'at' parameter or subject attribute and throws an error if it doesn't get one. Including a subject attribute by default should hopefully prevent any complaints.) [BB]
+
+- removed built-in :telltarget argument to simplify the API a bit. Now, if a command is called on a reference and already has a direct parameter, the reference is packed as the subject attribute instead. Also, 'telltarget' is no longer a reserved word.
+
+- true and false are now packed as AEDescs of typeTrue and typeFalse (same as AppleScript), not typeBoolean [BB]
+
+- when hashes containing a :class or AEType.new('pcls') key whose value is a Symbol or AEBaseType instance are packed, the resulting AEDesc is now coerced to that type (previously the class property was packed as just another key-value pair, and the result was an AEDesc of typeAERecord) [BB]
+
+- codecs module now unpacks a record-like AEDesc with an unknown type as a hash containing an additional 'class' property that indicates the original type (i.e. same as AppleScript)
+
+- aliased AEM::CommandError#number to #to_i
+
+- where property and element names are the same (e.g. file, text in BBEdit), appscript now packs this as a property specifier, unless the name is 'text', in which case it's packed as an elements specifier (i.e. [hopefully] same as AppleScript)
+
+- renamed macfile.rb/MacFile module to mactypes.rb/MacTypes
+
+- renamed MacTypes::Alias, MacTypes::MacFileURL methods: 
+
+	Alias.at -> Alias.path
+	FileURL.at -> FileURL.path
+	Alias.newDesc -> Alias.desc
+	FileURL.newDesc -> FileURL.desc
+
+- renamed AS.app methods:
+
+	app#byName -> app#by_name
+	app#byCreator -> app#by_creator
+	app#byID -> app#by_id
+	app#byPID -> app#by_pid
+	app#byURL -> app#by_url
+
+- renamed appscript reference methods:
+
+	startswith -> starts_with
+	endswith -> ends_with
+	isin -> is_in
+	doesnotstartwith -> does_not_start_with
+	doesnotendwith -> does_not_end_with
+	doesnotcontain -> does_not_contain
+	isnotin -> is_not_in
+
+- renamed built-in appscript command parameters:
+
+	:waitreply -> :wait_reply
+	:resulttype -> :result_type
+
+- renamed AEM::Application methods:
+
+	Application.newPath -> Application.by_path
+	Application.newURL -> Application.by_url
+	Application.newPID -> Application.by_pid
+	Application.newAEDesc -> Application.by_desc
+
+- renamed aem reference methods:
+
+	byindex -> by_index
+	byname -> by_name
+	byid -> by_id
+	byrange -> by_range
+	byfilter -> by_filter
+	startswith -> starts_with
+	endswith -> ends_with
+	isin -> is_in
+
+- renamed FindApp methods:
+
+	FindApp.byName -> FindApp.by_name
+	FindApp.byCreator -> FindApp.by_creator
+	FindApp.byID -> FindApp.by_id
+
+- changed type names in defaultterminology.rb to be more AppleScript-like, e.g. :String -> :string, :MissingValue -> :missing_value (note that there are still a few deliberate differences, e.g. :float instead of :real)
+
+- added month and weekday name-code definitions to defaultterminology.rb
+
+- changed internal variable and method names to follow Ruby style guidelines
+
+- added MacTypes::Units class
+
+- added add_unit_types method to Codecs class, allowing additional unit type definitions to be added
+
+- fixed appscript reference rendering bug where property/element names could get muddled (e.g. 'document' property would appear as 'documents')
+
+- fixed wierd rendering bug where rendered references would be invisible if client script contained an 'app' method of its own (Ruby was invoking this instead of ReferenceRenderer#method_missing)
+
+- moved findapp.rb and mactypes.rb to _aem/ (they're already re-exported by aem.rb, appscript.rb, etc. so clients don't need to require them directly)
+
+- 'help' is now a reserved word (though is not currently implemented)
+
+- Attempting to pack invalid UTF8 strings now raises TypeError instead of AEM::NotUTF8TextError
+
+- changed AEM::Application#running? to AEM::Application.is_running?(path)
+
+- added aem manual
+
+- replaced big if...elsif... block in Codecs#pack with case block
+
+- removed AEM::AEEventName (the 'evnt' type, cEventIdentifier, is used by OSAGetHandlerNames)
+
+- updated kae.rb; now contains constants scraped from the following OS X 10.4u SDK frameworks: 
+	AE.framework (all headers)
+	Carbon.framework (AEInteraction.h only)
+	OpenScripting.framework (all headers except FinderRegistry.h)
+
+- Connect.local_app_by_pid now returns an AEDesc of typeKernelProcessID
+
+- added basic support for equality tests and hashing to MacFile::Alias and MacFile::URL. Note that it only tests for exact data equality; two objects that identify the same filesystem object/location by different means, using paths of different case, etc. will test as false.
+
+- adjusted packing of 'make' command so that if target reference is typeObjectSpecifier then it's packed as the subject attribute but if it's typeInsertionLoc it's packed as an 'at' parameter (this avoids a bug in Cocoa Scripting where packing an insertion location as the subject attribute results in an error when CS tries to coerce it to an object specifier)
+
+- fixed various bugs in aem's transaction-handling code
+
+- added #abort_transaction and added optional 'session' argument to #start_transaction in AEM::Application and AS::Application
+
+
+2006-10-23 -- 0.1.6
+
+- improved test_aemreference.rb
+
+- fixed bug in aemreference.rb where comparing two non-equivalent aem references could return true
+
+- simplified four-char-code conversion routines in codecs.rb
+
+- AS::Reference#methods now returns names of application-defined properties, elements and commands in addition to names of built-in methods [MN]
+
+- AS::Reference#respond_to? now returns true for names of application-defined properties, elements and commands in addition to names of built-in methods [MN]
+
+- removed rbosadict; use ASDictionary.app instead (available from <http://appscript.sourceforge.net>)
+
+- removed AS::Application#useterminology; added optional 'terms' argument to Application constructors instead
+
+- in Terminology module, changed timeout for ascrgdte event from 120 to 30 sec
+
+- added dump tool + documentation
+
+- added info to manual on scripting non-stay-open applications
+
+- removed MacFile::Alias#newPath and MacFile::FileURL#newPath constructors (use #at instead)
+
+- changed MacFile::Alias#to_s and MacFile::FileURL#to_s to return plain path string instead of object representation (use #inspect for that)
+
+- removed MacFile::Alias#path and MacFile::FileURL#path (use #to_s instead)
+
+- added macfile manual
+
+- Connect.launch_app no longer waits for reply/error when sending a launch event to an already running application
+
+
+2006-10-18 -- 0.1.5
+
+- renamed MacFile::Alias#newPath, MacFile::FileURL#newPath to Alias#at and FileURL#at for conciseness; e.g.: FileURL.at("/some/path"). Note: newPath methods will be removed in 0.2.0.
+
+- appscript module now packs UInt32 csig attributes correctly [DH]
+
+- fixed little-endian bugs when packing and unpacking typeSInt64 and typeLongDateTime
+
+- packing and unpacking typeLongDateTime AEDescs is now about as accurate as can be expected, given the inherent problems of LongDateTime (i.e. UCConvertLongDateTimeToCFAbsoluteTime and UCConvertCFAbsoluteTimeToLongDateTime have off-by-an-hour [or whatever the local difference is] inaccuracies at ST/DST/ST boundaries)
+
+- improved error reporting in MacFile module: creating a MacFile::Alias object with a path to a non-existent filesystem object, getting path for MacFile::Alias object that no longer identifies a valid filesystem object, etc. now raises MacFile::FileNotFoundError instead of various MacOSErrors
+
+- comparison methods' arguments now display correctly when to_s/inspect is called on its-based references
+
+- its-based aem references now correctly unpack KAEContains comparison descriptors as 'reference.isin(value)', rather than trying to unpack them incorrectly as 'value.contains(reference)'
+
+- first/middle/last/any references now compare correctly with identical references that have been previously packed and unpacked. Previously the codecs module was unpacking them with different _key attributes, so equality tests would always return false even when the two references were identical.
+
+- Attempting to pack invalid UTF8 strings now raises AEM::NotUTF8TextError rather than AE::MacOSError -1700.
+
+- fixed launch method (was calling non-existent Connect.launch, not Connect.launchApp)
+
+- attempting to retrieve aete resource from an application that doesn't have any terminology no longer raises 'resource not found' (-192) error
+
+- AEM module now re-exports AE::MacOSError class for convenience
+
+- Apple Event Manager-raised errors that occur when sending events are now reported correctly (was giving 'uninitialized constant Send::Event::None' errors)
+
+- appscript referencerenderer module now renders class names in next and previous references correctly
+
+- GenericReference#to_s now includes 'AS.' prefix when rendering string representations of generic references
+
+- fixed ==() methods in appscript Reference and aem Application classes
+
+- implemented eql? methods so aem types, aem references and appscript references should now work correctly as hash keys
+
+- fixed endian bugs in Codecs when unpacking insertion location selectors and comparison and logic operators
+
+
+2006-10-15 -- 0.1.4
+
+- fixed error message when reporting an unknown parameter (was showing command name, not parameter name)
+
+- fixed bug in TextEdit_demo.rb script (count command's parameter should be :each, not :each_)
+
+- fixed bug where typeBoolean AEDescs would always unpack as true
+
+- fixed bugs when packing and unpacking AEDescs of typeSInt64
+
+- integers between 2*31 and 2**63-1 now pack as typeSInt64, not typeFloat
+
+- [mostly] fixed timezone and winter/summer time bugs; there's probably still problems at the points where DST begins and ends (some of which may be Ruby's fault; this is still to be determined)
+
+
+2006-10-13 -- 0.1.3
+
+- fixed a bug in appscript where the first argument in a command call would be ignored if it was false or nil [MN]
+
+- changed priority order for determining what an ambiguous keyword (e.g. :workbook in Excel) that may be either a type or enumerator name should be packed as; previously typeEnumerated was the default, now it's typeType [MN]
+
+
+2006-10-12 -- 0.1.2
+
+- fixed a bug where appscript was unpacking typeEnumerated AEDescs as AEM::AEEnums instead of Symbols [MN]
+
+
+2006-10-10 -- 0.1.1
+
+- made several corrections and improvements to appscript manual [MN]
+
+
+2006-10-09 -- 0.1.0
+
+- first release

data/LICENSE

@@ -0,0 +1 @@
+Copyright (C) 2006 HAS

data/README

@@ -0,0 +1,42 @@
+Appscript Read Me
+
+======================================================================
+ABOUT
+
+Ruby appscript (rb-appscript) is a high-level Apple event bridge for the Ruby scripting language. rb-appscript is closely based on the Python appscript (py-appscript) bridge.
+
+See the doc folder for more information.
+
+======================================================================
+REQUIREMENTS
+
+- Mac OS X 10.3+
+- Ruby 1.8+
+
+======================================================================
+INSTALLATION
+
+$ ruby extconf.rb
+$ make
+$ sudo make install
+
+-------
+
+Please note that the version of Ruby included with Mac OS X 10.4 is missing the header files needed to build appscript on PPC-based Macs. You can avoid this issue by installing the latest version of Ruby from <http://www.ruby-lang.org/en/downloads/> and updating your shell login profiles to suit.
+
+======================================================================
+NOTES
+
+- rb-appscript 0.2.0 contains a number of API changes from rb-appscript 0.1.x; see the CHANGES file and documentation for details
+
+======================================================================
+AUTHOR
+
+- HAS -- hhas -at- users - sourceforge - net <http://rb-appscript.rubyforge.org> <http://appscript.sourceforge.net>
+
+======================================================================
+COPYRIGHT
+
+Copyright (C) 2006 HAS 
+
+Appscript is released under the MIT License. See the LICENSE file for more information.

data/TODO

@@ -0,0 +1,31 @@
+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)
+
+- remove rbAE_pidToPsn from rbae.c? (no longer used by connect.rb)
+
+- allow users to extract a generic ref from a real ref (to_generic) for comparison purposes. Or vice-versa?
+
+- implement built-in help system by bridging to py-appscript
+
+- see if it's possible to work better with irb's autocomplete (autocomplete support is currently limited to start of a reference)
+
+- ae/aem/appscript-defined exception classes aren't quite idiomatic Ruby
+
+- finish commenting source code
+
+- 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)
+
+- include an example project (or source for) that uses ruby2exe to build a standalone 'applet'
+
+- profiling
+
+- finish writing tests
+
+- improve and polish documentation
+
+- finish problem apps chapter (see comments in HTML file)
+
+- see also TO DO items in source files
+
+- see also py-appscript's todo.txt file

data/doc/aem-manual/01_introduction.html

@@ -0,0 +1,48 @@
+<!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>aem | 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>1. Introduction</h1>
+
+<!-- top navigation -->
+<div class="navbar">
+	<a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_apioverview.html">Next</a>
+</div>
+
+<!-- content -->
+<div id="content">
+
+<h2>What is aem?</h2>
+
+<p>The aem package provides a mid-level object-oriented wrapper around the low-level ae extension. It provides the following services:</p>
+
+<ul>
+<li>an object-oriented API for constructing Apple Event Object Model queries ("references")</li>
+<li>data conversion between common Ruby and AEM types</li>
+<li>AEAddressDesc creation</li>
+<li>Apple event construction and dispatch.</li>
+</ul>
+
+<p>The aem package provides a direct foundation for the high-level appscript package. It can also be used directly by developers and end-users for controlling scriptable applications in situations where appscript is unavailable or unsuitable.</p>
+
+<p class="hilitebox">Note that this documentation is an API reference, not a full user guide. Some familiarity with Apple events and the Apple Event Manager is required in order to understand and use aem.</p>
+
+</div>
+
+<!-- bottom navigation -->
+<div class="navbar">
+	<a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_apioverview.html">Next</a>
+</div>
+
+<!--footer-->
+<p class="footer">&copy; 2006 HAS</p>
+</body>
+</html>

data/doc/aem-manual/02_apioverview.html

@@ -0,0 +1,89 @@
+<!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>aem | 2. API overview</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>2. API overview</h1>
+
+<!-- top navigation -->
+<div class="navbar">
+	<a href="01_introduction.html">Previous</a> | <a href="index.html">Up</a> | <a href="03_packingandunpackingdata.html">Next</a>
+</div>
+
+<!-- content -->
+<div id="content">
+
+<h2>Classes</h2>
+
+<p>The main aem classes are as follows:</p>
+
+<dl>
+<dt>Application</dt>
+<dd>Represents a scriptable application, and provides an <code>event</code> method for constructing Apple events.</dd>
+
+<dt>Event</dt>
+<dd>Represents a ready-to-send Apple event, and provides a <code>send</code> method for sending it. Returned by the <code>Application</code> class's <code>event</code> method.</dd>
+
+<dt>CommandError</dt>
+<dd>Exception raised to indicate an application or Apple Event Manager error.</dd>
+
+<dt>Codecs</dt>
+<dd>Provides <code>pack</code> and <code>unpack</code> methods for converting Ruby values to AE types, and vice-versa. Clients usually don't need to access this class directly.</dd>
+
+<dt>AEType, AEEnum</dt>
+<dd>Represent Apple event type and enumerator values.</dd>
+
+</dl>
+
+<p>In addition, there are a number of classes used to represent application references, although the user does not instantiate these directly.</p>
+
+
+<h2>Attributes</h2>
+
+<p>The AEM module exports three top-level methods for use in constructing application references:</p>
+
+<dl>
+<dt>app</dt>
+<dd>Returns the base object used to construct absolute references.</dd>
+
+<dt>con</dt>
+<dd>Returns the base object used to construct relative reference to container object (used in by-range specifiers).</dd>
+
+<dt>its</dt>
+<dd>Returns the base object used to construct relative reference to object being tested (used in by-filter specifiers).</dd>
+</dl>
+
+
+<p>References are constructed from these base objects using chained property/method calls.</p>
+
+
+<h2>Modules</h2>
+
+<p>The aem package also exports the following support module:</p>
+
+<dl>
+<dt>FindApp</dt>
+<dd>Provides functions for locating applications by name, bundle id or creator code.</dd>
+
+</dl>
+
+
+
+</div>
+
+<!-- bottom navigation -->
+<div class="navbar">
+	<a href="01_introduction.html">Previous</a> | <a href="index.html">Up</a> | <a href="03_packingandunpackingdata.html">Next</a>
+</div>
+
+<!--footer-->
+<p class="footer">&copy; 2006 HAS</p>
+</body>
+</html>

data/doc/aem-manual/03_packingandunpackingdata.html

@@ -0,0 +1,98 @@
+<!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>aem | 3. Packing and unpacking data</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>3. Packing and unpacking data</h1>
+
+<!-- top navigation -->
+<div class="navbar">
+	<a href="02_apioverview.html">Previous</a> | <a href="index.html">Up</a> | <a href="04_references.html">Next</a>
+</div>
+
+<!-- content -->
+<div id="content">
+
+
+<h2>Codecs</h2>
+
+<p>The <code>AEM::Codecs</code> class provides methods for converting Python data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
+
+<pre><code>Codecs
+
+    Constructor:
+        new
+
+    Methods:
+
+        pack(data) -- convert Ruby data to an AEDesc; will raise
+                a TypeError if data's type/class is unsupported
+            data : anything
+            Result : AEDesc
+
+        unpack(desc) -- convert an AEDesc to Ruby data; will return
+                the AEDesc unchanged if it's an unsupported type
+            desc : AEDesc
+            Result : anything
+
+        add_unit_types(types) -- register custom unit type definitions
+            types : list -- a list of lists, where each sublist is of form
+                    [name, code] or [name, code, pack_proc, unpack_proc]</code></pre>
+
+
+
+
+<!-- <h3>Notes</h3>
+
+TO DO: customisation options: subclassing and extending pack/unpack, overriding individual encoder/decoder methods and packUnknown/unpackUnknown; when to instantiate/when to modify; notes on appscript integration; notes on differences to py-appscript Codecs? notes on add_unit_types
+
+-->
+
+
+
+<h2>AE types</h2>
+
+<p>The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Python. Accordingly, aem defines several classes to represent these types on the Python side. All share a common abstract base class, <code>AETypeBase</code>:</p>
+
+<pre><code>AETypeBase -- Abstract base class
+
+    Constructor:
+        new(code)
+            code : str -- a four-character Apple event code
+
+    Methods:
+        code
+            Result : str -- the four-character code
+
+
+AEType &lt; AETypeBase -- represents an AE object of typeType
+
+
+AEEnum &lt; AETypeBase -- represents an AE object of typeEnumeration
+
+
+AEProp &lt; AETypeBase -- represents an AE object of typeProperty
+
+
+AEKey &lt; AETypeBase -- represents an AE object of typeKeyword</code></pre>
+
+
+
+</div>
+
+<!-- bottom navigation -->
+<div class="navbar">
+	<a href="02_apioverview.html">Previous</a> | <a href="index.html">Up</a> | <a href="04_references.html">Next</a>
+</div>
+
+<!--footer-->
+<p class="footer">&copy; 2006 HAS</p>
+</body>
+</html>