https://github.com/ccakes/protobuf-pl
A simple, vibe-coded Protocol Buffers code generator for Perl 5
https://github.com/ccakes/protobuf-pl
Last synced: about 1 year ago
JSON representation
A simple, vibe-coded Protocol Buffers code generator for Perl 5
- Host: GitHub
- URL: https://github.com/ccakes/protobuf-pl
- Owner: ccakes
- Created: 2025-06-07T15:53:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-22T04:47:07.000Z (about 1 year ago)
- Last Synced: 2025-06-22T05:27:17.683Z (about 1 year ago)
- Language: Perl
- Size: 60.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# protobuf-pl - Protocol Buffers Compiler for Perl
> **Note**: This entire repository was generated by AI with very little human intervention except to verify that it (mostly) works.
A pure Perl implementation of a Protocol Buffers compiler that generates Perl code from `.proto` files. This tool provides a solution for working with Protocol Buffers in Perl without requiring the official protoc compiler or external dependencies.
## Features
- **Pure Perl Implementation**: No external dependencies beyond Perl core modules
- **Proto3 Support**: Full support for Protocol Buffers version 3 syntax
- **Complete Wire Format**: Proper binary encoding/decoding using Protocol Buffers wire format
- **All Field Types**: Support for scalars, messages, enums, repeated fields, and maps
- **Nested Types**: Support for nested messages and enums
- **Import System**: Handle proto file imports and dependencies
- **Round-trip Fidelity**: Preserves unknown fields for forward/backward compatibility
## Quick Start
### Installation
Clone this repository and ensure the `script/protoc-gen-pl5` is executable:
```bash
git clone https://github.com/ccakes/protobuf-pl5
cd protobuf-pl
chmod +x script/protoc-gen-pl5
```
### Basic Usage
```bash
# Generate Perl code from a proto file
./script/protoc-gen-pl5 proto/example.proto
# Specify output directory
./script/protoc-gen-pl5 --out=lib/generated proto/example.proto
# Add include paths for imports
./script/protoc-gen-pl5 -I./proto -I./common --out=lib proto/example.proto
```
### Using Generated Code
```perl
use lib 'generated';
use Example::Person;
use Example::Status;
# Create a new message
my $person = Example::Person->new(
name => 'John Doe',
id => 123,
email => 'john@example.com'
);
# Add repeated fields
$person->phone_numbers(['555-1234', '555-5678']);
# Encode to binary format
my $binary = $person->encode;
# Decode from binary format
my $decoded = Example::Person->decode($binary);
# Access fields
print $decoded->name; # 'John Doe'
print $decoded->id; # 123
```
## Architecture
The compiler consists of four main components:
### 1. Parser (`lib/Proto/PL/Parser.pm`)
- Tokenizes and parses `.proto` files
- Handles imports and include paths
- Builds an Abstract Syntax Tree (AST)
- Supports proto3 syntax and features
### 2. AST (`lib/Proto/PL/AST.pm`)
- Defines node types for the syntax tree
- Represents messages, fields, enums, and file structure
- Provides methods for traversing and querying the AST
### 3. Generator (`lib/Proto/PL/Generator.pm`)
- Converts AST to Perl code
- Generates message classes with proper inheritance
- Creates field accessors and validation
- Handles package mapping to Perl namespaces
### 4. Runtime (`lib/Proto/PL/Runtime.pm`)
- Base classes for generated code
- Wire format encoding/decoding
- Message serialization and deserialization
- Field presence tracking and unknown field handling
## Generated Code Structure
For a proto file with package `example` containing a message `Person`, the generator creates:
```
lib/
└── Example/
└── Person.pm
```
Each generated class:
- Extends `Proto::PL::Runtime::Message`
- Provides field accessor methods
- Includes `encode()` and `decode()` methods
- Supports conversion to/from hash representations
- Maintains wire format compatibility
## Command Line Options
```bash
./script/protoc-gen-pl5 [options] proto_file...
Options:
--out, --output-dir DIR Output directory (default: lib)
-I, --include-path DIR Add directory to import search path
-h, --help Show help message
--version Show version information
```
## Supported Features
### ✅ Currently Supported
- Proto3 syntax
- Messages with all field types (scalar, message, enum)
- Nested messages and enums
- Repeated fields and maps
- Oneofs (union types)
- Optional fields
- Import statements
- Package declarations
- Wire format encoding/decoding
- JSON serialization
- Unknown field preservation
### ❌ Not Yet Supported
- Services and RPC definitions
- Proto2 specific features (required/optional semantics)
- Reflection capabilities
- Custom options
## Requirements
- Perl 5.10 or later
- Core Perl modules only (no CPAN dependencies)
## License
This software is distributed under the same terms as Perl itself.