docs 90%

Change-Id: I0c6891dc8fe2c53822a377bc03ff78cbce3d6208
YYCoder · Aug 9, 2021 · f136975 · f136975
1 parent 15456fc
commit f136975
Show file tree

Hide file tree

Showing 9 changed files with 162 additions and 89 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -12,8 +12,8 @@
             "program": "${workspaceFolder}",
             "args": [
                 // ! file pb 2 thrift
-                "-t=proto2thrift", "-i=./example/proto2thrift/idl.proto", "-o=./example/proto2thrift", "-use-space-indent=1",
-                "-name-case=pascalCase", "-field-case=pascalCase",
+                // "-t=proto2thrift", "-i=./example/proto2thrift/idl.proto", "-o=./example/proto2thrift", "-use-space-indent=1",
+                // "-name-case=pascalCase", "-field-case=pascalCase",
 
                 // ! content pb 2 thrift
                 // "-t=proto2thrift",
@@ -32,8 +32,8 @@
                 // "-field-case=pascalCase",
 
                 // ! multiple file thrift 2 pb
-                // "-t=thrift2proto", "-i=./example/multiple-thrift2proto/idl.thrift", "-o=./example/multiple-thrift2proto/output/output", "-use-space-indent=1",
-                // "-name-case=pascalCase", "-field-case=snakeCase", "-syntax=3",
+                "-t=thrift2proto", "-i=./example/multiple-thrift2proto/idl.thrift", "-o=./example/multiple-thrift2proto/output/output", "-use-space-indent=1",
+                "-name-case=pascalCase", "-field-case=snakeCase", "-syntax=3", "-r=1",
 
                 // ! multiple file pb 2 thrift
                 // "-t=proto2thrift", "-i=./example/multiple-proto2thrift/idl.proto", "-o=./example/multiple-proto2thrift", "-use-space-indent=1",

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # protobuf-thrift
-Little cli utility for lazy guy, transforming protobuf idl to thrift, and vice versa.
+Little cli utility for lazy guy😉 ~ Transforming protobuf idl to thrift, and vice versa.
 
 > [IDL](https://en.wikipedia.org/wiki/IDL)(Interface description language), which is a descriptive language used to define data types and interfaces in a way that is independent of the programming language or operating system/processor platform.
 
@@ -21,19 +21,30 @@ protobuf-thrift -t proto2thrift -i ./path/to/idl.thrift -o ./test.proto`
 ```
 
 ### Interactive Usage
+You can simply run like `protobuf-thrift -t thrift2proto` and then, paste your original idl file to the terminal and press ctrl+D.
 
-<video src="./docs/interactive.mp4" />
+![interactive.gif](./docs/2021-08-09%2021_54_20.gif)
+
+> Note that interactive mode can not use **-r** option, as there is no files, only stdin.
 
 ### Case Converting
+Protobuf-thrift provides complete case convert feature, thanks to [strcase](https://github.com/iancoleman/strcase), available options already listed in **--help** message.
 
 ### Recursive Transforming
+Under some circumstances, you may want to transform a whole idl repo to another language, we provide you **-r** option to indicate protobuf-thrift to transform all imported files.
+
+This option is off by default, so you have to specify it explicitly.
+
+```
+protobuf-thrift -t thrift2proto -i ./path/to/idl.thrift -o ./idl.proto -r 1`
+```
 
 
 ## Options
 
 ![](./docs/usage.jpeg)
 
-## Caveats
+## Caveat
 
 Since protobuf and thrift have many different grammars, we can only transform grammars that have same meaning, e.g. protobuf message => thrift struct, protobuf enum => thrift enum.
 
@@ -53,7 +64,12 @@ Here is a list of transformation rule, so we hope you won't have to worry about
 |bytes|binary|||
 |service|service|rpc => methods||
 |constant|const||not support currently|
+|package|namespace|||
+|import|include|||
+|syntax|||only supported in protobuf, so thrift will omit it|
+|option|||only supported in protobuf, so thrift will omit it|
+|extend|||only supported in protobuf, so thrift will omit it|
+|extension|||only supported in protobuf, so thrift will omit it|
 
-<!-- * import、package、option、syntax、extend、extension 都被忽略 -->
 
 
diff --git a/docs/2021-08-09 21_54_20.gif b/docs/2021-08-09 21_54_20.gif
diff --git a/docs/cn.md b/docs/cn.md
@@ -1,15 +1,71 @@
 # protobuf-thrift
-Little thing for lazy guy, transforming protobuf idl to thrift, and vice versa.
+为懒人准备的 protobuf 与 thrift 互转的小工具😉。
 
-> IDL(Interface description language), reference [Wikipedia](https://en.wikipedia.org/wiki/IDL).
+> [IDL](https://en.wikipedia.org/wiki/IDL)(Interface description language)。是指一种用于定义数据类型以及接口的描述性语言，与编程语言以及平台无关，常用在微服务架构中。
 
-[cn](./docs/cn.md)
+## 使用示例
 
-## Caveats
+### 基本用法
+将 thrift 文件转成 protobuf 文件：
 
-Since protobuf and thrift have many different grammars, so we can only transform grammars that have same meaning, e.g. protobuf message => thrift struct, protobuf enum => thrift enum.
+```
+protobuf-thrift -t thrift2proto -i ./path/to/idl.thrift -o ./idl.proto`
+```
+
+将 protobuf 文件转成 thrift 文件：
+
+```
+protobuf-thrift -t proto2thrift -i ./path/to/idl.thrift -o ./test.proto`
+```
+
+### 交互式用法
+直接使用 `protobuf-thrift -t thrift2proto` 命令会进入交互模式，直接粘贴你的源 idl 源码到终端，并按下 ctrl+D 即可。
+
+![interactive.gif](./2021-08-09%2021_54_20.gif)
+
+### 大小写转换
+得益于 [strcase](https://github.com/iancoleman/strcase)，Protobuf-thrift 提供了完整的变量大小写转换能力，可用的选项已经在 **--help** 提示信息中了，请自行查阅。
+
+### 递归转换
+某些场景下，我们可能需要将整个 idl 仓库转成另一种语言，此时我们就可以使用 **-r** 选项来递归地将 import 的文件全部转换。
+
+该选项默认是禁用的，要使用它时需要显式指定。
+
+
+```
+protobuf-thrift -t thrift2proto -i ./path/to/idl.thrift -o ./idl.proto -r 1`
+```
+
+
+## 可用选项
+
+![](./usage.jpeg)
+
+## 使用声明
+由于 protobuf 与 thrift 有很多语法上的不同，我们不可能完全将一种 idl 转换成另一种，protobuf-thrift 也只是一个帮助我们摆脱复制粘贴的小工具，它所提供的功能能够满足 80% 的场景就足够了。因此，我们只会尽可能将有相同语义的语法进行转换，如 protobuf message => thrift struct，protobuf enum => thrift enum。
+
+为了确保你能够明确的知道 protobuf-thrift 会如何转换，如下是目前的转换规则：
+
+|protobuf type|thrift type|field type|notice|
+|:--:|:--:|:--:|:--:|
+|message|struct|optional => optional; repeated T => list\<T\>|only protobuf 2 have optional field|
+|map<T1,T2>|map<T1,T2>||T1 only support int32/int64/string/float/double, due to thrift syntax|
+|enum|enum|||
+|int32|i32|||
+|int64|i64|||
+|float|double|||
+|double|double|||
+|bool|bool|||
+|string|string|||
+|bytes|binary|||
+|service|service|rpc => methods||
+|constant|const||not support currently|
+|package|namespace|||
+|import|include|||
+|syntax|||only supported in protobuf, so thrift will omit it|
+|option|||only supported in protobuf, so thrift will omit it|
+|extend|||only supported in protobuf, so thrift will omit it|
+|extension|||only supported in protobuf, so thrift will omit it|
 
-Here is a list of transformation rule, so we hope you won't have to worry about protobuf-thrift 
 
-* 
 
diff --git a/docs/interactive.mp4 b/docs/interactive.mp4
diff --git a/example/multiple-proto2thrift/common/admin.thrift b/example/multiple-proto2thrift/common/admin.thrift
@@ -1,7 +1,7 @@
-enum Status {
-    StatusUnknown = 0
-    StatusUnreviewed = 1
-    StatusOnline = 2
-    StatusRejected = 3
-    StatusOffline = 4
+enum status {
+	statusUnknown = 0
+	statusUnreviewed = 1
+	statusOnline = 2
+	statusRejected = 3
+	statusOffline = 4
 }
diff --git a/example/multiple-proto2thrift/idl.thrift b/example/multiple-proto2thrift/idl.thrift
@@ -1,26 +1,27 @@
-include "./test.thrift";
 include "./common/admin.thrift";
-enum OtherEnum {
-    OtherEnumUnknown = 0
-    Unreviewed = 1
-    Online = 2
-    Rejected = 3
-    Offline = 4
+include "./test.thrift";
+enum otherEnum {
+	otherEnumUnknown = 0
+	unreviewed = 1
+	online = 2
+	rejected = 3
+	offline = 4
 }
-struct Config {
-    1: i64 Id
-    2: i32 Tag
-    3: list<i32> TypeList
-    4: bool Boolean
-    5: admin.Status Status
-    6: map<i64,string> FailMap
-    7: double Fl
-    8: double Db
-    9: binary Bs
-    10: test.TimeRange Nested
-    11: list<test.TimeRange> NestedTypeList
-    12: map<string,test.TimeRange> NestedTypeMap
+struct config {
+	1: i64 id
+	2: i32 tag
+	3: list<i32> typeList
+	4: bool boolean
+	5: admin.status status
+	6: map<i64,string> failMap
+	7: double fl
+	8: double db
+	9: binary bs
+	10: test.timeRange nested
+	11: list<test.timeRange> nestedTypeList
+	12: map<string,test.timeRange> nestedTypeMap
 }
-service APIs {
-    Config TestOther (1: Config Req)
+
+service aPIs {
+	Config testOther (1: Config req)
 }
diff --git a/example/multiple-proto2thrift/test.thrift b/example/multiple-proto2thrift/test.thrift
@@ -1,4 +1,4 @@
-struct TimeRange {
-    1: i64 Start
-    2: i64 End
+struct timeRange {
+	1: i64 start
+	2: i64 end
 }
diff --git a/example/proto2thrift/idl.thrift b/example/proto2thrift/idl.thrift
@@ -1,48 +1,48 @@
 namespace * test.test.test;
 
-enum Status {
-    StatusUnknown = 0
-    StatusUnreviewed = 1
-    StatusOnline = 2
-    StatusRejected = 3
-    StatusOffline = 4
-}
-struct Config {
-    1: i64 Id
-    2: optional i32 Tag
-    3: list<i32> TypeList
-    4: optional bool Boolean
-    5: Status Status
-    6: map<i64,string> FailMap
-    7: double Fl
-    8: double Db
-    9: binary Bs
-    10: TimeRange Nested
-    11: list<TimeRange> NestedTypeList
-    12: map<string,TimeRange> NestedTypeMap
-}
-struct TimeRange {
-    1: i64 Start
-    2: i64 End
-}
-struct ReqOfTestGetApi {
-    1: i64 A
-    2: string B
-}
-struct RespOfTestGetApi {
-    1: i32 Code
-    2: string Message
-}
-struct ReqOfTestPostApi {
-    1: i64 A
-    2: string B
-}
-struct RespOfTestPostApi {
-    1: i32 Code
-    2: string Message
+enum status {
+	statusUnknown = 0
+	statusUnreviewed = 1
+	statusOnline = 2
+	statusRejected = 3
+	statusOffline = 4
+}
+struct reqOfTestPostApi {
+	1: i64 a
+	2: string b
+}
+struct respOfTestPostApi {
+	1: i32 code
+	2: string message
+}
+struct config {
+	1: i64 id
+	2: i32 tag
+	3: list<i32> typeList
+	4: bool boolean
+	5: status status
+	6: map<i64,string> failMap
+	7: double fl
+	8: double db
+	9: binary bs
+	10: timeRange nested
+	11: list<timeRange> nestedTypeList
+	12: map<string,timeRange> nestedTypeMap
+}
+struct timeRange {
+	1: i64 start
+	2: i64 end
+}
+struct reqOfTestGetApi {
+	1: i64 a
+	2: string b
+}
+struct respOfTestGetApi {
+	1: i32 code
+	2: string message
 }
 
-service APIs {
-    RespOfTestGetApi TestGetApi (1: ReqOfTestGetApi Req)
-    RespOfTestPostApi TestPostApi (1: ReqOfTestPostApi Req)
+service aPIs {
+	RespOfTestGetApi testGetApi (1: ReqOfTestGetApi req)
+	RespOfTestPostApi testPostApi (1: ReqOfTestPostApi req)
 }