rb-appscript 0.4.0 → 0.5.0

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

@@ -86,6 +86,6 @@ id                            wait_reply</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -150,6 +150,6 @@ $KCODE = "UTF8"</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/07_applicationobjects.html

@@ -152,6 +152,24 @@ set(reference, :to => value) -- Set an object's data.
 <p>Appscript identifies running applications by their process ids so it's possible to control multiple versions of an application running at the same time if their Application objects are created using process ids or eppc URLs.</p>
 
 
+<h3>Checking if an application is running</h3>
+
+<p>You can check if the application specified by an Application object is currently running by calling its <code>#is_running?</code> method. This is useful if you don't want to perform commands on an application that isn't already running. For example:</p>
+
+<pre><code>te = app('TextEdit')
+# Only perform TextEdit-related commands if it's already running:
+if te.is_running?
+    # all TextEdit-related code goes here...
+end</code></pre>
+
+<p class="hilitebox">Remember that appscript automatically launches a non-running application the first time your script makes reference to any of its properties, elements or commands. To avoid accidental launches, <em>all</em> code relating to that application must be included in a conditional block that only executes if <code>#is_running?</code> returns <code>true</code>.</p>
+
+
+<h3>Launch errors</h3>
+
+<p>If the application can't be launched for some reason (e.g. if it's in the Trash), an <code>Appscript::CantLaunchApplicationError</code> error will be raised. This provides a description of the problem (if it's a standard LaunchServices error) along with the original OS error number, which you can also obtain via the <code>CantLaunchApplicationError#to_i</code> method.</p>
+
+
 <h3>Using <code>launch</code> vs <code>run</code></h3>
 
 <p>When appscript launches a non-running application, it normally sends it a <code>run</code> command as part of the launching process. If you wish to avoid this, you should start the application by sending it a <code>launch</code> command before doing anything else. For example:</p>
@@ -186,6 +204,6 @@ te.launch
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -81,6 +81,6 @@ puts app('Finder').home == app('Finder').home.get
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -225,6 +225,6 @@ paragraphs[1].before</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -138,6 +138,6 @@ app('TextEdit').documents[1].text.paragraphs[1].before</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -201,6 +201,6 @@ print d
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -124,6 +124,6 @@ app('Address Book').people[
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -113,6 +113,6 @@ p result</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

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

@@ -84,6 +84,6 @@ require 'appscript'
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/index.html

@@ -43,6 +43,6 @@
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/index.html

@@ -26,6 +26,6 @@
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/mactypes-manual/index.html

@@ -39,6 +39,8 @@
 
         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
@@ -53,6 +55,8 @@
         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
 
@@ -88,6 +92,8 @@ Appscript.app('TextEdit').open(f)
 
 <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>
 
@@ -100,6 +106,8 @@ Appscript.app('TextEdit').open(f)
 
         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
@@ -114,6 +122,8 @@ Appscript.app('TextEdit').open(f)
         inspect
     
         path -- returns POSIX path string
+    
+        hfs_path -- returns HFS path string
 
         url -- returns file:// URL string
 
@@ -165,6 +175,8 @@ Appscript.app('older app').documents[1].save(:in => fs_spec)</code></pre>
 
 <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>
+
 
 
 
@@ -239,6 +251,6 @@ MacTypes::Alias.path('/some/non/existent/location')
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/osax-manual/index.html

@@ -107,9 +107,18 @@ osax.another_command</code></pre>
 
     Constructors:
 
-        ScriptingAddition.new(name) -- make a ScriptingAddition object
-                for the specified scripting addition, targetted at the
-                current application
+        ScriptingAddition.new(name, terms=nil) -- make a ScriptingAddition
+                object for the specified scripting addition, targetted
+                at the current application
+                
+                name: string -- a scripting addition's name, 
+                        e.g. "StandardAdditions"; basically its filename
+                        minus the '.osax' suffix
+                
+                terms : module or nil -- an optional terminology glue
+                        module,as exported by Terminology.dump; if
+                        given, ScriptingAddition will use this instead 
+                        of retrieving the terminology dynamically
 
     Methods:
 
@@ -117,7 +126,7 @@ osax.another_command</code></pre>
 
         commands -- returns names of all available commands
 
-        parameters(commandName) -- returns a command's parameter names
+        parameters(command_name) -- returns a command's parameter names
 
         # Specifying a different target application:
 
@@ -167,6 +176,8 @@ p sa.display_dialog("Ruby says hello!",
 
 <h2>Notes</h2>
 
+<h3>GUI interaction</h3>
+
 <p>When using scripting addition commands that require GUI access (e.g. <code>display_dialog</code>) targetted 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>
 
 <pre><code>sa = OSAX.osax("StandardAdditions", "System Events")
@@ -177,7 +188,27 @@ p sa.display_dialog("Ruby says hello!",
 # Result: {:button_returned=&gt;"Duuuude!"}</code></pre>
 
 
-<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 will prevent minimized windows expanding as normal when clicked on in the Dock.</p>
+<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>
@@ -188,6 +219,6 @@ p sa.display_dialog("Ruby says hello!",
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/extconf.rb

@@ -30,8 +30,8 @@
 
 require 'mkmf'
 
-$CFLAGS << ' -Wall'# -arch ppc -arch i386'
-$LDFLAGS = '-framework Carbon'
+$CFLAGS << ' -Wall'
+$LDFLAGS << ' -framework Carbon -framework ApplicationServices'
 
 # Avoid `ID' and `T_DATA' symbol collisions between Ruby and Carbon.
 # (adapted code from RubyAEOSA - FUJIMOTO Hisakuni  <hisa -at- fobj - com>)

data/rb-appscript.gemspec

@@ -2,7 +2,7 @@ require "rubygems"
 
 spec = Gem::Specification.new do |s|
 	s.name = "rb-appscript"
-	s.version = "0.4.0"
+	s.version = "0.5.0"
 	s.author = "HAS"
 	s.homepage = "http://rb-appscript.rubyforge.org/"
 	s.rubyforge_project="rb-appscript"

data/sample/AB_export_vcard.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+# Exports all Address Book entries as vcards to current working folder.
+#
+# Files are named as 'NAME.vcard' (note: existing files will be overwritten).
+# If the name is missing, 'unknown' is used instead. If two or more people
+# share the same name, files will be named 'NAME.vcard', 'NAME 1.vcard',
+# 'NAME 2.vcard', etc.
+
+
+# Note: if using the appscript gem, rubygems must be required first:
+begin; require 'rubygems'; rescue LoadError; end
+
+require 'appscript'
+include Appscript
+
+people = app('Address Book').people
+
+found_names = []
+people.name.get.zip(people.vcard.get).each do |name, vcard|
+	name = 'unknown' if name == ''
+	name = name.gsub('/', ':')
+	filename = "#{name}.vcard"
+	i = 1
+	while found_names.include?(filename.downcase)
+		filename = "#{name} #{i}.vcard"
+		i += 1
+	end
+	found_names.push(filename.downcase)
+	File.open(filename, 'w') { |f| f.puts vcard }
+end

data/sample/Add_iCal_event.rb

@@ -1,13 +1,13 @@
-#!/usr/local/bin/ruby
-
-require 'appscript'
-include Appscript
+#!/usr/bin/env ruby
 
 # Add an event to Home calendar that runs from 7am to 9 am tomorrow
 
 # Note: if using the appscript gem, rubygems must be required first:
 begin; require 'rubygems'; rescue LoadError; end
 
+require 'appscript'
+include Appscript
+
 calendar_name = 'Home'
 t = Time.now + 60 * 60 * 24
 start = Time.local(t.year, t.month, t.day, 7)

data/src/lib/_aem/connect.rb

@@ -1,4 +1,4 @@
-#!/usr/local/bin/ruby
+#!/usr/bin/ruby
 # Copyright (C) 2006 HAS. 
 # Released under MIT License.
 
@@ -28,7 +28,48 @@ module Connect
 	#######
 	# public
 	
-	def Connect.launch_app(path)
+	class CantLaunchApplicationError < RuntimeError
+	
+		# Taken from <http://developer.apple.com/documentation/Carbon/Reference/LaunchServicesReference>:
+		LSErrors = {
+			-10660 => "The application cannot be run because it is inside a Trash folder.",
+			-10810 => "An unknown error has occurred.",
+			-10811 => "The item to be registered is not an application.",
+			-10813 => "Data of the desired type is not available (for example, there is no kind string).",
+			-10814 => "No application in the Launch Services database matches the input criteria.",
+			-10817 => "Data is structured improperly (for example, an item's information property list is malformed).",
+			-10818 => "A launch of the application is already in progress.",
+			-10822 => "There is a problem communicating with the server process that maintains the Launch Services database.",
+			-10823 => "The filename extension to be hidden cannot be hidden.",
+			-10825 => "The application to be launched cannot run on the current Mac OS version.",
+			-10826 => "The user does not have permission to launch the application (on a managed network).",
+			-10827 => "The executable file is missing or has an unusable format.",
+			-10828 => "The Classic emulation environment was required but is not available.",
+			-10829 => "The application to be launched cannot run simultaneously in two different user sessions.",
+		}
+	
+		def initialize(error_number)
+			@error_number = error_number
+			super("#{ LSErrors.fetch(@error_number, 'OS error') } (#{ @error_number })")
+		end
+		
+		def to_i
+			return @error_number
+		end
+	end
+	
+	##
+	
+	def Connect.launch_application(path, event)
+		begin
+			return AE.launch_application(path, event,
+					LaunchContinue + LaunchNoFileFlags + LaunchDontSwitch)
+		rescue AE::MacOSError => err
+			raise CantLaunchApplicationError, err.to_i
+		end
+	end
+	
+	def Connect.launch_app_with_launch_event(path)
 		# Send a 'launch' event to an application. If application is not already running, it will be launched in background first.
 		begin
 			# If app is already running, calling AE.launch_application will send a 'reopen' event, so need to check for this first:
@@ -36,8 +77,7 @@ module Connect
 		rescue AE::MacOSError => err
 			if err.to_i == -600 # Application isn't running, so launch it and send it a 'launch' event
 				sleep(1)
-				AE.launch_application(path, LaunchEvent,  
-						LaunchContinue + LaunchNoFileFlags + LaunchDontSwitch)
+				launch_application(path, LaunchEvent)
 			else
 				raise
 			end
@@ -46,8 +86,11 @@ module Connect
 		end
 	end
 	
-	def Connect.is_running?(path)
-		# Is a local application running?
+	##
+	
+	def Connect.process_exists_for_path?(path)
+		# Does a local process launched from the specified application file exist?
+		# Note: if path is invalid, an AE::MacOSError is raised.
 		begin
 			AE.psn_for_application_path(path)
 			return true
@@ -59,6 +102,44 @@ module Connect
 			end
 		end
 	end
+
+	def Connect.process_exists_for_pid?(pid)
+		# Is there a local application process with the given unix process id?
+		begin
+			AE.psn_for_process_id(pid)
+			return true
+		rescue AE::MacOSError => err
+			if err.to_i == -600
+				return false
+			else
+				raise
+			end
+		end
+	end
+	
+	def Connect.process_exists_for_url?(url)
+		# Does an application process specified by the given eppc:// URL exist?
+		# Note: this will send a 'launch' Apple event to the target application.
+		return process_exists_for_desc?(AE::AEDesc.new(KAE::TypeApplicationURL, url))
+	end
+	
+	def Connect.process_exists_for_desc?(desc)
+		# Does an application process specified by the given AEAddressDesc exist?
+		# Returns false if process doesn't exist OR remote Apple events aren't allowed.
+		# Note: this will send a 'launch' Apple event to the target application.
+		begin
+			# This will usually raise error -1708 if process is running, and various errors
+			# if the process doesn't exist/can't be reached. If app is running but busy,
+			# AESendMessage may return a timeout error (this should be -1712, but
+			# -609 is often returned instead for some reason).
+			Send::Event.new(desc, 'ascrnoop').send
+		rescue Send::CommandError => err
+			return (not [-600, -905].include?(err.to_i)) # not running/no network access
+		end
+		return true
+	end
+	
+	##
 	
 	CurrentApp = make_address_desc([0, KCurrentProcess])
 	
@@ -73,8 +154,7 @@ module Connect
 		rescue AE::MacOSError => err
 			if err.to_i == -600 # Application isn't running, so launch it in background and send it a standard 'run' event.
 				sleep(1)
-				psn = AE.launch_application(path, RunEvent,  
-						LaunchContinue + LaunchNoFileFlags + LaunchDontSwitch)
+				psn = launch_application(path, RunEvent)
 			else
 				raise
 			end