rb-appscript 0.2.1 → 0.3.0

data/doc/appscript-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>
 
@@ -33,13 +33,12 @@
 	<li><a href="11_applicationcommands.html">Application Commands</a></li>
 	<li><a href="12_commandexamples.html">Command Examples</a></li>
 	<li><a href="13_performanceissues.html">Performance Issues</a></li>
-	<li><a href="14_problemapps.html">Dealing With Problem Applications</a></li>
-	<li><a href="15_notes.html">Notes</a></li>
+	<li><a href="14_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>
 

data/doc/index.html

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

data/doc/mactypes-manual/index.html

@@ -14,7 +14,7 @@
 
 <!-- top navigation -->
 <div class="navbar">
-    <a href="index.html">Up</a>
+    <a href="../index.html">Up</a>
     
 </div>
 
@@ -22,7 +22,7 @@
 <div id="content">
 <h2>What is mactypes?</h2>
 
-<p>The mactypes module provides user-friendly wrappers for OS X Alias and File 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>
+<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>
 
 <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>
 
@@ -86,8 +86,7 @@ Appscript.app('TextEdit').open(f)
 
 <h3>Notes</h3>
 
-<p>Note that comparing an <code>Alias</code> object against an <code>FileURL</code> object always returns false, even if both point to the same location.</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>
 
 
 <h2><code>MacTypes::FileURL</code></h2>
@@ -162,7 +161,7 @@ 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>Note that comparing <code>FileURL</code> objects only tests for exact data equality; two objects that identify the same filesystem location by different means (e.g.comparing a <code>FileURL</code> object that was created from an existing AEDesc of <code>TypeFSRef</code> against one created from scratch), using paths of different case, etc. will test as false.</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>
 
@@ -209,22 +208,33 @@ MacTypes::Alias.path('/some/non/existent/location')
 
         to_s -- returns the measurement as a string, e.g. "3.5 centimeters"</code></pre>
 
-<p>For convenience, the <code>Units</code> class also implements an additional class method, <code>Units.method_missing</code>, to allow new values to be created using the unit of measurement as the constructor call, e.g.:</p>
-
-<pre><code>MacTypes::Units.new(14, :inches)</code></pre>
-
-<p>can also be written as:</p>
+<p>The following unit types are defined as standard:</p>
 
-<pre><code>MacTypes::Units.inches(14)</code></pre>
+<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>See the <a href="../appscript-manual/06_classesandenums.html">Classes and Enumerated Types</a> chapter of the appscript manual for a full list of unit types built into aem/appscript. Additional application-specific unit types can be added if needed.</p>
+<p>Additional application-specific unit types can be added if needed.</p>
 
 
 </div>
 
 <!-- bottom navigation -->
 <div class="navbar">
-    <a href="index.html">Up</a>
+    <a href="../index.html">Up</a>
     
 </div>
 

data/doc/osax-manual/index.html

@@ -14,7 +14,7 @@
 
 <!-- top navigation -->
 <div class="navbar">
-    <a href="index.html">Up</a>
+    <a href="../index.html">Up</a>
 </div>
 
 <!-- content -->
@@ -54,11 +54,21 @@ p OSAX.scripting_additions
 
 <h2><code>OSAX.osax</code></h2>
 
-<p>The <code>osax</code> function provides a convenient shortcut for creating new <code>ScriptingAddition</code> instances:</p>
+<p>The <code>osax</code> function provides a convenient shortcut for creating new <code>ScriptingAddition</code> instances.</p>
+
+<pre><code>osax(name=nil, app_name=nil) -- convenience method for
+        creating a new ScriptingAddition instance
+    name : String | nil -- scripting addition's name
+            (nil = "StandardAdditions")
+    app_name : String | nil -- target application's name/path, or nil
+            for current application
+    Result : ScriptingAddition</code></pre>
+
+<p>For example:</p>
 
 <pre><code>require "osax"
 
-sa = OSAX.osax("StandardAdditions")
+sa = OSAX.osax
 
 p sa
 # Result: #&lt;OSAX::ScriptingAddition
@@ -75,6 +85,18 @@ p sa
 
 <p>To specify applications by other means (e.g. URL), create a <code>ScriptingAddition</code> object first, then call the appropriate <code>by...</code> method.</p>
 
+<p>For convenience, if both arguments are nil then a <code>ScriptingAddition</code> object for StandardAdditions is created and returned. This object is also cached internally for efficiency and returned as-is in subsequent calls; thus, for example:</p>
+
+<pre><code>sa = osax
+sa.some_command
+sa.another_command</code></pre>
+
+<p>could also be written as:</p>
+
+<pre><code>osax.some_command
+osax.another_command</code></pre>
+
+<p>without the additional overhead of creating a new ScriptingAddition object each time.</p>
 
 
 
@@ -121,7 +143,7 @@ p sa
 
 # Create a new ScriptingAddition object:
 
-sa = OSAX.osax("StandardAdditions")
+sa = OSAX.osax
 
 
 # List all available commands:
@@ -160,7 +182,7 @@ p sa.display_dialog("Ruby says hello!",
 
 <!-- bottom navigation -->
 <div class="navbar">
-    <a href="index.html">Up</a>
+    <a href="../index.html">Up</a>
 </div>
 
 <!--footer-->

data/rb-appscript.gemspec

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

data/sample/AB_list_people_with_emails.rb

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 
-# Lists the name and email(s) of every person in Address Book with one or more email addresses.
+# Lists the name and email(s) of every person in Address Book with
+# one or more email addresses.
 
 require "appscript"
 include Appscript

data/sample/Add_iCal_event.rb

@@ -0,0 +1,18 @@
+#!/usr/local/bin/ruby
+
+require 'appscript'
+include Appscript
+
+# Add an event to Home calendar that runs from 7am to 9 am tomorrow
+
+calendar_name = 'Home'
+t = Time.now + 60 * 60 * 24
+start = Time.local(t.year, t.month, t.day, 7)
+end_ = start + 60 * 60 * 2
+summary = 'First pants, then shoes.'
+
+app('iCal').calendars[calendar_name].events.end.make(
+        :new => :event, :with_properties => {
+                :start_date => start, 
+                :end_date => end_, 
+                :summary => summary})

data/sample/Export_Address_Book_phone_numbers.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+# Exports phone numbers from Address Book.
+
+require "osax"
+include Appscript, OSAX
+
+# create Application object for Address Book
+AB = app("Address Book")
+
+# prompt user for name of Address Book group to export from
+DefaultChoice = ["<All>"]
+
+groups = DefaultChoice + AB.groups.name.get
+choice = osax.choose_from_list(groups, :default_items => DefaultChoice)
+if choice == false # user cancelled
+	exit
+elsif choice == DefaultChoice
+	ref = AB
+else
+	ref = AB.groups[choice[0]]
+end
+
+# build a reference identifying those people with one or more phone numbers
+p = ref.people[its.phones.ne([])]
+
+# get first and last names for those people, replacing any :missing_value
+# entries with empty strings
+last_names = p.last_name.get.collect { |val| val.is_a?(String) ? val : "" }
+first_names = p.first_name.get.collect { |val| val.is_a?(String) ? val : "" }
+
+# get lists of phone numbers and locations for those people
+locations = p.phones.label.get
+numbers = p.phones.value.get
+
+# build an array containing each person's details:
+# [[last name, first name, locations, numbers], ...]
+people = last_names.zip(first_names, locations, numbers)
+
+# sort array by last and first name
+people.sort! do |a, b|
+	a[0,2].collect { |s| s.downcase } <=> b[0,2].collect { |s| s.downcase }
+end
+
+# print table
+puts " #{'_' * 70} "
+people.each do |last_name, first_name, locations, numbers|
+	name = [last_name, first_name].delete_if { |s| s == "" }.join(', ')
+	puts "|#{' ' * 70}|"
+	# print each phone number in turn
+	numbers.zip(locations).each do |number, location|
+		puts "| #{name.ljust(32)} #{number.ljust(20)} (#{(location + ')').ljust(13)} |"
+		name = ""
+	end
+	puts "|#{'_' * 70}|"
+end

data/sample/Hello_world.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-# Hello world in TextEdit.
+# 1. "Hello world" in TextEdit:
 
 require "appscript"
 include Appscript
@@ -8,3 +8,11 @@ include Appscript
 te = app('TextEdit')
 te.activate
 te.documents.end.make(:new => :document, :with_properties => {:text => "Hello World!\n"})
+
+
+# 2. "Hello world" using StandardAdditions:
+
+require "osax"
+include OSAX
+
+osax.display_dialog("Hello World")

data/sample/Select_all_HTML_files.rb

@@ -5,5 +5,7 @@
 require "appscript"
 include Appscript
 
-w = app('Finder').Finder_windows[1].target.get
-w.files[its.name_extension.is_in(['htm', 'html'])].select
+finder = app('Finder')
+finder.activate
+folder = finder.Finder_windows[1].target.get
+folder.files[its.name_extension.is_in(['htm', 'html'])].select

data/sample/iTunes_top40_to_html.rb

@@ -40,7 +40,7 @@ END
 
 # Choose the file to write
 sa = OSAX.osax('StandardAdditions')
-out_file = sa.choose_file_name(:default_name=>'My iTunes Top 40.html')
+out_file = sa.choose_file_name(:default_name=>'My-iTunes-Top-40.html')
 
 # Get the played count, name and album for every track in iTunes
 tracks = app('iTunes').library_playlists[1].tracks
@@ -58,8 +58,11 @@ tmpl.prettyprint = true
 File.open(out_file.to_s, 'w') { |f| tmpl.expand(f, data) }
 
 # Open file in Safari for viewing
-safari = app('Safari')
-safari.activate
-safari.open(out_file)
+# safari = app('Safari')
+# safari.activate
+# safari.open(out_file)
+
+# Open file in default web browser for viewing
+sa.open_location(out_file.url)
 
 

data/src/lib/_aem/aemreference.rb

@@ -71,7 +71,7 @@ module AEMReference
 			@result = []
 		end
 		
-		def method_missing(name, *args)
+		def send(name, *args)
 			self.result.push([name] + args)
 			return self
 		end
@@ -182,8 +182,7 @@ module AEMReference
 		end
 		
 		def AEM_resolve(obj)
-			return @_container.AEM_resolve(obj).send(@_keyname)
-		end
+			return @_container.AEM_resolve(obj).send(@_keyname)		end
 	end
 	
 	
@@ -298,33 +297,33 @@ module AEMReference
 		# property represents a one-to-one relationship, e.g. textedit.documents[1].text.end is valid
 			
 		def start
-			return InsertionSpecifier.new(self, Beginning, 'start')
+			return InsertionSpecifier.new(self, Beginning, :start)
 		end
 		
 		def end
-			return InsertionSpecifier.new(self, End, 'end')
+			return InsertionSpecifier.new(self, End, :end)
 		end
 		
 		def before
-			return InsertionSpecifier.new(self, Before, 'before')
+			return InsertionSpecifier.new(self, Before, :before)
 		end
 		
 		def after
-			return InsertionSpecifier.new(self, After, 'after')
+			return InsertionSpecifier.new(self, After, :after)
 		end
 		
 		# Property and element references can be used on any type of object reference:
 		
-		def property(propertycode)
-			return Property.new(KAE::CProperty, self, propertycode)
+		def property(code)
+			return Property.new(KAE::CProperty, self, code)
 		end
 		
-		def userproperty(name)
+		def user_property(name)
 			return UserProperty.new(KAE::CProperty, self, name)
 		end
 		
-		def elements(elementcode)
-			return AllElements.new(elementcode, self)
+		def elements(code)
+			return AllElements.new(code, self)
 		end
 	
 		# Relative position references
@@ -333,12 +332,12 @@ module AEMReference
 		# simplifies the class structure a bit. As with all reference forms, it's mostly left to the client to
 		# ensure the references they construct can be understood by the target application.
 		
-		def previous(elementcode)
-			return ElementByRelativePosition.new(elementcode, self, Previous, 'previous')
+		def previous(code)
+			return ElementByRelativePosition.new(code, self, Previous, :previous)
 		end
 		
-		def next(elementcode)
-			return ElementByRelativePosition.new(elementcode, self, Next, 'next')
+		def next(code)
+			return ElementByRelativePosition.new(code, self, Next, :next)
 		end
 	end
 	
@@ -352,7 +351,7 @@ module AEMReference
 
 		# Syntax: ref.property(code)
 			
-		By = 'property'
+		By = :property
 		KeyForm = AEMReference.pack_enum(KAE::FormPropertyID)
 		
 		def _pack_key(codecs)
@@ -360,7 +359,7 @@ module AEMReference
 		end
 		
 		def AEM_resolve(obj)
-			return @_container.AEM_resolve(obj).property(@_key)
+			return @_container.AEM_resolve(obj).send(:property, @_key)
 		end
 	end
 	
@@ -371,17 +370,17 @@ module AEMReference
 		# Scriptable applications shouldn't use this reference form, but OSA script applets can.
 		# Note that OSA languages may have additional rules regarding case sensitivity/conversion.
 	
-		# Syntax: ref.userproperty(name)
+		# Syntax: ref.user_property(name)
 	
-		By = 'userproperty'
-		KeyForm = AEMReference.pack_enum('usrp')
+		By = :user_property
+		KeyForm = AEMReference.pack_enum(KAE::FormUserPropertyID)
 		
 		def _pack_key(codecs)
 			return codecs.pack(@_key).coerce(KAE::TypeChar)
 		end
 		
 		def AEM_resolve(obj)
-			return @_container.AEM_resolve(obj).userproperty(@_key)
+			return @_container.AEM_resolve(obj).send(:user_property, @_key)
 		end
 	end
 	
@@ -417,7 +416,7 @@ module AEMReference
 		
 		# Syntax: elements_ref.by_name(string)
 		
-		By = 'by_name'
+		By = :by_name
 		KeyForm = AEMReference.pack_enum(KAE::FormName)
 	end
 	
@@ -429,7 +428,7 @@ module AEMReference
 		
 		# Note that a few apps (e.g. Finder) may allow other values as well (e.g. Aliases/FSRefs)
 		
-		By = 'by_index'
+		By = :by_index
 		KeyForm = AEMReference.pack_enum(KAE::FormAbsolutePosition)
 	end
 	
@@ -439,7 +438,7 @@ module AEMReference
 		
 		# Syntax: elements_ref.by_id(anything)
 		
-		By = 'by_id'
+		By = :by_id
 		KeyForm = AEMReference.pack_enum(KAE::FormUniqueID)
 	end
 	
@@ -511,19 +510,19 @@ module AEMReference
 		Any = AEMReference.pack_absolute_ordinal(KAE::KAEAny)
 		
 		def first
-			return ElementByOrdinal.new(@AEM_want, self, First, 'first')
+			return ElementByOrdinal.new(@AEM_want, self, First, :first)
 		end
 		
 		def middle
-			return ElementByOrdinal.new(@AEM_want, self, Middle, 'middle')
+			return ElementByOrdinal.new(@AEM_want, self, Middle, :middle)
 		end
 		
 		def last
-			return ElementByOrdinal.new(@AEM_want, self, Last, 'last')
+			return ElementByOrdinal.new(@AEM_want, self, Last, :last)
 		end
 		
 		def any
-			return ElementByOrdinal.new(@AEM_want, self, Any, 'any')
+			return ElementByOrdinal.new(@AEM_want, self, Any, :any)
 		end
 		
 		def by_name(name)
@@ -542,8 +541,8 @@ module AEMReference
 			return ElementsByRange.new(@AEM_want, self, [start, stop])
 		end
 		
-		def by_filter(expression)
-			return ElementsByFilter.new(@AEM_want, self, expression)
+		def by_filter(test)
+			return ElementsByFilter.new(@AEM_want, self, test)
 		end
 	end
 	
@@ -581,7 +580,7 @@ module AEMReference
 		end
 		
 		def AEM_resolve(obj)
-			return @_container.AEM_resolve(obj).by_range(*@_key)
+			return @_container.AEM_resolve(obj).send(:by_range, *@_key)
 		end
 	end
 	
@@ -617,7 +616,7 @@ module AEMReference
 		end
 		
 		def AEM_resolve(obj)
-			return @_container.AEM_resolve(obj).by_filter(@_key)
+			return @_container.AEM_resolve(obj).send(:by_filter, @_key)
 		end
 	end
 	
@@ -721,7 +720,7 @@ module AEMReference
 		end
 		
 		def AEM_resolve(obj)
-			return @_container.AEM_resolve(obj).elements(@AEM_want)
+			return @_container.AEM_resolve(obj).send(:elements, @AEM_want)
 		end
 	end
 	
@@ -819,22 +818,22 @@ module AEMReference
 	
 	
 	class GreaterThan < ComparisonTest
-		Name = 'gt'
+		Name = :gt
 		Operator = AEMReference.pack_enum(KAE::KAEGreaterThan)
 	end
 	
 	class GreaterOrEquals < ComparisonTest
-		Name = 'ge'
+		Name = :ge
 		Operator = AEMReference.pack_enum(KAE::KAEGreaterThanEquals)
 	end
 	
 	class Equals < ComparisonTest
-		Name = 'eq'
+		Name = :eq
 		Operator = AEMReference.pack_enum(KAE::KAEEquals)
 	end
 	
 	class NotEquals < Equals
-		Name = 'ne'
+		Name = :ne
 		OperatorNOT = AEMReference.pack_enum(KAE::KAENOT)
 		
 		def AEM_pack_self(codecs)
@@ -843,32 +842,32 @@ module AEMReference
 	end
 	
 	class LessThan < ComparisonTest
-		Name = 'lt'
+		Name = :lt
 		Operator = AEMReference.pack_enum(KAE::KAELessThan)
 	end
 	
 	class LessOrEquals < ComparisonTest
-		Name = 'le'
+		Name = :le
 		Operator = AEMReference.pack_enum(KAE::KAELessThanEquals)
 	end
 	
 	class StartsWith < ComparisonTest
-		Name = 'starts_with'
+		Name = :starts_with
 		Operator = AEMReference.pack_enum(KAE::KAEBeginsWith)
 	end
 	
 	class EndsWith < ComparisonTest
-		Name = 'ends_with'
+		Name = :ends_with
 		Operator = AEMReference.pack_enum(KAE::KAEEndsWith)
 	end
 	
 	class Contains < ComparisonTest
-		Name = 'contains'
+		Name = :contains
 		Operator = AEMReference.pack_enum(KAE::KAEContains)
 	end
 	
 	class IsIn < Contains
-		Name = 'is_in'
+		Name = :is_in
 	
 		def AEM_pack_self(codecs)
 			return AEMReference.pack_list_as(KAE::TypeCompDescriptor, [
@@ -911,24 +910,24 @@ module AEMReference
 	
 	class AND < LogicalTest
 		Operator = AEMReference.pack_enum(KAE::KAEAND)
-		Name = 'and'
+		Name = :and
 	end
 	
 	class OR < LogicalTest
 		Operator = AEMReference.pack_enum(KAE::KAEOR)
-		Name = 'or'
+		Name = :or
 	end
 	
 	class NOT < LogicalTest
 		Operator = AEMReference.pack_enum(KAE::KAENOT)
-		Name = 'not'
+		Name = :not
 			
 		def to_s
 			return "#{@_operands[0].inspect}.not"
 		end
 		
 		def AEM_resolve(obj)
-			return @_operands[0].AEM_resolve(obj).not
+			return @_operands[0].AEM_resolve(obj).send(:not)
 		end
 	end
 	
@@ -971,7 +970,7 @@ module AEMReference
 		
 		# Syntax: app
 		
-		Name = 'app'
+		Name = :app
 		Type = AE::AEDesc.new(KAE::TypeNull, '')
 	end
 	
@@ -981,7 +980,7 @@ module AEMReference
 		
 		# Syntax: con
 		
-		Name = 'con'
+		Name = :con
 		Type = AE::AEDesc.new(KAE::TypeCurrentContainer, '')
 	end
 	
@@ -991,7 +990,7 @@ module AEMReference
 		
 		# Syntax: its
 		
-		Name = 'its'
+		Name = :its
 		Type = AE::AEDesc.new(KAE::TypeObjectBeingExamined, '')
 	end