Re: Please review new Perl 5 Module List

Martijn Koster (m.koster@nexor.co.uk)
Tue, 28 Feb 1995 15:07:46 +0000 

Gisle wrote:

> I think splitting is a good idea.  May I suggest something like this:
> Classes:
>     WWW::Request
>     WWW::Response
>     WWW::URL
>     WWW::MIME::Header  (or just WWW::Header)

Yes, having separate classes for Request and Response is cleaner than
just using a HTRequest which behaves different depending on if the
data has been received yet.

> In order to create an environment in order to issue requests you must
> create a WWW::Request object.  You might set some attributes of this
> object before you perform the actual request with the doit method.
> The doit method returns a WWW::Response object (the WWW::Response
> object should have no other constructor).

And you can call doit > once and it will use the same settings,
Nitpick: I loathe "doit", can we make it "send" or "request" or
something?
 
> The WWW::Response object will initially capture the state of the request
> after the headers have been read, but before the content (if any) has
> been read.  You might use various methods to inquire about the
> response code and various header entries.  Or use the content method
> to read the content.

Yup.

> The WWW::URL class is used to represent URLs.  The current design is
> OK, but the tie interface will be replaced by the metods like: scheme,
> host, port, path, query, fragment.

OK. I also think the '""' overloading should be taken out given the
disclaimer in perlovl.pod. Well cool though...

> The WWW::MIME::Header class is used to represent a collection of
> header entries.
> 
> Typical usage would be: [nice]
> ...
> The library might also provide convenience routines like this:
> 
> sub get
> {
>    my $request = new WWW::Request;
>    my $response = $request->doit("GET", @_);
>    return ($response->code, $response->headers, $response->content);
> }

Maybe these should go into separate files, so people can mix and match.

> WWW::Request methods:
> 
>     new();
>         Constructor
> 
>     set_default_header($key, $val);
> 
>     set_timeout($seconds);
>         Returns the old value
> 
>     set_content($contentRef);
>         Setting these things make more of the parameters to
>         doit() optional.
> 
>     doit($method, $url, $headers, $content, $timeout);
>         Returns a reference to a WWW::Response object.

I'd suggest removing the 'set_', and use the construct discussed
before.

 
> WWW::Response methods:
> 
>     code()
>         Returns the the nummeric response code
> 
>     mnemonic()
>         Returns the textual representation of the response code
> 
>     isRedirect();
>     isOK();
>     isXXX();
>         Test the response code
> 
>     headers();
>         Returns a ref to the WWW::MIME::Header object
> 
>     contentType();
>     contentEncoding();
>     contentLength();
>         Returns the corresponing header value
> 
>     content()
>         Returns the content as a string
>     content($file);
>         Writes the content to a file.  Returns 0 ok.
>     content(sub {...})
>         Reads the content in suitable chunks

I suggest adding an optional 'size' argument to indicate the
size of the chunks to read in.

>                                               and calls sub for each
>         chunk. 

along with optionally the length of the data read?

>               At EOF it calls sub with undef as argument.

Is that required? You know input has ended when &content returns.
What about errors that may occur during the callbacks? &content
could return an result code of some sort, or even an error message.
Should WWW::Response change it's internal result code if &content
failed?

> 
> WWW::URL methods:
> 
>     new($string);
>        Creates a new URL object based on the string representation.
> 
>     scheme()
>     host()
>     port()
>     path()
>     query()
>     fragment()
>        Set or query parts/attributes of an URL
> 
>     str()
>        Returns a string representation of the URL
> 
>     parent($baseUrl)
>        Make a relative URL into an absoulute URL.  Perhaps a better
>        name for this method.

expand? complete? resolve? Does the Internet-Draft give any
inspiration? :)
 
>     proxify()
>        Convert an URL into a proxified versjon based on some
>        environment variables.

Maybe for a future version, but proxifying should probably
be integrated closer into WWW::Request, something like.

   $request->proxy(
	                # for these schemes
	['http', 'gopher'],
	                # try these caching servers in turn
	['http://web.nexor.co.uk:8001', 'http://cache.hensa.ac.uk/'],
	                # don't proxy requests to these
	['web', '.*.nexor.co.uk', '128\.243\.9\..*']);
   
   $request->proxy(['wais'], ['http://web.nexor.co.uk:8001']);

   $request->get("wais:whatever");

This allows far finer control than environment variable currently do.
Then you can have $request->request() try proxies for unsupported
schemes instead of dying, and you'd have instant support for Gopher,
News etc. :-)


I really like this design. Is there anything we've missed out that we
might regret? It looks like client-side format transformation and
caching can be added without upsetting the API. I guess interrupts and
multi-threading might be different, but will probably have to wait
until Perl supports it anyway... We will need HTML parsing, but that
should be completely separate. Anything else?

-- Martijn
__________
Internet: m.koster@nexor.co.uk
X-400: C=GB; A= ; P=Nexor; O=Nexor; S=koster; I=M
X-500: c=GB@o=NEXOR Ltd@cn=Martijn Koster
WWW: http://web.nexor.co.uk/mak/mak.html