.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "URI::SmartURI 3pm"
.TH URI::SmartURI 3pm "2018-08-28" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
URI::SmartURI \- Subclassable and hostless URIs
.SH "VERSION"
.IX Header "VERSION"
Version 0.032
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    my $uri = URI::SmartURI\->new(
\&        \*(Aqhttp://host/foo/\*(Aq,
\&        { reference => \*(Aqhttp://host/bar/\*(Aq }
\&    );
\&
\&    my $hostless = $uri\->hostless; # \*(Aq/foo/\*(Aq
\&
\&    $hostless\->absolute; # \*(Aqhttp://host/foo/\*(Aq
\&
\&    $uri\->relative; # \*(Aq../foo/\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a sort of \*(L"subclass\*(R" of \s-1URI\s0 using delegation with some extra methods,
all the methods that work for \s-1URI\s0s will work on these objects as well.
.PP
It's similar in spirit to URI::WithBase.
.PP
It's also completely safe to subclass for your own use.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.ie n .SS "URI::SmartURI\->new($str, [$scheme|{reference => $ref, scheme => $scheme}])"
.el .SS "URI::SmartURI\->new($str, [$scheme|{reference => \f(CW$ref\fP, scheme => \f(CW$scheme\fP}])"
.IX Subsection "URI::SmartURI->new($str, [$scheme|{reference => $ref, scheme => $scheme}])"
Takes a uri \f(CW$str\fR and an optional scheme or hashref with a reference uri
(for computing relative/absolute URIs) and an optional scheme.
.PP
.Vb 1
\&    my $uri = URI::SmartURI\->new(\*(Aqhttp://dev.catalyst.perl.org/\*(Aq);
\&
\&    my $uri = URI::SmartURI\->new(\*(Aq/dev.catalyst.perl.org/new\-wiki/\*(Aq, \*(Aqhttp\*(Aq);
\&
\&    my $uri = URI::SmartURI\->new(
\&        \*(Aqhttp://search.cpan.org/~jrockway/Catalyst\-Manual\-5.701003/\*(Aq, 
\&        { reference => \*(Aqhttp://search.cpan.org/\*(Aq }
\&    );
.Ve
.PP
The object returned will be blessed into a scheme-specific subclass, based on
the class of the underlying \f(CW$uri\fR\->obj (\s-1URI\s0 object.) For example,
URI::SmartURI::http, which derives from URI::SmartURI (or
\&\f(CW$uri\fR\->factory_class if you're subclassing.)
.ie n .SS "URI::SmartURI\->new_abs($str, $base_uri)"
.el .SS "URI::SmartURI\->new_abs($str, \f(CW$base_uri\fP)"
.IX Subsection "URI::SmartURI->new_abs($str, $base_uri)"
Proxy for \s-1URI\s0\->new_abs
.SS "URI::SmartURI\->newlocal($filename, [$os])"
.IX Subsection "URI::SmartURI->newlocal($filename, [$os])"
Proxy for \s-1URI::URL\s0\->newlocal
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$uri\->hostless"
.el .SS "\f(CW$uri\fP\->hostless"
.IX Subsection "$uri->hostless"
Returns the \s-1URI\s0 with the scheme and host parts stripped.
.ie n .SS "$uri\->reference"
.el .SS "\f(CW$uri\fP\->reference"
.IX Subsection "$uri->reference"
Accessor for the reference \s-1URI\s0 (for relative/absolute below.)
.ie n .SS "$uri\->relative"
.el .SS "\f(CW$uri\fP\->relative"
.IX Subsection "$uri->relative"
Returns the \s-1URI\s0 relative to the reference \s-1URI.\s0
.ie n .SS "$uri\->absolute"
.el .SS "\f(CW$uri\fP\->absolute"
.IX Subsection "$uri->absolute"
Returns the absolute \s-1URI\s0 using the reference \s-1URI\s0 as base.
.ie n .SS """"""
.el .SS "``''"
.IX Subsection """"""
stringification works, just like with \s-1URI\s0s
.SS "=="
.IX Subsection "=="
and == does as well
.ie n .SS "$uri\->eq($other_uri)"
.el .SS "\f(CW$uri\fP\->eq($other_uri)"
.IX Subsection "$uri->eq($other_uri)"
Explicit equality check to another \s-1URI,\s0 can be used as
URI::SmartURI::eq($uri1, \f(CW$uri2\fR) as well.
.ie n .SS "$uri\->obj"
.el .SS "\f(CW$uri\fP\->obj"
.IX Subsection "$uri->obj"
Accessor for the \s-1URI\s0 object methods are delegated to.
.ie n .SS "$uri\->factory_class"
.el .SS "\f(CW$uri\fP\->factory_class"
.IX Subsection "$uri->factory_class"
The class whose constructor was called to create the \f(CW$uri\fR object, usually
URI::SmartURI or your own subclass. This is used to call class (rather
than object) methods.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
These are used internally by SmartURI, and are not interesting for general use,
but may be useful for writing subclasses.
.ie n .SS "$uri\->_opts"
.el .SS "\f(CW$uri\fP\->_opts"
.IX Subsection "$uri->_opts"
Returns a hashref of options for the \f(CW$uri\fR (reference and scheme.)
.ie n .SS "$class\->_resolve_uri_class($uri_class)"
.el .SS "\f(CW$class\fP\->_resolve_uri_class($uri_class)"
.IX Subsection "$class->_resolve_uri_class($uri_class)"
Converts, eg., \*(L"URI::http\*(R" to \*(L"URI::SmartURI::http\*(R".
.ie n .SS "$class\->_make_uri_class($uri_class)"
.el .SS "\f(CW$class\fP\->_make_uri_class($uri_class)"
.IX Subsection "$class->_make_uri_class($uri_class)"
Creates a new proxy class class for a \s-1URI\s0 class, with all exports and
constructor intact, and returns its name, which is made using
_resolve_uri_class (above).
.ie n .SS "$class\->_inflate_uris(\e@rray, $opts)"
.el .SS "\f(CW$class\fP\->_inflate_uris(\e@rray, \f(CW$opts\fP)"
.IX Subsection "$class->_inflate_uris(@rray, $opts)"
Inflate any \s-1URI\s0 objects in \f(CW@rray\fR into URI::SmartURI objects, all other
members pass through unharmed. \f(CW$opts\fR is a hashref of options to include in the
objects created.
.ie n .SS "$class\->_deflate_uris(@rray)"
.el .SS "\f(CW$class\fP\->_deflate_uris(@rray)"
.IX Subsection "$class->_deflate_uris(@rray)"
Deflate any URI::SmartURI objects in \f(CW@rray\fR into the \s-1URI\s0 objects
they are proxies for, all other members pass through unharmed.
.SH "MAGICAL IMPORT"
.IX Header "MAGICAL IMPORT"
On import with the \f(CW\*(C`\-import_uri_mods\*(C'\fR flag it loads all the \s-1URI\s0 .pms into your
class namespace.
.PP
This works:
.PP
.Vb 3
\&    use URI::SmartURI \*(Aq\-import_uri_mods\*(Aq;
\&    use URI::SmartURI::WithBase;
\&    use URI::SmartURI::URL;
\&
\&    my $url = URI::SmartURI::URL\->new(...); # URI::URL proxy
.Ve
.PP
Even this works:
.PP
.Vb 2
\&    use URI::SmartURI \*(Aq\-import_uri_mods\*(Aq;
\&    use URI::SmartURI::Escape qw(%escapes);
.Ve
.PP
It even works with a subclass of URI::SmartURI.
.PP
I only wrote this functionality so that I could run the \s-1URI\s0 test suite without
much modification, it has no real practical value.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-uri\-smarturi at rt.cpan.org\*(C'\fR, or through the web
interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI\-SmartURI>.  I
will be notified, and then you'll automatically be notified of progress on your
bug as I make changes.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc URI::SmartURI
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=URI\-SmartURI>
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/URI\-SmartURI>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/d/URI\-SmartURI>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/URI\-SmartURI>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catalyst::Plugin::SmartURI, \s-1URI\s0, URI::WithBase
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to folks on freenode #perl for helping me out when I was getting stuck,
Somni, revdiablo, PerlJam and others whose nicks I forget.
.SH "AUTHOR"
.IX Header "AUTHOR"
Rafael Kitover, \f(CW\*(C`<rkitover at cpan.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 2008 Rafael Kitover
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.