view release on metacpan or  search on metacpan

lib/Google/ProtocolBuffers/Dynamic.pm  view on Meta::CPAN

    };

If L</check_enum_values> is true (the default), trying to encode a
message containing an invalid enum value will result in an error,
trying to decode it will ignore the invalid value. If
L</check_enum_values> is false, invalid enum values are passed through
unchanged.

=head2 ONEOF

Oneof fields don't generate any specific accessors, however calling
the setter for one of the contained fields will clear the other fields
that are members of the same oneof.

=head2 EXTENSIONS

Extension fields are treated like other scalar/repeated fields, except
that accessor names are generated using the fully-qualified name of
the extension.

For example

    package test;

    // ...

    extend Message1 {
        optional int32 value = 102;
    }

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

will create (scalar, in this case) accessors for fields named
C<test_value> and C<test_message2_extension2>.

In addition to per-field accessors, there is a set of generic
extension accessors (documented in
L<Google::ProtocolBuffers::Dynamic::Message/EXTENSION METHODS>).

=head2 SERVICES

Each service is mapped to a generated Perl class, with each method
mapped to a Perl method.

C<Google::ProtocolBuffers::Dynamic> does not provide an RPC
implementation, but supports generating a gRPC client using
L<Grpc::XS> (other implementations might be provided in the future).

In addition, there is a C<noop> service mapping mode that exposes
introspection information to simplify the mapping of external RPC
implementation on top of C<Google::ProtocolBuffers::Dynamic>.

The exact interface of mapped methods depends on the underlying RPC
implementation (for example, for L<Grpc::XS>, the return value is a
subclass of L<Grpc::Client::AbstractCall>) and whether the method uses
client/server streaming.

=head2 INTROSPECTION

All mapped entities provide access to an introspection object that
describes the Protocol Buffers object definition.

Each mapped message has a C<message_descriptor> class method returning a L<MessageDef|Google::ProtocolBuffers::Dynamic::Introspection/Google::ProtocolBuffers::Dynamic::MessageDef> object.

Each mapped enum has an C<enum_descriptor> class method returning an L<EnumDef|Google::ProtocolBuffers::Dynamic::Introspection/Google::ProtocolBuffers::Dynamic::EnumDef> object.

Each mapped service has a C<service_descriptor> class method returning a L<ServiceDef|Google::ProtocolBuffers::Dynamic::Introspection/Google::ProtocolBuffers::Dynamic::ServiceDef> object.

=head1 METHODS

This section describes methods used to load/map Protocol Buffer
messages, see above for the API of mapped messages.

The normal usage pattern is:

=over 4

=item create a new C<Google::ProtocolBuffers::Dynamic> instance

=item call L</load_string>/L</load_file> one or more times

=item call L</map> to map Protocol Buffer types to Perl packages

=back

L</map> is a wrapper around the various C<map_*> methods and
L</resolve_references>, so there should be no reason for using those
directly.

=head2 new

    $dynamic = Google::ProtocolBuffers::Dynamic->new;
    $dynamic = Google::ProtocolBuffers::Dynamic->new($root_directory);

When specified, C<$root_directory> is used as base for relative paths in
C<load_file>.

=head2 load_file

    $dynamic->load_file($file_path);

Loads the specified file, searching for it in the path passed to the
constructor.

=head2 load_string

    $dynamic->load_string($file_name, $string);

Parses message definitions from a string. The C<$file_name> parameter
is only used to report errors, and can be the empty string.

=head2 load_serialized_string

    $dynamic->load_serialized_string($string);

Parses message definitions from serialized descriptor data in the