NAME

Google::ProtocolBuffers::Dynamic::Message - abstract interface for message classes

VERSION

version 0.26

DESCRIPTION

Message classes generated by Google::ProtocolBuffers::Dynamic don't have a base class, but you can think of them as implementing the interface described below.

METHODS

new

    $msg = Message::Class->new({
        field1         => $value1,
        message_field1 => {
            # ...
        },
        message_field2 => Message::OtherClass->new(...),
    });

Constructs a new message instances using the passed-in data.

Construction recurses into message fields, and it takes ownership of the passed-in hash, so don't use it afterwards.

new_and_check

Constructs a new message instances using the passed-in data, and then calls "check". See also "new".

decode

    $msg = Message::Class->decode($serialized_data);

Deserializes Protocol Buffer binary data into a message instance.

decode_json

    $msg = Message::Class->decode_json($json_data);

Deserializes Protocol Buffer JSON data into a message instance.

encode

    $serialized_data = Message::Class->encode({ ... });
    $serialized_data = Message::Class->encode($message_instance);
    $serialized_data = $message_instance->encode;

Serializes the given message instance (or mix of message instances and plain hashes) to Protocol Buffer binary format.

encode_json

    $serialized_data = Message::Class->encode_json({ ... });
    $serialized_data = Message::Class->encode_json($message_instance);
    $serialized_data = $message_instance->encode_json;

Serializes the given message instance (or mix of message instances and plain hashes) to Protocol Buffer JSON format.

check

    Message::Class->check({ ... });
    Message::Class->check($message_instance);
    $message_instance->check;

Performs a sanity check, verifying (recursively) that the object structure does not contain unknown fields. Consider this as a typo protection: this check passing does not imply encoding will succeed (for example, scalar values are not checked).

message_descriptor

    $descriptor = Message::Class->message_descriptor();
    $descriptor = $message_instance->message_descriptor();

Returns an introspection object describing the fields and types of this message. See Google::ProtocolBuffers::Dynamic::Introspection for the full API.

See also "enum_descriptor" in Google::ProtocolBuffers::Dynamic::Introspection.

EXTENSION METHODS

In the list below, extension_id is either the fully-qualified name of the extension or the generated constant key for that extension.

For example, given the message definitions:

    syntax = "proto2";

    package test;

    message Message1 {
        optional int32 value = 1;
        extensions 100 to 150;
    }

    extend Message1 {
        optional int32 value = 102;
    }

    message Message2 {
        extend Message1 {
            optional int32 extension2 = 101;
        }
    }

and the Perl message mapping:

    $dynamic->map({ package => 'test', to => 'Some::Perl::Package' });

the following Perl code can be used to access extension values:

    $message1 = Some::Perl::Package::Message1->decode(...);

    $value = $message1->get_extension('test.value');
    $value = $message2->get_extension(Some::Perl::Package::TEST_VALUE_KEY());
    $value = $message1->get_extension('test.Message2.extension2');
    $value = $message2->get_extension(Some::Perl::Package::TEST_MESSAGE2_EXTENSION2_KEY());

keep also in mind that getters and setters follow the style set by "accessor_style" in Google::ProtocolBuffers::Dynamic.

has_extension

    $has_field = $msg->has_extension($extension_id);

True if the extension field has a value.

clear_extension

    $msg->clear_extension($extension_id);

Clears the current value of an extension field.

get_extension

    $value = $msg->get_extension($extension_id);

Returns the value of a non-repeated extension field.

set_extension

    $msg->set_extension($extension_id, $value);

Sets the value of a non-repeated extension field.

get_extension_item

    $value = $msg->get_extension_item($extension_id, $index);

Gets the value of a repeated extension field item.

set_extension_item

    $msg->set_extension_item($extension_id, $index, $value);

Sets a new value for a repeated extension field item.

add_extension_item

    $msg->add_extension_item($extension_id, $value);

Appends an item to a repeated extension field.

extension_size

    $size = $msg->extension_size($extension_id);

Returns the number of items contained in a repeated extension field.

get_extension_list

    $arrayref = $msg->get_extension_list($extension_id);

Returns a mutable reference to the array backing a repeated extension field.

set_extension_list

    $msg->set_extension_list($extension_id, $arrayref);

Sets a new value for repeated extension fields.

AUTHOR

Mattia Barbon <mattia@barbon.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015-2016 by Mattia Barbon.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Google::ProtocolBuffers::Dynamic

perl -MCPAN -e shell
install Google::ProtocolBuffers::Dynamic