uri.html

来自「perl教程」· HTML 代码 · 共 912 行 · 第 1/3 页

If not, then $uri is simply returned.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="generic_methods">GENERIC METHODS</a></h1>
<p>The following methods are available to schemes that use the
common/generic syntax for hierarchical namespaces.  The descriptions of
schemes below indicate which these are.  Unknown schemes are
assumed to support the generic syntax, and therefore the following
methods:</p>
<dl>
<dt><strong><a name="item_authority">$uri-&gt;authority</a></strong>

<dt><strong>$uri-&gt;authority( $new_authority )</strong>

<dd>
<p>Sets and returns the escaped authority component
of the $uri.</p>
</dd>
</li>
<dt><strong>$uri-&gt;path</strong>

<dt><strong>$uri-&gt;path( $new_path )</strong>

<dd>
<p>Sets and returns the escaped path component of
the $uri (the part between the host name and the query or fragment).
The path can never be undefined, but it can be the empty string.</p>
</dd>
</li>
<dt><strong><a name="item_path_query">$uri-&gt;path_query</a></strong>

<dt><strong>$uri-&gt;path_query( $new_path_query )</strong>

<dd>
<p>Sets and returns the escaped path and query
components as a single entity.  The path and the query are
separated by a &quot;?&quot; character, but the query can itself contain &quot;?&quot;.</p>
</dd>
</li>
<dt><strong><a name="item_path_segments">$uri-&gt;path_segments</a></strong>

<dt><strong>$uri-&gt;path_segments( $segment, ... )</strong>

<dd>
<p>Sets and returns the path.  In a scalar context, it returns
the same value as $uri-&gt;path.  In a list context, it returns the
unescaped path segments that make up the path.  Path segments that
have parameters are returned as an anonymous array.  The first element
is the unescaped path segment proper;  subsequent elements are escaped
parameter strings.  Such an anonymous array uses overloading so it can
be treated as a string too, but this string does not include the
parameters.</p>
</dd>
<dd>
<p>Note that absolute paths have the empty string as their first
<em>path_segment</em>, i.e. the <em>path</em> <code>/foo/bar</code> have 3
<em>path_segments</em>; &quot;&quot;, &quot;foo&quot; and &quot;bar&quot;.</p>
</dd>
</li>
<dt><strong><a name="item_query">$uri-&gt;query</a></strong>

<dt><strong>$uri-&gt;query( $new_query )</strong>

<dd>
<p>Sets and returns the escaped query component of
the $uri.</p>
</dd>
</li>
<dt><strong><a name="item_query_form">$uri-&gt;query_form</a></strong>

<dt><strong>$uri-&gt;query_form( $key1 =&gt; $val1, $key2 =&gt; $val2, ... )</strong>

<dt><strong>$uri-&gt;query_form( \@key_value_pairs )</strong>

<dt><strong>$uri-&gt;query_form( \%hash )</strong>

<dd>
<p>Sets and returns query components that use the
<em>application/x-www-form-urlencoded</em> format.  Key/value pairs are
separated by &quot;&amp;&quot;, and the key is separated from the value by a &quot;=&quot;
character.</p>
</dd>
<dd>
<p>The form can be set either by passing separate key/value pairs, or via
an array or hash reference.  Passing an empty array or an empty hash
removes the query component, whereas passing no arguments at all leaves
the component unchanged.  The order of keys is undefined if a hash
reference is passed.  The old value is always returned as a list of
separate key/value pairs.  Assigning this list to a hash is unwise as
the keys returned might repeat.</p>
</dd>
<dd>
<p>The values passed when setting the form can be plain strings or
references to arrays of strings.  Passing an array of values has the
same effect as passing the key repeatedly with one value at a time.
All the following statements have the same effect:</p>
</dd>
<dd>
<pre>
    <span class="variable">$uri</span><span class="operator">-&gt;</span><span class="variable">query_form</span><span class="operator">(</span><span class="string">foo</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">,</span> <span class="string">foo</span> <span class="operator">=&gt;</span> <span class="number">2</span><span class="operator">);</span>
    <span class="variable">$uri</span><span class="operator">-&gt;</span><span class="variable">query_form</span><span class="operator">(</span><span class="string">foo</span> <span class="operator">=&gt;</span> <span class="operator">[</span><span class="number">1</span><span class="operator">,</span> <span class="number">2</span><span class="operator">]</span><span class="operator">);</span>
    <span class="variable">$uri</span><span class="operator">-&gt;</span><span class="variable">query_form</span><span class="operator">(</span><span class="operator">[</span> <span class="string">foo</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">,</span> <span class="string">foo</span> <span class="operator">=&gt;</span> <span class="number">2</span> <span class="operator">]</span><span class="operator">);</span>
    <span class="variable">$uri</span><span class="operator">-&gt;</span><span class="variable">query_form</span><span class="operator">(</span><span class="operator">[</span> <span class="string">foo</span> <span class="operator">=&gt;</span> <span class="operator">[</span><span class="number">1</span><span class="operator">,</span> <span class="number">2</span><span class="operator">]</span> <span class="operator">]</span><span class="operator">);</span>
    <span class="variable">$uri</span><span class="operator">-&gt;</span><span class="variable">query_form</span><span class="operator">(</span><span class="operator">{</span> <span class="string">foo</span> <span class="operator">=&gt;</span> <span class="operator">[</span><span class="number">1</span><span class="operator">,</span> <span class="number">2</span><span class="operator">]</span> <span class="operator">}</span><span class="operator">);</span>
</pre>
</dd>
<dd>
<p>The <code>URI::QueryParam</code> module can be loaded to add further methods to
manipulate the form of a URI.  See <a href="../lib/URI/QueryParam.html">the URI::QueryParam manpage</a> for details.</p>
</dd>
</li>
<dt><strong><a name="item_query_keywords">$uri-&gt;query_keywords</a></strong>

<dt><strong>$uri-&gt;query_keywords( $keywords, ... )</strong>

<dt><strong>$uri-&gt;query_keywords( \@keywords )</strong>

<dd>
<p>Sets and returns query components that use the
keywords separated by &quot;+&quot; format.</p>
</dd>
<dd>
<p>The keywords can be set either by passing separate keywords directly
or by passing a reference to an array of keywords.  Passing an empty
array removes the query component, whereas passing no arguments at
all leaves the component unchanged.  The old value is always returned
as a list of separate words.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="server_methods">SERVER METHODS</a></h1>
<p>For schemes where the <em>authority</em> component denotes an Internet host,
the following methods are available in addition to the generic
methods.</p>
<dl>
<dt><strong><a name="item_userinfo">$uri-&gt;userinfo</a></strong>

<dt><strong>$uri-&gt;userinfo( $new_userinfo )</strong>

<dd>
<p>Sets and returns the escaped userinfo part of the
authority component.</p>
</dd>
<dd>
<p>For some schemes this is a user name and a password separated by
a colon.  This practice is not recommended. Embedding passwords in
clear text (such as URI) has proven to be a security risk in almost
every case where it has been used.</p>
</dd>
</li>
<dt><strong><a name="item_host">$uri-&gt;host</a></strong>

<dt><strong>$uri-&gt;host( $new_host )</strong>

<dd>
<p>Sets and returns the unescaped hostname.</p>
</dd>
<dd>
<p>If the $new_host string ends with a colon and a number, then this
number also sets the port.</p>
</dd>
</li>
<dt><strong><a name="item_port">$uri-&gt;port</a></strong>

<dt><strong>$uri-&gt;port( $new_port )</strong>

<dd>
<p>Sets and returns the port.  The port is a simple integer
that should be greater than 0.</p>
</dd>
<dd>
<p>If a port is not specified explicitly in the URI, then the URI scheme's default port
is returned. If you don't want the default port
substituted, then you can use the $uri-&gt;_port method instead.</p>
</dd>
</li>
<dt><strong><a name="item_host_port">$uri-&gt;host_port</a></strong>

<dt><strong>$uri-&gt;host_port( $new_host_port )</strong>

<dd>
<p>Sets and returns the host and port as a single
unit.  The returned value includes a port, even if it matches the
default port.  The host part and the port part are separated by a
colon: &quot;:&quot;.</p>
</dd>
</li>
<dt><strong><a name="item_default_port">$uri-&gt;default_port</a></strong>

<dd>
<p>Returns the default port of the URI scheme to which $uri
belongs.  For <em>http</em> this is the number 80, for <em>ftp</em> this
is the number 21, etc.  The default port for a scheme can not be
changed.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="schemespecific_support">SCHEME-SPECIFIC SUPPORT</a></h1>
<p>Scheme-specific support is provided for the following URI schemes.  For <code>URI</code>
objects that do not belong to one of these, you can only use the common and
generic methods.</p>
<dl>
<dt><strong><a name="item_data_3a"><strong>data</strong>:</a></strong>

<dd>
<p>The <em>data</em> URI scheme is specified in RFC 2397.  It allows inclusion
of small data items as &quot;immediate&quot; data, as if it had been included
externally.</p>
</dd>
<dd>
<p><code>URI</code> objects belonging to the data scheme support the common methods
and two new methods to access their scheme-specific components:
$uri-&gt;media_type and $uri-&gt;data.  See <a href="../lib/URI/data.html">the URI::data manpage</a> for details.</p>
</dd>
</li>
<dt><strong><a name="item_file_3a"><strong>file</strong>:</a></strong>

<dd>
<p>An old specification of the <em>file</em> URI scheme is found in RFC 1738.
A new RFC 2396 based specification in not available yet, but file URI
references are in common use.</p>
</dd>
<dd>
<p><code>URI</code> objects belonging to the file scheme support the common and
generic methods.  In addition, they provide two methods for mapping file URIs
back to local file names; $uri-&gt;file and $uri-&gt;dir.  See <a href="../lib/URI/file.html">the URI::file manpage</a>
for details.</p>
</dd>
</li>
<dt><strong><a name="item_ftp_3a"><strong>ftp</strong>:</a></strong>

<dd>
<p>An old specification of the <em>ftp</em> URI scheme is found in RFC 1738.  A
new RFC 2396 based specification in not available yet, but ftp URI
references are in common use.</p>
</dd>
<dd>
<p><code>URI</code> objects belonging to the ftp scheme support the common,
generic and server methods.  In addition, they provide two methods for
accessing the userinfo sub-components: $uri-&gt;user and $uri-&gt;password.</p>
</dd>
</li>
<dt><strong><a name="item_gopher_3a"><strong>gopher</strong>:</a></strong>

<dd>
<p>The <em>gopher</em> URI scheme is specified in
&lt;draft-murali-url-gopher-1996-12-04&gt; and will hopefully be available
as a RFC 2396 based specification.</p>
</dd>
<dd>
<p><code>URI</code> objects belonging to the gopher scheme support the common,
generic and server methods. In addition, they support some methods for
accessing gopher-specific path components: $uri-&gt;gopher_type,
$uri-&gt;selector, $uri-&gt;search, $uri-&gt;string.</p>
</dd>
</li>
<dt><strong><a name="item_http_3a"><strong>http</strong>:</a></strong>

<dd>
<p>The <em>http</em> URI scheme is specified in RFC 2616.
The scheme is used to reference resources hosted by HTTP servers.</p>
</dd>
<dd>
<p><code>URI</code> objects belonging to the http scheme support the common,
generic and server methods.</p>
</dd>
</li>
<dt><strong><a name="item_https_3a"><strong>https</strong>:</a></strong>

<dd>
<p>The <em>https</em> URI scheme is a Netscape invention which is commonly
implemented.  The scheme is used to reference HTTP servers through SSL
connections.  Its syntax is the same as http, but the default
port is different.</p>
</dd>
</li>
<dt><strong><a name="item_ldap_3a"><strong>ldap</strong>:</a></strong>

<dd>
<p>The <em>ldap</em> URI scheme is specified in RFC 2255.  LDAP is the
Lightweight Directory Access Protocol.  An ldap URI describes an LDAP
search operation to perform to retrieve information from an LDAP
directory.</p>
</dd>
<dd>
<p><code>URI</code> objects belonging to the ldap scheme support the common,
generic and server methods as well as ldap-specific methods: $uri-&gt;dn,
$uri-&gt;attributes, $uri-&gt;scope, $uri-&gt;filter, $uri-&gt;extensions.  See
<a href="../lib/URI/ldap.html">the URI::ldap manpage</a> for details.</p>
</dd>
</li>
<dt><strong><a name="item_ldapi_3a"><strong>ldapi</strong>:</a></strong>

<dd>