NAME

HTTP::Proxy::GreaseMonkey - Run GreaseMonkey scripts in any browser

VERSION

This document describes HTTP::Proxy::GreaseMonkey version 0.03

SYNOPSIS

  use HTTP::Proxy;
  use HTTP::Proxy::GreaseMonkey;

  my $proxy = HTTP::Proxy->new( port => 8030 );
  my $gm = HTTP::Proxy::GreaseMonkey->new;
  $gm->add_script( 'gm/myscript.js' );
  $proxy->push_filter(
      mime     => 'text/html',
      response => $gm
  );
  $proxy->start;

DESCRIPTION

GreaseMonkey allows arbitrary user defined Javascript to be run against specific pages. Unfortunately GreaseMonkey only works with FireFox.

HTTP::Proxy::GreaseMonkey creates a local HTTP proxy that allows GreaseMonkey user scripts to be used with any browser.

When you install HTTP::Proxy::GreaseMonkey a program called gmproxy is installed in your default bin directory. To launch the GreaseMonkey proxy issue a command something like this:

$ gmproxy ~/.userscripts

By default the proxy will listen on port 8030. The supplied directory is scanned before each request; any scripts that have been updated or added will be reloaded and any that have been deleted will be discarded.

Mac OS

On MacOS net.hexten.gmproxy.plist is created in the project home directory. Create a directory called ~/.userscripts and then add gmproxy as a launch item:

$ cp net.hexten.gmproxy.plist ~/Library/LaunchAgents
$ launchctl load ~/Library/LaunchAgents/net.hexten.gmproxy.plist
$ launchctl start net.hexten.gmproxy

Then change your network settings to route HTTP through proxy localhost:8030. Once this is done gmproxy will load automatically when you log in.

Important: As of 2007-12-17 PubSubAgent crashes periodically (actually during .mac synchronisation) when HTTP is proxied. The solution appears to be to add *.mac.com to the list of domains that bypass the proxy. As far as I'm aware this is a Mac OS problem that has nothing specifically to do with HTTP::Proxy::GreaseMonkey.

Other Platforms

Patches welcome from anyone who has equivalent instructions for other platforms.

Limitations

Currently none of the GM_* functions are supported. If anyone has a good idea about how to support them please drop me a line.

INTERFACE

init

Called to initialise the filter.

add_script( $script )

Add a GM script to the proxy. The argument may be the filename of a script or an existing HTTP::Proxy::GreaseMonkey::Script.

verbose

Set / get verbosity.

will_modify

Will this filter modify content? Called by HTTP::Proxy.

begin

Called at the start of processing.

filter

The filter entry point. Called for each chunk of input.

end

Finished processing.

get_passthru_key

Get the passthru key that is used to signal to the proxy that it should rewrite request URLs.

get_gm_globals

Return a block of Javascript that initialises various globals that are required by the GreaseMonkey environment.

get_support_script

Returns a block of Javascript that is injected before any user scripts. Typically this code provides the GM_* support functions.

CONFIGURATION AND ENVIRONMENT

HTTP::Proxy::GreaseMonkey requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-http-proxy-greasemonkey@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Andy Armstrong <andy@hexten.net>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Andy Armstrong <andy@hexten.net>.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.