castanaut 1.0.0

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,3 @@
+== 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
+scripts/coords.js
+scripts/gebys.js
+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
+tasks/test.rake
+test/example_script.screenplay
+test/googling.screenplay

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,25 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'castanaut'
+
+task :default => 'spec:run'
+
+PROJ.name = 'castanaut'
+PROJ.authors = 'Joseph Pearson'
+PROJ.email = 'joseph@inventivelabs.com.au'
+PROJ.url = 'http://castanaut.rubyforge.org'
+PROJ.version = Castanaut::VERSION
+
+PROJ.rubyforge_name = 'castanaut'
+PROJ.rdoc_remote_dir = 'doc'
+
+PROJ.exclude += ['^spec\/*', '^test\/*']
+
+PROJ.spec_opts << '--color'
+
+# EOF

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/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