NAME
MarpaX::RFC::RFC3986 - Uniform Resource Identifier (URI): Generic Syntax - Marpa Parser
VERSION
version 0.001
SYNOPSIS
use MarpaX::RFC::RFC3986;
use Try::Tiny;
use Data::Dumper;
print Dumper(MarpaX::RFC::RFC3986->new('http://www.perl.org'));
try {
print STDERR "\nThe following is an expected failure:\n";
MarpaX::RFC::RFC3986->new('http://invalid##');
} catch {
print STDERR "$_\n";
return;
}DESCRIPTION
This module parses an URI reference as per RFC3986 STD 66, with RFC6874 update about IPv6 Zone Identifiers. It is not intended as a replacement of the URI module, but more for data validation using a strict grammar with good error reporting.
URI DESCRIPTION
Quoted from the RFC here is the overall structure of an URI that will help understand the meaning of the methods thereafter:
foo://example.com:8042/over/there?name=ferret#nose
\_/ \______________/\_________/ \_________/ \__/
| | | | |
scheme authority path query fragment
| _____________________|__
/ \ / \
urn:example:animal:ferret:noseThe grammar is parsing both absolute URI and relative URI, the corresponding start rule being named a URI reference.
An absolute URI has the following structure:
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]while a relative URI is splitted into:
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Back to the overall structure, the authority is:
authority = [ userinfo "@" ] host [ ":" port ]where the host can be an IP-literal with Zone information:
IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
ZoneID = 1*( unreserved / pct-encoded )
IPv6addrz = IPv6address "%25" ZoneIDCLASS METHODS
MarpaX::RFC::RFC3986->new(@options) --> InstanceOf['MarpaX::RFC::RFC3986']
Instantiate a new object. Usage is either MarpaX::RFC::RFC3986->new(value => $url) or MarpaX::RFC::RFC3986->new($url). This method will croak if the the $url parameter cannot coerce to a string nor is a valid URI. The variable $self is used below to refer to this object instance.
MarpaX::RFC::RFC3986->grammar --> InstanceOf['Marpa::R2::Scanless::G']
A Marpa::R2::Scanless::G instance, hosting the computed grammar. This is a class variable, i.e. works also with $self.
MarpaX::RFC::RFC3986->bnf --> Str
The BNF grammar used to parse an URI. This is a class variable, i.e. works also with $self.
OBJECT METHODS
$self->value --> Str
The variable given in input to new().
$self->scheme --> Str|Undef
The URI scheme. Can be undefined.
$self->authority --> Str|Undef
The URI authority. Can be undefined.
$self->path --> Str
The URI path. Note that an URI always have a path, although it can be empty.
$self->query --> Str|Undef
The URI query. Can be undefined.
$self->fragment --> Str|Undef
The URI fragment. Can be undefined.
$self->hier_part --> Str|Undef
The URI hier part. Can be undefined.
$self->userinfo --> Str|Undef
The URI userinfo. Can be undefined.
$self->host --> Str|Undef
The URI host. Can be undefined.
$self->port --> Str|Undef
The URI port. Can be undefined.
$self->relative_part --> Str|Undef
The URI relative part. Can be undefined.
$self->ip_literal --> Str|Undef
The URI IP literal. Can be undefined.
$self->zoneid --> Str|Undef
The URI IP's zone id. Can be undefined.
$self->is_absolute --> Bool
Returns a true value if the URI is absolute, false otherwise.
SEE ALSO
Uniform Resource Identifier (URI): Generic Syntax
Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at https://rt.cpan.org/Public/Dist/Display.html?Name=MarpaX-RFC-RFC3986. You will be notified automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/jddurand/marpax-rfc-rfc3986
git clone git://github.com/jddurand/marpax-rfc-rfc3986.gitAUTHOR
Jean-Damien Durand <jeandamiendurand@free.fr>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Jean-Damien Durand.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.