The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MarpaX-RFC-RFC3986-0.002
River stage zero No dependents
++
/ MarpaX::RFC::RFC3986

NAME

MarpaX::RFC::RFC3986 - Uniform Resource Identifier (URI): Generic Syntax - Marpa Parser

VERSION

version 0.002

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:nose

The 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 split 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, and IPV4 address or a registered name:

         host = IP-literal / IPv4address / reg-name

The Zone Identifier is an extension to original RFC3986, and is defined in RFC6874:

         IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture  ) "]"

         ZoneID = 1*( unreserved / pct-encoded )

         IPv6addrz = IPv6address "%25" ZoneID

CLASS 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->ipv4address( --> Str|Undef)

The URI IP Version 4 address. Can be undefined.

$self->reg_name( --> Str|Undef)

The URI registered name. Can be undefined.

$self->is_absolute( --> Bool)

Returns a true value if the URI is absolute, false otherwise.

SEE ALSO

Marpa::R2

URI

Data::Validate::URI

Uniform Resource Identifier (URI): Generic Syntax

Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers

URI Design and Ownership

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.git

AUTHOR

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.