protozoa/parser

Protocol Buffer Parser Module

This module provides parsing functionality for Protocol Buffer (.proto) files. It transforms proto3 syntax text into structured Gleam data types that can be used for code generation and type analysis.

Capabilities

Full proto3 syntax support: Messages, enums, services, fields, imports, packages
Nested structures: Supports nested messages and enums within messages
Advanced features: Oneofs, maps, repeated fields, optional fields, field options
Service definitions: Parses RPC services with method definitions and streaming support
Import handling: Parses import statements (public, weak, regular)
Robust parsing: Handles comments, whitespace, and malformed input gracefully
Type definitions: Comprehensive type system covering all proto3 types

Main Function

The primary entry point is parse() which takes raw proto file content as a string and returns a structured ProtoFile representation. All other types in this module are internal data structures used to represent the parsed content.

Proto3 Support

Supported proto3 features:

Messages with fields (scalar types, message types, enums)
Nested messages and enums
Oneof groups for union types
Repeated fields for arrays/lists
Map fields for key-value pairs
Service definitions with RPC methods
Streaming RPC support (client, server, bidirectional)
Field options (deprecated, json_name, packed)
Import statements with search path resolution
Package declarations for namespacing
Field numbers and naming

Limitations

Only proto3 syntax (no proto2)
No service definitions (RPC)
Basic comment handling (strips // comments)
Limited validation (focuses on structure over semantics)

Types

Enum

</>

Represents a Protocol Buffer enum definition.

pub type Enum {
  Enum(name: String, values: List(@internal EnumValue))
}

Constructors

Enum(name: String, values: List(@internal EnumValue))

Field

</>

Represents a field in a Protocol Buffer message.

pub type Field {
  Field(
    name: String,
    field_type: ProtoType,
    number: Int,
    oneof_name: option.Option(String),
    options: List(FieldOption),
  )
}

Constructors

Field(
  name: String,
  field_type: ProtoType,
  number: Int,
  oneof_name: option.Option(String),
  options: List(FieldOption),
)

FieldOption

</>

Represents a field option in a Protocol Buffer field definition.

pub type FieldOption {
  Deprecated(Bool)
  JsonName(String)
  Packed(Bool)
}

Constructors

```
Deprecated(Bool)
```
```
JsonName(String)
```
```
Packed(Bool)
```

Import

</>

pub type Import {
  Import(path: String, public: Bool, weak: Bool)
}

Constructors

Import(path: String, public: Bool, weak: Bool)

Message

</>

Represents a Protocol Buffer message definition.

pub type Message {
  Message(
    name: String,
    fields: List(Field),
    oneofs: List(Oneof),
    nested_messages: List(Message),
    enums: List(Enum),
  )
}

Constructors

Message(
  name: String,
  fields: List(Field),
  oneofs: List(Oneof),
  nested_messages: List(Message),
  enums: List(Enum),
)

Method

</>

Represents an RPC method in a Protocol Buffer service.

pub type Method {
  Method(
    name: String,
    input_type: String,
    output_type: String,
    client_streaming: Bool,
    server_streaming: Bool,
  )
}

Constructors

Method(
  name: String,
  input_type: String,
  output_type: String,
  client_streaming: Bool,
  server_streaming: Bool,
)

Oneof

</>

Represents a oneof group in a Protocol Buffer message. Only one field in the group can be set at a time.

pub type Oneof {
  Oneof(name: String, fields: List(Field))
}

Constructors

Oneof(name: String, fields: List(Field))

ParseError

</>

pub type ParseError {
  InvalidSyntax(line: String, reason: String)
  MissingRequiredSyntax(String)
  InvalidFieldNumber(field: String, number: String)
  DuplicateFieldNumber(message: String, number: Int)
  MalformedField(line: String)
  MalformedMessage(line: String)
  MalformedEnum(line: String)
  InvalidMapType(line: String)
  EmptyMessage(name: String)
}

Constructors

InvalidSyntax(line: String, reason: String)

```
MissingRequiredSyntax(String)
```

InvalidFieldNumber(field: String, number: String)

DuplicateFieldNumber(message: String, number: Int)

```
MalformedField(line: String)
```
```
MalformedMessage(line: String)
```
```
MalformedEnum(line: String)
```
```
InvalidMapType(line: String)
```
```
EmptyMessage(name: String)
```

Path

</>

pub type Path {
  Path(path: String, content: ProtoFile)
}

Constructors

```
Path(path: String, content: ProtoFile)
```

ProtoFile

</>

Represents a parsed Protocol Buffer file.

pub type ProtoFile {
  ProtoFile(
    syntax: String,
    package: option.Option(String),
    imports: List(Import),
    messages: List(Message),
    enums: List(Enum),
    services: List(Service),
  )
}

Constructors

ProtoFile(
  syntax: String,
  package: option.Option(String),
  imports: List(Import),
  messages: List(Message),
  enums: List(Enum),
  services: List(Service),
)

ProtoType

</>

Represents the different types that can be used in Protocol Buffer definitions.

pub type ProtoType {
  Double
  Float
  Int32
  Int64
  UInt32
  UInt64
  SInt32
  SInt64
  Fixed32
  Fixed64
  SFixed32
  SFixed64
  Bool
  String
  Bytes
  MessageType(String)
  EnumType(String)
  Repeated(ProtoType)
  Optional(ProtoType)
  Map(ProtoType, ProtoType)
}

Constructors

```
Double
```
```
Float
```
```
Int32
```
```
Int64
```
```
UInt32
```
```
UInt64
```
```
SInt32
```
```
SInt64
```
```
Fixed32
```
```
Fixed64
```
```
SFixed32
```
```
SFixed64
```
```
Bool
```
```
String
```
```
Bytes
```
```
MessageType(String)
```
```
EnumType(String)
```
```
Repeated(ProtoType)
```
```
Optional(ProtoType)
```
```
Map(ProtoType, ProtoType)
```

Service

</>

Represents a Protocol Buffer service definition.

pub type Service {
  Service(name: String, methods: List(Method))
}

Constructors

Service(name: String, methods: List(Method))

Values

describe_parse_error

</>

pub fn describe_parse_error(error: ParseError) -> String

parse

</>

pub fn parse(content: String) -> Result(ProtoFile, ParseError)

Parses a simple Protocol Buffer file from its text content. This is a simplified parser that handles basic proto3 syntax.

Limitations

Only supports proto3 syntax
Limited support for nested types

Examples

let proto_content = "syntax = 'proto3'; message Person { string name = 1; }"
let proto_file = parse(proto_content)