ch20_05.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

new_abs($<em class="replaceable">str</em>, $<em class="replaceable">base_uri</em>)
</pre><p>Creates a new absolute URI object.
<tt class="literal">$</tt><em class="replaceable"><tt>str</tt></em> represents the
absolute URI, and
<tt class="literal">$</tt><em class="replaceable"><tt>base_uri</tt></em> represents
the relative URI.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>opaque</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
opaque([$<em class="replaceable">new_opaque_value</em>])
</pre><p>Sets and gets the scheme-specific part of
<tt class="literal">$</tt><em class="replaceable"><tt>uri</tt></em>.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>path</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
path([$<em class="replaceable">path</em>])
</pre><p>Sets and gets the escaped path component of
<tt class="literal">$</tt><em class="replaceable"><tt>uri</tt></em>. Returns empty
string ("") if there is no path.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>path</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
path([$<em class="replaceable">new_path</em>])
</pre><p>Gets and sets the same value as <tt class="literal">opaque</tt>, unless the
URI supports the generic syntax for heirarchical namespaces.
<tt class="literal">path</tt> returns the part of the URI between the
hostname and the fragment.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>path_query</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
path_query([$<em class="replaceable">path_here</em>])
</pre><p>Sets and gets the escapted path and query components.</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>path_segments</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
path_segments([$<em class="replaceable">seg</em>])
</pre><p>Sets and gets the path. In a scalar content,
<tt class="literal">path_segments</tt> is equivalent to
<tt class="literal">path</tt>. In a list contents,
<tt class="literal">path_segments</tt> returns the unescaped path segments
that make up the path.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>port</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
port([$<em class="replaceable">new_port</em>])
</pre><p>Sets and gets the port, which is an integer. If
<tt class="literal">$</tt><em class="replaceable"><tt>new_port</tt></em> is not
defined, then the default port of the URI scheme will be returned.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>query</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
query([$<em class="replaceable">q</em>])
</pre><p>Sets and gets the escaped query component of
<tt class="literal">$</tt> <em class="emphasis">uri</em> .
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>query_form</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
query_form([$<em class="replaceable">key</em> =&gt; $<em class="replaceable">val</em>])
</pre><p>Sets and gets query components that use the urlencoded format.</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>query_keywords</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
query_keywords([$<em class="replaceable">keywords</em>])
</pre><p>Sets and gets query components that use keywords separated by a
<tt class="literal">+</tt>.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>rel</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
rel($<em class="replaceable">base_uri</em>)
</pre><p>Returns a relative URI reference, if one exists. Otherwise,
<tt class="literal">$</tt><em class="replaceable"><tt>uri</tt></em> is returned.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>scheme</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
scheme([$<em class="replaceable">some_scheme</em>])
</pre><p>Sets and gets the scheme part of the URI. Such values include:
<tt class="literal">data</tt>, <tt class="literal">file</tt>,
<tt class="literal">ftp</tt>, <tt class="literal">gopher</tt>,
<tt class="literal">http</tt>, <tt class="literal">https</tt>,
<tt class="literal">ldap</tt>, <tt class="literal">mailto</tt>,
<tt class="literal">news</tt>, <tt class="literal">nntp</tt>,
<tt class="literal">pop</tt>, <tt class="literal">rlogin</tt>,
<tt class="literal">rsync</tt>, <tt class="literal">snews</tt>,
<tt class="literal">telnet</tt>, and <tt class="literal">ssh</tt>. In the case of
relative URIs, <tt class="literal">scheme</tt> will return
<tt class="literal">undef</tt>; otherwise, <tt class="literal">scheme</tt> will
return the scheme in lowercase. With
<tt class="literal">$</tt><em class="replaceable"><tt>some_scheme</tt></em>,
<tt class="literal">scheme</tt> will set the scheme of the current URI.
<tt class="literal">scheme</tt> will die if the scheme isn't supported, or
if it contains non-US-ASCII characters.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>userinfo</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
userinfo([$<em class="replaceable">new_userinfo</em>])
</pre><p>Sets and gets the escaped
"userinfo" part of the authority
component (of the URI). Often, the userinfo will appear as a username
and password separated by a colon. Bear in mind that sending a
password in the clear is a bad idea.
</p></div>
</div>
</div>
<a name="perlnut2-CHP-20-SECT-5.2" /><div class="sect2">
<h3 class="sect2">20.5.2. URI::Escape</h3>

<p>This module escapes or unescapes
"unsafe" characters within a URL
string. Unsafe characters in URLs are described by RFC 1738. Before
you form URI::URL objects and use that class's
methods, you should make sure your strings are properly escaped. This
module does not create its own objects; it exports the following
functions:
</p>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>uri_escape</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
uri_escape <em class="replaceable">uri</em>, [<em class="replaceable">regexp</em>]
</pre><p>Given a URI as the first parameter, returns the equivalent URI with
certain characters replaced with <tt class="literal">%</tt> followed by two
hexadecimal digits. The first parameter can be a text string, such as
<tt class="literal">"http:www.oreilly.com"</tt>, or an object of type
URI::URL. When invoked without a second parameter,
<tt class="literal">uri_escape</tt> escapes characters specified by RFC
1738. Otherwise, you can pass in a regular expression (in the context
of <tt class="literal">[ ]</tt>) of characters to escape as the second
parameter. For example:
</p><blockquote><pre class="code">$escaped_uri = uri_escape($uri, 'aeiou')</pre></blockquote><p>This code escapes all lowercase vowels in <tt class="literal">$uri</tt> and
returns the escaped version.
</p></div>

<a name="INDEX-2634" /><a name="INDEX-2635" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>uri_unescape</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
uri_unescape <em class="replaceable">uri</em>
</pre><p>Substitutes any instance of <tt class="literal">%</tt> followed by two
hexadecimal digits back into its original form and returns the entire
URI in unescaped form.<a name="INDEX-2634" /><a name="INDEX-2635" /> 
</p></div>

</div>
<a name="perlnut2-CHP-20-SECT-5.3" /><div class="sect2">
<h3 class="sect2">20.5.3. URI::URL</h3>

<p><a name="INDEX-2636" /><a name="INDEX-2637" /><a name="INDEX-2638" />This module creates URL objects that
store all the elements of a URL. These objects are used by the
<tt class="literal">request</tt> method of LWP::UserAgent for server
addresses, port numbers, filenames, protocol, and many other elements
that can be loaded into a URL.
</p>

<p><a name="INDEX-2639" />The <tt class="literal">new</tt> constructor
is used to make a URI::URL object:
</p>

<blockquote><pre class="code">$url = URI::URL-&gt;new($url_string [, $base_url])</pre></blockquote>

<p>This method creates a new URI::URL object with the URL given as the
first parameter. An optional base URL can be specified as the second
parameter and is useful for generating an absolute URL from a
relative URL.
</p>

<p>The following methods are for the URI::URL class.</p>


<a name="INDEX-2640" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>abs</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">url</em>-&gt;abs([<em class="replaceable">base</em>, [<em class="replaceable">scheme</em>]])
</pre><p><a name="INDEX-2640" />Returns the absolute URL, given a base.
If invoked with no parameters, any previous definition of the base is
used. The second parameter is a Boolean that modifies
<tt class="literal">abs</tt>'s behavior. When the second
parameter is nonzero, <tt class="literal">abs</tt> will accept a relative
URL with a scheme but no host, such as
<tt class="literal">http:index.html</tt>.
</p></div>

<a name="INDEX-2641" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>as_string</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">url</em>-&gt;as_string(  )
</pre><p><a name="INDEX-2641" />Returns the URL as a scalar string. All
defined components of the URL are included in the string.
</p></div>