# Google protobuf support for Lua
[![Build Status](https://img.shields.io/github/workflow/status/starwing/lua-protobuf/CI)](https://github.com/starwing/lua-protobuf/actions?query=branch%3Amaster)[![Coverage Status](https://img.shields.io/coveralls/github/starwing/lua-protobuf)](https://coveralls.io/github/starwing/lua-protobuf?branch=master)
English | [中文](https://github.com/starwing/lua-protobuf/blob/master/README.zh.md)
---
This project offers a C module for Lua (5.1, 5.2, 5.3, 5.4 and LuaJIT) manipulating Google's protobuf protocol, both for version 2 and 3 syntax and semantics. It splits to the lower-level and the high-level parts for different goals.
For converting between binary protobuf data with Lua tables, using `pb.load()` loads the compiled protobuf schema content (`*.pb` file) generated by Google protobuf's compiler named `protoc` and call `pb.encode()`/`pb.decode()`.
Or use these modules to manipulate the raw wire format in lower-level way:
- `pb.slice`: a wire format decoding module.
- `pb.buffer`: a buffer implement that use to encode basic types into protobuf's wire format. It can be used to support streaming decode protobuf data.
- `pb.conv`: a module converting integers in the protobuf wire format.
- `pb.io`: a module access `stdin/stdout` or other files in binary mode.
If you don't want to depend Google's protobuf compiler, `protoc.lua` is a pure Lua module translating text-based protobuf schema content into the `*.pb` binary format.
## Install
To install, you could just use `luarocks`:
```shell
luarocks install lua-protobuf
```
If you want to build it from source, just clone the repo and use luarocks:
```shell
git clone https://github.com/starwing/lua-protobuf
luarocks make rockspecs/lua-protobuf-scm-1.rockspec
```
If you don't have luarocks, use `hererocks` to install Lua and luarocks:
```shell
pip install hererocks
git clone https://github.com/starwing/lua-protobuf
hererocks -j 2.0 -rlatest .
bin/luarocks make lua-protobuf/rockspecs/lua-protobuf-scm-1.rockspec CFLAGS="-fPIC -Wall -Wextra" LIBFLAGS="-shared"
cp protoc.lua pb.so ..
```
Or you can build it by hand, it only has a pure Lua module `protoc.lua` and a pair of C source: `pb.h` and `pb.c`. *Notice* that in order to build the `pb` C module, you need Lua header file and/or libary file installed. replace `$LUA_HEADERS` and `$LUA_LIBS` below to real install locations.
To build it on macOS, use your favor compiler:
```shell
gcc -O2 -shared -undefined dynamic_lookup -I "$LUA_HEADERS" pb.c -o pb.so
```
On Linux, use the nearly same command:
```shell
gcc -O2 -shared -fPIC -I "$LUA_HEADERS" pb.c -o pb.so
```
On Windows, you could use MinGW or MSVC, create a `*.sln` project or build it on the command line (notice the `Lua_BUILD_AS_DLL` flag):
```shell
cl /O2 /LD /Fepb.dll /I "$LUA_HEADERS" /DLUA_BUILD_AS_DLL pb.c "$LUA_LIBS"
```
## Example
```lua
local pb = require "pb"
local protoc = require "protoc"
-- load schema from text (just for demo, use protoc.new() in real world)
assert(protoc:load [[
message Phone {
optional string name = 1;
optional int64 phonenumber = 2;
}
message Person {
optional string name = 1;
optional int32 age = 2;
optional string address = 3;
repeated Phone contacts = 4;
} ]])
-- lua table data
local data = {
name = "ilse",
age = 18,
contacts = {
{ name = "alice", phonenumber = 12312341234 },
{ name = "bob", phonenumber = 45645674567 }
}
}
-- encode lua table data into binary format in lua string and return
local bytes = assert(pb.encode("Person", data))
print(pb.tohex(bytes))
-- and decode the binary data back into lua table
local data2 = assert(pb.decode("Person", bytes))
print(require "serpent".block(data2))
```
## Use case
[![零境交错](https://img.tapimg.com/market/images/e59627dc9039ff22ba7d000b5c9fe7f6.jpg?imageView2/2/h/560/q/40/format/jpg/interlace/1/ignore-error/1)](http://djwk.qq.com)
## Usage
### `protoc` Module
| Function | Returns | Descriptions |
| ------------------- | ------------- | ---------------------------------------------------- |
| `protoc.new()` | Proroc object | create a new compiler instance |
| `protoc.reload()` | true | reload all google standard messages into `pb` module |
| `p:parse(string)` | table | transform schema to `DescriptorProto` table |
| `p:compile(string)` | string | transform schema to binary *.pb format data |
| `p:load(string)` | true | load schema into `pb` module |
| `p.loaded` | table | contains all parsed `DescriptorProto` table |
| `p.unknown_import` | see below | handle schema import error |
| `p.unknown_type` | see below | handle unknown type in schema |
| `p.include_imports` | bool | auto load imported proto |
To parse a text schema content, create a compiler instance first:
```lua
local p = protoc.new()
```
Then, set some options to the compiler, e.g. the unknown handlers:
```lua
-- set some hooks
p.unknown_import = function(self, module_name) ... end
p.unknown_type = function(self, type_name) ... end
-- ... and options
p.include_imports = true
```
The `unknown_import` and `unknown_type` handle could be `true`, string or a function. Seting it to `true` means all *non-exist* modules and types are given a default value without triggering an error; A string means a Lua pattern that indicates whether an unknown module or type should raise an error, e.g.
```lua
p.unknown_type = "Foo.*"
```
means all types prefixed by `Foo` will be treat as existing type and do not trigger errors.
If these are functions, the unknown type and module name will be passed to functions. For module handler, it should return a `DescriptorProto` Table produced by `p:load()` functions, for type handler, it should return a type name and type, such as `message` or `enum`, e.g.
```lua
function p:unknown_import(name)
-- if can not find "foo.proto", load "my_foo.proto" instead
return p:parsefile("my_"..name)
end
function p:unknown_type(name)
-- if cannot find "Type", treat it as ".MyType" and is a message type return ".My"..name, "message"
end
```
After setting options, use `load()` or `compile()` or `parse()` function to get result.
### `pb` Module
`pb` module has high-level routines to manipulate protobuf messages.
In below table of functions, we have several types that have special means:
- `type`: a string that indicates the protobuf message type, `".Foo"` means the type in a proto definition that has not `package` statement declared. `"foo.Foo"` means the type in a proto definition that declared `package foo;`
- `data`: could be string, `pb.Slice` value or `pb.Buffer` value.
- `iterator`: a function that can use in Lua `for in` statement, e.g.
```lua
for name in pb.types() do
print(name)
end
```
**NOTICE**: Only `pb.load()` returns error on failure, *do check* the result it returns. Other routines raise a error when failure for convenience.
| Function | Returns | Description |
| ------------------------------ | --------------- | ------------------------------------------------------- |
| `pb.clear()` | None | clear all types |
| `pb.clear(type)` | None | delete specific type |
| `pb.load(data)` | boolean,integer | load a binary schema data into `pb` module |
| `pb.encode(type, table)` | string | encode a message table into binary form |
| `pb.encode(type, table, b)` | buffer | encode a message ta
没有合适的资源?快使用搜索试试~ 我知道了~
温馨提示
skynet_fly是基于skynet扩展的可以快速开发web,游戏,和需要rpc调用的框架。 使用skynet_fly的好处: * 支持不停服更新。 * 一键生成skynet的配置文件和skynet_fly的配置文件以及配套shell脚本。 * 对匹配房间类游戏做了gate,ws_gate的基础设施封装以及pb,json协议的支持,开发游戏只需要实现相关业务逻辑。 * 对redis,mysql,timer,log 使用封装。 * 基于skynet cluster封装出简单易用的远程rpc调用。 * 支持服务发现。 * 支持http服务长连接。 * 支持http服务路由,中间件模式。 * 支持jwt鉴权。 * 内置日志分割。 * 支持快进时间。 * 支持orm(数据关系映射)目前适配了(mysql,mongo),数据库可无缝切换。
资源推荐
资源详情
资源评论
收起资源包目录
skynet-fly websocket/hhtp 热更新方案 rpc远程调用 快速开始 游戏服务 数字炸弹游戏 (523个子文件)
README.adoc 3KB
CHANGELOG.adoc 1015B
ca2-database.txt.attr 21B
.busted 104B
dtoa.c 86KB
rax.c 73KB
ssl.c 67KB
pb.c 62KB
pkey.c 57KB
lstrlib.c 46KB
lua_cjson.c 46KB
ots.c 45KB
x509.c 39KB
asn1.c 38KB
crl.c 29KB
compat-5.3.c 28KB
cipher.c 28KB
lzlib.c 27KB
lfs.c 26KB
ec.c 25KB
cms.c 22KB
bio.c 22KB
ocsp.c 21KB
csr.c 19KB
digest.c 16KB
pkcs7.c 14KB
openssl.c 13KB
ltablib.c 13KB
xexts.c 13KB
compat.c 12KB
rsa.c 12KB
xname.c 12KB
engine.c 12KB
lbn.c 10KB
th-lock.c 10KB
mac.c 9KB
testmod.c 9KB
misc.c 8KB
xstore.c 8KB
lutf8lib.c 7KB
xattrs.c 7KB
auxiliar.c 6KB
fpconv.c 6KB
strbuf.c 6KB
lbitlib.c 5KB
xalgor.c 5KB
srp.c 5KB
lhash.c 5KB
dh.c 4KB
lua_rax.c 4KB
hmac.c 4KB
lua-chat_filter.c 4KB
pkcs12.c 4KB
callback.c 3KB
g_fmt.c 2KB
dsa.c 2KB
util.c 2KB
subsidiar.c 532B
ca2-serial 3B
CHANGES 1KB
dist.cmake 13KB
lua.cmake 11KB
FindLua.cmake 4KB
FindLuaJIT.cmake 3KB
ca2.cnf 748B
agent4.cnf 564B
ca1.cnf 541B
agent1.cnf 510B
agent2.cnf 510B
agent3.cnf 510B
config 1KB
config 1KB
config 1KB
config 892B
config 785B
alice.crt 1KB
doc.css 3KB
octets-escaped.dat 406B
lfs.def 76B
lfs.def 52B
zlib.def 23B
luafilesystem_dll.dsp 5KB
luafilesystem.dsw 611B
.gitattributes 24B
.gitignore 430B
.gitignore 311B
.gitignore 146B
.gitignore 146B
.gitignore 72B
.gitignore 18B
.gitignore 9B
.gitignore 7B
.gitignore 6B
.gitmodules 213B
.gitmodules 83B
pb.h 52KB
compat-5.3.h 12KB
private.h 12KB
rax.h 9KB
sk.h 5KB
共 523 条
- 1
- 2
- 3
- 4
- 5
- 6
资源评论
风蓝天明
- 粉丝: 3
- 资源: 2
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
最新资源
- 基于STM32使用HAL库实现USB组合设备之多路CDC源码+说明文档.zip
- 金融贸易项目springboot
- mybatis动态sqlSQL 映射 XML 文件是所有 sql 语句
- 基于基于STM32的智能家居系统源码+qt上位机源码.zip
- 深圳房地产资源数据报告
- 基于stm32的智能门禁系统源码+设计文档+演示视频.zip
- cef + chromium 完整源码支持h265和h264
- 基于SpringBoot的API管理平台源代码+数据库,以项目的形式管理API文档,可以进行API的编辑、测试、Mock等操作
- protobuf 3.11版本,静态编译
- 2023NOC创客智慧编程赛项真题图形化-选拔赛(有解析)
资源上传下载、课程学习等过程中有任何疑问或建议,欢迎提出宝贵意见哦~我们会及时处理!
点击此处反馈
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功