/ 
Catalyst-Plugin-SmartURI-0.01_01
River stage one • 1 direct dependent • 1 total dependent
/ Catalyst::SmartURI

NAME

Catalyst::SmartURI - URIs with extra sugar

VERSION

Version 0.01

SYNOPSIS

my $uri = Catalyst::SmartURI->new(
    'http://host/foo/',
    { reference => 'http://host/bar/' }
);

my $hostless = $uri->hostless; # '/foo/'

$hostless->absolute; # 'http://host/foo/'

$uri->relative; # '../foo/'

DESCRIPTION

This is a sort of "subclass" of URI using delegation with some extra methods, all the methods that work for URIs will work on these objects as well.

It's similar in spirit to URI::WithBase.

It's also completely safe to subclass for your own use.

CONSTRUCTORS

Catalyst::SmartURI->new($str, [$scheme|{reference => $ref, scheme => $scheme}])

Takes a uri $str and an optional scheme or hashref with a reference uri (for computing relative/absolute URIs) and an optional scheme.

my $uri = Catalyst::SmartURI->new('http://dev.catalyst.perl.org/');

my $uri = Catalyst::SmartURI->new('/catwiki.toeat.com/', 'http');

my $uri = Catalyst::SmartURI->new(
    'http://search.cpan.org/~jrockway/Catalyst-Manual-5.701003/', 
    { reference => 'http://search.cpan.org/' }
);

The object returned will be blessed into a scheme-specific subclass, based on the class of the underlying $uri->obj (URI object.) For example, Catalyst::SmartURI::http, and this class derives from the Catalyst::SmartURI.

Catalyst::SmartURI->new_abs($str, $base_uri)

Proxy for URI->new_abs

Catalyst::SmartURI->newlocal($filename, [$os])

Proxy for URI::URL->newlocal

METHODS

$uri->hostless

Returns the URI with the scheme and host parts stripped.

$uri->reference

Accessor for the reference URI (for relative/absolute below.)

$uri->relative

Returns the URI relative to the reference URI.

$uri->absolute

Returns the absolute URI using the reference URI as base.

""

stringification works, just like with URIs

==

and == does as well

$uri->eq($other_uri)

Explicit equality check to another URI, can be used as Catalyst::SmartURI::eq($uri1, $uri2) as well.

$uri->obj

Accessor for the URI object methods are delegated to.

$uri->factory_class

The class whose constructor was called to create the $uri object, usually Catalyst::SmartURI or your own subclass. This is used to call class (rather than object) methods.

INTERNAL METHODS

These are used internally by SmartURI, and are not interesting for general use, maybe for subclassing purposes.

$uri->_opts

Returns a hashref of options for the $uri (reference and scheme.)

$class->_resolve_uri_class($uri_class)

Converts, eg., "URI::http" to "Catalyst::SmartURI::http".

$class->_make_uri_class($uri_class)

Creates a new proxy class class for a URI class, with all exports and constructor intact, and returns its name, which is made using _resolve_uri_class (above).

$class->_inflate_uris(\@rray, $opts)

Inflate any URI objects in @rray into Catalyst::SmartURI objects, all other members pass through unharmed. $opts is a hashref of options to include in the objects created.

$class->_deflate_uris(@rray)

Deflate any Catalyst::SmartURI objects in @rray into the URI objects they are proxies for, all other members pass through unharmed.

MAGICAL IMPORT

On import with the -import_uri_mods flag it loads all the URI .pms into your class namespace.

This works:

use Catalyst::SmartURI '-import_uri_mods';
use Catalyst::SmartURI::WithBase;
use Catalyst::SmartURI::URL;

my $url = Catalyst::SmartURI::URL->new(...); # URI::URL proxy

Even this works:

use Catalyst::SmartURI '-import_uri_mods';
use Catalyst::SmartURI::Escape qw(%escapes);

It even works with a subclass of Catalyst::SmartURI.

I only wrote this functionality so that I could run the URI test suite without much modification, it has no real practical value.

AUTHOR

Rafael Kitover, <rkitover at cpan.org>

COPYRIGHT & LICENSE

Copyright (c) 2008 Rafael Kitover

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