castanaut 1.0.0

data/lib/castanaut/movie.rb

@@ -0,0 +1,353 @@
+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
+
+    # 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

data/lib/castanaut/plugin.rb

@@ -0,0 +1,26 @@
+module Castanaut
+
+  # Castanaut uses plugins to extend the available actions beyond simple
+  # mouse and keyboard input. Typically each plugin is application-specific.
+  # See the Safari, Mousepose and Ishowu plugins for examples, and review the
+  # README.txt for details on creating your own.
+  #
+  # In short, for a plugin called "foo", your script should have this structure:
+  #
+  #   module Castanaut
+  #     module Plugin
+  #       module Foo
+  #
+  #         # define your stage directions (ie, Movie instance methods) here.
+  #
+  #       end
+  #     end
+  #   end
+  #     
+  # The script must exist in a sub-directory of the screenplay's location 
+  # called "plugins", and must be called (in this case): foo.rb.
+  #
+  module Plugin
+  end
+
+end

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.0'
+  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/plugins/ishowu.rb

@@ -0,0 +1,94 @@
+module Castanaut; module Plugin
+  
+  # This module provides primitive support for iShowU, a screencast capturing
+  # tool for Mac OS X from Shiny White Box.
+  #
+  # iShowU is widely considered a good, simple application for its purpose,
+  # but you're by no means required to use it for Castanaut. Simply write
+  # your own module for Snapz Pro, or ScreenFlow, or whatever you like.
+  #
+  # Shiny White Box is promising much better Applescript support in an 
+  # imminent version, which could tidy up this module quite a bit.
+  #
+  # More info: http://www.shinywhitebox.com/home/home.html
+  module Ishowu
+
+    # Set the screencast to capture a particular region of the screen.
+    # Generate appropriately-formatted co-ordinates using Castanaut::Movie#to.
+    def ishowu_set_region(*options)
+      ishowu_applescriptify
+
+      options = combine_options(*options)
+
+      ishowu_menu_item("Capture", "Capture full screen")
+      sleep(0.2)
+      ishowu_menu_item("Capture", "Capture custom area", false)
+      sleep(0.2)
+      automatically "mousewarp 4 4"
+
+      drag to(options[:to][:left], options[:to][:top])
+
+      sleep(0.2)
+      bounds = screen_size
+      automatically "mousewarp #{bounds[:to][:width]} #{bounds[:to][:height]}"
+      drag to(
+        options[:to][:left] + options[:to][:width],
+        options[:to][:top] + options[:to][:height]
+      )
+      hit Enter
+      ishowu_hide
+    end
+
+    # Tell iShowU to start recording. Will automatically stop recording when
+    # the movie is ended, unless you set :auto_stop => false in options.
+    def ishowu_start_recording(options = {})
+      ishowu_hide
+      ishowu_menu_item("Capture", "Start capture")
+      unless options[:auto_stop] == false
+        at_end_of_movie { ishowu_stop_recording }
+      end
+    end
+
+    # Tell iShowU to stop recording.
+    def ishowu_stop_recording
+      ishowu_menu_item("Capture", "Stop capture")
+    end
+
+    # Execute an iShowU menu option.
+    def ishowu_menu_item(menu, item, quiet = true)
+      ascript = %Q`
+        tell application "iShowU"
+          activate
+          tell application "System Events"
+            click menu item "#{item}" of menu "#{menu}" of menu bar item "#{menu}" of menu bar 1 of process "iShowU"
+          #{'set visible of process "iShowU" to false' if quiet}
+          end tell
+        end
+      `
+      execute_applescript(ascript)
+    end
+
+    # Hide the iShowU window. This is a bit random, and suggestions are 
+    # welcomed.
+    def ishowu_hide
+      ishowu_menu_item("iShowU", "Hide iShowU")
+    end
+
+    private
+    # iShowU is not Applescript-enabled out of the box. This fix, arguably
+    # a hack, lets us do some limited work with it in Applescript.
+    def ishowu_applescriptify
+      execute_applescript(%Q`
+        try
+        tell application "Finder"
+          set the a_app to (application file id "com.tcdc.Digitizer") as alias
+        end tell
+        set the plist_filepath to the quoted form of ¬
+        ((POSIX path of the a_app) & "Contents/Info")
+        do shell script "defaults write " & the plist_filepath & space ¬
+        & "NSAppleScriptEnabled -bool YES"
+        end try
+      `)
+    end
+  end
+end; end

data/lib/plugins/mousepose.rb

@@ -0,0 +1,38 @@
+module Castanaut; module Plugin
+
+  # This module provides actions for controlling Mousepose, a commercial
+  # application from Boinx Software. Basically it lets you put a halo around
+  # the mouse whenever a key mouse action occurs.
+  #
+  # It doesn't do any configuration of Mousepose on the fly. Configure 
+  # Mousepose settings before running your screenplay.
+  #
+  # Tested against Mousepose 2. More info: http://www.boinx.com/mousepose
+  module Mousepose
+
+    # Put a halo around the mouse. If a block is given to this method,
+    # the halo will be turned off when the block completes. Otherwise,
+    # you'll have to use dim to dismiss the halo.
+    def highlight
+      execute_applescript(%Q`
+        tell application "Mousepose"
+          start effect
+        end
+      `)
+      if block_given?
+        yield
+        dim
+      end
+    end
+
+    # Dismiss the halo around the mouse that was invoked by a previous
+    # highlight method.
+    def dim
+      execute_applescript(%Q`
+        tell application "Mousepose"
+          stop effect
+        end
+      `)
+    end
+  end
+end; end

data/lib/plugins/safari.rb

@@ -0,0 +1,124 @@
+module Castanaut
+
+  module Plugin
+    # This module provides actions for controlling Safari. It's tested against
+    # Safari 3 on Mac OS X 10.5.2.
+    module Safari
+
+      # Open a URL in the front Safari tab.
+      def url(str)
+        execute_applescript(%Q`
+          tell application "safari" 
+            do JavaScript "location.href = '#{str}'" in front document 
+          end tell
+        `)
+      end
+
+      # Get the co-ordinates of an element in the front Safari tab. Use this
+      # with Castanaut::Movie#cursor to send the mouse cursor to the element.
+      #
+      # Options include:
+      # * :index - an integer (*n*) that gets the *n*th element matching the 
+      #   selector. Defaults to the first element.
+      # * :area - whereabouts in the element do you want the coordinates. 
+      #   Valid values are: left, center, right, and top, middle, bottom. 
+      #   Defaults to ["center", "middle"].
+      #   If single axis is given (eg "left"), the other axis uses its default.
+      def to_element(selector, options = {})
+        pos = options.delete(:area)
+        coords = element_coordinates(selector, options)
+
+        x_axis, y_axis = [:center, :middle]
+        [pos].flatten.first(2).each do |p|
+          p = p.to_s.downcase
+          x_axis = p.to_sym if %w[left center right].include?(p)
+          y_axis = p.to_sym if %w[top middle bottom].include?(p)
+        end
+        
+        edge_offset = options[:edge_offset] || 3
+        case x_axis
+          when :left
+            x = coords[0] + edge_offset
+          when :center
+            x = (coords[0] + coords[2] * 0.5).to_i 
+          when :right
+            x = (coords[0] + coords[2]) - edge_offset
+        end
+
+        case y_axis
+          when :top
+            y = coords[1] + edge_offset
+          when :middle
+            y = (coords[1] + coords[3] * 0.5).to_i
+          when :bottom
+            y = (coords[1] + coords[3]) - edge_offset
+        end
+
+        result = { :to => { :left => x, :top => y } }
+      end
+
+      private
+        # Note: the script should set the Castanaut.result variable.
+        def execute_javascript(scpt)
+          execute_applescript %Q`
+            tell application "Safari"
+              do JavaScript "
+                document.oldTitle = document.title;
+                #{escape_dq(scpt)}
+                if (typeof Castanaut.result != 'undefined') {
+                  document.title = Castanaut.result;
+                }
+              " in front document
+              set the_result to ((name of window 1) as string)
+              do JavaScript "
+                document.title = document.oldTitle;
+              " in front document
+              return the_result
+            end tell
+          `
+        end
+
+        def element_coordinates(selector, options = {})
+          index = options[:index] || 0
+          gebys = script('gebys.js')
+          cjs = script('coords.js')
+          coords = execute_javascript(%Q`
+            #{gebys}
+            #{cjs}
+            Castanaut.result = Castanaut.Coords.forElement(
+              '#{selector}',
+              #{index}
+            );
+          `)
+
+          unless coords.match(/\d+ \d+ \d+ \d+/)
+            raise Castanaut::Exceptions::ElementNotFound
+          end
+
+          coords = coords.split(' ').collect {|c| c.to_i}
+
+          if coords.any? {|c| c < 0 }
+            raise Castanaut::Exceptions::ElementOffScreen
+          end
+
+          coords
+        end
+
+    end
+  end 
+
+  module Exceptions
+    # When getting an element's coordinates, this is raised if no element on
+    # the page matches the selector given.
+    class ElementNotFound < CastanautError
+    end
+
+    # When getting an element's coordinates, this is raised if the element
+    # is found, but cannot be shown on the screen. Normally, we automatically
+    # scroll to an element that is currently off-screen, but sometimes that
+    # might not be possible (such as if the element is display: none).
+    class ElementOffScreen < CastanautError
+    end
+  end
+
+end