NAME

POEx::URI - URI extension for POE event specfiers

SYNOPSIS

    use URI;

    my $uri = URI->new( "$session/$event" );

    $poe_kernel->post( $uri->session, $uri->event, @args );
    $poe_kernel->post( @$uri, @args );

    $uri->host( $host );
    $uri->port( 33100 );
    $poe_kernel->post( IKC => $uri, @args );

DESCRIPTION

This module implements the URIs that reference POE session/event tuples. Objects of this class represent non-standard "Uniform Resource Identifier references" of the poe: scheme.

The canonical forms of POE URIs are:

    poe:event
    poe:session/
    poe:session/event
    poe://kernel/session/
    poe://kernel/session/event

Events may also have parameters :

    poe:event?foo=bar
    poe:event?b+20+BINGO

See "argument" below.

URI fragements (the bits after #) make no sense.

Use

This module attempts to have no pre-conception on how the URIs would be used. Core POE has way of turning URIs into event invocations. However, you may use "as_array" to invoke the event referenced by a URI.

    $poe_kernel->post( @$uri );

The presence of a kernel name in the URI presuposes some form of inter-kernel communication. POE::Component::IKC doesn't currently support URIs, beyond the fact that a subscribed remote session will have a local thunk session with the alias of the form poe://kernel/session. So using "as_array" will be able to access it.

METHODS

event

    my $name = $uri->event
    $old = $uri->event( $name );

Sets and returns the event part of the $uri. If the $name contains a forward-slash (/), it is escaped (%2F).

To clear the event name, use '' or undef, which are equivalent.

session

    my $name = $uri->session
    $old = $uri->session( $name );

Sets and returns the session part of the $uri. If the $name contains a forward-slash (/), it is escaped (%2F).

To clear the event name, use '' or undef, which are equivalent

kernel

    my $kernel = $uri->kernel;
    $old = $uri->kernel( $name );

Sets and returns the kernel part of the $uri. A kernel may be a dotted quad IPv4 address (127.0.0.1), an IPv6 address ([::1]) or a hostname (localhost.localdomain) followed by a port number. A kernel may also be kernel ID or alias.

The kernel only make sense when using IKC.

To clear the kernel name, use '' or undef, which are equivalent.

host

    $host = $uri->host;
    $old = $uri->host( $host );

Sets and returns the host part of the $uri's kernel. If the kernel wasn't host:port, then it is converted to that.

port

    $port = $uri->port;
    $old = $uri->port( $port );

Sets and retuns the port part of the $uri's kernel. If the kernel wasn't a host name, then it becomes one.

default_port

The default POE port is 603 which is POE upside-down and backwards. Almost.

argument

    $arg = $uri->argument
    $old = $uri->argument( $new_arg );
    $old = $uri->argument( %new_arg );
    $old = $uri->argument( \@new_arg );

Sets and returns the argument for this $uri. And argument may be a string, a hash ("query_form" in URI) or an arrayref ("query_keywords" in URI).

See "as_array" to see how the argument is passed to the event handler.

user

    $user = $uri->user;
    $old = $uri->user( $user );

Sets and returns the username part of the $uri's "userinfo" in URI. If the user name contains :, it is escaped.

A user only makes sense in IKC.

password

    $pw = $uri->password;
    $old = $uri->password( $passwd );

Sets and returns the password part of the $uri's "userinfo" in URI. If the password contains :, it is escaped.

The user name and password are seperated by :. This is might be a security issue. Beware.

While this method is called password, it works just as well with pass phrases.

A password only makes sense in IKC.

as_array

    $poe_kernel->post( @$uri, @args );
    $poe_kernel->post( $uri->as_array, @args );

Returns a URI object to a session/event tuple, suitable for posting or calling. POEx::URI objects are also converted to arrays automatically by overloading.

If a kernel name is present, and it is not the local kernel ID, then it is prepended to the session name. This is compatible with IKC after subscribing to the remote session.

If an argument is present, it is returned as the last item.

canonical

    my $full = $uri->canonical;

Returns a normalized version of the URI. For POE URIs, the hostname is folded to lower case.

path

    $path = $uri->path;
    $old = $uri->path( $new_path );

Sets and returns the session/event tupple of a $uri. If the new path contains more then one slash, the last segment of the path is the event, and the others are the session and those slash are escaped.

path_segments

    ( $session, $event ) = $uri->path_segments;
    @old = $uri->path_segments( @new );

Sets and returns the path. In a scalar context, it returns the same value as $uri->path. In a list context, it returns the unescaped path segments that make up the path. See "path_segments" in URI for more details.

SEE ALSO

POE, URI, http://www.faqs.org/rfcs/rfc3986.html.

AUTHOR

Philip Gwyn, <gwyn -at- cpan.org>

COPYRIGHT AND LICENSE

Some of this code is based on URI and related subclasses was developed by Gisle Aas et al.

Copyright (C) 2009 by Philip Gwyn

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm POEx::URI

perl -MCPAN -e shell
install POEx::URI