NAME
Net::Gopher - The Perl Gopher/Gopher+ client API
SYNOPSIS
use Net::Gopher;
my $gopher = new Net::Gopher;
# connect to a gopher server:
$gopher->connect($host, Port => $port, Timeout => $timeout)
or die $gopher->error;
# request something from the server:
my $response = $gopher->request('/menu', Type => 1);
# check for errors:
if ($response->is_success) {
...
} else {
print $response->error;
}
# disconnect from the server:
$gopher->disconnect;
# or, if you have a (even partial) URL, you can do it this way:
$repsonse = $gopher->request_url($url);
# the content of the response:
my $content = $gopher->content;
# or just get the entire (unmodified) response as a string:
my $string = $response->as_string;
...DESCRIPTION
Net::Gopher is a Gopher/Gopher+ client API for Perl. Net::Gopher implements the Gopher and Gopher+ protocols as desbribed in RFC 1436: The Internet Gopher Protocol, Anklesaria, et al., and in Gopher+: Upward Compatible Enhancements to the Internet Gopher Protocol, Anklesaria, et al.; bringing Gopher and Gopher+ support to Perl, and enabling Perl 5 applications to easily interact with both Gopher as well as Gopher+ servers.
METHODS
The following methods are available:
new([BufferSize => $num_bytes, GopherPlus => $boolean, Debug => $boolean])
This is the constructor method. It creates a new Net::Gopher object and returns a reference to it. This method takes several optional named parameters. BufferSize is the size (in bytes) of the buffer to use when reading data from the socket. If you don't specify BufferSize, then the default of 1024 will be used instead. GopherPlus allows you to turn on or turn off support for Gopher+. When turned off, Net::Gopher will never make Gopher+ requests, only Gopher requests. By default, support for Gopher+ is on. Finally, Debug allows you turn on or turn of debugging information, which by default is off.
Also see the corresponding get/set buffer_size(), gopher_plus(), and debug() methods below.
connect($host [, Port => $port_num, Timeout => $seconds])
This method attempts to connect to a Gopher server. If connect() is able to connect, it returns true; false otherwise (call error() to find out why). As its first argument it takes a mandatory hostname (e.g., gopher.host.com). In addition to the hostname, it takes two optional named paramters. The first, Port, takes an optional port number. If you don't supply this, then the default of 70 will be used instead. The second, Timeout, takes the number of seconds at which a timeout will occur when attempting to connect to a Gopher server. If you don't supply this, then the default of 60 seconds will be used instead.
request($selector [, Representation => $mime_type, DataBlock => $data |, Attributes => $attributes] [, Type => $type])
This method sends a request to the Gopher/Gopher+ server you've connected to with connect(), and returns a Net::Gopher::Response object for the server's response. The first argument is the selector string to send to the server. This method also takes four optional named parameters. The first, Representation, is used for Gopher+ requests to ask a Gopher+ server to return an item in a specified format (MIME type):
$gopher->request($selector,
Representation => 'text/plain'
Type => $type
);The second named parameter, DataBlock, is for Gopher+ requests and enables you to send data from a Gopher+ Ask form to a Gopher+ server. This method will take care of the rest, including adding the dataflag to the request to tell the Gopher+ server that there's a data block.
The third named parameter, Attributes, is for Gopher+ item attribute/directory attribute information requests, and enables you to request only certain info blocks (e.g., "+INFO+ADMIN" to only retrieve the INFO and ADMIN blocks). You can either specify each block name for Attributes in one big string:
$gopher->request($selector,
Attributes => '+NAME+NAME2+NAME3',
Type => $type
);or you can put them in an array ref:
$gopher->request($selector,
Attributes => ['+NAME', '+NAME2', '+NAME3'],
Type => $type
);Also note that when using the array ref format, you don't have to prefix each block name with a plus; this method will do it for you if you don't.
The fourth named parameter, Type, helps Net::Gopher determine how exactly it should handle the response from the Gopher server, and what (if any) modifications it should make to the response content (see the Net::Gopher::Response content() method). If you don't supply this, then the default item type of 1 will be used instead.
For Gopher+ requests, while you'll usually need to add a trailing tab and plus to the selector string, it's not always necessary; if either the Representation or DataBlock parameters are defined, then this method will realize that this is a Gopher+ request and will add the trailing tab and plus to your selector string for you if they are not already present. The same holds true for Gopher+ item attribute information requests; if the Attributes parameter is defined then this method will realize this is a Gopher+ item attribute information request and will add the trailing tab and exclamation point to your selector string for you if there isn't already either a tab and exclamation point or tab and dollar sign at the end of your selector.
disconnect()
Call this method to disconnect from the Gopher server after requesting something from it. Not really necessary since the Gopher server will usually close the connection first.
request_url($url)
This method allows you to bypass the connect(), request(), and disconnect() sequence. If you have a Gopher URL you can just supply it to this method and it will connect to the server and request it for you. This method will return a Net::Gopher::Response object just like request() does.
buffer_size($size)
This is a get/set method that enables you to change the buffer sized used. (The default is 1024.)
gopher_plus($boolean)
This is a get/set method that enables you to turn on or turn off support for Gopher+ (default is on). Just supply a true value for on, or a false value for off.
debug($boolean)
This is a get/set method that enables you to turn on or turn off Net::Gopher debugging (default is off). Just supply a true value for on, or a false value for off.
error()
This method returns a string containing an error message or undef if no error has occurred.
BUGS
If you encounter bugs, you can alert me of them by emailing me at <william_g_davis at users dot sourceforge dot net> or, if you have PerlMonks account, you can go to perlmonks.org and /msg me (William G. Davis).
SEE ALSO
Net::Gopher::Response
COPYRIGHT
Copyright 2003, William G. Davis.
This code is free software released under the GNU General Public License, the full terms of which can be found in the "COPYING" file that came with the distribution of the module.