/ 
Google-ProtocolBuffers-Dynamic-0.41_15
River stage one • 3 direct dependents • 6 total dependents
/ Google::ProtocolBuffers::Dynamic::Introspection

NAME

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

VERSION

version 0.41_15

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;

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;

die()s because even if $message_def and $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;

Google::ProtocolBuffers::Dynamic::MessageDef

name

$name = $message_def->name;

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

full_name

$name = $message_def->full_name;

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

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.

find_field_by_number

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

Returns the field matching the given number, or undef.

find_field_by_name

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

Returns the field with the given name, or undef.

find_oneof_by_name

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

Returns the oneof with the given name, or undef.

fields, oneofs

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

Returns all fields/oneof as an array reference.

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.

file

$file_def = $message_def->file;

Returns the file this message was defined in.

options

$options = $message_def->options;

Describes the options set on the message, see OPTIONS. Always returns a value, even if no options are set.

Google::ProtocolBuffers::Dynamic::FieldDef

name

$name = $field_def->name;

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

full_name

$name = $field_def->full_name;

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

number

$number = $field_def->number;

The field number as declared in the message definition.

label

$label = $field_def->label;

Returns the field label (whether the field is required, repeated or optional).

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

Simple boolean accessors.

descriptor_type

$protobuf_type = $field_def->descriptor_type;

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

value_type

$value_type = $field_def->value_type;

Returns the underlying field type (note that this returns the same int32 type for, e.g. int32, sint32, fixed32 and sfixed32 fields).

default_value

$value = $field_def->default_value;

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

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).

containing_oneof

$oneof_def = $field_def->containing_oneof;

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

real_containing_oneof

$oneof_def = $field_def->real_containing_oneof;

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

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.

has_presence

$has_presence = $field_def->has_presence;

Returns whether the field supports field presence.

file

$file_def = $field_def->file;

Returns the file this field was defined in.

options

$options = $field_def->options;

Describes the options set on the field, see OPTIONS. Always returns a value, even if no options are set.

Google::ProtocolBuffers::Dynamic::OneofDef

name

$name = $oneof_def->name;

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

full_name

$name = $oneof_def->full_name;

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

field_count

$count = $oneof_def->field_count;

The number of fields.

find_field_by_number

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

Returns the field matching the given number, or undef.

find_field_by_name

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

Returns the field with the given name, or undef.

fields

$field_defs = $oneof_def->fields;

Returns all fields as an array reference.

containing_type

$message_def = $oneof_def->containing_type;

Containing message.

is_synthetic

$is_synthetic = $oneof_def->is_synthetic;

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

file

$file_def = $oneof_def->file;

Returns the file this oneof was defined in.

options

$options = $oneof_def->options;

Describes the options set on the oneof, see OPTIONS. Always returns a value, even if no options are set.

Google::ProtocolBuffers::Dynamic::EnumDef

name

$name = $enum_def->name;

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

full_name

$name = $enum_def->full_name;

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

default_value

$value = $enum_def->default_value;

Default value for this enum.

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 undef.

find_name_by_number

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

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

values

$value_map = $enum_def->values;

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

file

$file_def = $enum_def->file;

Returns the file this enum was defined in.

options

$options = $enum_def->options;

Describes the options set on the enum, see OPTIONS. Always returns a value, even if no options are set.

Google::ProtocolBuffers::Dynamic::ServiceDef

name

$name = $service_def->name;

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

full_name

$name = $service_def->full_name;

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

methods

$method_defs = $service_def->methods;

Returns all methods as an array reference.

file

$file_def = $service_def->file;

Returns the file this service was defined in.

options

$options = $service_def->options;

Describes the options set on the service, see OPTIONS. Always returns a value, even if no options are set.

Google::ProtocolBuffers::Dynamic::MethodDef

name

$name = $method_def->name;

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

full_name

$name = $method_def->full_name;

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

containing_service

$service_def = $method_def->containing_service;

Containing service definition.

input_type

$message_def = $method_def->input_type;

Input type for the method.

output_type

$message_def = $method_def->output_type;

Output type for the method.

client_streaming

$is_streaming_client = $method_def->client_streaming.

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

server_streaming

$is_streaming_server = $method_def->server_streaming.

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

file

$file_def = $method_def->file;

Returns the file this method was defined in.

options

$options = $method_def->options;

Describes the options set on the method, see OPTIONS. Always returns a value, even if no options are set.

Google::ProtocolBuffers::Dynamic::FileDef

name

$name = $file_def->name;

The file name relative to the search path.

package

$package = $file_def->package;

The Protocol Buffers package declared in the file.

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.

options

$options = $file_def->options;

Describes the options set on the file, see OPTIONS. Always returns a value, even if no options are set.

OPTIONS

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

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

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

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 undef.

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 undef.

CONSTANTS

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

Labels

Return value of the "label" method.

LABEL_OPTIONAL
LABEL_REPEATED
LABEL_REQUIRED

Value types

Return value of the "value_type" method.

VALUE_FLOAT
VALUE_DOUBLE
VALUE_BOOL
VALUE_STRING
VALUE_BYTES
VALUE_MESSAGE
VALUE_ENUM
VALUE_INT32
VALUE_UINT32
VALUE_INT64
VALUE_UINT64

Descriptor types

Return value of the "descriptor_type" method.

DESCRIPTOR_DOUBLE
DESCRIPTOR_FLOAT
DESCRIPTOR_INT64
DESCRIPTOR_UINT64
DESCRIPTOR_INT32
DESCRIPTOR_FIXED64
DESCRIPTOR_FIXED32
DESCRIPTOR_BOOL
DESCRIPTOR_STRING
DESCRIPTOR_GROUP
DESCRIPTOR_MESSAGE
DESCRIPTOR_BYTES
DESCRIPTOR_UINT32
DESCRIPTOR_ENUM
DESCRIPTOR_SFIXED32
DESCRIPTOR_SFIXED64
DESCRIPTOR_SINT32
DESCRIPTOR_SINT64

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.