<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">=encoding UTF8

=head1 NAME

URI::Fast - A fast(er) URI parser

=head1 SYNOPSIS

  use URI::Fast qw(uri);

  my $uri = uri 'http://www.example.com/some/path?fnord=slack&amp;foo=bar';

  if ($uri-&gt;scheme =~ /http(s)?/) {
    my @path  = $uri-&gt;path;
    my $fnord = $uri-&gt;param('fnord');
    my $foo   = $uri-&gt;param('foo');
  }

  if ($uri-&gt;path =~ /\/login/ &amp;&amp; $uri-&gt;scheme ne 'https') {
    $uri-&gt;scheme('https');
    $uri-&gt;param('upgraded', 1);
  }

=head1 DESCRIPTION

C&lt;URI::Fast&gt; is a faster alternative to L&lt;URI&gt;. It is written in C and provides
basic parsing and modification of a URI.

L&lt;URI&gt; is an excellent module; it is battle-tested, robust, and handles many
edge cases. As a result, it is rather slower than it would otherwise be for
more trivial cases, such as inspecting the path or updating a single query
parameter.

=head1 EXPORTED SUBROUTINES

Subroutines are exported on demand.

=head2 uri

Accepts a URI string, minimally parses it, and returns a C&lt;URI::Fast&gt; object.

=head2 iri

Similar to L&lt;/uri&gt;, but returns a C&lt;URI::Fast::IRI&gt; object. A C&lt;URI::Fast::IRI&gt;
differs from a C&lt;URI::Fast&gt; in that UTF-8 characters are permitted and will not
be percent-encoded when modified.

=head2 uri_split

Behaves (hopefully) identically to L&lt;URI::Split&gt;, but roughly twice as fast.

=head2 encode/decode

See L&lt;/ENCODING&gt;.

=head1 ATTRIBUTES

Unless otherwise specified, all attributes serve as full accessors, allowing
the URI segment to be both retrieved and modified.

Each attribute further has a matching clearer method (C&lt;clear_*&gt;) which unsets
its value.

=head2 scheme

Gets or sets the scheme portion of the URI (e.g. C&lt;http&gt;), excluding C&lt;://&gt;.

=head2 auth

The authorization section is composed of the username, password, host name, and
port number:

  hostname.com
  someone@hostname.com
  someone:secret@hostname.com:1234

Setting this field may be done with a string (see the note below about
L&lt;/ENCODING&gt;) or a hash reference of individual field names (C&lt;usr&gt;, C&lt;pwd&gt;,
C&lt;host&gt;, and C&lt;port&gt;). In both cases, the existing values are completely
replaced by the new values and any values not present are deleted.

=head3 usr

The username segment of the authorization string. Updating this value alters
L&lt;/auth&gt;.

=head3 pwd

The password segment of the authorization string. Updating this value alters
L&lt;/auth&gt;.

=head3 host

The host name segment of the authorization string. May be a domain string or an
IP address. Updating this value alters L&lt;/auth&gt;.

=head3 port

The port number segment of the authorization string. Updating this value alters
L&lt;/auth&gt;.

=head2 path

In scalar context, returns the entire path string. In list context, returns a
list of path segments, split by C&lt;/&gt;.

The path may also be updated using either a string or an array ref of segments:

  $uri-&gt;path('/foo/bar');
  $uri-&gt;path(['foo', 'bar']);

=head2 query

In scalar context, returns the complete query string, excluding the leading
C&lt;?&gt;. The query string may be set in several ways.

  $uri-&gt;query("foo=bar&amp;baz=bat"); # note: no percent-encoding performed
  $uri-&gt;query({foo =&gt; 'bar', baz =&gt; 'bat'}); # foo=bar&amp;baz=bat
  $uri-&gt;query({foo =&gt; 'bar', baz =&gt; 'bat'}, ';'); # foo=bar;baz=bat

In list context, returns a hash ref mapping query keys to array refs of their
values (see L&lt;/query_hash&gt;).

=head3 query_keys

Does a fast scan of the query string and returns a list of unique parameter
names that appear in the query string.

=head3 query_hash

Scans the query string and returns a hash ref of key/value pairs. Values are
returned as an array ref, as keys may appear multiple times.

=head3 param

Gets or sets a parameter value. Setting a parameter value will replace existing
values completely; the L&lt;/query&gt; string will also be updated. Setting a
parameter to C&lt;undef&gt; deletes the parameter from the URI.

  $uri-&gt;param('foo', ['bar', 'baz']);
  $uri-&gt;param('fnord', 'slack');

  my $value_scalar    = $uri-&gt;param('fnord'); # fnord appears once
  my @value_list      = $uri-&gt;param('foo');   # foo appears twice
  my $value_scalar    = $uri-&gt;param('foo');   # croaks; expected single value but foo has multiple

  # Delete 'foo'
  $uri-&gt;param('foo', undef);

An optional third parameter may be specified to control the character used to
separate key/value pairs.

  $uri-&gt;param('foo', 'bar', ';'); # foo=bar
  $uri-&gt;param('baz', 'bat', ';'); # foo=bar;baz=bat

=head3 add_param

Updates the query string by adding a new value for the specified key. If the
key already exists in the query string, the new value is appended without
altering the original value.

  $uri-&gt;param('foo', 'bar');  # foo=bar
  $uri-&gt;param('foo', 'baz');  # foo=bar&amp;foo=baz

=head2 frag

The fragment section of the URI, excluding the leading C&lt;#&gt;.

=head1 ENCODING

C&lt;URI::Fast&gt; tries to do the right thing in most cases with regard to reserved
and non-ASCII characters. C&lt;URI::Fast&gt; will fully encode reserved and non-ASCII
characters when setting C&lt;individual&gt; values. However, the "right thing" is a
bit ambiguous when it comes to setting compound fields like L&lt;/auth&gt;, L&lt;/path&gt;,
and L&lt;/query&gt;.

When setting these fields with a string value, reserved characters are expected
to be present, and are therefore accepted as-is. However, any non-ASCII
characters will be percent-encoded (since they are unambiguous and there is no
risk of double-encoding them).

  $uri-&gt;auth('someone:secret@áżŹĎÎ´ÎżĎ.com:1234');
  print $uri-&gt;auth; # "someone:secret@%E1%BF%AC%CF%8C%CE%B4%CE%BF%CF%82.com:1234"

On the other hand, when setting these fields with a I&lt;reference&gt; value, each
field is fully percent-encoded:

  $uri-&gt;auth({usr =&gt; 'some one', host =&gt; 'somewhere.com'});
  print $uri-&gt;auth; # "some%20one@somewhere.com"

The same goes for return values. For compound fields returning a string,
non-ASCII characters are decoded but reserved characters are not. When
returning a list or reference of the deconstructed field, individual values are
decoded of both reserved and non-ASCII characters.

=head2 encode

Percent-encodes a string for use in a URI. By default, both reserved and UTF-8
chars (C&lt;! * ' ( ) ; : @ &amp; = + $ , / ? # [ ] %&gt;) are encoded.

A second (optional) parameter provides a string containing any characters the
caller does not wish to be encoded. An empty string will result in the default
behavior described above.

For example, to encode all characters in a query-like string I&lt;except&gt; for
those used by the query:

  my $encoded = URI::Fast::encode($some_string, '?&amp;=');

=head2 decode

Decodes a percent-encoded string.

  my $decoded = URI::Fast::decode($some_string);

=head1 SPEED

See L&lt;URI::Fast::Benchmarks&gt;.

=head1 SEE ALSO

=over

=item L&lt;URI&gt;

The de facto standard.

=item L&lt;Panda::URI&gt;

Written in C++ and purportedly very fast, but appears to only support Linux.

=back

=head1 ACKNOWLEDGEMENTS

Thanks to L&lt;ZipRecruiter|https://www.ziprecruiter.com&gt; for encouraging their
employees to contribute back to the open source ecosystem. Without their
dedication to quality software development this distribution would not exist.

=head1 AUTHOR

Jeff Ober &lt;sysread@fastmail.fm&gt;

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Jeff Ober.

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

</pre></body></html>