/ 
Google-Protobuf-Loader-0.01
River stage zero No dependents
/ Google::Protobuf::Loader

NAME

Google::Protobuf::Loader - Automatically load .proto file using the standard "use" syntax.

SYNOPSIS

use Google::Protobuf::Loader;
use Proto::Foo::Bar;

my $proto = Proto::Foo::Bar::Baz->new();
print $proto->message_descriptor()->full_name();  # prints foo.Bar

DESCRIPTION

This module uses Google::ProtocolBuffers::Dynamic to load .proto files using a standard use syntax.

Note: To install the Google::ProtocolBuffers::Dynamic module and its dependencies you need to have some Protocol Buffer headers on your system that are provided, at least on Debian based systems, by the libprotoc-dev package.

Once loaded with use Google::Protobuf::Loader; this module will intercept use statement with a bare-word or filename starting with Proto:: (or Proto/). When they are seen, the module will then search for a .proto file matching the name used, including its capitalization, but without its Proto prefix. For example use Proto::Foo::Bar; will search for a file named Foo/Bar.proto. The search is performed in the standard @INC directories (but does not execute any of the hooks that this may contain).

When such a file is found, it is parsed by Google::ProtocolBuffers::Dynamic and loaded in a Perl package named based on the package declaration in the .proto file (that declaration is required when using this module). The Perl package name is generated by turning the snake-case proto package into a camel-case name and prefixing it with Proto. For example, package foo.bar_baz; in the .proto file will give a Perl Proto::Foo::BarBaz package containing the class definition for all the messages defined in the proto file.

The proto files that are loaded by this module can use import statements. In that case, the proto file that they name are searched for in the @INC directories as-is (without any change to their name). The packages that they name are loaded in Perl following the same rule as described above.

For the API of the generated classes, please refer to the documentation of Google::ProtocolBuffers::Dynamic, especially its Language Mapping section, and Google::ProtocolBuffers::Dynamic::Message.

OPTIONS

You can pass options to the module when it is loaded initially:

use Google::Protobuf::Loader option => value, ...;

Currently, a single option is supported: map_options whose value must be a hash reference containing options passed to the map call used with Google::ProtocolBuffers::Dynamic to load the proto. The list of supported options is here.

Note that this option will apply only for .proto files loaded from the same package as where the option is set. However, any .proto file is only loaded once in a program, the first time that is is required. So you should either pass the same options all the time or ensure that you only loads proto files that are not used anywhere else.

AUTHOR

Mathias Kende mailto:mathias@cpan.org

COPYRIGHT AND LICENSE

Copyright 2024 Mathias Kende

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SEE ALSO