topfunky-castanaut 1.0.1

data/Copyright.txt

@@ -0,0 +1,29 @@
+== Castanaut
+
+Copyright (C) 2008 Inventive Labs.
+
+This program is free software. It comes without any warranty, to
+the extent permitted by applicable law. You can redistribute it
+and/or modify it under the terms of the Do What The Fuck You Want
+To Public License, Version 2, as published by Sam Hocevar. See
+http://sam.zoy.org/wtfpl/COPYING for more details.
+
+=== DomQuery
+
+The DomQuery implementation is included from the Ext JS distribution, which
+uses the MIT license requiring the following copyright and permission 
+notices. These pertain only to the script/gebys.js file.
+
+Copyright (c) 2006-2007 Ext JS, LLC.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.

data/History.txt

@@ -0,0 +1,9 @@
+=== 1.0.1 / 2008-09-10
+
+* Added click_menu_item function. [topfunky]
+* Added basic TextMate plugin. Name is textmate to comply with Castanaut expectations. [topfunky]
+* Added gemspec.
+
+=== 1.0.0 / 2008-02-21
+
+* Initial release.

data/Manifest.txt

@@ -0,0 +1,31 @@
+Copyright.txt
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/castanaut
+cbin/osxautomation
+lib/castanaut.rb
+lib/castanaut/exceptions.rb
+lib/castanaut/keys.rb
+lib/castanaut/main.rb
+lib/castanaut/movie.rb
+lib/castanaut/plugin.rb
+lib/plugins/ishowu.rb
+lib/plugins/mousepose.rb
+lib/plugins/safari.rb
+lib/plugins/textmate.rb
+scripts/coords.js
+scripts/gebys.js
+spec/castanaut_spec.rb
+spec/spec_helper.rb
+tasks/ann.rake
+tasks/annotations.rake
+tasks/doc.rake
+tasks/gem.rake
+tasks/manifest.rake
+tasks/post_load.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/spec.rake
+tasks/svn.rake

data/README.txt

@@ -0,0 +1,161 @@
+= Castanaut: Automate your screencasts.
+
+    Author: Joseph Pearson
+    http://gadgets.inventivelabs.com.au/castanaut
+
+== 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 supports Mac OS X 10.5 only.
+
+== SYNOPSIS:
+
+=== Writing screenplays
+
+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:
+
+  launch "Safari", at(10, 10, 800, 600)
+  type "http://www.inventivelabs.com.au"
+  hit Enter
+  pause 2
+  move to(100, 100)
+  move to(200, 100)
+  move to(200, 200)
+  move to(100, 200)
+  move to(100, 100)
+  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 
+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.  
+You are free to contravene our recommendation though. You
+can tweak the robot in the Mac OS X Speech Preferences pane.
+
+=== Running your screenplay
+
+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 
+directory where you are running the command.
+
+Of course, it isn't always convenient to drop to the terminal to run your
+screenplay. So there's also a method of executing your screenplays directly.
+You need to add this line (the "shebang" line) at the top of your screenplay:
+
+#!/usr/bin/env castanaut
+
+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.
+
+At this point, you should be able to double-click the screenplay, or invoke
+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 
+arguments.
+
+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 
+it with the following command:
+
+  which "castanaut"
+
+
+=== 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 
+Castanaut::Movie class.
+
+=== Using plugins
+
+Of course, just using the built-in stage directions is a little bit awkward
+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.
+
+To use a plugin, simply declare it:
+
+  plugin "safari"
+
+  launch "Safari", at(32, 32, 800, 600)
+  url "http://www.google.com"
+  pause 4
+  move to_element('input[name="q"]')
+  click
+  type "Castanaut"
+  move to_element('input[type="submit"]')
+  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
+returns the co-ordinates of a page element (using CSS selectors) relative to
+the screen.
+
+=== Creating your own plugins
+
+Advanced users can create their own plugins. Put them in a directory 
+called "plugins" below the directory containing the screenplays that use
+the plugin.
+
+Take a look at the plugins that Castanaut comes with for examples on creating
+your own.
+
+== REQUIREMENTS:
+
+* Mac OS X 10.5
+
+== INSTALL:
+
+Run the following command to install Castanaut
+
+  sudo gem install castanaut
+
+Once installed, you should run the following command for two reasons:
+
+  castanaut
+
+Reason 1 is to confirm that it is installed correctly. Reason 2 is to set up
+the permissions on the utility that controls your mouse and keyboard during
+Castanaut movies. You may be asked for a password here.
+
+If you just see a "ScreenplayNotFound" exception here, everything's good.
+
+== LICENSE:
+
+Copyright (C) 2008 Inventive Labs.
+
+Released under the WTFPL: http://sam.zoy.org/wtfpl.
+
+Portions released under the MIT License.
+
+See Copyright.txt for full licensing details.

data/Rakefile

@@ -0,0 +1,19 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/castanaut.rb'
+
+task :default => 'spec:run'
+
+Hoe.new('castanaut', Castanaut::VERSION) do |p|
+  p.developer('Joseph Pearson', 'joseph@inventivelabs.com.au')
+  p.description = "Automate your screencasts."
+  p.summary = "Automate your screencasts."
+  p.url = "http://castanaut.rubyforge.org"
+  p.remote_rdoc_dir = 'doc'
+  
+end
+
+# PROJ.exclude += ['^spec\/*', '^test\/*']
+# PROJ.spec_opts << '--color'

data/bin/castanaut

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(
+  File.join(File.dirname(__FILE__), '..', 'lib', 'castanaut')
+)
+
+Castanaut::Main.run ARGV

data/lib/castanaut.rb

@@ -0,0 +1,64 @@
+# $Id$
+
+# Equivalent to a header guard in C/C++
+# Used to prevent the class/module from being loaded more than once
+unless defined? Castanaut
+
+# The Castanaut module. For orienting yourself within the code, it's 
+# recommended you begin with the documentation for the Movie class, 
+# which is the big one. 
+#
+# Execution typically begins with the Main class.
+module Castanaut
+
+  # :stopdoc:
+  VERSION = '1.0.1'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+  FILE_RUNNING = "/tmp/castanaut.running"
+  FILE_APPLESCRIPT = "/tmp/castanaut.scpt"
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, *args)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, *args)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module Castanaut
+
+Castanaut.require_all_libs_relative_to __FILE__
+
+end  # unless defined?
+
+# EOF

data/lib/castanaut/exceptions.rb

@@ -0,0 +1,32 @@
+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 
+  # descend from CastanautError).
+  module Exceptions
+    # The abstract parent class of all Castanaut errors.
+    class CastanautError < RuntimeError
+    end
+
+    # Raised if Castanaut was invoked with no screenplay argument, or one
+    # pointing to a non-existent file.
+    class ScreenplayNotFound < CastanautError
+    end
+
+    # If Castanaut::Movie#run sees a non-zero exit status from the shell 
+    # process, this error will be raised.
+    class ExternalActionError < CastanautError
+    end
+
+    # If the FILE_RUNNING flag file is deleted or moved during the execution
+    # of a movie, it will terminate and raise this exception.
+    class AbortedByUser < CastanautError
+    end
+
+    # Despite asking for permission, the osxautomation utility in cbin cannot
+    # be executed. This is pretty fatal to our intentions, so we abort with
+    # this exception.
+    class OSXAutomationPermissionError < CastanautError
+    end
+  end
+end

data/lib/castanaut/keys.rb

@@ -0,0 +1,43 @@
+module Castanaut
+  
+  # Some standard keys (for use with 'hit'), presumably only for US keyboards.
+  
+  #
+  Return        = "0x24"
+  Enter         = "0x4C"
+  Tab           = "0x30"
+  Space         = "0x31"
+  Backspace     = "0x33"
+  Esc           = "0x35"
+
+  Shift         = "0x38"
+  CapsLock      = "0x39"
+  Alt           = "0x3A"
+  Ctrl          = "0x3B"
+
+  LArrow        = "0x7B"
+  RArrow        = "0x7C"
+  DArrow        = "0x7D"
+  UArrow        = "0x7E"
+
+  Insert        = "0x72"
+  Home          = "0x73"
+  PageUp        = "0x74"
+  Delete        = "0x75"
+  End           = "0x77"
+  PageDown      = "0x79"
+
+  F1            = "0x7A"
+  F2            = "0x78"
+  F3            = "0x63"
+  F4            = "0x76"
+  F5            = "0x60"
+  F6            = "0x61"
+  F7            = "0x62"
+  F8            = "0x64"
+  F9            = "0x65"
+  F10           = "0x6D"
+  F11           = "0x67"
+  F12           = "0x6F"
+
+end

data/lib/castanaut/main.rb

@@ -0,0 +1,20 @@
+module Castanaut
+
+  # When running the Castanaut library as an executable, this class manages
+  # the invocation of the user-specified screenplay.
+  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 
+    # should cause Castanaut to stop.
+    def self.run(args)
+      if File.exists?(Castanaut::FILE_RUNNING) 
+        File.unlink(Castanaut::FILE_RUNNING)
+      else
+        Castanaut::Movie.new(args.shift)
+      end
+    end
+
+  end
+
+end

data/lib/castanaut/movie.rb

@@ -0,0 +1,428 @@
+module Castanaut
+  # The movie class is the containing context within which screenplays are 
+  # invoked. It provides a number of basic stage directions for your 
+  # screenplays, and can be extended with plugins.
+  class Movie
+
+    # Runs the "screenplay", which is a file containing Castanaut instructions.
+    #
+    def initialize(screenplay)
+      perms_test
+
+      if !screenplay || !File.exists?(screenplay)
+        raise Castanaut::Exceptions::ScreenplayNotFound 
+      end
+      @screenplay_path = screenplay
+
+      File.open(FILE_RUNNING, 'w') {|f| f.write('')}
+
+      begin
+        # We run the movie in a separate thread; in the main thread we 
+        # continue to check the "running" file flag and kill the movie if 
+        # it is removed.
+        movie = Thread.new do
+          begin
+            eval(IO.read(@screenplay_path), binding)
+          rescue => e
+            @e = e
+          ensure
+            File.unlink(FILE_RUNNING) if File.exists?(FILE_RUNNING)
+          end
+        end
+
+        while File.exists?(FILE_RUNNING)
+          sleep 0.5
+          break unless movie.alive?
+        end
+
+        if movie.alive?
+          movie.kill
+          raise Castanaut::Exceptions::AbortedByUser
+        end
+
+        raise @e if @e
+      rescue => e
+        puts "ABNORMAL EXIT: #{e.message}\n" + e.backtrace.join("\n")
+      ensure
+        roll_credits
+        File.unlink(FILE_RUNNING) if File.exists?(FILE_RUNNING)
+      end
+    end
+
+    # Launch the application matching the string given in the first argument.
+    # (This resolution is handled by Applescript.)
+    #
+    # If the options hash is given, it should contain the co-ordinates for
+    # the window (top, left, width, height). The to method will format these
+    # co-ordinates appropriately.
+    #
+    def launch(app_name, *options)
+      options = combine_options(*options)
+
+      ensure_window = ""
+      case app_name.downcase
+        when "safari"
+          ensure_window = "if (count(windows)) < 1 then make new document"
+      end
+
+      positioning = ""
+      if options[:to]
+        pos = "#{options[:to][:left]}, #{options[:to][:top]}"
+        dims = "#{options[:to][:left] + options[:to][:width]}, " +
+          "#{options[:to][:top] + options[:to][:height]}"
+        if options[:to][:width]
+          positioning = "set bounds of front window to {#{pos}, #{dims}}"
+        else
+          positioning = "set position of front window to {#{pos}}"
+        end
+      end
+
+      execute_applescript(%Q`
+        tell application "#{app_name}"
+          activate
+          #{ensure_window}
+          #{positioning}
+        end tell
+      `)
+    end
+
+    # Move the mouse cursor to the specified co-ordinates.
+    #
+    def cursor(*options)
+      options = combine_options(*options)
+      apply_offset(options)
+      @cursor_loc ||= {}
+      @cursor_loc[:x] = options[:to][:left]
+      @cursor_loc[:y] = options[:to][:top]
+      automatically "mousemove #{@cursor_loc[:x]} #{@cursor_loc[:y]}"
+    end
+
+    alias :move :cursor
+
+    # Send a mouse-click at the current mouse location.
+    #
+    def click(btn = 'left')
+      automatically "mouseclick #{mouse_button_translate(btn)}"
+    end
+
+    # Send a double-click at the current mouse location.
+    #
+    def doubleclick(btn = 'left')
+      automatically "mousedoubleclick #{mouse_button_translate(btn)}"
+    end
+    
+    # Send a triple-click at the current mouse location.
+    # 
+    def tripleclick(btn = 'left')
+      automatically "mousetripleclick #{mouse_button_translate(btn)}"
+    end
+
+    # Press the button down at the current mouse location. Does not 
+    # release the button until the mouseup method is invoked.
+    #
+    def mousedown(btn = 'left')
+      automatically "mousedown #{mouse_button_translate(btn)}"
+    end
+
+    # Releases the mouse button pressed by a previous mousedown.
+    #
+    def mouseup(btn = 'left')
+      automatically "mouseup #{mouse_button_translate(btn)}"
+    end
+
+    # "Drags" the mouse by (effectively) issuing a mousedown at the current 
+    # mouse location, then moving the mouse to the specified coordinates, then
+    # issuing a mouseup.
+    #
+    def drag(*options)
+      options = combine_options(*options)
+      apply_offset(options)
+      automatically "mousedrag #{options[:to][:left]} #{options[:to][:top]}"
+    end
+
+    # Sends the characters into the active control in the active window.
+    #
+    def type(str)
+      automatically "type #{str}"
+    end
+
+    # Sends the keycode (a hex value) to the active control in the active 
+    # window. For more about keycode values, see Mac Developer documentation.
+    #
+    def hit(key)
+      automatically "hit #{key}"
+    end
+
+    # Don't do anything for the specified number of seconds (can be portions
+    # of a second).
+    #
+    def pause(seconds)
+      sleep seconds
+    end
+
+    # Use Leopard's native text-to-speech functionality to emulate a human
+    # voice saying the narrative text.
+    #
+    def say(narrative)
+      run(%Q`say "#{escape_dq(narrative)}"`)
+    end
+    
+    ##
+    # Click a menu item in any application.
+    #
+    # The name of the application should be the first argument.
+    #
+    # Three dots will be automatically replaced by the appropriate ellipsis.
+    #
+    #   click_menu_item("TextMate", "Navigation", "Go to Symbol...")
+    
+    def click_menu_item(*items)
+      items_as_applescript_array = items.map {|i| i.gsub!('...', "…"); %("#{i}")}.join(", ")
+      ascript = %Q(
+      -- menu_click, by Jacob Rus, September 2006
+      -- http://www.macosxhints.com/article.php?story=20060921045743404
+      -- 
+      -- Accepts a list of form: `{"Finder", "View", "Arrange By", "Date"}`
+      -- Execute the specified menu item.  In this case, assuming the Finder 
+      -- is the active application, arranging the frontmost folder by date.
+
+      on menu_click(mList)
+      	local appName, topMenu, r
+
+      	-- Validate our input
+      	if mList's length < 3 then error "Menu list is not long enough"
+
+      	-- Set these variables for clarity and brevity later on
+      	set {appName, topMenu} to (items 1 through 2 of mList)
+      	set r to (items 3 through (mList's length) of mList)
+
+      	-- This overly-long line calls the menu_recurse function with
+      	-- two arguments: r, and a reference to the top-level menu
+      	tell application "System Events" to my menu_click_recurse(r, ((process appName)'s ¬
+      		(menu bar 1)'s (menu bar item topMenu)'s (menu topMenu)))
+      end menu_click
+
+      on menu_click_recurse(mList, parentObject)
+      	local f, r
+
+      	-- `f` = first item, `r` = rest of items
+      	set f to item 1 of mList
+      	if mList's length > 1 then set r to (items 2 through (mList's length) of mList)
+
+      	-- either actually click the menu item, or recurse again
+      	tell application "System Events"
+      		if mList's length is 1 then
+      			click parentObject's menu item f
+      		else
+      			my menu_click_recurse(r, (parentObject's (menu item f)'s (menu f)))
+      		end if
+      	end tell
+      end menu_click_recurse
+
+
+      menu_click({#{items_as_applescript_array}})
+      )
+      execute_applescript(ascript)
+    end
+
+    ##
+    # Warning: FLAKY
+    #
+    # Hit a command key combo.
+    #
+    # Use lowercase for normal, or uppercase if shift should be used also.
+    #
+    # Option and Ctrl aren't currently supported.
+    
+    def keystroke(character)
+      execute_applescript(%Q'
+    	  tell application "System Events"
+    		  keystroke "#{character}"
+    	  end tell    
+      ')
+    end
+    
+    # Starts saying the narrative text, and simultaneously begins executing
+    # the given block. Waits until both are finished.
+    #
+    def while_saying(narrative)
+      if block_given?
+        fork { say(narrative) }
+        yield
+        Process.wait
+      else
+        say(narrative)
+      end
+    end
+
+    # Get a hash representing specific screen co-ordinates. Use in combination
+    # with cursor, drag, launch, and similar methods.
+    #
+    def to(l, t, w = nil, h = nil)
+      result = {
+        :to => {
+          :left => l,
+          :top => t
+        }
+      }
+      result[:to][:width] = w if w
+      result[:to][:height] = h if h
+      result
+    end
+
+    alias :at :to
+
+    # Get a hash representing specific screen co-ordinates *relative to the
+    # current mouse location.
+    #
+    def by(x, y)
+      unless @cursor_loc
+        @cursor_loc = automatically("mouselocation").strip.split(' ')
+        @cursor_loc = {:x => @cursor_loc[0].to_i, :y => @cursor_loc[1].to_i}
+      end
+      to(@cursor_loc[:x] + x, @cursor_loc[:y] + y)
+    end
+
+    # The result of this method can be added +to+ a co-ordinates hash, 
+    # offsetting the top and left values by the given margins.
+    #
+    def offset(x, y)
+      { :offset => { :x => x, :y => y } }
+    end
+
+
+    # Returns a region hash describing the entire screen area. (May be wonky
+    # for multi-monitor set-ups.)
+    #
+    def screen_size
+      coords = execute_applescript(%Q`
+        tell application "Finder"
+            get bounds of window of desktop
+        end tell
+      `)
+      coords = coords.split(", ").collect {|c| c.to_i}
+      to(*coords)
+    end
+
+    # Runs a shell command, performing fairly naive (but effective!) exit 
+    # status handling. Returns the stdout result of the command.
+    #
+    def run(cmd)
+      #puts("Executing: #{cmd}")
+      result = `#{cmd}`
+      raise Castanaut::Exceptions::ExternalActionError if $?.exitstatus > 0
+      result
+    end
+  
+    # Adds custom methods to this movie instance, allowing you to perform
+    # additional actions. See the README.txt for more information.
+    #
+    def plugin(str)
+      str.downcase!
+      begin
+        require File.join(File.dirname(@screenplay_path),"plugins","#{str}.rb")
+      rescue LoadError
+        require File.join(LIBPATH, "plugins", "#{str}.rb")
+      end
+      extend eval("Castanaut::Plugin::#{str.capitalize}")
+    end
+
+    # Loads a script from a file into a string, looking first in the
+    # scripts directory beneath the path where Castanaut was executed,
+    # and falling back to Castanaut's gem path.
+    #
+    def script(filename)
+      @cached_scripts ||= {}
+      unless @cached_scripts[filename]
+        fpath = File.join(File.dirname(@screenplay_path), "scripts", filename)
+        scpt = nil
+        if File.exists?(fpath)
+          scpt = IO.read(fpath)
+        else
+          scpt = IO.read(File.join(PATH, "scripts", filename))
+        end
+        @cached_scripts[filename] = scpt
+      end
+
+      @cached_scripts[filename]
+    end
+
+    # This stage direction is slightly different to the other ones. It collects
+    # a set of directions to be executed when the movie ends, or when it is
+    # aborted by the user. Mostly, it's used for cleaning up stuff. Here's
+    # an example:
+    #
+    #   ishowu_start_recording
+    #   at_end_of_movie do
+    #     ishowu_stop_recording
+    #   end
+    #   move to(100, 100) # ... et cetera
+    #
+    # You can use this multiple times in your screenplay -- remember that if
+    # the movie is aborted by the user before this direction is used, its
+    # contents won't be executed. So in general, create an at_end_of_movie
+    # block after every action that you want to revert (like in the example
+    # above).
+    def at_end_of_movie(&blk)
+      @end_credits ||= []
+      @end_credits << blk
+    end
+
+    protected
+      def execute_applescript(scpt)
+        File.open(FILE_APPLESCRIPT, 'w') {|f| f.write(scpt)}
+        result = run("osascript #{FILE_APPLESCRIPT}")
+        File.unlink(FILE_APPLESCRIPT)
+        result
+      end
+
+      def automatically(cmd)
+        run("#{osxautomation_path} \"#{cmd}\"")
+      end
+
+      def escape_dq(str)
+        str.gsub(/\\/,'\\\\\\').gsub(/"/, '\"')
+      end
+
+      def combine_options(*args)
+        options = args.inject({}) { |result, option| result.update(option) }
+      end
+
+    private
+      def osxautomation_path
+        File.join(PATH, "cbin", "osxautomation")
+      end
+
+      def perms_test
+        return if File.executable?(osxautomation_path)
+        puts "IMPORTANT: Castanaut has recently been installed or updated. " +
+          "You need to give it the right to control mouse and keyboard " +
+          "input during screenplays."
+
+        run("sudo chmod a+x #{osxautomation_path}")
+
+        if File.executable?(osxautomation_path)
+          puts "Permission granted. Thanks."
+        else
+          raise Castanaut::Exceptions::OSXAutomationPermissionError
+        end
+      end
+
+      def apply_offset(options)
+        return unless options[:to] && options[:offset]
+        options[:to][:left] += options[:offset][:x] || 0
+        options[:to][:top] += options[:offset][:y] || 0
+      end
+
+      def mouse_button_translate(btn)
+        return btn if btn.is_a?(Integer)
+        {"left" => 1, "right" => 2, "middle" => 3}[btn]
+      end
+
+      def roll_credits
+        return unless @end_credits && @end_credits.any?
+        @end_credits.each {|credit| credit.call}
+      end
+      
+  end
+end