基于云风的skynet，搭建开箱即用的微服务框架，提供优雅的服务热更新

# Google protobuf support for Lua [](https://github.com/starwing/lua-protobuf/actions?query=branch%3Amaster)[](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 [](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