NAME

HTTP::ProxyPAC - use a PAC (Proxy Auto Config) file to get proxy info

SYNOPSIS

  use HTTP::ProxyPAC;

  my $pac = HTTP::ProxyPAC->new(pacAccessor[, options]);
  
  my $res = $pac->find_proxy($url);
  if ($res->proxy) {
      $ua->proxy('http' => $res->proxy);
  }

DESCRIPTION

HTTP::ProxyPAC allows use of a Proxy Auto Configuration file to determine whether a URL needs to be accessed via a proxy server, and if so the URL of the proxy server. You can use a .pac file from a web browser, or a wpad.dat file obtained via the WPAD protocol: <http://en.wikipedia.org/wiki/Web_Proxy_Autodiscovery_Protocol>.

METHODS

new

  $pac = HTTP::ProxyPAC->new(pacAccessor[, options]);

creates a new HTTP::ProxyPAC object. pacAccessor leads to a JavaScript function FindProxyForURL. It can be

a URL like "http://example.com/proxy.pac"
a file path like "/path/to/proxy.pac"
a reference to a string that contains the Javascript function, like "\$content", or
an open filehandle from which the Javascript function can be read, like $fh

options are by their nature optional. If included they can be 1 or 2 key=>value pairs.

The key "interp" can be followed by a case-independent value 'js' or 'javascript' to use the JavaScript module and the SpiderMonkey/libjs JavaScript interpreter from Mozilla. Any other value (nominally 'je') will use the JE module as the interpreter.

If no "interp" option is provided, HTTP::ProxyPAC will first test whether JavaScript is installed, and use it if so. If not it will test whether JE is installed, and use it if so. If neither is installed, the new call will die with an error message.

The key "lib" can be followed by the case-independent value 'perl' to use the Perl library functions that HTTP::ProxyPAC inherited from HTTP::ProxyAutoConfig. They have been improved in version 0.2. Any other value (nominally 'js'), or no "lib" option at all, will cause HTTP::ProxyPAC to use the JavaScript library originally written by NetScape when they originated the Proxy Auto Config scheme.

find_proxy

  $res = $pac->find_proxy($url);
  @res = $pac->find_proxy($url);

find_proxy executes the FindProxyForURL function provided in the first operand of new. It takes a URL as a string or a URI object, and returns a HTTP::ProxyPAC::Result object that indictaes whether the URL should be accessed directly, or if not the URL of the proxy server via which it can be accessed.

FindProxyForURL function can return multiple candidates. In that case, find_proxy will return all of the Result objects in list context, or the first Result object in scalar context.

<http://search.cpan.org/perldoc%3FHTTP::ProxyPAC::Result> describes how to use the returned object(s).

WHAT ABOUT HTTP::ProxyAutoConfig?

The HTTP::ProxyAutoConfig module performs a similar function, and the "lib=>'perl'" option uses many functions derived from HTTP::ProxyAutoConfig (Thanks!).

But the Javascript to Perl translator in HTTP::ProxyAutoConfig is a pretty hard thing to get right, and can generate bad perl code if there's any JavaScript in the .pac or wpad.dat file other than the basic function calls defined for the PAC scheme.

So the original author created this module to use the JavaScript module (and SpiderMonkey/libjs from mozilla.org) as a JavaScript interpreter. This might be overkill for this task, but is definitely more robust.

Version 0.2 and higher can use either the JavaScript module or the JE module which is self-contained and doesn't require you to install SpiderMonkey/libjs from Mozilla by hand. Thus CPAN or CPANPLUS can do the complete installation of version 0.2 or higher.

AUTHORS

  Tatsuhiko Miyagawa <miyagawa@bulknews.net>
  Craig MacKenna     <craig@animalhead.com> for 0.2

Ryan Eatmon wrote the Perl PAC functions in HTTP::ProxyAutoConfig, which were used by the original author. These functions have been improved in version 0.2 of both modules, and can be replaced by the original JavaScript functions.

COPYRIGHT AND LICENSE

  Copyright (C) 2006, Tatsuhiko Miyagawa
  Copyright (C) 2010, Craig MacKenna

This module is free software; you may redistribute it and/or modify it under the same terms as Perl 5.10.1. For more details, see the full text of the licenses at <http://www.perlfoundation.org/artistic_license_1_0> and <http://www.gnu.org/licenses/gpl-2.0.html>

This program is distributed in the hope that it will be useful, but it is provided 'as is' and without any express or implied warranties. For details, see the full text of the licenses at the above URLs.