castanaut 1.0.0 → 1.1.0

data/lib/castanaut/movie.rb

@@ -1,24 +1,67 @@
 module Castanaut
-  # The movie class is the containing context within which screenplays are 
-  # invoked. It provides a number of basic stage directions for your 
+
+  # 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.
+  #
+  # If you're working to make Castanaut compatible with your operating system,
+  # you must make sure that *all* methods in this class work correctly.
   class Movie
 
-    # Runs the "screenplay", which is a file containing Castanaut instructions.
+    def self.register(name)
+      unless reg = Castanaut::Movie.instance_variable_get(:@movie_classes)
+        reg = Castanaut::Movie.instance_variable_set(:@movie_classes, {})
+      end
+      self.instance_variable_set(:@name, name)
+      reg.update(self => name)
+    end
+
+
+    def self.spawn(screenplay = nil, monitor = true)
+      reg = Castanaut::Movie.instance_variable_get(:@movie_classes)
+      klass = reg.keys.detect { |k| k.platform_supported? }
+      klass.new(screenplay, monitor)
+    end
+
+
+    #  Creates the movie. If a screenplay is provided here, it will be run.
+    #  If monitor is true, we'll monitor the kill file (FILE_RUNNING) -
+    #  if it is deleted, we abort.
     #
-    def initialize(screenplay)
-      perms_test
+    def initialize(screenplay = nil, monitor = true)
+      if self.class == Castanaut::Movie
+        raise "#{self} is an abstract class. Try the spawn method."
+      end
 
-      if !screenplay || !File.exists?(screenplay)
-        raise Castanaut::Exceptions::ScreenplayNotFound 
+      if screenplay
+        monitor ? _play_and_monitor(screenplay) : _play(screenplay)
+      end
+    end
+
+
+    # Simply plays the screenplay in the current thread.
+    def _play(screenplay)
+      unless File.exists?(@screenplay_path = screenplay)
+        raise Castanaut::Exceptions::ScreenplayNotFound
+      end
+      eval(IO.read(@screenplay_path), binding)
+      roll_credits
+    end
+
+
+    # Plays the screenplay in a separate thread, and monitors the killfile
+    # (which is at FILE_RUNNING) - if it is deleted, the screenplay will
+    # abort.
+    def _play_and_monitor(screenplay)
+      unless File.exists?(@screenplay_path = 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 
+        # 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
@@ -49,123 +92,55 @@ module Castanaut
       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
+    #--------------------------------------------------------------------------
+    # IMPLEMENTED DIRECTIONS
+    #
+    # You can override these in subclasses, but you'd probably want to have
+    # a very good reason.
+    #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-    # Move the mouse cursor to the specified co-ordinates.
+    # Don't do anything for the specified number of seconds (can be portions
+    # of a second).
     #
-    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]}"
+    def pause(seconds)
+      sleep seconds
     end
 
-    alias :move :cursor
 
-    # Send a mouse-click at the current mouse location.
+    # Groups directions into labelled blocks. This lets you skip (see below)
+    # to the end of the block if you need to.
     #
-    def click(btn = 'left')
-      automatically "mouseclick #{mouse_button_translate(btn)}"
-    end
-
-    # Send a double-click at the current mouse location.
+    #   perform "Build CouchDB from source" do
+    #     launch "Terminal"
+    #     type "./configure"
+    #     hit Enter
+    #     ...
+    #   end
     #
-    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)}"
+    def perform(label)
+      yield
+    rescue Castanaut::Exceptions::SkipError => e
+      puts "Skipping remaining directions in '#{label}'"
     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.
+    # Lets you skip out of a perform block if you need to. Usually raised
+    # when some condition fails. For example:
     #
-    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.
+    # perform "Point to heading" do
     #
-    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.
+    #   move to_element('h2') rescue skip
+    #   say "This is the heading."
     #
-    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.
+    # end
     #
-    def hit(key)
-      automatically "hit #{key}"
+    def skip
+      raise Castanaut::Exceptions::SkipError
     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.
@@ -180,6 +155,7 @@ module Castanaut
       end
     end
 
+
     # Get a hash representing specific screen co-ordinates. Use in combination
     # with cursor, drag, launch, and similar methods.
     #
@@ -197,18 +173,17 @@ module Castanaut
 
     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
+      @cursor_loc ||= cursor_location
       to(@cursor_loc[:x] + x, @cursor_loc[:y] + y)
     end
 
-    # The result of this method can be added +to+ a co-ordinates hash, 
+
+    # 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)
@@ -216,41 +191,15 @@ module Castanaut
     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 
+    # 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,
@@ -259,8 +208,7 @@ module Castanaut
     def script(filename)
       @cached_scripts ||= {}
       unless @cached_scripts[filename]
-        fpath = File.join(File.dirname(@screenplay_path), "scripts", filename)
-        scpt = nil
+        fpath = contextual_path("scripts", filename)
         if File.exists?(fpath)
           scpt = IO.read(fpath)
         else
@@ -272,6 +220,34 @@ module Castanaut
       @cached_scripts[filename]
     end
 
+
+    # Adds custom methods to this movie instance, allowing you to perform
+    # additional actions. The str can be either the file name
+    # (e.g. 'snapz_pro') or the class name (e.g. 'SnapzPro').
+    # See the README.txt for more information.
+    #
+    # FIXME: sort out this underscore/camelize mess.
+    #
+    def plugin(str)
+      # copied stright from the Rails underscore helper
+      str = str.to_s
+      str.gsub!(/::/, '/')
+      str.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+      str.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      str.tr!("-", "_")
+      str.downcase!
+      fpath =
+      begin
+        require contextual_path("plugins", "#{str}.rb")
+      rescue LoadError
+        require File.join(LIBPATH, "plugins", "#{str}.rb")
+      end
+      # copied stright from the Rails camelize helper
+      str = str.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+      extend eval("Castanaut::Plugin::#{str}")
+    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
@@ -293,45 +269,202 @@ module Castanaut
       @end_credits << blk
     end
 
+
+    #--------------------------------------------------------------------------
+    # KEYBOARD INPUT DIRECTIONS
+    #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    # Sends the characters into the active control in the active window.
+    #
+    # Options are:
+    #
+    # * <tt>:speed</tt> - approximate umber of characters per second
+    #     A speed of 0 types as quickly as possible. (default - 50)
+    #
+    def type(str, opts = {})
+      not_supported('type')
+    end
+
+
+    # Hit a single key on the keyboard (with optional modifiers).
+    #
+    # Valid keys include any single character or any of the constants in keys.rb
+    #
+    # Valid modifiers include one or more of the following:
+    #   Command
+    #   Ctrl
+    #   Alt
+    #   Shift
+    #
+    # Examples:
+    #   hit Castanaut::Tab
+    #   hit 'a', Castanaut::Command
+    #
+    def hit(key, *modifiers)
+      not_supported('hit')
+    end
+
+
+    #---------------------------------------------------------------------------
+    # MOUSE INPUT DIRECTIONS
+    #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    # Move the mouse cursor to the specified co-ordinates.
+    # Example:
+    #
+    #   cursor to(20, 20)
+    #
+    def cursor(*options)
+      not_supported('cursor')
+    end
+
+    alias :move :cursor
+
+
+    # Get a hash representing the current mouse cursor co-ordinates.
+    #
+    # Should return a hash with :x & :y keys.
+    #
+    def cursor_location
+      not_supported('cursor_location')
+    end
+
+
+    # Send a mouse-click at the current mouse location.
+    #
+    def click(btn = 'left')
+      not_supported('click')
+    end
+
+
+    # Send a double-click at the current mouse location.
+    #
+    def doubleclick(btn = 'left')
+      not_supported('doubleclick')
+    end
+
+
+    # Send a triple-click at the current mouse location.
+    #
+    def tripleclick(btn = 'left')
+      not_supported('tripleclick')
+    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')
+      not_supported('mousedown')
+    end
+
+
+    # Releases the mouse button pressed by a previous mousedown.
+    #
+    def mouseup(btn = 'left')
+      not_supported('mouseup')
+    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)
+      not_supported('drag')
+    end
+
+
+    #--------------------------------------------------------------------------
+    # WINDOWS AND APPLICATIONS DIRECTIONS
+    #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    # Launch the application matching the string given in the first argument.
+    # If the options hash is given, it should contain the co-ordinates for
+    # the window.
+    #
+    # Example:
+    #
+    #   launch "Firefox", at(10, 10, 800, 600)
+    #
+    def launch(app_name, *options)
+      not_supported('launch')
+    end
+
+    alias :activate :launch
+
+
+    # Returns a region hash describing the entire screen area.
+    #
+    # Should return a hash with :width & :height keys.
+    #
+    def screen_size
+      not_supported('screen_size')
+    end
+
+
+    #--------------------------------------------------------------------------
+    # USEFUL UTILITIES
+    #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    # Use text-to-speech functionality to emulate a human
+    # voice saying the narrative text.
+    #
+    def say(narrative)
+      not_supported('say')
+    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
+
+      # Find a file relative to the movie execution context -- that is,
+      # either the location of the screenplay file, or the present working
+      # directory if there is no screenplay file.
+      #
+      def contextual_path(*args)
+        if @screenplay_path
+          File.join(*([File.dirname(@screenplay_path)] + args))
+        else
+          File.join(*args)
+        end
       end
 
-      def automatically(cmd)
-        run("#{osxautomation_path} \"#{cmd}\"")
+
+      # A method used by the compatibility layer to raise a NotSupportedError
+      # explaining which requested options are not supported by the current
+      # operating system.
+      #
+      # Example:
+      #   # On a Mac OS 10.5 (Leopard) machine
+      #   hit 'a', Castanaut::Command
+      #   => "Mac OS 10.5 (Leopard) does not support modifier keys for
+      #     the 'hit' method."
+      #
+      def not_supported(message)
+        message.gsub!(/\.$/, '')
+        raise Castanaut::Exceptions::NotSupportedError.new(
+          "#{self.class.to_s} does not support #{message}."
+        )
       end
 
+
+      # Escapes double quotes.
+      #
       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")
+      # Combines a list of hashes into one hash.
+      # Example:
+      #
+      #   combine_options({:x=>10}, {:y=>20})
+      #   # => {:y=>20, :x=>10}
+      #
+      def combine_options(*args)
+        args.inject({}) { |result, option| result.update(option) }
       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]
@@ -339,15 +472,12 @@ module Castanaut
         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