From f9d28a08cf9a179e61f16246132b3f25a0ace907 Mon Sep 17 00:00:00 2001 From: Peefy Date: Wed, 6 Nov 2024 10:30:26 +0800 Subject: [PATCH] docs: add external dynamic config merge and json_merge_patch module faq documents Signed-off-by: Peefy --- docs/user_docs/support/faq-kcl.md | 17 ++++++++++++++++- .../current/user_docs/support/faq-kcl.md | 13 +++++++++++++ .../version-0.10/user_docs/support/faq-kcl.md | 13 +++++++++++++ .../version-0.10/user_docs/support/faq-kcl.md | 17 ++++++++++++++++- .../version-0.7/user_docs/support/faq-kcl.md | 2 +- .../version-0.8/user_docs/support/faq-kcl.md | 2 +- .../version-0.9/user_docs/support/faq-kcl.md | 2 +- 7 files changed, 61 insertions(+), 5 deletions(-) diff --git a/docs/user_docs/support/faq-kcl.md b/docs/user_docs/support/faq-kcl.md index 60aa3eed..eec6157c 100644 --- a/docs/user_docs/support/faq-kcl.md +++ b/docs/user_docs/support/faq-kcl.md @@ -1720,6 +1720,8 @@ configNew: key2: value2 ``` + + ### The solution to the conflicting values on the attribute 'attr' between {value1} and {value2} error in KCL When an error like conflicting values on the attribute 'attr' between {value1} and {value2} occurs in KCL, it is usually a problem with the use of the merge attribute operator `:`, indicating that when the `value1` and `value2` configurations are merged, the attribute A conflict error occurred at `attr`. In general, modify the attr attribute of value2 to other attribute operators, use `=` to indicate overwrite, and use `+=` to indicate addition @@ -1736,6 +1738,19 @@ We can use the `=` attribute operator to modify it to the following form data = {k: 1} | {k = 2} # Ok: the value 2 will override the value 1 through the `=` operator ``` +### Use the `json_merge_patch` module to merge configuration + +If we want to merge external configurations, as shown in the following code, we can use the `json_marge_patch` module, because the default attribute operator for external configurations is `: `, which may encounter merge conflict errors. + +```python +_vals1 = yaml.decode(file.read("...")) +_vals2 = option("...") + +_vals = _vals1 | _vals2 +``` + +Please refer to [here](https://github.com/kcl-lang/modules/tree/main/json_merge_patch) for more information on how to use the `json_merge_patch` module. + ## 38. How to traverse multiple elements at the same time in the for comprehension? In KCL, we can use for comprehension to traverse multiple elements @@ -2442,7 +2457,7 @@ data: dataIsUnique: true ``` -## 55. How do i omit attributes in the output for variables with "None" value? +## 55. How to omit attributes in the output for variables with "None" value? In KCL, there is a builtin disableNone feature `-n` that does not print variables with null value. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-kcl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-kcl.md index d02820d5..4f5ff078 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-kcl.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-kcl.md @@ -1748,6 +1748,19 @@ data = {k: 1} | {k: 2} # Error: conflicting values on the attribute 'k' between data = {k: 1} | {k = 2} # Ok: the value 2 will override the value 1 through the `=` operator ``` +### 使用 `json_merge_patch` 库合并配置 + +如果我们对外部读取的配置有合并诉求，比如下面的代码显示的那样，则可以使用 `json_merge_patch` 库来操作，因为外部配置默认的属性运算符为 `:`, 可能会遇到合并冲突错误 + +```python +_vals1 = yaml.decode(file.read("...")) +_vals2 = option("...") + +_vals = _vals1 | _vals2 +``` + +`json_merge_patch` 库使用的方式详见[这里](https://github.com/kcl-lang/modules/tree/main/json_merge_patch) + ## 38. KCL 中如何同时遍历多个元素 KCL 中可以使用 for 推导表达式遍历多个元素 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/user_docs/support/faq-kcl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/user_docs/support/faq-kcl.md index d02820d5..4f5ff078 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/user_docs/support/faq-kcl.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/user_docs/support/faq-kcl.md @@ -1748,6 +1748,19 @@ data = {k: 1} | {k: 2} # Error: conflicting values on the attribute 'k' between data = {k: 1} | {k = 2} # Ok: the value 2 will override the value 1 through the `=` operator ``` +### 使用 `json_merge_patch` 库合并配置 + +如果我们对外部读取的配置有合并诉求，比如下面的代码显示的那样，则可以使用 `json_merge_patch` 库来操作，因为外部配置默认的属性运算符为 `:`, 可能会遇到合并冲突错误 + +```python +_vals1 = yaml.decode(file.read("...")) +_vals2 = option("...") + +_vals = _vals1 | _vals2 +``` + +`json_merge_patch` 库使用的方式详见[这里](https://github.com/kcl-lang/modules/tree/main/json_merge_patch) + ## 38. KCL 中如何同时遍历多个元素 KCL 中可以使用 for 推导表达式遍历多个元素 diff --git a/versioned_docs/version-0.10/user_docs/support/faq-kcl.md b/versioned_docs/version-0.10/user_docs/support/faq-kcl.md index 60aa3eed..eec6157c 100644 --- a/versioned_docs/version-0.10/user_docs/support/faq-kcl.md +++ b/versioned_docs/version-0.10/user_docs/support/faq-kcl.md @@ -1720,6 +1720,8 @@ configNew: key2: value2 ``` + + ### The solution to the conflicting values on the attribute 'attr' between {value1} and {value2} error in KCL When an error like conflicting values on the attribute 'attr' between {value1} and {value2} occurs in KCL, it is usually a problem with the use of the merge attribute operator `:`, indicating that when the `value1` and `value2` configurations are merged, the attribute A conflict error occurred at `attr`. In general, modify the attr attribute of value2 to other attribute operators, use `=` to indicate overwrite, and use `+=` to indicate addition @@ -1736,6 +1738,19 @@ We can use the `=` attribute operator to modify it to the following form data = {k: 1} | {k = 2} # Ok: the value 2 will override the value 1 through the `=` operator ``` +### Use the `json_merge_patch` module to merge configuration + +If we want to merge external configurations, as shown in the following code, we can use the `json_marge_patch` module, because the default attribute operator for external configurations is `: `, which may encounter merge conflict errors. + +```python +_vals1 = yaml.decode(file.read("...")) +_vals2 = option("...") + +_vals = _vals1 | _vals2 +``` + +Please refer to [here](https://github.com/kcl-lang/modules/tree/main/json_merge_patch) for more information on how to use the `json_merge_patch` module. + ## 38. How to traverse multiple elements at the same time in the for comprehension? In KCL, we can use for comprehension to traverse multiple elements @@ -2442,7 +2457,7 @@ data: dataIsUnique: true ``` -## 55. How do i omit attributes in the output for variables with "None" value? +## 55. How to omit attributes in the output for variables with "None" value? In KCL, there is a builtin disableNone feature `-n` that does not print variables with null value. diff --git a/versioned_docs/version-0.7/user_docs/support/faq-kcl.md b/versioned_docs/version-0.7/user_docs/support/faq-kcl.md index 4c882144..48ee0bf3 100644 --- a/versioned_docs/version-0.7/user_docs/support/faq-kcl.md +++ b/versioned_docs/version-0.7/user_docs/support/faq-kcl.md @@ -2440,7 +2440,7 @@ data: dataIsUnique: true ``` -## 55. How do i omit attributes in the output for variables with "None" value? +## 55. How to omit attributes in the output for variables with "None" value? In KCL, there is a builtin disableNone feature `-n` that does not print variables with null value. diff --git a/versioned_docs/version-0.8/user_docs/support/faq-kcl.md b/versioned_docs/version-0.8/user_docs/support/faq-kcl.md index 710699d8..4113c864 100644 --- a/versioned_docs/version-0.8/user_docs/support/faq-kcl.md +++ b/versioned_docs/version-0.8/user_docs/support/faq-kcl.md @@ -2440,7 +2440,7 @@ data: dataIsUnique: true ``` -## 55. How do i omit attributes in the output for variables with "None" value? +## 55. How to omit attributes in the output for variables with "None" value? In KCL, there is a builtin disableNone feature `-n` that does not print variables with null value. diff --git a/versioned_docs/version-0.9/user_docs/support/faq-kcl.md b/versioned_docs/version-0.9/user_docs/support/faq-kcl.md index 56ad6af4..9c9e4e68 100644 --- a/versioned_docs/version-0.9/user_docs/support/faq-kcl.md +++ b/versioned_docs/version-0.9/user_docs/support/faq-kcl.md @@ -2442,7 +2442,7 @@ data: dataIsUnique: true ``` -## 55. How do i omit attributes in the output for variables with "None" value? +## 55. How to omit attributes in the output for variables with "None" value? In KCL, there is a builtin disableNone feature `-n` that does not print variables with null value.