castanaut 1.0.0 → 1.1.0

data/History.txt

@@ -1,3 +1,14 @@
-== 1.0.0 / 2008-02-21
+== 1.1.0 / 2010-02-26
+
+* Replaced the gem/rubyforge packaging cruft with a gemspec and rake task.
+* IRB support (see README). [metavida / joseph]
+* Added click_menu_item function. [topfunky]
+* Added basic TextMate plugin. Name is textmate to comply with Castanaut
+    expectations. [topfunky]
+* Added wait_for_element method [metavida]
+* Added perform method for organization. [topfunky]
+* Keystroke method using special keys if necessary. [jlsync / topfunky]
+
+=== 1.0.0 / 2008-02-21
 
 * Initial release.

data/README.txt

@@ -5,16 +5,16 @@
 
 == DESCRIPTION:
 
-Castanaut lets you write executable scripts for your screencasts. With a 
-simple dictionary of stage directions, you can create complex interactions 
-with a variety of applications. Currently, and for the foreseeable future, 
+Castanaut lets you write executable scripts for your screencasts. With a
+simple dictionary of stage directions, you can create complex interactions
+with a variety of applications. Currently, and for the foreseeable future,
 Castanaut supports Mac OS X 10.5 only.
 
 == SYNOPSIS:
 
 === Writing screenplays
 
-You write your screenplays as Ruby files. Castanaut has been designed to 
+You write your screenplays as Ruby files. Castanaut has been designed to
 read fairly naturally to the non-technical, within Ruby's constraints.
 
 Here's a simple screenplay:
@@ -31,12 +31,12 @@ Here's a simple screenplay:
   say "I drew a square!"
 
 With any luck we don't need to explain to you what this screenplay
-does. The only thing that might need some explanation is "say" -- this has a 
-robotic voice speak the given string. (Also: all numbers are pixel 
+does. The only thing that might need some explanation is "say" -- this has a
+robotic voice speak the given string. (Also: all numbers are pixel
 co-ordinates).
 
 About the robot: no, we don't recommend you use this in real screencasts for
-a large audience. Most people find it a little offputting.  
+a large audience. Most people find it a little offputting.
 You are free to contravene our recommendation though. You
 can tweak the robot in the Mac OS X Speech Preferences pane.
 
@@ -46,7 +46,7 @@ Simply give the screenplay to the castanaut command, like this:
 
   castanaut test.screenplay
 
-This assumes you have a screenplay file called "test.screenplay" in the 
+This assumes you have a screenplay file called "test.screenplay" in the
 directory where you are running the command.
 
 Of course, it isn't always convenient to drop to the terminal to run your
@@ -57,7 +57,7 @@ You need to add this line (the "shebang" line) at the top of your screenplay:
 
 Then you need to set the screenplay to be executable by running this command
 on it:
-  
+
   chmod a+x test.screenplay
 
 Again, substitute "test.screenplay" for your screenplay's filename.
@@ -68,25 +68,38 @@ it with Quicksilver, or run it any other way that floats your boat.
 === Stopping the screenplay
 
 If you want to abruptly terminate execution before the end of the screenplay,
-you just need to run the 'castanaut' command again -- with or without any 
+you just need to run the 'castanaut' command again -- with or without any
 arguments.
 
-Of course, that might be easier said than done, if you haven't got full 
+Of course, that might be easier said than done, if you haven't got full
 control of the mouse or keyboard at the time. One recommendation is to assign
 a system hot-key to invoke castanaut. I use a Quicksilver trigger for this,
 assigned to Shift-F1, that calls castanaut. You'll need the full path to
-the command for this, which is usually /usr/bin/castanaut, but you can check 
+the command for this, which is usually /usr/bin/castanaut, but you can check
 it with the following command:
 
   which "castanaut"
 
+=== Running interactively with IRB
+
+You can now run Castanaut interactively from IRB — to test commands, try stuff
+out, etc:
+
+    $ irb -r 'castanaut'
+    >> irb Castanaut::Movie.spawn
+    >> move to(100, 100)
+    => "Moving mouse.\n"
+
+Note that this technique creates an IRB subsession, so you'll have to exit out
+of that before exiting out of IRB. There's heaps you can do with subsessions -
+read up about them online.
 
 === What stage directions can I make?
 
 Out of the box, Castanaut performs mouse actions, keyboard actions,
 robot speech and application launches.
 
-For a complete overview of the built-in stage directions, see the 
+For a complete overview of the built-in stage directions, see the
 Castanaut::Movie class.
 
 === Using plugins
@@ -96,9 +109,12 @@ and verbose. Plugins allow you to extend the available dictionary with
 some additional convenience actions. Typically a plugin is specific to an
 application.
 
-Castanaut comes with several plugins, including Castanaut::Plugin::Safari for
-interacting with the contents of web-pages, and Castanaut::Plugin::Ishowu for
-recording screencasts using the iShowU application from Shiny White Box.
+Castanaut comes with several plugins, including
+
+* Castanaut::Plugin::Safari for interacting with the contents of web-pages
+* Castanaut::Plugin::Ishowu for recording screencasts using the iShowU
+  application from Shiny White Box.
+* Castanaut::Plugin::Textmate for opening files to specific line numbers.
 
 To use a plugin, simply declare it:
 
@@ -114,7 +130,7 @@ To use a plugin, simply declare it:
   click
   pause 4
   say "Oh. I was hoping for more results."
-  
+
 
 In the example above, we use the two methods provided by the Safari module:
 url, which causes Safari to navigate to the given url, and to_element, which
@@ -123,7 +139,7 @@ the screen.
 
 === Creating your own plugins
 
-Advanced users can create their own plugins. Put them in a directory 
+Advanced users can create their own plugins. Put them in a directory
 called "plugins" below the directory containing the screenplays that use
 the plugin.
 
@@ -134,12 +150,19 @@ your own.
 
 * Mac OS X 10.5
 
+or
+
+* Mac OS X 10.4
+* The Extras Suite application <http://www.kanzu.com/main.html#extrasuites>
+
 == INSTALL:
 
 Run the following command to install Castanaut
 
   sudo gem install castanaut
 
+If you're using Mac OS X 10.4 (Tiger) you will also need to download and install the XTool scripting additions.
+
 Once installed, you should run the following command for two reasons:
 
   castanaut

data/lib/castanaut/exceptions.rb

@@ -1,7 +1,7 @@
 module Castanaut
   # All Castanaut errors are defined within this module. If you are creating
-  # a plugin, you should re-open this module in your plugin script file to 
-  # add any plugin-specific exceptions (it's also a good idea to have them 
+  # a plugin, you should re-open this module in your plugin script file to
+  # add any plugin-specific exceptions (it's also a good idea to have them
   # descend from CastanautError).
   module Exceptions
     # The abstract parent class of all Castanaut errors.
@@ -13,7 +13,7 @@ module Castanaut
     class ScreenplayNotFound < CastanautError
     end
 
-    # If Castanaut::Movie#run sees a non-zero exit status from the shell 
+    # If Castanaut::Movie#run sees a non-zero exit status from the shell
     # process, this error will be raised.
     class ExternalActionError < CastanautError
     end
@@ -28,5 +28,16 @@ module Castanaut
     # this exception.
     class OSXAutomationPermissionError < CastanautError
     end
+
+    # Raised within Compatibility layers if the  requested method or options are
+    # not supported by the current operating system.
+    class NotSupportedError < CastanautError
+    end
+
+    # Allows you to skip the rest of a perform block (therefore usually
+    # raised if some condition fails). See Movie#skip for the shorthand.
+    class SkipError < CastanautError
+    end
+
   end
 end

data/lib/castanaut/keys.rb

@@ -1,7 +1,7 @@
 module Castanaut
-  
+
   # Some standard keys (for use with 'hit'), presumably only for US keyboards.
-  
+
   #
   Return        = "0x24"
   Enter         = "0x4C"
@@ -14,6 +14,7 @@ module Castanaut
   CapsLock      = "0x39"
   Alt           = "0x3A"
   Ctrl          = "0x3B"
+  Command       = "0x37"
 
   LArrow        = "0x7B"
   RArrow        = "0x7C"

data/lib/castanaut/main.rb

@@ -5,13 +5,13 @@ module Castanaut
   class Main
 
     # If Castanaut is not running, this runs the movie specified as the first
-    # argument. If it *is* already running, this nixes the flag file, which 
+    # argument. If it *is* already running, this nixes the flag file, which
     # should cause Castanaut to stop.
     def self.run(args)
-      if File.exists?(Castanaut::FILE_RUNNING) 
+      if File.exists?(Castanaut::FILE_RUNNING)
         File.unlink(Castanaut::FILE_RUNNING)
       else
-        Castanaut::Movie.new(args.shift)
+        Castanaut::Movie.spawn(args.shift)
       end
     end