{
    "content": [
        {
            "type": "text",
            "text": "# URI (perldoc)\n\n**Summary:** URI - Uniform Resource Identifiers (absolute and relative)\n\n**Synopsis:** use URI ();\n$u1 = URI->new(\"http://www.example.com\");\n$u2 = URI->new(\"foo\", \"http\");\n$u3 = $u2->abs($u1);\n$u4 = $u3->clone;\n$u5 = URI->new(\"HTTP://WWW.example.com:80\")->canonical;\n$str = $u->asstring;\n$str = \"$u\";\n$scheme = $u->scheme;\n$opaque = $u->opaque;\n$path   = $u->path;\n$frag   = $u->fragment;\n$u->scheme(\"ftp\");\n$u->host(\"ftp.example.com\");\n$u->path(\"cpan/\");\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (20 lines)\n- **DESCRIPTION** (30 lines)\n- **CONSTRUCTORS** (49 lines)\n- **COMMON METHODS** (106 lines)\n- **GENERIC METHODS** (93 lines)\n- **SERVER METHODS** (54 lines)\n- **SCHEME-SPECIFIC SUPPORT** (214 lines)\n- **CONFIGURATION VARIABLES** (34 lines)\n- **BUGS** (29 lines)\n- **SEE ALSO** (12 lines)\n- **COPYRIGHT** (7 lines)\n- **AUTHORS / ACKNOWLEDGMENTS** (11 lines)\n\n## Full Content\n\n### NAME\n\nURI - Uniform Resource Identifiers (absolute and relative)\n\n### SYNOPSIS\n\nuse URI ();\n\n$u1 = URI->new(\"http://www.example.com\");\n$u2 = URI->new(\"foo\", \"http\");\n$u3 = $u2->abs($u1);\n$u4 = $u3->clone;\n$u5 = URI->new(\"HTTP://WWW.example.com:80\")->canonical;\n\n$str = $u->asstring;\n$str = \"$u\";\n\n$scheme = $u->scheme;\n$opaque = $u->opaque;\n$path   = $u->path;\n$frag   = $u->fragment;\n\n$u->scheme(\"ftp\");\n$u->host(\"ftp.example.com\");\n$u->path(\"cpan/\");\n\n### DESCRIPTION\n\nThis module implements the \"URI\" class. Objects of this class represent\n\"Uniform Resource Identifier references\" as specified in RFC 2396 (and\nupdated by RFC 2732).\n\nA Uniform Resource Identifier is a compact string of characters that\nidentifies an abstract or physical resource. A Uniform Resource\nIdentifier can be further classified as either a Uniform Resource\nLocator (URL) or a Uniform Resource Name (URN). The distinction between\nURL and URN does not matter to the \"URI\" class interface. A\n\"URI-reference\" is a URI that may have additional information attached\nin the form of a fragment identifier.\n\nAn absolute URI reference consists of three parts: a *scheme*, a\n*scheme-specific part* and a *fragment* identifier. A subset of URI\nreferences share a common syntax for hierarchical namespaces. For these,\nthe scheme-specific part is further broken down into *authority*, *path*\nand *query* components. These URIs can also take the form of relative\nURI references, where the scheme (and usually also the authority)\ncomponent is missing, but implied by the context of the URI reference.\nThe three forms of URI reference syntax are summarized as follows:\n\n<scheme>:<scheme-specific-part>#<fragment>\n<scheme>://<authority><path>?<query>#<fragment>\n<path>?<query>#<fragment>\n\nThe components into which a URI reference can be divided depend on the\n*scheme*. The \"URI\" class provides methods to get and set the individual\ncomponents. The methods available for a specific \"URI\" object depend on\nthe scheme.\n\n### CONSTRUCTORS\n\nThe following methods construct new \"URI\" objects:\n\n$uri = URI->new( $str )\n$uri = URI->new( $str, $scheme )\nConstructs a new URI object. The string representation of a URI is\ngiven as argument, together with an optional scheme specification.\nCommon URI wrappers like \"\" and <>, as well as leading and trailing\nwhite space, are automatically removed from the $str argument before\nit is processed further.\n\nThe constructor determines the scheme, maps this to an appropriate\nURI subclass, constructs a new object of that class and returns it.\n\nIf the scheme isn't one of those that URI recognizes, you still get\nan URI object back that you can access the generic methods on. The\n\"$uri->hasrecognizedscheme\" method can be used to test for this.\n\nThe $scheme argument is only used when $str is a relative URI. It\ncan be either a simple string that denotes the scheme, a string\ncontaining an absolute URI reference, or an absolute \"URI\" object.\nIf no $scheme is specified for a relative URI $str, then $str is\nsimply treated as a generic URI (no scheme-specific methods\navailable).\n\nThe set of characters available for building URI references is\nrestricted (see URI::Escape). Characters outside this set are\nautomatically escaped by the URI constructor.\n\n$uri = URI->newabs( $str, $baseuri )\nConstructs a new absolute URI object. The $str argument can denote a\nrelative or absolute URI. If relative, then it is absolutized using\n$baseuri as base. The $baseuri must be an absolute URI.\n\n$uri = URI::file->new( $filename )\n$uri = URI::file->new( $filename, $os )\nConstructs a new *file* URI from a file name. See URI::file.\n\n$uri = URI::file->newabs( $filename )\n$uri = URI::file->newabs( $filename, $os )\nConstructs a new absolute *file* URI from a file name. See\nURI::file.\n\n$uri = URI::file->cwd\nReturns the current working directory as a *file* URI. See\nURI::file.\n\n$uri->clone\nReturns a copy of the $uri.\n\n### COMMON METHODS\n\nThe methods described in this section are available for all \"URI\"\nobjects.\n\nMethods that give access to components of a URI always return the old\nvalue of the component. The value returned is \"undef\" if the component\nwas not present. There is generally a difference between a component\nthat is empty (represented as \"\") and a component that is missing\n(represented as \"undef\"). If an accessor method is given an argument, it\nupdates the corresponding component in addition to returning the old\nvalue of the component. Passing an undefined argument removes the\ncomponent (if possible). The description of each accessor method\nindicates whether the component is passed as an escaped\n(percent-encoded) or an unescaped string. A component that can be\nfurther divided into sub-parts are usually passed escaped, as unescaping\nmight change its semantics.\n\nThe common methods available for all URI are:\n\n$uri->scheme\n$uri->scheme( $newscheme )\nSets and returns the scheme part of the $uri. If the $uri is\nrelative, then $uri->scheme returns \"undef\". If called with an\nargument, it updates the scheme of $uri, possibly changing the class\nof $uri, and returns the old scheme value. The method croaks if the\nnew scheme name is illegal; a scheme name must begin with a letter\nand must consist of only US-ASCII letters, numbers, and a few\nspecial marks: \".\", \"+\", \"-\". This restriction effectively means\nthat the scheme must be passed unescaped. Passing an undefined\nargument to the scheme method makes the URI relative (if possible).\n\nLetter case does not matter for scheme names. The string returned by\n$uri->scheme is always lowercase. If you want the scheme just as it\nwas written in the URI in its original case, you can use the\n$uri->scheme method instead.\n\n$uri->hasrecognizedscheme\nReturns TRUE if the URI scheme is one that URI recognizes.\n\nIt will also be TRUE for relative URLs where a recognized scheme was\nprovided to the constructor, even if \"$uri->scheme\" returns \"undef\"\nfor these.\n\n$uri->opaque\n$uri->opaque( $newopaque )\nSets and returns the scheme-specific part of the $uri (everything\nbetween the scheme and the fragment) as an escaped string.\n\n$uri->path\n$uri->path( $newpath )\nSets and returns the same value as $uri->opaque unless the URI\nsupports the generic syntax for hierarchical namespaces. In that\ncase the generic method is overridden to set and return the part of\nthe URI between the *host name* and the *fragment*.\n\n$uri->fragment\n$uri->fragment( $newfrag )\nReturns the fragment identifier of a URI reference as an escaped\nstring.\n\n$uri->asstring\nReturns a URI object to a plain ASCII string. URI objects are also\nconverted to plain strings automatically by overloading. This means\nthat $uri objects can be used as plain strings in most Perl\nconstructs.\n\n$uri->asiri\nReturns a Unicode string representing the URI. Escaped UTF-8\nsequences representing non-ASCII characters are turned into their\ncorresponding Unicode code point.\n\n$uri->canonical\nReturns a normalized version of the URI. The rules for normalization\nare scheme-dependent. They usually involve lowercasing the scheme\nand Internet host name components, removing the explicit port\nspecification if it matches the default port, uppercasing all escape\nsequences, and unescaping octets that can be better represented as\nplain characters.\n\nFor efficiency reasons, if the $uri is already in normalized form,\nthen a reference to it is returned instead of a copy.\n\n$uri->eq( $otheruri )\nURI::eq( $firsturi, $otheruri )\nTests whether two URI references are equal. URI references that\nnormalize to the same string are considered equal. The method can\nalso be used as a plain function which can also test two string\narguments.\n\nIf you need to test whether two \"URI\" object references denote the\nsame object, use the '==' operator.\n\n$uri->abs( $baseuri )\nReturns an absolute URI reference. If $uri is already absolute, then\na reference to it is simply returned. If the $uri is relative, then\na new absolute URI is constructed by combining the $uri and the\n$baseuri, and returned.\n\n$uri->rel( $baseuri )\nReturns a relative URI reference if it is possible to make one that\ndenotes the same resource relative to $baseuri. If not, then $uri\nis simply returned.\n\n$uri->secure\nReturns a TRUE value if the URI is considered to point to a resource\non a secure channel, such as an SSL or TLS encrypted one.\n\n### GENERIC METHODS\n\nThe following methods are available to schemes that use the\ncommon/generic syntax for hierarchical namespaces. The descriptions of\nschemes below indicate which these are. Unrecognized schemes are assumed\nto support the generic syntax, and therefore the following methods:\n\n$uri->authority\n$uri->authority( $newauthority )\nSets and returns the escaped authority component of the $uri.\n\n$uri->path\n$uri->path( $newpath )\nSets and returns the escaped path component of the $uri (the part\nbetween the host name and the query or fragment). The path can never\nbe undefined, but it can be the empty string.\n\n$uri->pathquery\n$uri->pathquery( $newpathquery )\nSets and returns the escaped path and query components as a single\nentity. The path and the query are separated by a \"?\" character, but\nthe query can itself contain \"?\".\n\n$uri->pathsegments\n$uri->pathsegments( $segment, ... )\nSets and returns the path. In a scalar context, it returns the same\nvalue as $uri->path. In a list context, it returns the unescaped\npath segments that make up the path. Path segments that have\nparameters are returned as an anonymous array. The first element is\nthe unescaped path segment proper; subsequent elements are escaped\nparameter strings. Such an anonymous array uses overloading so it\ncan be treated as a string too, but this string does not include the\nparameters.\n\nNote that absolute paths have the empty string as their first\n*pathsegment*, i.e. the *path* \"/foo/bar\" have 3 *pathsegments*;\n\"\", \"foo\" and \"bar\".\n\n$uri->query\n$uri->query( $newquery )\nSets and returns the escaped query component of the $uri.\n\n$uri->queryform\n$uri->queryform( $key1 => $val1, $key2 => $val2, ... )\n$uri->queryform( $key1 => $val1, $key2 => $val2, ..., $delim )\n$uri->queryform( \\@keyvaluepairs )\n$uri->queryform( \\@keyvaluepairs, $delim )\n$uri->queryform( \\%hash )\n$uri->queryform( \\%hash, $delim )\nSets and returns query components that use the\n*application/x-www-form-urlencoded* format. Key/value pairs are\nseparated by \"&\", and the key is separated from the value by a \"=\"\ncharacter.\n\nThe form can be set either by passing separate key/value pairs, or\nvia an array or hash reference. Passing an empty array or an empty\nhash removes the query component, whereas passing no arguments at\nall leaves the component unchanged. The order of keys is undefined\nif a hash reference is passed. The old value is always returned as a\nlist of separate key/value pairs. Assigning this list to a hash is\nunwise as the keys returned might repeat.\n\nThe values passed when setting the form can be plain strings or\nreferences to arrays of strings. Passing an array of values has the\nsame effect as passing the key repeatedly with one value at a time.\nAll the following statements have the same effect:\n\n$uri->queryform(foo => 1, foo => 2);\n$uri->queryform(foo => [1, 2]);\n$uri->queryform([ foo => 1, foo => 2 ]);\n$uri->queryform([ foo => [1, 2] ]);\n$uri->queryform({ foo => [1, 2] });\n\nThe $delim parameter can be passed as \";\" to force the key/value\npairs to be delimited by \";\" instead of \"&\" in the query string.\nThis practice is often recommended for URLs embedded in HTML or XML\ndocuments as this avoids the trouble of escaping the \"&\" character.\nYou might also set the $URI::DEFAULTQUERYFORMDELIMITER variable\nto \";\" for the same global effect.\n\nThe \"URI::QueryParam\" module can be loaded to add further methods to\nmanipulate the form of a URI. See URI::QueryParam for details.\n\n$uri->querykeywords\n$uri->querykeywords( $keywords, ... )\n$uri->querykeywords( \\@keywords )\nSets and returns query components that use the keywords separated by\n\"+\" format.\n\nThe keywords can be set either by passing separate keywords directly\nor by passing a reference to an array of keywords. Passing an empty\narray removes the query component, whereas passing no arguments at\nall leaves the component unchanged. The old value is always returned\nas a list of separate words.\n\n### SERVER METHODS\n\nFor schemes where the *authority* component denotes an Internet host,\nthe following methods are available in addition to the generic methods.\n\n$uri->userinfo\n$uri->userinfo( $newuserinfo )\nSets and returns the escaped userinfo part of the authority\ncomponent.\n\nFor some schemes this is a user name and a password separated by a\ncolon. This practice is not recommended. Embedding passwords in\nclear text (such as URI) has proven to be a security risk in almost\nevery case where it has been used.\n\n$uri->host\n$uri->host( $newhost )\nSets and returns the unescaped hostname.\n\nIf the $newhost string ends with a colon and a number, then this\nnumber also sets the port.\n\nFor IPv6 addresses the brackets around the raw address is removed in\nthe return value from $uri->host. When setting the host attribute to\nan IPv6 address you can use a raw address or one enclosed in\nbrackets. The address needs to be enclosed in brackets if you want\nto pass in a new port value as well.\n\n$uri->ihost\nReturns the host in Unicode form. Any IDNA A-labels are turned into\nU-labels.\n\n$uri->port\n$uri->port( $newport )\nSets and returns the port. The port is a simple integer that should\nbe greater than 0.\n\nIf a port is not specified explicitly in the URI, then the URI\nscheme's default port is returned. If you don't want the default\nport substituted, then you can use the $uri->port method instead.\n\n$uri->hostport\n$uri->hostport( $newhostport )\nSets and returns the host and port as a single unit. The returned\nvalue includes a port, even if it matches the default port. The host\npart and the port part are separated by a colon: \":\".\n\nFor IPv6 addresses the bracketing is preserved; thus\nURI->new(\"http://[::1]/\")->hostport returns \"[::1]:80\". Contrast\nthis with $uri->host which will remove the brackets.\n\n$uri->defaultport\nReturns the default port of the URI scheme to which $uri belongs.\nFor *http* this is the number 80, for *ftp* this is the number 21,\netc. The default port for a scheme can not be changed.\n\n### SCHEME-SPECIFIC SUPPORT\n\nScheme-specific support is provided for the following URI schemes. For\n\"URI\" objects that do not belong to one of these, you can only use the\ncommon and generic methods.\n\ndata:\nThe *data* URI scheme is specified in RFC 2397. It allows inclusion\nof small data items as \"immediate\" data, as if it had been included\nexternally.\n\n\"URI\" objects belonging to the data scheme support the common\nmethods and two new methods to access their scheme-specific\ncomponents: $uri->mediatype and $uri->data. See URI::data for\ndetails.\n\nfile:\nAn old specification of the *file* URI scheme is found in RFC 1738.\nA new RFC 2396 based specification in not available yet, but file\nURI references are in common use.\n\n\"URI\" objects belonging to the file scheme support the common and\ngeneric methods. In addition, they provide two methods for mapping\nfile URIs back to local file names; $uri->file and $uri->dir. See\nURI::file for details.\n\nftp:\nAn old specification of the *ftp* URI scheme is found in RFC 1738. A\nnew RFC 2396 based specification in not available yet, but ftp URI\nreferences are in common use.\n\n\"URI\" objects belonging to the ftp scheme support the common,\ngeneric and server methods. In addition, they provide two methods\nfor accessing the userinfo sub-components: $uri->user and\n$uri->password.\n\ngopher:\nThe *gopher* URI scheme is specified in\n<draft-murali-url-gopher-1996-12-04> and will hopefully be available\nas a RFC 2396 based specification.\n\n\"URI\" objects belonging to the gopher scheme support the common,\ngeneric and server methods. In addition, they support some methods\nfor accessing gopher-specific path components: $uri->gophertype,\n$uri->selector, $uri->search, $uri->string.\n\nhttp:\nThe *http* URI scheme is specified in RFC 2616. The scheme is used\nto reference resources hosted by HTTP servers.\n\n\"URI\" objects belonging to the http scheme support the common,\ngeneric and server methods.\n\nhttps:\nThe *https* URI scheme is a Netscape invention which is commonly\nimplemented. The scheme is used to reference HTTP servers through\nSSL connections. Its syntax is the same as http, but the default\nport is different.\n\nldap:\nThe *ldap* URI scheme is specified in RFC 2255. LDAP is the\nLightweight Directory Access Protocol. An ldap URI describes an LDAP\nsearch operation to perform to retrieve information from an LDAP\ndirectory.\n\n\"URI\" objects belonging to the ldap scheme support the common,\ngeneric and server methods as well as ldap-specific methods:\n$uri->dn, $uri->attributes, $uri->scope, $uri->filter,\n$uri->extensions. See URI::ldap for details.\n\nldapi:\nLike the *ldap* URI scheme, but uses a UNIX domain socket. The\nserver methods are not supported, and the local socket path is\navailable as $uri->unpath. The *ldapi* scheme is used by the\nOpenLDAP package. There is no real specification for it, but it is\nmentioned in various OpenLDAP manual pages.\n\nldaps:\nLike the *ldap* URI scheme, but uses an SSL connection. This scheme\nis deprecated, as the preferred way is to use the *starttls*\nmechanism.\n\nmailto:\nThe *mailto* URI scheme is specified in RFC 2368. The scheme was\noriginally used to designate the Internet mailing address of an\nindividual or service. It has (in RFC 2368) been extended to allow\nsetting of other mail header fields and the message body.\n\n\"URI\" objects belonging to the mailto scheme support the common\nmethods and the generic query methods. In addition, they support the\nfollowing mailto-specific methods: $uri->to, $uri->headers.\n\nNote that the \"foo@example.com\" part of a mailto is *not* the\n\"userinfo\" and \"host\" but instead the \"path\". This allows a mailto\nURI to contain multiple comma separated email addresses.\n\nmms:\nThe *mms* URL specification can be found at <http://sdp.ppona.com/>.\n\"URI\" objects belonging to the mms scheme support the common,\ngeneric, and server methods, with the exception of userinfo and\nquery-related sub-components.\n\nnews:\nThe *news*, *nntp* and *snews* URI schemes are specified in\n<draft-gilman-news-url-01> and will hopefully be available as an RFC\n2396 based specification soon. (Update: as of April 2010, they are\nin RFC 5538 <https://tools.ietf.org/html/rfc5538>.\n\n\"URI\" objects belonging to the news scheme support the common,\ngeneric and server methods. In addition, they provide some methods\nto access the path: $uri->group and $uri->message.\n\nnntp:\nSee *news* scheme.\n\nnntps:\nSee *news* scheme and RFC 5538\n<https://tools.ietf.org/html/rfc5538>.\n\npop:\nThe *pop* URI scheme is specified in RFC 2384. The scheme is used to\nreference a POP3 mailbox.\n\n\"URI\" objects belonging to the pop scheme support the common,\ngeneric and server methods. In addition, they provide two methods to\naccess the userinfo components: $uri->user and $uri->auth\n\nrlogin:\nAn old specification of the *rlogin* URI scheme is found in RFC\n1738. \"URI\" objects belonging to the rlogin scheme support the\ncommon, generic and server methods.\n\nrtsp:\nThe *rtsp* URL specification can be found in section 3.2 of RFC\n2326. \"URI\" objects belonging to the rtsp scheme support the common,\ngeneric, and server methods, with the exception of userinfo and\nquery-related sub-components.\n\nrtspu:\nThe *rtspu* URI scheme is used to talk to RTSP servers over UDP\ninstead of TCP. The syntax is the same as rtsp.\n\nrsync:\nInformation about rsync is available from <http://rsync.samba.org/>.\n\"URI\" objects belonging to the rsync scheme support the common,\ngeneric and server methods. In addition, they provide methods to\naccess the userinfo sub-components: $uri->user and $uri->password.\n\nsip:\nThe *sip* URI specification is described in sections 19.1 and 25 of\nRFC 3261. \"URI\" objects belonging to the sip scheme support the\ncommon, generic, and server methods with the exception of path\nrelated sub-components. In addition, they provide two methods to get\nand set *sip* parameters: $uri->paramsform and $uri->params.\n\nsips:\nSee *sip* scheme. Its syntax is the same as sip, but the default\nport is different.\n\nsnews:\nSee *news* scheme. Its syntax is the same as news, but the default\nport is different.\n\ntelnet:\nAn old specification of the *telnet* URI scheme is found in RFC\n1738. \"URI\" objects belonging to the telnet scheme support the\ncommon, generic and server methods.\n\ntn3270:\nThese URIs are used like *telnet* URIs but for connections to IBM\nmainframes. \"URI\" objects belonging to the tn3270 scheme support the\ncommon, generic and server methods.\n\nssh:\nInformation about ssh is available at <http://www.openssh.com/>.\n\"URI\" objects belonging to the ssh scheme support the common,\ngeneric and server methods. In addition, they provide methods to\naccess the userinfo sub-components: $uri->user and $uri->password.\n\nsftp:\n\"URI\" objects belonging to the sftp scheme support the common,\ngeneric and server methods. In addition, they provide methods to\naccess the userinfo sub-components: $uri->user and $uri->password.\n\nurn:\nThe syntax of Uniform Resource Names is specified in RFC 2141. \"URI\"\nobjects belonging to the urn scheme provide the common methods, and\nalso the methods $uri->nid and $uri->nss, which return the Namespace\nIdentifier and the Namespace-Specific String respectively.\n\nThe Namespace Identifier basically works like the Scheme identifier\nof URIs, and further divides the URN namespace. Namespace Identifier\nassignments are maintained at\n<http://www.iana.org/assignments/urn-namespaces>.\n\nLetter case is not significant for the Namespace Identifier. It is\nalways returned in lower case by the $uri->nid method. The\n$uri->nid method can be used if you want it in its original case.\n\nurn:isbn:\nThe \"urn:isbn:\" namespace contains International Standard Book\nNumbers (ISBNs) and is described in RFC 3187. A \"URI\" object\nbelonging to this namespace has the following extra methods (if the\nBusiness::ISBN module is available): $uri->isbn,\n$uri->isbnpublishercode, $uri->isbngroupcode (formerly\nisbncountrycode, which is still supported by issues a deprecation\nwarning), $uri->isbnasean.\n\nurn:oid:\nThe \"urn:oid:\" namespace contains Object Identifiers (OIDs) and is\ndescribed in RFC 3061. An object identifier consists of sequences of\ndigits separated by dots. A \"URI\" object belonging to this namespace\nhas an additional method called $uri->oid that can be used to\nget/set the oid value. In a list context, oid numbers are returned\nas separate elements.\n\n### CONFIGURATION VARIABLES\n\nThe following configuration variables influence how the class and its\nmethods behave:\n\n$URI::ABSALLOWRELATIVESCHEME\nSome older parsers used to allow the scheme name to be present in\nthe relative URL if it was the same as the base URL scheme. RFC 2396\nsays that this should be avoided, but you can enable this old\nbehaviour by setting the $URI::ABSALLOWRELATIVESCHEME variable to\na TRUE value. The difference is demonstrated by the following\nexamples:\n\nURI->new(\"http:foo\")->abs(\"http://host/a/b\")\n==>  \"http:foo\"\n\nlocal $URI::ABSALLOWRELATIVESCHEME = 1;\nURI->new(\"http:foo\")->abs(\"http://host/a/b\")\n==>  \"http:/host/a/foo\"\n\n$URI::ABSREMOTELEADINGDOTS\nYou can also have the abs() method ignore excess \"..\" segments in\nthe relative URI by setting $URI::ABSREMOTELEADINGDOTS to a TRUE\nvalue. The difference is demonstrated by the following examples:\n\nURI->new(\"../../../foo\")->abs(\"http://host/a/b\")\n==> \"http://host/../../foo\"\n\nlocal $URI::ABSREMOTELEADINGDOTS = 1;\nURI->new(\"../../../foo\")->abs(\"http://host/a/b\")\n==> \"http://host/foo\"\n\n$URI::DEFAULTQUERYFORMDELIMITER\nThis value can be set to \";\" to have the query form \"key=value\"\npairs delimited by \";\" instead of \"&\" which is the default.\n\n### BUGS\n\nThere are some things that are not quite right:\n\n*   Using regexp variables like $1 directly as arguments to the URI\naccessor methods does not work too well with current perl\nimplementations. I would argue that this is actually a bug in perl.\nThe workaround is to quote them. Example:\n\n/(...)/ || die;\n$u->query(\"$1\");\n\n*   The escaping (percent encoding) of chars in the 128 .. 255 range\npassed to the URI constructor or when setting URI parts using the\naccessor methods depend on the state of the internal UTF8 flag (see\nutf8::isutf8) of the string passed. If the UTF8 flag is set the\nUTF-8 encoded version of the character is percent encoded. If the\nUTF8 flag isn't set the Latin-1 version (byte) of the character is\npercent encoded. This basically exposes the internal encoding of\nPerl strings.\n\nPARSING URIs WITH REGEXP\nAs an alternative to this module, the following (official) regular\nexpression can be used to decode a URI:\n\nmy($scheme, $authority, $path, $query, $fragment) =\n$uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\\?([^#]*))?(?:#(.*))?|;\n\nThe \"URI::Split\" module provides the function urisplit() as a readable\nalternative.\n\n### SEE ALSO\n\nURI::file, URI::WithBase, URI::QueryParam, URI::Escape, URI::Split,\nURI::Heuristic\n\nRFC 2396: \"Uniform Resource Identifiers (URI): Generic Syntax\",\nBerners-Lee, Fielding, Masinter, August 1998.\n\n<http://www.iana.org/assignments/uri-schemes>\n\n<http://www.iana.org/assignments/urn-namespaces>\n\n<http://www.w3.org/Addressing/>\n\n### COPYRIGHT\n\nCopyright 1995-2009 Gisle Aas.\n\nCopyright 1995 Martijn Koster.\n\nThis program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n\n### AUTHORS / ACKNOWLEDGMENTS\n\nThis module is based on the \"URI::URL\" module, which in turn was\n(distantly) based on the \"wwwurl.pl\" code in the libwww-perl for perl4\ndeveloped by Roy Fielding, as part of the Arcadia project at the\nUniversity of California, Irvine, with contributions from Brooks Cutter.\n\n\"URI::URL\" was developed by Gisle Aas, Tim Bunce, Roy Fielding and\nMartijn Koster with input from other people on the libwww-perl mailing\nlist.\n\n\"URI\" and related subclasses was developed by Gisle Aas.\n\n"
        }
    ],
    "structuredContent": {
        "command": "URI",
        "section": "",
        "mode": "perldoc",
        "summary": "URI - Uniform Resource Identifiers (absolute and relative)",
        "synopsis": "use URI ();\n$u1 = URI->new(\"http://www.example.com\");\n$u2 = URI->new(\"foo\", \"http\");\n$u3 = $u2->abs($u1);\n$u4 = $u3->clone;\n$u5 = URI->new(\"HTTP://WWW.example.com:80\")->canonical;\n$str = $u->asstring;\n$str = \"$u\";\n$scheme = $u->scheme;\n$opaque = $u->opaque;\n$path   = $u->path;\n$frag   = $u->fragment;\n$u->scheme(\"ftp\");\n$u->host(\"ftp.example.com\");\n$u->path(\"cpan/\");",
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 20,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 30,
                "subsections": []
            },
            {
                "name": "CONSTRUCTORS",
                "lines": 49,
                "subsections": []
            },
            {
                "name": "COMMON METHODS",
                "lines": 106,
                "subsections": []
            },
            {
                "name": "GENERIC METHODS",
                "lines": 93,
                "subsections": []
            },
            {
                "name": "SERVER METHODS",
                "lines": 54,
                "subsections": []
            },
            {
                "name": "SCHEME-SPECIFIC SUPPORT",
                "lines": 214,
                "subsections": []
            },
            {
                "name": "CONFIGURATION VARIABLES",
                "lines": 34,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 29,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "AUTHORS / ACKNOWLEDGMENTS",
                "lines": 11,
                "subsections": []
            }
        ]
    }
}