|
1 | | -# gloto |
| 1 | +# Protozoa |
2 | 2 |
|
3 | 3 | A Protocol Buffers library for Gleam, providing encoding and decoding of protobuf messages. |
4 | 4 |
|
5 | | -[](https://hex.pm/packages/gloto) |
6 | | -[](https://hexdocs.pm/gloto/) |
7 | | - |
8 | | -## Installation |
9 | | - |
10 | | -```sh |
11 | | -gleam add gloto@1 |
12 | | -``` |
13 | | - |
14 | | -## Usage |
15 | | - |
16 | | -### Encoding Messages |
17 | | - |
18 | | -```gleam |
19 | | -import gloto |
20 | | -import gleam/int |
21 | | -import gleam/io |
22 | | -
|
23 | | -pub fn encode_example() { |
24 | | - // Create a protobuf message with multiple fields |
25 | | - let message = gloto.build_message([ |
26 | | - gloto.encode_int32(1, 42), // Field 1: int32 |
27 | | - gloto.encode_string(2, "Hello"), // Field 2: string |
28 | | - gloto.encode_bool(3, True), // Field 3: bool |
29 | | - ]) |
30 | | - |
31 | | - // message is now a BitArray containing the encoded protobuf |
32 | | - message |
33 | | -} |
34 | | -``` |
35 | | - |
36 | | -### Decoding Messages |
37 | | - |
38 | | -```gleam |
39 | | -import gloto |
40 | | -import gleam/int |
41 | | -import gleam/io |
42 | | -
|
43 | | -pub fn decode_example(data: BitArray) { |
44 | | - case gloto.decode(data) { |
45 | | - Ok(fields) -> { |
46 | | - // Find specific fields by number |
47 | | - case gloto.find_field(fields, 1) { |
48 | | - Ok(field) -> { |
49 | | - case gloto.decode_varint_value(field) { |
50 | | - Ok(value) -> io.println("Field 1: " <> int.to_string(value)) |
51 | | - Error(_) -> io.println("Failed to decode field 1") |
52 | | - } |
53 | | - } |
54 | | - Error(_) -> io.println("Field 1 not found") |
55 | | - } |
56 | | - } |
57 | | - Error(_) -> io.println("Failed to decode message") |
58 | | - } |
59 | | -} |
60 | | -``` |
61 | | - |
62 | | -### Nested Messages |
63 | | - |
64 | | -```gleam |
65 | | -import gloto |
66 | | -
|
67 | | -pub fn nested_message_example() { |
68 | | - // Create an inner message |
69 | | - let inner = gloto.build_message([ |
70 | | - gloto.encode_string(1, "inner value"), |
71 | | - gloto.encode_int32(2, 100), |
72 | | - ]) |
73 | | - |
74 | | - // Embed it in an outer message |
75 | | - let outer = gloto.build_message([ |
76 | | - gloto.encode_int32(1, 999), |
77 | | - gloto.encode_message_field(2, inner), // Nested message in field 2 |
78 | | - ]) |
79 | | - |
80 | | - outer |
81 | | -} |
82 | | -``` |
83 | | - |
84 | | -### Repeated Fields |
85 | | - |
86 | | -Protocol Buffers supports repeated fields. Simply encode multiple values with the same field number: |
87 | | - |
88 | | -```gleam |
89 | | -import gloto |
90 | | -
|
91 | | -pub fn repeated_fields_example() { |
92 | | - let message = gloto.build_message([ |
93 | | - gloto.encode_int32(1, 10), |
94 | | - gloto.encode_int32(1, 20), // Same field number |
95 | | - gloto.encode_int32(1, 30), // Creates a repeated field |
96 | | - gloto.encode_string(2, "other field"), |
97 | | - ]) |
98 | | - |
99 | | - // When decoding, use find_all_fields to get all values |
100 | | - case gloto.decode(message) { |
101 | | - Ok(fields) -> { |
102 | | - let repeated = gloto.find_all_fields(fields, 1) |
103 | | - // repeated will contain all three int32 values |
104 | | - repeated |
105 | | - } |
106 | | - Error(_) -> panic |
107 | | - } |
108 | | -} |
109 | | -``` |
110 | | - |
111 | | -## Supported Types |
112 | | - |
113 | | -- **Varint**: int32, int64, bool |
114 | | -- **Fixed32**: 32-bit values with fixed size |
115 | | -- **Fixed64**: 64-bit values with fixed size |
116 | | -- **Length-delimited**: strings, bytes, nested messages |
117 | | - |
118 | | -## Architecture |
119 | | - |
120 | | -The library is structured into three main modules: |
121 | | - |
122 | | -- `gloto/wire` - Wire format types and tag encoding/decoding |
123 | | -- `gloto/encoder` - Functions for encoding various protobuf types |
124 | | -- `gloto/decoder` - Functions for decoding protobuf messages |
125 | | -- `gloto` - High-level API for working with protobuf messages |
126 | | - |
127 | | -## Future Plans |
128 | | - |
129 | | -- Code generation from .proto files |
130 | | -- gRPC support |
131 | | -- Schema validation |
132 | | -- More comprehensive type support |
133 | | - |
134 | | -## Development |
135 | | - |
136 | | -```sh |
137 | | -gleam run # Run the project |
138 | | -gleam test # Run the tests |
139 | | -``` |
140 | | - |
141 | | -Further documentation can be found at <https://hexdocs.pm/gloto>. |
| 5 | +[](https://hex.pm/packages/protozoa) |
| 6 | +[](https://hexdocs.pm/protozoa/) |
0 commit comments