# PODNAME: Google::ProtocolBuffers::Dynamic::Introspection - introspection API for classes

__END__

=pod

=encoding UTF-8

=head1 NAME

Google::ProtocolBuffers::Dynamic::Introspection - introspection API for classes

=head1 VERSION

version 0.43

=head1 SYNOPSIS

    $message_def = Some::Class->message_descriptor;
    $field_def = $message_def->find_field_by_name('some_field');

    $message_name = $message_def->full_name;
    $field_name = $field_def->full_name

    $enum_def = Some::Enum::Package->enum_descriptor;
    $value = $enum_def->values;

=head1 DESCRIPTION

Introspection API wrapping Protocol Buffers descriptor API.

Note that this API does not respect referential integrity; for example
this snippet

    $message_def = ...;
    $field_def = $message_def->find_field_by_name($name);
    $containing_def = $field_def->containing_type;

    die "Oops" if $message_def != $containing_def;

C<die()>s because even if C<$message_def> and C<$containing_def>
represent the same underlying entity, their are two distinct objects
in Perl. This is true for all methods returning an object.

The same applies to multiple invocations of the same method, for example

    $message_def = ...;
    $field_def = $message_def->find_field_by_name($name);
    $field_def_again = $message_def->find_field_by_name($name);

    die "Oops" if $field_def != $field_def_again;

=head1 Google::ProtocolBuffers::Dynamic::MessageDef

=head2 name

    $name = $message_def->name;

The short name of this message (the one used in the message definition).

=head2 full_name

    $name = $message_def->full_name;

The fully-qualified name of this message (including package and outer
messages).

=head2 field_count, oneof_count

    $count = $message_def->field_count;

The number of fields/oneofs. The number of fields includes fields
declared in oneofs, but does not include the oneof declaration
themselves.

=head2 find_field_by_number

    $field_def = $message_def->find_field_by_number($number);

Returns the field matching the given number, or C<undef>.

=head2 find_field_by_name

    $field_def = $message_def->find_field_by_name($name);

Returns the field with the given name, or C<undef>.

=head2 find_oneof_by_name

    $oneof_def = $message_def->find_oneof_by_name($name);

Returns the oneof with the given name, or C<undef>.

=head2 fields, oneofs

    $field_defs = $message_def->fields;
    $oneof_defs = $message_def->oneofs;

Returns all fields/oneof as an array reference.

=head2 is_map_entry

    $is_map = $message_def->is_map_entry;

True if this message is a key/value pair that Protocol Buffers 3 uses
to represent a map entry.

=head2 file

    $file_def = $message_def->file;

Returns the file this message was defined in.

=head2 options

    $options = $message_def->options;

Describes the options set on the message, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 Google::ProtocolBuffers::Dynamic::FieldDef

=head2 name

    $name = $field_def->name;

The short name of this field (the one used in the message definition).

=head2 full_name

    $name = $field_def->full_name;

The fully-qualified name of this field (including package and outer
messages).

=head2 number

    $number = $field_def->number;

The field number as declared in the message definition.

=head2 label

    $label = $field_def->label;

Returns the L<field label|/Labels> (whether the field is C<required>,
C<repeated> or C<optional>).

=head2 is_extension, is_packed, is_message, is_string, is_repeatedm, is_primitive, is_map

Simple boolean accessors.

=head2 descriptor_type

    $protobuf_type = $field_def->descriptor_type;

Returns the L<field type|/Descriptor types> as specified in the
message declaration (note that this returns different types for,
e.g. C<int32>, C<sint32>, C<fixed32> and C<sfixed32> fields).

=head2 value_type

    $value_type = $field_def->value_type;

Returns the L<underlying field type|/Value types> (note that this
returns the same C<int32> type for, e.g. C<int32>, C<sint32>,
C<fixed32> and C<sfixed32> fields).

=head2 default_value

    $value = $field_def->default_value;

The default value for this field (the type depends on field
type). Returns C<undef> for message/group fields, returns the default
value for the underlying type for repeated fields.

=head2 containing_type

    $message_def = $field_def->containing_type;

Containing message (for extension fields this is the message being
extended, not the message where the extension is declared).

=head2 containing_oneof

    $oneof_def = $field_def->containing_oneof;

Containing oneof definition, or C<undef> if this field is not part of
an oneof.

=head2 real_containing_oneof

    $oneof_def = $field_def->real_containing_oneof;

Containing oneof definition. Returns C<undef> if this field is not part of
an oneof, or is part of the synthetic oneof created by proto3 optional.

=head2 enum_type, message_type

    $enum_def = $field_def->enum_type;
    $message_def = $field_def->message_type;

For fields with type enum or message, returns the matching type
definition, or undef if the fields is not a message/enum.

=head2 has_presence

    $has_presence = $field_def->has_presence;

Returns whether the field supports L<field presence|https://github.com/protocolbuffers/protobuf/blob/master/docs/field_presence.md#application-note-field-presence>.

=head2 file

    $file_def = $field_def->file;

Returns the file this field was defined in.

=head2 options

    $options = $field_def->options;

Describes the options set on the field, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 Google::ProtocolBuffers::Dynamic::OneofDef

=head2 name

    $name = $oneof_def->name;

The short name of this oneof (the one used in the message definition).

=head2 full_name

    $name = $oneof_def->full_name;

The fully-qualified name of this oneof (including package and outer
messages).

=head2 field_count

    $count = $oneof_def->field_count;

The number of fields.

=head2 find_field_by_number

    $field_def = $oneof_def->find_field_by_number($number);

Returns the field matching the given number, or C<undef>.

=head2 find_field_by_name

    $field_def = $oneof_def->find_field_by_name($name);

Returns the field with the given name, or C<undef>.

=head2 fields

    $field_defs = $oneof_def->fields;

Returns all fields as an array reference.

=head2 containing_type

    $message_def = $oneof_def->containing_type;

Containing message.

=head2 is_synthetic

    $is_synthetic = $oneof_def->is_synthetic;

C<true> for oneof definitions that have been created by proto3
C<optional> implementation.

=head2 file

    $file_def = $oneof_def->file;

Returns the file this oneof was defined in.

=head2 options

    $options = $oneof_def->options;

Describes the options set on the oneof, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 Google::ProtocolBuffers::Dynamic::EnumDef

=head2 name

    $name = $enum_def->name;

The short name of this enum (the one used in the message definition).

=head2 full_name

    $name = $enum_def->full_name;

The fully-qualified name of this enum (including package and outer
messages).

=head2 default_value

    $value = $enum_def->default_value;

Default value for this enum.

=head2 find_number_by_name

    $number = $enum_def->find_number_by_name($name);

Returns the integer value of the enum entry with the given name, or
C<undef>.

=head2 find_name_by_number

    $name = $enum_def->find_name_by_number($number);

Returns the name of the enum entry with the given value, or C<undef>.

=head2 values

    $value_map = $enum_def->values;

Returns a hash reference containing all name/value pairs for this
enum.

=head2 file

    $file_def = $enum_def->file;

Returns the file this enum was defined in.

=head2 options

    $options = $enum_def->options;

Describes the options set on the enum, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 Google::ProtocolBuffers::Dynamic::ServiceDef

=head2 name

    $name = $service_def->name;

The short name of this service (the one used in the message definition).

=head2 full_name

    $name = $service_def->full_name;

The fully-qualified name of this service (including package).

=head2 methods

    $method_defs = $service_def->methods;

Returns all methods as an array reference.

=head2 file

    $file_def = $service_def->file;

Returns the file this service was defined in.

=head2 options

    $options = $service_def->options;

Describes the options set on the service, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 Google::ProtocolBuffers::Dynamic::MethodDef

=head2 name

    $name = $method_def->name;

The short name of this method (the one used in the service definition).

=head2 full_name

    $name = $method_def->full_name;

The fully-qualified name of this method (including package and service name).

=head2 containing_service

    $service_def = $method_def->containing_service;

Containing service definition.

=head2 input_type

    $message_def = $method_def->input_type;

Input type for the method.

=head2 output_type

    $message_def = $method_def->output_type;

Output type for the method.

=head2 client_streaming

    $is_streaming_client = $method_def->client_streaming.

True if the service accepts streaming input (i.e. the input type has
the C<stream> annotation in the method definition).

=head2 server_streaming

    $is_streaming_server = $method_def->server_streaming.

True if the service produces streaming output (i.e. the output type has
the C<stream> annotation in the method definition).

=head2 file

    $file_def = $method_def->file;

Returns the file this method was defined in.

=head2 options

    $options = $method_def->options;

Describes the options set on the method, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 Google::ProtocolBuffers::Dynamic::FileDef

=head2 name

    $name = $file_def->name;

The file name relative to the search path.

=head2 package

    $package = $file_def->package;

The Protocol Buffers package declared in the file.

=head2 dependencies, public_dependencies, messages, enums, services, extensions

    $message_defs = $file_def->messages;
    $enum_defs = $file_def->enums;
    $service_defs = $file_def->servicess;
    $field_defs = $file_def->extensionss;
    $file_defs = $file_def->dependencies;
    $file_defs = $file_def->public_dependencies;

Returns all messages/enums/services/extensions/dependencies and
public dependencies as an array reference.

=head2 options

    $options = $file_def->options;

Describes the options set on the file, see L<OPTIONS|/OPTIONS>.
Always returns a value, even if no options are set.

=head1 OPTIONS

This section documents the option objects returned by the vairous
C<options()> methods.

Standard Protocol Buffers options can be accessed by using a method
with the same name of the option (e.g. C<<< $options->java_package >>>.

In addition to that, all option objects provide the following methods.

=head2 custom_option_by_name

    $option_value = $options->custom_option_by_name('myoptions.some_option');

Return the value of a custom option. If the option is not set on this
entity, returns the default value. If the option name does not match
an existing custom option, return C<undef>.

=head2 custom_option_by_number

    $option_value = $options->custom_option_by_name(51234);

Return the value of a custom option. If the option is not set on this
entity, returns the default value. If the option name does not match
an existing custom option, return C<undef>.

=head1 CONSTANTS

All the constants below are available as
C<Google::ProtocolBuffers::Dynamic::CONSTANT> and can be exported
either individually or using the C<:labels>, C<:descriptor> and
C<:values> exporter tags.

=head2 Labels

Return value of the L</label> method.

=over 4

=item LABEL_OPTIONAL

=item LABEL_REPEATED

=item LABEL_REQUIRED

=back

=head2 Value types

Return value of the L</value_type> method.

=over 4

=item VALUE_FLOAT

=item VALUE_DOUBLE

=item VALUE_BOOL

=item VALUE_STRING

=item VALUE_BYTES

=item VALUE_MESSAGE

=item VALUE_ENUM

=item VALUE_INT32

=item VALUE_UINT32

=item VALUE_INT64

=item VALUE_UINT64

=back

=head2 Descriptor types

Return value of the L</descriptor_type> method.

=over 4

=item DESCRIPTOR_DOUBLE

=item DESCRIPTOR_FLOAT

=item DESCRIPTOR_INT64

=item DESCRIPTOR_UINT64

=item DESCRIPTOR_INT32

=item DESCRIPTOR_FIXED64

=item DESCRIPTOR_FIXED32

=item DESCRIPTOR_BOOL

=item DESCRIPTOR_STRING

=item DESCRIPTOR_GROUP

=item DESCRIPTOR_MESSAGE

=item DESCRIPTOR_BYTES

=item DESCRIPTOR_UINT32

=item DESCRIPTOR_ENUM

=item DESCRIPTOR_SFIXED32

=item DESCRIPTOR_SFIXED64

=item DESCRIPTOR_SINT32

=item DESCRIPTOR_SINT64

=back

=head1 AUTHOR

Mattia Barbon <mattia@barbon.org>

=head1 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.

=cut
