rb-appscript 0.5.3 → 0.6.0

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

@@ -90,8 +90,6 @@ puts app('Finder').home == app('Finder').home.get
 <a href="07_applicationobjects.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="09_referenceforms.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

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

@@ -235,8 +235,6 @@ paragraphs[1].before</code></pre>
 <a href="08_realvsgenericreferences.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="10_referenceexamples.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/appscript-manual/10_referenceexamples.html

@@ -127,7 +127,7 @@ app('Tex-Edit Plus').documents[1].paragraphs[
 # a reference to every file of folder "Documents" of home of application "Finder" ¬
 #     whose name extension is &quot;txt&quot; and size < 10240
 app('Finder').home.folders['Documents'].files[
-    its.name_extension.eq('txt').AND(its.size.lt(10240))]</code></pre>
+    its.name_extension.eq('txt').and(its.size.lt(10240))]</code></pre>
 
 
 <h3>Insertion location references</h3>
@@ -148,8 +148,6 @@ app('TextEdit').documents[1].text.paragraphs[1].before</code></pre>
 <a href="09_referenceforms.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="11_applicationcommands.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/appscript-manual/11_applicationcommands.html

@@ -166,6 +166,35 @@ app('Finder').home.items.get(:result_type =&gt; :alias)</code></pre>
 </ol>
 
 
+<h3>Command errors</h3>
+
+
+<p>The <code>Appscript::CommandError</code> exception describes an error raised by the target application or Apple Event Manager when sending a command.</p>
+
+<pre><code>CommandError < RuntimeError
+
+    Methods:
+        
+        error_number : FixNum -- Mac OS error number
+        
+        error_message : String -- application-supplied/generic error description
+        
+        offending_object : anything | nil -- object that caused the error, 
+                                             if given by application
+        
+        expected_type : anything | nil -- object that caused a coercion error, 
+                                          if given by application
+        
+        partial_result : anything | nil -- part of return value constructed 
+                                           before error occurred, if given 
+                                           by application
+        
+        to_i : FixNum -- equivalent to #error_number
+
+        to_s : String -- formatted error information</code></pre>
+
+
+
 <h3>Note to AppleScript users</h3>
 
 <p>Unlike AppleScript, which implicitly sends a <code>get</code> command to any unresolved application object references at the end of evaluating an expression, appscript only resolves a reference when it receives an appropriate command. For example:</p>
@@ -210,8 +239,6 @@ print d
 <a href="10_referenceexamples.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="12_commandexamples.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/appscript-manual/12_commandexamples.html

@@ -132,8 +132,6 @@ app('Address Book').people[
 <a href="11_applicationcommands.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="13_performanceissues.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/appscript-manual/13_performanceissues.html

@@ -136,8 +136,6 @@ p result</code></pre>
 <a href="12_commandexamples.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="14_notes.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/appscript-manual/14_notes.html

@@ -57,33 +57,16 @@ require 'appscript'
 <p>Some applications (e.g. QuarkXpress) may return values which appscript cannot convert to equivalent Ruby types. These values are usually of types which are defined, used and understood only by that particular application, and will be represented in Ruby as raw <code>AE::AEDesc</code> objects (e.g. <code>#&lt;AE::AEDesc:0x33fc40&gt;</code>). While there's not much you can do with raw <code>AEDesc</code> objects within Ruby (it's best just to treat them as opaque types), subsequent commands can pass them back to the application for further use and/or conversion just like any other value.</p>
 
 
-<h3>Dealing with problem applications</h3>
-
-<p>Appscript provides a number of mechanisms for dealing with problematic applications. See the <a href="http://appscript.sourceforge.net">appscript website</a> for more information.</p>
-
-
 <h3>Credits</h3>
 
 <p>Many thanks to Bill Birkett, Jordan Breeding, Fujimoto Hisakuni, Jordan K Hubbard, Alexander Kellett, Chris Nebel, Matt Neuburg, Laurent Sansonetti, Michelle Steiner, Kevin Van Vechten, and all the appscript users who've provided comments, criticisms and encouragement along the way.</p>
 
 
-<h3>Donations</h3>
-
-<p>You can <a href="http://sourceforge.net/donate/index.php?group_id=175009">donate to the appscript project</a> via SourceForge.net. Special thanks to all those appscript users who have already contributed.</p>
-
-
 <h3>Website</h3>
 
 <p><a href="http://appscript.sourceforge.net">http://appscript.sourceforge.net</a></p>
 
 
-<h3>Copyright</h3>
-
-<p>(C) 2006-2008 HAS -- hhas -at- users - sourceforge - net</p>
-
-<p>Appscript is released under the MIT License.</p>
-
-
 </div>
 
 <!-- bottom navigation -->
@@ -91,8 +74,6 @@ require 'appscript'
 <div class="footer">
 <a href="13_performanceissues.html">Previous</a> &bull;
 <a href="index.html">Up</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/appscript-manual/index.html

@@ -56,8 +56,6 @@
 <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>
 
 </body>

data/doc/index.html

@@ -39,10 +39,7 @@
 
 </div>
 
-<div class="footer">
-&nbsp;
-<span>&copy; 2006-2008 HAS</span>
-</div>
+<div class="footer">&nbsp;</div>
 
 </body>
 </html>

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

@@ -48,8 +48,6 @@
 <a href="index.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="02_aliasclass.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>    
 </div>
 
 </body>

data/doc/mactypes-manual/02_aliasclass.html

@@ -96,20 +96,12 @@ MacTypes::Alias.path('/some/non/existent/location')
 
 <h3>Notes</h3>
 
-<!-- TO DO: relative paths, normalisation
-
-<p>When creating an <code>Alias</code> instance, POSIX paths may be either relative or absolute and are automatically normalised using <code>os.path.abspath</code>. Paths to non-existent filesystem locations will result in a <code>MacTypes::FileNotFoundError</code> being raised.</p>
-
--->
-
 <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. using aliases as <code>Hash</code> keys).</p>
 
 </div>
 
-<!-- TO DO: where to put FileNotFoundError section? -->
-
 <h3><code>MacTypes::FileNotFoundError</code></h3>
 
 <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>
@@ -126,8 +118,6 @@ MacTypes::Alias.path('/some/non/existent/location')
 <a href="01_introduction.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="03_fileurlclass.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/mactypes-manual/03_fileurlclass.html

@@ -92,14 +92,6 @@ Appscript.app('TextEdit').documents[1].save(:in => f)
 
 <h3>Notes</h3>
 
-<!-- TO DO: relative paths, normalisations
-
-<p>When creating a <code>File</code> instance, POSIX paths may be either relative or absolute and are automatically normalised using <code>os.path.abspath</code>.</p>
-
--->
-
-<!-- TO DO: check this section for consistency with py-appscript manual -->
-
 <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 instead:</p>
@@ -128,9 +120,7 @@ Appscript.app('older app').documents[1].save(:in => fs_spec)</code></pre>
 <a href="02_aliasclass.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="04_unitsclass.html">Next</a>
-    
-<span>&copy; 2006-2008 HAS</span>
-</div>
+    </div>
 
 </body>
 </html>

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

@@ -94,8 +94,6 @@ MacTypes::Units.new(3.5, :square_meters)</code></pre>
 <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>

data/doc/mactypes-manual/index.html

@@ -47,8 +47,6 @@
 <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>
 
 </body>

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

@@ -61,8 +61,6 @@ sa.say("Hello world", :using=&gt;"Victoria")</code></pre>
 <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>

data/doc/osax-manual/02_interface.html

@@ -141,8 +141,6 @@ osax.another_command</code></pre>
 <a href="01_introduction.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="03_examples.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/osax-manual/03_examples.html

@@ -67,8 +67,6 @@ p sa.display_dialog("Ruby says hello!",
 <a href="02_interface.html">Previous</a> &bull;
 <a href="index.html">Up</a> &bull;
 <a href="04_notes.html">Next</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/osax-manual/04_notes.html

@@ -30,6 +30,12 @@
 
 <h2>4. Notes</h2>
 
+
+<h3>Event loops</h3>
+
+<p>Ruby-based applications that use a Carbon/Cocoa event loop can import the <code>OSAX</code> module as normal, but should not use it before the event loop has started as sending Apple events outwith the main event loop can disrupt the process's normal event handling.</p>
+
+
 <h3>GUI interaction</h3>
 
 <p>When using scripting addition commands that require GUI access (e.g. <code>display_dialog</code>) targeted at the command-line Ruby interpreter, the osax module will automatically convert the non-GUI interpreter process into a full GUI process to allow these commands to operate correctly. If you want to avoid this, target these commands at a faceless GUI application such as System Events instead:</p>
@@ -42,29 +48,6 @@ p sa.display_dialog("Ruby says hello!",
 # Result: {:button_returned=&gt;"Duuuude!"}</code></pre>
 
 
-<h3>64-bit limitations</h3>
-
-<p>The <code>OSAX</code> module currently only supports dynamic retrieval of scripting addition terminology when running in 32-bit processes. To use it in 64-bit processes, use the <code>Terminology</code> module's <code>dump</code> method to export a static terminology 'glue' module for the desired scripting addition (running it in a 32-bit process), then import that module and pass it as the second argument to the <code>ScriptingAddition</code> class's initialiser. For example, to export a glue module for Standard Additions:</p>
-
-<pre><code>require 'appscript'
-
-Terminology.dump('/System/Library/ScriptingAdditions/StandardAdditions.osax', 
-        'StandardAdditions', 'standard_additions.rb')</code></pre>
-
-<p>To create a new <code>ScriptingAddition</code> instance using the terminology provided by this glue module:</p>
-
-<pre><code>require 'osax'
-require 'standard_additions'
-
-sa = OSAX::ScriptingAddition.new('StandardAdditions', StandardAdditions)</code></pre>
-
-
-<h3>Known problems</h3>
-
-<p>When using the <code>OSAX</code> module within RubyCocoa-based applications, avoid creating <code>ScriptingAddition</code> instances before the main event loop is started as this can result in the application behaving strangely (minimised windows don't expand correctly) due to a bug in OS X's <code>OSAGetAppTerminology</code> function.</p>
-
-
-
 </div>
 
 <!-- bottom navigation -->
@@ -72,8 +55,6 @@ sa = OSAX::ScriptingAddition.new('StandardAdditions', StandardAdditions)</code><
 <div class="footer">
 <a href="03_examples.html">Previous</a> &bull;
 <a href="index.html">Up</a>
-
-<span>&copy; 2006-2008 HAS</span>
 </div>
 
 </body>

data/doc/osax-manual/index.html

@@ -47,8 +47,6 @@
 <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>
 
 </body>

data/rb-appscript.gemspec

@@ -2,9 +2,8 @@ require "rubygems"
 
 spec = Gem::Specification.new do |s|
 	s.name = "rb-appscript"
-	s.version = "0.5.3"
-	s.author = "HAS"
-	s.homepage = "http://appscript.sourceforge.net/rb-appscript"
+	s.version = "0.6.0"
+	s.homepage = "http://appscript.sourceforge.net/"
 	s.rubyforge_project="rb-appscript"
 	s.summary="Ruby appscript (rb-appscript) is a high-level, user-friendly Apple event bridge that allows you to control scriptable Mac OS X applications using ordinary Ruby scripts."
 	s.files = Dir["**/*"].delete_if { |name| ["MakeFile", "ae.bundle", "mkmf.log", "rbae.o", "SendThreadSafe.o", "src/osx_ruby.h", "src/osx_intern.h"].include?(name) }

data/src/lib/_aem/aemreference.rb

@@ -3,8 +3,6 @@
 #
 # aemreference -- an object-oriented API for constructing object specifier AEDescs
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
 
 ######################################################################
 # Endianness support
@@ -85,14 +83,14 @@ module AEMReference
 	# BASE CLASS
 	######################################################################
 	
-	class Base
+	class Query
 	
 		def initialize
 			@_comparable = nil
 		end
 	
 		def AEM_comparable
-			# called by Base#==; returns the data needed to compare two aem references
+			# called by Query#==; returns the data needed to compare two aem references
 			if not @_comparable
 				collector = AEMReference::CollectComparable.new
 				AEM_resolve(collector)
@@ -123,7 +121,7 @@ module AEMReference
 	# BASE CLASS FOR ALL REFERENCE FORMS
 	######################################################################
 	
-	class Specifier < Base
+	class Specifier < Query
 		# Base class for insertion specifier and all object specifier classes.
 		
 		attr_reader :_key, :_container
@@ -719,7 +717,7 @@ module AEMReference
 	###################################
 	# Unresolved reference
 	
-	class DeferredSpecifier < Base
+	class DeferredSpecifier < Query
 		def initialize(desc, codecs)
 			@_ref = nil
 			@_desc = desc
@@ -758,7 +756,7 @@ module AEMReference
 	###################################
 	# Base class
 	
-	class Test < Base
+	class Test < Query
 	
 		# Logical tests
 		

data/src/lib/_aem/codecs.rb

@@ -3,14 +3,15 @@
 #
 # codecs -- convert native Ruby objects to AEDescs, and vice-versa
 #
-# Copyright (C) 2006-2009 HAS. Released under MIT License.
-#
+
+require "date"
 
 require "ae"
 require "kae"
 require "_aem/typewrappers"
 require "_aem/aemreference"
 require "_aem/mactypes"
+require "_aem/encodingsupport"
 
 # Note that AE strings (typeChar, typeUnicodeText, etc.) are unpacked as UTF8-encoded Ruby strings, and UTF8-encoded Ruby strings are packed as typeUnicodeText. Using UTF8 on the Ruby side avoids data loss; using typeUnicodeText on the AEM side provides compatibility with all [reasonably well designed] applications. To change this behaviour (e.g. to support legacy apps that demand typeChar and break on typeUnicodeText), subclass Codecs and override pack and/or unpack methods to provide alternative packing/unpacking of string values. Users can also pack data manually using AE::AEDesc.new(type, data).
 
@@ -129,6 +130,7 @@ module DisableObjectSpecifierCaching
 	end
 end
 
+#######
 
 class Codecs
 	# Provides pack and unpack methods for converting data between Ruby and AE types.
@@ -141,7 +143,16 @@ class Codecs
 
 	def initialize
 		@unit_type_codecs = UnitTypeCodecs.new
+		# Note: while typeUnicodeText is deprecated (see AEDataModel.h), it's still the
+		# most commonly used Unicode type so is used here for compatibility's sake.
+		# typeUTF8Text was initially tried, but existing applications had problems with it; i.e.
+		# some apps make unsafe assumptions on what to expect based on AS's behaviour.
+		# Once AppleScript is using typeUTF8Text/typeUTF16ExternalRepresentation
+		# and existing applications don't choke, this code can be similarly upgraded.
 		@pack_text_as_type = KAE::TypeUnicodeText
+		# on Ruby 1.9+, set String encoding to UTF-8
+		@encoding_support = AEMEncodingSupport.encoding_support
+		@unpack_dates_as_datetime = false
 	end
 	
 	######################################################################
@@ -173,6 +184,25 @@ class Codecs
 		end
 		@pack_text_as_type = code
 	end
+	
+	def use_ascii_8bit
+		# By default on Ruby 1.9+, Codecs#pack creates String instances with UTF-8 
+		# encoding and #unpack ensures all strings are UTF-8 encoded before packing 
+		# them into AEDescs of typeUTF8Text. To force the old-style behaviour where
+		# strings are treated as byte strings containing UTF-8 data, call:
+		#
+		#	some_application.AS_app_data.use_ascii_8bit_strings
+		#
+		# This will cause Strings to use the binary ASCII-8BIT encoding; as in Ruby 1.8, 
+		# the user is responsible for ensuring that strings contain UTF-8 data.
+		@encoding_support = AEMEncodingSupport::DisableStringEncodings
+	end
+	
+	def use_datetime
+		# By default dates are unpacked as Time instances, which have limited range.
+		# Call this method to unpack dates as DateTime instances instead.
+		@unpack_dates_as_datetime = true
+	end
 
 	######################################################################
 	# Subclasses could override these to provide their own reference roots if needed
@@ -201,7 +231,7 @@ class Codecs
 	
 	def pack(val) # clients may override this to replace existing packers
 		case val
-			when AEMReference::Base then val.AEM_pack_self(self)
+			when AEMReference::Query then val.AEM_pack_self(self)
 			
 			when Fixnum, Bignum then
 				if SInt32Bounds === val
@@ -215,23 +245,7 @@ class Codecs
 				end
 			
 			when String then 
-				begin
-					# Note: while typeUnicodeText is deprecated (see AEDataModel.h), it's still the
-					# most commonly used Unicode type so is used here for compatibility's sake.
-					# typeUTF8Text was initially tried, but existing applications had problems with it; i.e.
-					# some apps make unsafe assumptions on what to expect based on AS's behaviour.
-					# Once AppleScript is using typeUTF8Text/typeUTF16ExternalRepresentation
-					# and existing applications don't choke, this code can be similarly upgraded.
-					# Note: while the BOM is optional in typeUnicodeText, it's not included by AS
-					# and some apps, e.g. iTunes 7, will handle it incorrectly, so it's omitted here.)
-					AE::AEDesc.new(KAE::TypeUTF8Text, val).coerce(@pack_text_as_type)
-				rescue AE::MacOSError => e
-					if e.to_i == -1700 # couldn't coerce to TypeUnicodeText
-						raise TypeError, "Not valid UTF8 data or couldn't coerce to type %{@pack_text_as_type}: #{val.inspect}"
-					else
-						raise
-					end
-				end
+				@encoding_support.pack_string(val, @pack_text_as_type)
 			
 			when TrueClass then TrueDesc
 			when FalseClass then FalseDesc
@@ -240,7 +254,11 @@ class Codecs
 			
 			when Time
 				AE::AEDesc.new(KAE::TypeLongDateTime,
-						[AE.convert_unix_seconds_to_long_date_time(val.to_i)].pack('q'))
+					[AE.convert_unix_seconds_to_long_date_time(val.to_i)].pack('q'))
+			
+			when DateTime, Date then
+				AE::AEDesc.new(KAE::TypeLongDateTime,
+					[AE.convert_string_to_long_date_time(val.strftime('%F %T'))].pack('q'))
 			
 			when Array then pack_array(val)
 			when Hash then pack_hash(val)
@@ -345,13 +363,18 @@ class Codecs
 					KAE::TypeIntlText, 
 					KAE::TypeUTF16ExternalRepresentation,
 					KAE::TypeStyledText
-				desc.coerce(KAE::TypeUTF8Text).data
+				@encoding_support.unpack_string(desc)
 				
 			when KAE::TypeFalse then false
 			when KAE::TypeTrue then true
 			
 			when KAE::TypeLongDateTime then
-				Time.at(AE.convert_long_date_time_to_unix_seconds(desc.data.unpack('q')[0]))
+				t = desc.data.unpack('q')[0]
+				if @unpack_dates_as_datetime
+					DateTime.strptime(AE.convert_long_date_time_to_string(t), '%F %T')
+				else
+					Time.at(AE.convert_long_date_time_to_unix_seconds(t))
+				end
 			
 			when KAE::TypeAEList then unpack_aelist(desc)
 			when KAE::TypeAERecord then unpack_aerecord(desc)
@@ -609,7 +632,7 @@ class Codecs
 		# reference being tested is second operand, so need to make sure first operand is an its-based ref;
 		# if not, rearrange accordingly.
 		# Since type-checking is involved, this extra hook is provided so that appscript's AppData subclass can override this method to add its own type checking
-		if  op1.is_a?(AEMReference::Base) and op1.AEM_root == AEMReference::Its
+		if  op1.is_a?(AEMReference::Query) and op1.AEM_root == AEMReference::Its
 			return op1.contains(op2)
 		else
 			return op2.is_in(op1)