Update for xresloader 2.8.0

.vscode/settings.json

@@ -1,23 +1,23 @@
 {
-    "editor.fontFamily": "Noto Sans Mono CJK SC, YaHei Consolas Hybrid,Source Code Pro,Microsoft YaHei,Consolas,serif",
-    "editor.fontSize": 16,
-    "restructuredtext.builtDocumentationPath": "${workspaceRoot}/build/html",
-    "restructuredtext.linter.extraArgs": [],
-    "files.associations": {
-        "*.ejs": "html",
-        "algorithm": "cpp",
-        "iosfwd": "cpp",
-        "fstream": "cpp",
-        "vector": "cpp",
-        "xstring": "cpp",
-        "xutility": "cpp"
-    },
-    "python.linting.pylintPath": "${workspaceFolder}/py3env/bin/pylint",
-    "python.linting.flake8Path": "${workspaceFolder}/py3env/bin/flake8",
-    "python.formatting.yapfPath": "${workspaceFolder}/py3env/bin/yapf",
-    "python.formatting.autopep8Path": "${workspaceFolder}/py3env/bin/autopep8",
-    "python.linting.pycodestylePath": "${workspaceFolder}/py3env/bin/pep8",
-    "python.linting.pydocstylePath": "${workspaceFolder}/py3env/bin/pydocstyle",
-    "python.pythonPath": "${workspaceFolder}/py3env/bin/python",
-    "restructuredtext.confPath": "${workspaceFolder}\\source"
-}
+  "editor.fontFamily": "Noto Sans Mono CJK SC, YaHei Consolas Hybrid,Source Code Pro,Microsoft YaHei,Consolas,serif",
+  "editor.fontSize": 16,
+  "restructuredtext.builtDocumentationPath": "${workspaceRoot}/build/html",
+  "restructuredtext.linter.extraArgs": [],
+  "files.associations": {
+    "*.ejs": "html",
+    "algorithm": "cpp",
+    "iosfwd": "cpp",
+    "fstream": "cpp",
+    "vector": "cpp",
+    "xstring": "cpp",
+    "xutility": "cpp"
+  },
+  // "python.linting.pylintPath": "${workspaceFolder}/py3env/bin/pylint",
+  // "python.linting.flake8Path": "${workspaceFolder}/py3env/bin/flake8",
+  // "python.formatting.yapfPath": "${workspaceFolder}/py3env/bin/yapf",
+  // "python.formatting.autopep8Path": "${workspaceFolder}/py3env/bin/autopep8",
+  // "python.linting.pycodestylePath": "${workspaceFolder}/py3env/bin/pep8",
+  // "python.linting.pydocstylePath": "${workspaceFolder}/py3env/bin/pydocstyle",
+  // "python.pythonPath": "${workspaceFolder}/py3env/bin/python",
+  "restructuredtext.confPath": "${workspaceFolder}\\source"
+}

source/sample/quick_start/sample-conf/kind.proto

@@ -1,6 +1,7 @@
 syntax = "proto3";
 
 import "xresloader.proto";
+// xresloader的发布页面 https://github.com/xresloader/xresloader/releases 下载 protocols.zip ，即可获取xresloader.proto
 
 enum cost_type {
   EN_CT_UNKNOWN = 0;

source/sample/quick_start/sample-conf/sample.xml

@@ -15,6 +15,7 @@
         <java_option desc="java选项-客户端模式">-client</java_option>
 
         <default_scheme name="KeyRow" desc="默认scheme模式参数-Key行号，对应上面Id、Level、CostType、CostValue那一行">2</default_scheme>
+        <option desc="全局自定义选项" name="美化文本输出，缩进为2个空格">--pretty 2</option>
     </global>
 
     <groups desc="分组信息（可选）">

source/sample/xresconv_conf.xml

@@ -3,7 +3,7 @@
     <include desc="可以包含其他文件配置，然后本文件里的配置将会覆盖或合并配置，相对于当前xml的目录">sample.xml</include>
     <global>
         <work_dir desc="工作目录，相对于当前xml的目录">../xresloader/sample</work_dir>
-        <xresloader_path desc="xresloader地址，相对于当前xml的目录">../target/xresloader-2.7.1.jar</xresloader_path>
+        <xresloader_path desc="xresloader地址，相对于当前xml的目录">../target/xresloader-2.8.0.jar</xresloader_path>
 
         <proto desc="协议类型，对应xresloader的-p选项">protobuf</proto>
         <output_type desc="输出类型，-t选项，支持多个同时配置多种输出">bin</output_type>
@@ -24,6 +24,8 @@
         <!-- default_scheme 是下面直接填写scheme时的默认参数。如果后面的scheme标签设置两相同的name，则该条目会覆盖默认配置 -->
         <default_scheme name="KeyRow" desc="默认scheme模式参数-Key行号">2</default_scheme>
         <default_scheme name="MacroSource" desc="默认scheme模式参数-Key行号">资源转换示例.xlsx|macro|2,1</default_scheme>
+
+        <option desc="全局自定义选项" name="美化文本输出，缩进为2个空格">--pretty 2</option>
     </global>
 
     <gui>

source/users/advance_usage.rst

@@ -3,13 +3,13 @@
 
 .. _xresloader: https://github.com/xresloader/xresloader
 .. _xresloader sample: https://github.com/xresloader/xresloader/tree/master/sample
-.. _xresloader sample proto_v3 kind.proto: https://github.com/xresloader/xresloader/tree/master/sample
+.. _`xresloader/sample/proto_v3/kind.proto`: https://github.com/xresloader/xresloader/blob/master/sample/proto_v3/kind.proto
 .. _xresloader header extensions: https://github.com/xresloader/xresloader/tree/master/header/extensions
 .. _xresloader header extensions v2: https://github.com/xresloader/xresloader/tree/master/header/extensions/v2
 .. _xresloader header extensions v3: https://github.com/xresloader/xresloader/tree/master/header/extensions/v3
 
 文本替换（别名/宏）
----------------------------------------------
+-----------------------------------------------------
 
 为了便于理解，我们支持配置一组别名的表。在 ``MacroSource`` 中，主配置为文件名，次配置为表明，补充配置为Key-Value的开始行号和列号。比如：
 
@@ -32,14 +32,14 @@
 +--------+-------+
 
 多表数据合并
----------------------------------------------
+-----------------------------------------------------
 
 如果Excel的多个表的结构相同（列对应的字段相同）。则我们可以通过配置多个 ``DataSource`` 来让 `xresloader`_ 对多个表进行数据合并。这样我们可以把数据按类型分布在几个表中并在转换的时候最后合并。
 
 详见 `xresloader sample`_ 中 ``资源转换示例.xlsx`` 的 ``scheme_upgrade`` 、 ``upgrade_10001`` 和 ``upgrade_10002`` 表。
 
 数据验证器
----------------------------------------------
+-----------------------------------------------------
 
 `xresloader`_ 提供了一个基于协议描述得高级功能- **数据验证器** 。用于限制输入数据的范围。 
 **数据验证器** 的使用方法是在Excel的字段名后面跟 ``@`` 符号，然后输入协议名称或者数字范围 ``A-B`` ，多个验证器可以用 ``|`` 隔开。 
@@ -91,7 +91,7 @@
 这时在转出数据的时候，转出的数据是 ``unit_attribute.hp`` 的字段编号 ``1`` 。
 
 Protobuf 插件支持
----------------------------------------------
+-----------------------------------------------------
 
 项目中可以导入 `xresloader header extensions`_ 目录， 然后通过导入 `xresloader header extensions v2`_ 或 `xresloader header extensions v3`_ 中的相应proto文件，就可以获得额外的插件扩展支持。
 
@@ -114,7 +114,7 @@ Protobuf插件 - Message插件
 | org.xresloader.ue.not_data_table         |   bool  | 生成UE Utility代码时，不生产加载代码，这用于带name字段的依赖类型                                |
 +------------------------------------------+---------+-------------------------------------------------------------------------------------------------+
 
-比如 `xresloader sample proto_v3 kind.proto`_ 里， ``arr_in_arr_cfg`` 配置了相关字段，会影响到一些输出。
+比如 `xresloader/sample/proto_v3/kind.proto`_ 里， ``arr_in_arr_cfg`` 配置了相关字段，会影响到一些输出。
 
 Protobuf插件 - Field插件
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -185,7 +185,7 @@ Protobuf插件 - EnumValue插件
 |    org.xresloader.enum_alias         |  string |                                   枚举值别名，可用于验证器和Excel中直接填别名                                        |
 +--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
 
-比如 `xresloader sample proto_v3 kind.proto`_ 里， ``role_upgrade_cfg`` 内的 ``CostType`` 这一列配置验证器引射到协议的 ``cost_type`` 和 协议描述字段。
+比如 `xresloader/sample/proto_v3/kind.proto`_ 里， ``role_upgrade_cfg`` 内的 ``CostType`` 这一列配置验证器引射到协议的 ``cost_type`` 和 协议描述字段。
 
 .. literalinclude:: ../sample/quick_start/sample-conf/kind.proto
     :language: proto
@@ -222,15 +222,112 @@ Protobuf插件 - Oneof插件(2.8.0版本及以上)
 即，我们可能会有一个 ``role_server`` 和 ``role_client`` 。这两个数据结构不一样，但指向同一个数据源。
 
 批量转表的include标签
----------------------------------------------
+-----------------------------------------------------
 
 公式支持
----------------------------------------------
+-----------------------------------------------------
 
 `xresloader`_ 支持公式功能，但是不建议使用跨文件公式。是因为有些平台里，文件的引用可能会使用绝对路径，这时候如果改变一个文件中的值会影响另一个文件。
 而另一个文件计算公式的时候读取失败，则会用之前的数据缓存（Excel中对所有公式的计算结果有缓存）。这时候数据可能滞后，但是是没有提示的。可能会引起困惑。
 
 定长数组
----------------------------------------------
+-----------------------------------------------------
 
 详见 :ref:`数据类型说明-定长数组 <data-types-stable-array>` 章节。
+
+Plain模式（需要 `xresloader`_ 2.7.0及以上）
+-----------------------------------------------------
+
+为了方便某些特殊场景使用，从 `xresloader`_ 2.7.0版本开始，我们开支支持Plain模式。
+Plain模式的配置方式允许把数字和字符串数组和整个message配置在一个单元格里，多个元素或者多个字段按分隔符分割。分隔符支持多个候选项，实际执行会采用按输入的字符串中，第一个找到的候选项。
+默认的分隔符候选项是 ``,;|`` 。
+
+Plain模式不需要额外配置，当数组元素没有配置下标或者配置的映射字段直接指向一个message时，将自动使用Plain模式解析。
+
+比如对于以下协议：
+
+.. code-block:: proto
+
+  message cfg {
+      int32 id = 1;
+      plain_message plain_msg = 2;
+      repeated int32 plain_arr = 3;
+  }
+
+  message plain_message {
+      int32 id = 1;
+      repeated int32 param = 2;
+  }
+
+如果Excel配置是如下形式:
+
++------------+------------+------------+
+|   配置ID   |  Plain结构 | Plain数组  |
++============+============+============+
+|  id        | plain_msg  | plain_arr  |
++------------+------------+------------+
+| 101        | 101\|1,2,3 | 7;8;9      |
++------------+------------+------------+
+
+那么对于 ``plain_msg`` 字段输入的字符串是 ``101|1,2,3`` ，第一个 ``|`` 会作为 ``plain_msg`` 的字段分隔符， ``,`` 会作为 ``plain_msg.param`` 的数组分隔符。 
+而对于 ``plain_arr`` 字段输入的字符串是 ``7;8;9`` , ``;`` 会作为数组分隔符。
+
+如果想要指定自定义分隔符，特别是对 ``repeated message`` 要区分message的分隔符和数组的分隔符，可以使用使用 ``org.xresloader.field_separator`` 插件和 ``org.xresloader.msg_separator`` 插件。
+需要注意的是，对于数组（repeated）的字段，字段分隔符仅接受通过 ``org.xresloader.field_separator`` 指定，而非数组的复杂数据结构（非repeated message） ``org.xresloader.field_separator`` 插件和 ``org.xresloader.msg_separator`` 都可以用于指定分隔符。
+
+同时，在Plain模式中，message字段解析是严格按照配置的field number的顺序。
+
+更多详情请参考 `xresloader sample`_ 的 ``arr_in_arr`` 表，对应协议是 `xresloader/sample/proto_v3/kind.proto`_ 中的 ``message arr_in_arr_cfg`` 。
+
+**``UE-Csv`` 和 ``UE-Json`` 输出的Plain模式需要 `xresloader`_ 2.8.0及以上。**
+
+Oneof/Union支持（需要 `xresloader`_ 2.8.0及以上）
+-----------------------------------------------------
+
+`xresloader`_ 对Oneof的支持和Plain模式类似，并且只能通过Plain模式一样的方法配置，可以使用 ``org.xresloader.oneof_separator`` 插件指定自定义分隔符。
+
+Oneof/Union支持的配置方法是直接在Excel字段映射中配置oneof的名字。输入字符串中第一组为字段的名字、数字标识（field number）或别名，第二组为对应的类型的Plain模式输入。比如:
+
+.. code-block:: proto
+
+  // 常量类型
+  enum cost_type {
+      EN_CT_UNKNOWN              = 0;
+      EN_CT_MONEY                = 10001 [(org.xresloader.enum_alias) = "金币"];
+      EN_CT_DIAMOND              = 10101 [(org.xresloader.enum_alias) = "钻石"];
+  }
+  message cfg {
+    int32 id = 1;
+    oneof reward {
+      plain_message msg       = 11 [ (org.xresloader.field_alias) = "嵌套结构" ];
+      int64         user_exp  = 12 [ (org.xresloader.field_alias) = "数字类型" ];
+      string        note      = 13 [ (org.xresloader.field_alias) = "描述文本" ];
+      cost_type     enum_type = 14 [ (org.xresloader.field_alias) = "货币类型" ];
+    }
+  }
+  message plain_message {
+      int32 id = 1;
+      repeated int32 param = 2;
+  }
+
+以下输入都是允许的：
+
++------------+-------------------------+
+|   配置ID   |  Oneof结构              |
++============+=========================+
+| id         | reward                  |
++------------+-------------------------+
+| 1001       | msg\|101;1,2,3          |
++------------+-------------------------+
+| 1002       | 数字类型\|100           |
++------------+-------------------------+
+| 1003       | 13\|Hello World         |
++------------+-------------------------+
+| 1004       | enum_type\|金币         |
++------------+-------------------------+
+| 1005       | 货币类型\|EN_CT_DIAMOND |
++------------+-------------------------+
+
+需要特别注意的是，和Plain模式一样，message字段解析是严格按照配置的field number的顺序，如果message里有嵌套的oneof，那么oneof的输入位置是第一个相关字段的位置，并且该oneof里后续的字段不需要配置。
+
+更多详情请参考 `xresloader sample`_ 的 ``test_oneof`` 表，对应协议是 `xresloader/sample/proto_v3/kind.proto`_ 中的 ``message event_cfg`` 。

source/users/faq.rst

@@ -35,11 +35,7 @@ Windows下控制台里执行执行会报文件编码错误？（java.nio.charset
             at java.nio.charset.Charset.forName(Unknown Source)
             at org.apache.logging.log4j.util.PropertiesUtil.getCharsetProperty(PropertiesUtil.java:146)
             at org.apache.logging.log4j.util.PropertiesUtil.getCharsetProperty(PropertiesUtil.java:134)
-            at org.apache.logging.log4j.core.appender.ConsoleAppender$Target.getCharset(ConsoleAppender.java:85)
-            at org.apache.logging.log4j.core.appender.ConsoleAppender$Target$1.getDefaultCharset(ConsoleAppender.java:71)
-            at org.apache.logging.log4j.core.appender.ConsoleAppender$Builder.build(ConsoleAppender.java:218)
-            at org.apache.logging.log4j.core.appender.ConsoleAppender$Builder.build(ConsoleAppender.java:185)
-            at org.apache.logging.log4j.core.config.plugins.util.PluginBuilder.build(PluginBuilder.java:122)
+            ...
     ...
 
 和
@@ -51,15 +47,7 @@ Windows下控制台里执行执行会报文件编码错误？（java.nio.charset
             at org.apache.logging.log4j.core.config.plugins.util.PluginBuilder.findFactoryMethod(PluginBuilder.java:224)
             at org.apache.logging.log4j.core.config.plugins.util.PluginBuilder.build(PluginBuilder.java:130)
             at org.apache.logging.log4j.core.config.AbstractConfiguration.createPluginObject(AbstractConfiguration.java:952)
-            at org.apache.logging.log4j.core.config.AbstractConfiguration.createConfiguration(AbstractConfiguration.java:892)
-            at org.apache.logging.log4j.core.config.AbstractConfiguration.createConfiguration(AbstractConfiguration.java:884)
-            at org.apache.logging.log4j.core.config.AbstractConfiguration.doConfigure(AbstractConfiguration.java:508)
-            at org.apache.logging.log4j.core.config.AbstractConfiguration.initialize(AbstractConfiguration.java:232)
-            at org.apache.logging.log4j.core.config.AbstractConfiguration.start(AbstractConfiguration.java:244)
-            at org.apache.logging.log4j.core.LoggerContext.setConfiguration(LoggerContext.java:545)
-            at org.apache.logging.log4j.core.LoggerContext.reconfigure(LoggerContext.java:617)
-            at org.apache.logging.log4j.core.LoggerContext.reconfigure(LoggerContext.java:634)
-            at org.apache.logging.log4j.core.LoggerContext.start(LoggerContext.java:229)
+            ...
     ...
 
 这是因为在Windows控制台中，如果编码是UTF-8，java获取编码时会获取到cp65001，而这个编码java本身是不识别的。这种情况可以按下面的方法解决：
@@ -92,3 +80,24 @@ proto v2版本API解析repeated的整数或浮点数类型字段失败(Wire Type
 repeated的数值类型在proto v2里默认是 ``[ packed = false ]`` 而在proto v3里是 ``[ packed = true ]`` 。解决方法是显式指定打包方式。
 
 详见 :ref:`output-format-proto v2 and proto v3` 。
+
+为什么在proto里定义的是一个无符号(unsigned)类型(uint32、uint64等)，实际输出的UE代码是有符号(signed)的(int32/int64)？
+----------------------------------------------------------------------------------------------------------------
+
+因为有一些语言是没有无符号(unsigned)类型的，为了统一数据类型，我们统一转换为有符号类型，转换方式和protobuf的java版SDK保持一致。如果需要使用大于int32最大值的uint32类型，请用int64代替。
+
+为什么 ``UE-Csv`` 和 ``UE-Json`` 输出的代码会多一个 ``Name`` 字段?
+----------------------------------------------------------------------------------------------------------------
+
+因为对 ``UE-Json`` 输出中， ``Name`` 是一个特殊字段，也用于UE中内置的接口的查找索引。所以为了统一输出的数据结构（ 这样无论是 ``UE-Csv`` 还是 ``UE-Json`` 都可以用相同的代码结构来导入 ），我们对 ``UE-Csv`` 和 ``UE-Json`` 统一自动生成 ``Name`` 字段。但是如果用户自定义了 ``Name`` 字段， 我们会使用用户自定义的 ``Name`` 字段。
+
+要如何配置可以让Excel里的数据指向UE的类型或资源
+----------------------------------------------------------------------------------------------------------------
+
+可以使用 ``org.xresloader.ue.ue_type_name`` 插件和 ``org.xresloader.ue.ue_type_is_class`` 插件。详见： :ref:`output-format-export ue`
+
+为什么UE的代码输出里对 ``oneof`` 的case输出使用 ``FString`` 的字段名而不使用 ``UEnum()``
+----------------------------------------------------------------------------------------------------------------
+
+主要是因为（当前版本4.X）UE的 ``UEnum()`` 的支持仅支持基于 ``uint8`` 的，但是protobuf的field number是 ``int32`` 。为了兼容性所以没有使用 ``UEnum()`` 。 
+如果输出int32的话再UE里不太好操作，所以输出了字符串类型，方便蓝图里或UE代码里通过UE内置的反射机制访问。