NAME

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

VERSION

version 0.43

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