NAME

PubNub::PubSub - Perl library for rapid publishing of messages on PubNub.com

SYNOPSIS

    use PubNub::PubSub;
    use 5.010;
    use Data::Dumper;

    my $pubnub = PubNub::PubSub->new(
        pub_key => 'demo', # only required for publish
        sub_key => 'demo',
        channel => 'sandbox',
    );

    # publish
    $pubnub->publish({
        messages => ['message1', 'message2'],
        callback => sub {
            my ($res) = @_;

            # $res is a L<Mojo::Message::Response>
            say $res->code; # 200
            say Dumper(\$res->json); # [1,"Sent","14108733777591385"]
        }
    });
    $pubnub->publish({
        channel  => 'sandbox2', # optional, if not applied, the one in ->new will be used.
        messages => ['message3', 'message4']
    });

    # subscribe
    $pubnub->subscribe({
        callback => sub {
            my (@messages) = @_;
            foreach my $msg (@messages) {
                print "# Got message: $msg\n";
            }
            return 1; # 1 to continue, 0 to stop
        }
    });

DESCRIPTION

PubNub::PubSub is Perl library for rapid publishing of messages on PubNub.com based on Mojo::UserAgent

perl clone of https://gist.github.com/stephenlb/9496723#pubnub-http-pipelining

For a rough test:

• run perl examples/subscribe.pl in one terminal (or luanch may terminals with subscribe.pl)

• run perl examples/publish.pl in another terminal (you'll see all subscribe terminals will get messages.)

METHOD

new

• pub_key

  optional, default pub_key for publish

• sub_key

  optional, default sub_key for all methods

• channel

  optional, default channel for all methods

• publish_callback

  optional. default callback for publish

• debug

  set ENV MOJO_USERAGENT_DEBUG to debug

subscribe

subscribe channel to listen for the messages.

Arguments are:

callback

Callback to run on the channel

channel

Channel to listen on, defaults to the base object's channel attribute.

subkey

Subscription key. Defaults to base object's subkey attribute.

raw_msg

Pass the whole message in, as opposed to the json element of the payload.

This is useful when you need to process time tokens or channel names.

The format is a triple of (\@messages, $timetoken, $channel).

timetoken

Time token for initial request. Defaults to 0.

    $pubnub->subscribe({
        callback => sub {
            my (@messages) = @_;
            foreach my $msg (@messages) {
                print "# Got message: $msg\n";
            }
            return 1; # 1 to continue, 0 to stop
        }
    });

return 0 to stop

subscribe_multi

Subscribe to multiple channels. Arguments are:

channels

an arrayref of channel names

callback

A callback, either a coderef which handles all requests, or a hashref dispatch table with one entry per channel.

If a dispatch table is used a _default entry catches all unrecognized channels. If an unrecognized channel is found, a warning is generated and the loop exits.

The message results are passed into the functions in raw_msg form (i.e. a tuple ref of (\@messages, $timetoken, $channel) for performance reasons.

publish

publish messages to channel

    $pubnub->publish({
        messages => ['message1', 'message2'],
        callback => sub {
            my ($res) = @_;

            # $res is a L<Mojo::Message::Response>
            say $res->code; # 200
            say Dumper(\$res->json); # [1,"Sent","14108733777591385"]
        }
    });
    $pubnub->publish({
        channel  => 'sandbox2', # optional, if not applied, the one in ->new will be used.
        messages => ['message3', 'message4']
    });

Note if you need shared callback, please pass it when do ->new with publish_callback.

new Parameters specifically for Publish V2 ONLY

• ortt - Origination TimeToken where "r" = DOMAIN and "t" = TIMETOKEN

• meta - any JSON payload - intended as a safe and unencrypted payload

• ear - Eat At Read (read once)

• seqn - Sequence Number - for Guaranteed Delivery/Ordering

We'll first try to read from messages, if not specified, fall back to the same level as messages. eg:

    $pubnub->publish({
        messages => [
            {
                message => 'test message.',
                ortt => {
                    "r" => 13,
                    "t" => "13978641831137500"
                },
                meta => {
                    "stuff" => []
                },
                ear  => 'True',
                seqn => 12345,
            },
            {
                ...
            }
        ]
    });

    ## if you have common part, you can specified as the same level as messages
    $pubnub->publish({
        messages => [
            {
                message => 'test message.',
                ortt => {
                    "r" => 13,
                    "t" => "13978641831137500"
                },
                seqn => 12345,
            },
            {
                ...
            }
        ],
        meta => {
            "stuff" => []
        },
        ear  => 'True',
    });

history

fetches historical messages of a channel

• sub_key

  optional, default will use the one passed to ->new

• channel

  optional, default will use the one passed to ->new

• count

  Specifies the number of historical messages to return. The Default is 100.

• reverse

  Setting to true will traverse the time line in reverse starting with the newest message first. Default is false. If both start and end arguments are provided, reverse is ignored and messages are returned starting with the newest message.

• start

  Time token delimiting the start of time slice (exclusive) to pull messages from.

• end

  Time token delimiting the end of time slice (inclusive) to pull messages from.

Sample code:

    my $history = $pubnub->history({
        count => 20,
        reverse => "false"
    });
    # $history is [["message1", "message2", ... ],"Start Time Token","End Time Token"]

for example, to fetch all the rows in history

    my $history = $pubnub->history({
        reverse => "true",
    });
    while (1) {
        print Dumper(\$history);
        last unless @{$history->[0]}; # no messages
        sleep 1;
        $history = $pubnub->history({
            reverse => "true",
            start => $history->[2]
        });
    }

JSON USAGE

This module effectively runs a Mojolicious application in the background. For those parts of JSON which do not have a hard Perl equivalent, such as booleans, the Mojo::JSON module's semantics work. This means that JSON bools are handled as references to scalar values 0 and 1 (i.e. \0 for false and \1 for true).

This has changed since 0.08, where True and False were used.

GITHUB

https://github.com/binary-com/perl-pubnub-pubsub

AUTHOR

Binary.com <fayland@gmail.com>

cpanm PubNub::PubSub

perl -MCPAN -e shell
install PubNub::PubSub