Skip to content

Commit c07aba0

Browse files
starwingstarwing
committed
improve documents
1 parent 1c1e4f0 commit c07aba0

3 files changed

Lines changed: 36 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -193,20 +193,21 @@ In below table of functions, we have several types that have special means:
193193
| `pb.encode(type, table, b)` | buffer | encode a message table into binary form to buffer |
194194
| `pb.decode(type, data)` | table | decode a binary message into Lua table |
195195
| `pb.decode(type, data, table)` | table | decode a binary message into a given Lua table |
196-
| `pb.pack(fmt, ...)` | string | same as `buffer.pack()` but return string |
197-
| `pb.unpack(data, fmt, ...)` | values... | same as `slice.unpack()` but accept data |
196+
| `pb.pack(type, ...)` | string | encode a message with flatten fields (ordered by field number) |
197+
| `pb.unpack(data, type, ...)` | values... | decode a message with flatten fields (just like above) |
198198
| `pb.types()` | iterator | iterate all types in `pb` module |
199199
| `pb.type(type)` | see below | return informations for specific type |
200200
| `pb.fields(type)` | iterator | iterate all fields in a message |
201201
| `pb.field(type, string)` | see below | return informations for specific field of type |
202-
| `pb.typefmt(type)` | String | transform type name of field into pack/unpack formatter |
202+
| `pb.typefmt(type)` | string | transform type name of field into pack/unpack formatter |
203203
| `pb.enum(type, string)` | number | get the value of a enum by name |
204204
| `pb.enum(type, number)` | string | get the name of a enum by value |
205205
| `pb.defaults(type[, table/nil])` | table | get the default table of type |
206206
| `pb.hook(type[, function])` | function | get or set hook functions |
207207
| `pb.option(string)` | string | set options to decoder/encoder |
208208
| `pb.state()` | `pb.State` | retrieve current pb state |
209209
| `pb.state(newstate \| nil)` | `pb.State` | set new pb state and retrieve the old one |
210+
| `pb.tohex(string)` | string | encode string as hexadigits, for debug purposes |
210211

211212
#### Schema loading
212213

@@ -318,6 +319,10 @@ local function make_hook(name, func)
318319
end
319320
```
320321

322+
You could enable “encode hooking” function by call `pb.option “enable_enchooks”`. encode hooks will be called **before** any message or enum value been encoded. The hook caller only accepts one value, the comming encoding value, and can returns a new value that instead to be encoded. The hook could returns `nil` or just not return anything to makes `pb.encode` just encode the original value.
323+
324+
You could setup encode hooks by `pb.encode_hook()` routine, it’s just as same as `pb.hook()`, but for getting/setting the encode hooks.
325+
321326
#### Options
322327

323328
Setting options to change the behavior of other routines.
@@ -335,15 +340,17 @@ These options are supported currently:
335340
| `use_default_values` | set default values by copy values from default table before decode |
336341
| `use_default_metatable` | set default values by set table from `pb.default()` as the metatable |
337342
| `enable_hooks` | `pb.decode` will call `pb.hooks()` hook functions |
338-
| `disable_hooks` | `pb.decode` do not call hooks **(default)** |
339-
| `encode_default_values` | default values also encode |
343+
| `disable_hooks` | `pb.decode` do not call hooks **(default)** |
344+
| `enable_enchooks` | `pb.encode` will call `pb.encode_hook()` hook functions |
345+
| `disable_enchooks` | do not call hooks when encoding messages **(default)** |
346+
| `encode_default_values` | `pb.encode` encode the default value into the wire format |
340347
| `no_encode_default_values` | do not encode default values **(default)** |
341348
| `decode_default_array` | work with `no_default_values`,decode null to empty table for array |
342349
| `no_decode_default_array` | work with `no_default_values`,decode null to nil for array **(default)** |
343-
| `encode_order` | guarantees the same message will be encoded into the same result with the same schema and the same data (but the order itself is not specified) |
350+
| `encode_order` | `pb.encode` encode the messages with field number order |
344351
| `no_encode_order` | do not have guarantees about encode orders **(default)** |
345-
| `decode_default_message` | decode null message to default message table |
346-
| `no_decode_default_message` | decode null message to null **(default)** |
352+
| `decode_default_message` | `pb.decode` decode the empty messages as a empty table |
353+
| `no_decode_default_message` | `pb.decode` decode the empty messages as `nil` **(default)** |
347354

348355
*Note*: The string returned by `int64_as_string` or `int64_as_hexstring` will prefix a `'#'` character. Because Lua may convert between string with number, prefix a `'#'` makes Lua return the string as-is.
349356

‎README.zh.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -212,21 +212,23 @@ end
212212
| `pb.encode(type, table, b)` | buffer | 同上，但是编码进额外提供的buffer对象里并返回 |
213213
| `pb.decode(type, data)` | table | 将二进制data按照type消息类型解码为一个表 |
214214
| `pb.decode(type, data, table)` | table | 同上，但是解码到你提供的表里 |
215-
| `pb.pack(fmt, ...)` | string | 同 `buffer.pack()` ，但直接用字符串返回二进制数据 |
216-
| `pb.unpack(data, fmt, ...)` | values... | 同 `slice.unpack()` 但是接受任何二进制类型数据 |
215+
| `pb.pack(type, ...)` | string | 编码展开后的消息（后续参数按number顺序提供） |
216+
| `pb.unpack(data, fmt, ...)` | values... | 解码展开后的消息（同上） |
217217
| `pb.types()` | iterator | 遍历内存数据库里所有的消息类型，返回具体信息 |
218218
| `pb.type(type)` | 详情见下 | 返回内存数据库特定消息类型的具体信息 |
219219
| `pb.fields(type)` | iterator | 遍历特定消息里所有的域，返回具体信息 |
220220
| `pb.field(type, string)` | 详情见下 | 返回特定消息里特定域的具体信息 |
221221
| `pb.field(type, number)` | 详情见下 | 返回特定消息里特定域的具体信息 |
222-
| `pb.typefmt(type)` | String | 得到 protobuf 数据类型名对应的 pack/unpack 的格式字符串 |
222+
| `pb.typefmt(type)` | string | 得到 protobuf 数据类型名对应的 pack/unpack 的格式字符串 |
223223
| `pb.enum(type, string)` | number | 提供特定枚举里的名字，返回枚举数字 |
224224
| `pb.enum(type, number)` | string | 提供特定枚举里的数字，返回枚举名字 |
225225
| `pb.defaults(type[, table|nil])` | table | 获得或设置特定消息类型的默认表 |
226226
| `pb.hook(type[, function])` | function | 获得或设置特定消息类型的解码钩子 |
227+
| `pb.encode_hook(type[, function])` | function | 获得或设置特定消息类型的编码钩子 |
227228
| `pb.option(string)` | string | 设置编码或解码的具体选项 |
228229
| `pb.state()` | `pb.State` | 返回当前的内存数据库 |
229230
| `pb.state(newstate \| nil)` | `pb.State` | 设置或删除当前的内存数据库，返回旧的内存数据库 |
231+
| `pb.tohex(string)` | string | 将string（通常是二进制数据）编码成16进制串用于显示，通常用于调试的目的。 |
230232

231233
#### 内存数据库载入 Schema 信息
232234

@@ -353,6 +355,10 @@ local function make_hook(name, func)
353355
end
354356
```
355357

358+
你可以通过 `pb.option “enable_enchooks”` 启用编码钩子功能。编码钩子会在编码消息中任何 `message` 或者 `enum` 类型的成员**之前**调用。只有一个参数即该成员本体。如果你有返回任何值，那么这个值就会被作为这个 `message` 或者 `enum` 被编码。返回 `nil` （或者不返回值）则待编码的值不变。
359+
360+
编码钩子通过 `pb.encode_hook()` 函数设置，该函数和 `pb.hook()` 类似，但是用来设置编码钩子。
361+
356362
#### 选项
357363

358364
你可以通过调用`pb.option()`函数设置选项来改变编码/解码时的行为。
@@ -372,11 +378,13 @@ end
372378
| `use_default_metatable` | 将默认值表作为解码目标表的元表使用 |
373379
| `enable_hooks` | `pb.decode` 启用钩子功能 |
374380
| `disable_hooks` | `pb.decode` 禁用钩子功能 **(默认)** |
381+
| `enable_enchooks` | `pb.encode`启用钩子功能 |
382+
| `disable_enchooks` | `pb.encode` 禁用钩子功能 **(默认)** |
375383
| `encode_default_values` | 默认值也参与编码 |
376384
| `no_encode_default_values` | 默认值不参与编码 **(默认)** |
377385
| `decode_default_array` | 配合`no_default_values`选项，对于数组，将空值解码为空表 |
378386
| `no_decode_default_array` | 配合`no_default_values`选项，对于数组，将空值解码为nil **(默认)** |
379-
| `encode_order` | 保证对相同的schema和data，`pb.encode`编码出的结果一致。注意这个选项会损失效率 |
387+
| `encode_order` | 保证对相同的schema和data，`pb.encode`编码出的结果一致（按照field number的顺序进行编码）。如果message中空field特别多，可能会导致效率下降。 |
380388
| `no_encode_order` | 不保证对相同输入，`pb.encode`编码出的结果一致。**(默认)** |
381389
| `decode_default_message` | 将空子消息解析成默认值表 |
382390
| `no_decode_default_message` | 将空子消息解析成 `nil` **(default)** |

‎pb.c‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1576,14 +1576,15 @@ static void lpb_checktable(lua_State *L, int idx, const pb_Field *f) {
15761576
(const char*)f->name, luaL_typename(L, idx));
15771577
}
15781578

1579-
static void lpb_useenchooks(lua_State *L, lpb_State *LS, const pb_Type *t) {
1580-
lpb_pushenchooktable(L, LS);
1579+
static void lpb_useenchooks(lpb_Env *e, int idx, const pb_Type *t) {
1580+
lua_State *L = e->L;
1581+
lpb_pushenchooktable(L, e->LS);
15811582
if (lua53_rawgetp(L, -1, t) != LUA_TNIL) {
1582-
lua_pushvalue(L, -3);
1583+
lua_pushvalue(L, lpb_relindex(idx, 2));
15831584
lua_call(L, 1, 1);
15841585
if (!lua_isnil(L, -1)) {
15851586
lua_pushvalue(L, -1);
1586-
lua_replace(L, -4);
1587+
lua_replace(L, lpb_relindex(idx, 3));
15871588
}
15881589
}
15891590
lua_pop(L, 2);
@@ -1618,14 +1619,14 @@ static void lpbE_field(lpb_Env *e, int idx, const pb_Field *f, lpbE_Mode m) {
16181619
int r;
16191620
switch (f->type_id) {
16201621
case PB_Tenum:
1621-
if (e->LS->use_enc_hooks) lpb_useenchooks(L, e->LS, f->type);
1622+
if (e->LS->use_enc_hooks) lpb_useenchooks(e, idx, f->type);
16221623
v.u64 = lpbE_readenum(e, idx, f);
16231624
if (m == lpbE_NoZero && v.u64 == 0) return;
16241625
else if (m != lpbE_Raw) lpbE_writetag(e, f);
16251626
len = pb_addvarint64(e->b, v.u64);
16261627
break;
16271628
case PB_Tmessage:
1628-
if (e->LS->use_enc_hooks) lpb_useenchooks(L, e->LS, f->type);
1629+
if (e->LS->use_enc_hooks) lpb_useenchooks(e, idx, f->type);
16291630
lpb_checktable(L, idx, f);
16301631
oldlen = pb_bufflen(e->b);
16311632
assert(m != lpbE_Raw);
@@ -1732,9 +1733,8 @@ static int Lpb_encode(lua_State *L) {
17321733
luaL_checktype(L, 2, LUA_TTABLE);
17331734
e.L = L, e.LS = LS, e.b = test_buffer(L, 3);
17341735
if (e.b == NULL) e.b = &LS->buffer, pb_bufflen(e.b) = 0;
1735-
lua_pushvalue(L, 2);
1736-
if (e.LS->use_enc_hooks) lpb_useenchooks(L, e.LS, t);
1737-
lpbE_encode(&e, -1, t);
1736+
if (e.LS->use_enc_hooks) lpb_useenchooks(&e, 2, t);
1737+
lpbE_encode(&e, 2, t);
17381738
if (e.b != &LS->buffer)
17391739
lua_settop(L, 3);
17401740
else

0 commit comments

Comments
 (0)