From cb1420ba4f0e478e743f199ff10d4f46ed56afd2 Mon Sep 17 00:00:00 2001
From: peefy <xpf6677@163.com>
Date: Fri, 6 Sep 2024 11:15:33 +0800
Subject: [PATCH] docs: add mixin and protocol faq documents

Signed-off-by: peefy <xpf6677@163.com>
---
 docs/user_docs/support/faq-kcl.md             | 27 +++++++++++++++++++
 .../current/user_docs/support/faq-kcl.md      | 25 +++++++++++++++++
 .../version-0.10/user_docs/support/faq-kcl.md | 25 +++++++++++++++++
 .../reference/lang/codelab/collaborative.md   |  4 +--
 .../reference/lang/codelab/schema.md          | 12 ++++++---
 .../reference/lang/codelab/simple.md          |  2 +-
 .../version-0.10/user_docs/support/faq-kcl.md | 27 +++++++++++++++++++
 7 files changed, 116 insertions(+), 6 deletions(-)

diff --git a/docs/user_docs/support/faq-kcl.md b/docs/user_docs/support/faq-kcl.md
index 56ad6af4f..60aa3eed0 100644
--- a/docs/user_docs/support/faq-kcl.md
+++ b/docs/user_docs/support/faq-kcl.md
@@ -2731,3 +2731,30 @@ import another_module
 ```
 
 Both `another-module = "0.1.1"` and `another_module = "0.1.1"` are equivalent, and using both will result in an error.
+
+## 69. What features in general programming languages are equivalent to mixin and protocol in KCL?
+
+Mixins in KCL are similar to:
+
+- Multiple Inheritance: Allows a class to inherit properties and methods from multiple parent classes.
+- Interface Implementation: Provides additional methods and properties to a class.
+- Traits: In languages that support traits (like Rust), they are used to define behaviors that can be shared by multiple types.
+
+KCL's mixins allow you to define a set of reusable properties and methods, which can then be mixed into multiple schemas, enabling code reuse and behavior sharing.
+
+Protocols in KCL are analogous to:
+
+- Interfaces: Define a set of method signatures that types must implement.
+- Abstract Base Classes: Define a set of abstract methods that must be implemented by subclasses.
+- Protocols: In some languages (like Swift), protocols are used to define a blueprint of methods, properties, and other requirements.
+
+KCL's protocols are used to define a set of rules or contracts that schemas can choose to adhere to. They provide a way to ensure that certain schemas have specific structures or behaviors.
+
+Key Differences:
+
+- Flexibility: KCL's mixins and protocols are designed to be more flexible, suitable for configuration and policy definition scenarios.
+- Compile-time Checking: KCL enforces mixin and protocol rules at compile-time, ensuring type safety.
+- Configuration-oriented: These features in KCL are more geared towards building and validating complex configuration structures, rather than just traditional object-oriented programming.
+- Immutability: KCL emphasizes immutability, which influences how mixins and protocols are used, making them more suitable for declarative configurations.
+
+In summary, KCL's mixins and protocols combine concepts from various programming languages but are optimized for configuration management and policy definition, providing a powerful and flexible way to construct and validate complex data structures.
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 e22668eb2..d02820d5f 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
@@ -2710,3 +2710,28 @@ import another_module
 ```
 
 `another-module = "0.1.1"` 和 `another_module = "0.1.1"` 是等价的, 如果同时在 `kcl.mod` 中使用这两种写法会得到一个错误。
+
+## 69. KCL 语言中的 mixin 和 protocol 相当于一般编程语言中的什么特性?
+
+Mixin 在 KCL 中相当于其他语言中的：
+
+- 多重继承（Multiple Inheritance）：允许一个类从多个父类继承属性和方法。
+- 接口实现（Interface Implementation）：为类提供额外的方法和属性。
+- 特征（Traits）：在一些支持特征的语言中（如 Rust），traits 用于定义可以被多个类型共享的行为。
+
+KCL 的 mixin 允许你定义一组可重用的属性和方法，然后将它们混入到多个 schema 中，实现代码复用和行为共享。
+
+Protocol 在 KCL 中类似于其他语言中的：
+
+- 接口（Interface）：定义了一组方法签名，类型必须实现这些方法。
+- 抽象基类（Abstract Base Class）：定义了一组必须被子类实现的抽象方法。
+- 协议（Protocol）：在一些语言中（如 Swift），协议用于定义一组方法、属性和其他要求的蓝图。
+
+KCL 的 protocol 用于定义一组规则或契约，schema 可以选择遵守这些规则。它们提供了一种方式来确保某些 schema 具有特定的结构或行为。
+
+关键区别：
+
+- 灵活性：KCL 的 mixin 和 protocol 设计得更加灵活，适用于配置和策略定义场景。
+- 编译时检查：KCL 在编译时强制执行 mixin 和 protocol 的规则，确保类型安全。
+- 配置导向：这些特性在 KCL 中更多地用于构建和验证复杂的配置结构，而不仅仅是传统的面向对象编程。
+- 不可变性：KCL 强调不可变性，这影响了 mixin 和 protocol 的使用方式，使它们更适合于声明式配置。
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 e22668eb2..d02820d5f 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
@@ -2710,3 +2710,28 @@ import another_module
 ```
 
 `another-module = "0.1.1"` 和 `another_module = "0.1.1"` 是等价的, 如果同时在 `kcl.mod` 中使用这两种写法会得到一个错误。
+
+## 69. KCL 语言中的 mixin 和 protocol 相当于一般编程语言中的什么特性?
+
+Mixin 在 KCL 中相当于其他语言中的：
+
+- 多重继承（Multiple Inheritance）：允许一个类从多个父类继承属性和方法。
+- 接口实现（Interface Implementation）：为类提供额外的方法和属性。
+- 特征（Traits）：在一些支持特征的语言中（如 Rust），traits 用于定义可以被多个类型共享的行为。
+
+KCL 的 mixin 允许你定义一组可重用的属性和方法，然后将它们混入到多个 schema 中，实现代码复用和行为共享。
+
+Protocol 在 KCL 中类似于其他语言中的：
+
+- 接口（Interface）：定义了一组方法签名，类型必须实现这些方法。
+- 抽象基类（Abstract Base Class）：定义了一组必须被子类实现的抽象方法。
+- 协议（Protocol）：在一些语言中（如 Swift），协议用于定义一组方法、属性和其他要求的蓝图。
+
+KCL 的 protocol 用于定义一组规则或契约，schema 可以选择遵守这些规则。它们提供了一种方式来确保某些 schema 具有特定的结构或行为。
+
+关键区别：
+
+- 灵活性：KCL 的 mixin 和 protocol 设计得更加灵活，适用于配置和策略定义场景。
+- 编译时检查：KCL 在编译时强制执行 mixin 和 protocol 的规则，确保类型安全。
+- 配置导向：这些特性在 KCL 中更多地用于构建和验证复杂的配置结构，而不仅仅是传统的面向对象编程。
+- 不可变性：KCL 强调不可变性，这影响了 mixin 和 protocol 的使用方式，使它们更适合于声明式配置。
diff --git a/versioned_docs/version-0.10/reference/lang/codelab/collaborative.md b/versioned_docs/version-0.10/reference/lang/codelab/collaborative.md
index 84ee81605..7edbc2180 100644
--- a/versioned_docs/version-0.10/reference/lang/codelab/collaborative.md
+++ b/versioned_docs/version-0.10/reference/lang/codelab/collaborative.md
@@ -83,7 +83,7 @@ In order to complete the collaborative configuration development, we first need
 │           └── main.k
 ├── kcl.mod
 └── pkg
-    └── sever.k
+    └── server.k
 ```
 
 The directory of the project mainly contains three parts:
@@ -280,7 +280,7 @@ server:
     env: dev
 ```
 
-Using the same method, we can build the production configuration, write the code in the `dev/main.k` file, and add a label to it.
+Using the same method, we can build the production configuration, write the code in the `prod/main.k` file, and add a label to it.
 
 ```python
 import pkg
diff --git a/versioned_docs/version-0.10/reference/lang/codelab/schema.md b/versioned_docs/version-0.10/reference/lang/codelab/schema.md
index 3b2e086a5..55b3bd5e9 100644
--- a/versioned_docs/version-0.10/reference/lang/codelab/schema.md
+++ b/versioned_docs/version-0.10/reference/lang/codelab/schema.md
@@ -526,7 +526,7 @@ nginx = Nginx {
 ```python
 nginx = NginxProd {
     labels.run = "my-nginx"
-    labels.env = "pre-prod"
+    labels.env = "prod"
 }
 ```
 
@@ -575,10 +575,10 @@ Now, we can complete the declaration of the server configuration through the Dep
 
 However, usually, the actual situation is more complicated, and the deployment may have a variety of optional variable accessories.
 
-For example, we want to support a persistent volume claim based on an existing schema, as a reusable Kubernetes schema. In this case, we can just wrapper it with a `mixin` and a `protocol` as follows:
+For example, we want to support a persistent volume claim based on an existing schema, as a reusable Kubernetes schema. In this case, we can just wrap it with a `mixin` and a `protocol` as follows:
 
 ```python
-import k8spkg.api.core.v1
+import k8s.api.core.v1
 
 protocol PVCProtocol:
     pvc?: {str:}
@@ -604,6 +604,12 @@ mixin PersistentVolumeClaimMixin for PVCProtocol:
         }
 ```
 
+> Note: for the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency:
+> ```bash
+> kcl mod init
+> kcl mod add k8s
+> ```
+
 With this PersistentVolumeClaimMixin, we define a PVC schema with a clear `user interface`, and use Kubernetes PVC as an implementation. Then, we can define a server schema with Deployment schema, and PVC mixin schema.
 
 ```
diff --git a/versioned_docs/version-0.10/reference/lang/codelab/simple.md b/versioned_docs/version-0.10/reference/lang/codelab/simple.md
index 56be5805d..0a8e60d20 100644
--- a/versioned_docs/version-0.10/reference/lang/codelab/simple.md
+++ b/versioned_docs/version-0.10/reference/lang/codelab/simple.md
@@ -450,7 +450,7 @@ _priorityCpuMap = {
     "3" = 1024
 }
 # Using a dict to simplify logic and the default value is 2048
-_cpu = _priorityCpuMap[_priority] or 2048
+_cpu = _priorityCpuMap[str(_priority)] or 2048
 _name = "nginx"
 # exported variables
 cpu = _cpu
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 56ad6af4f..60aa3eed0 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
@@ -2731,3 +2731,30 @@ import another_module
 ```
 
 Both `another-module = "0.1.1"` and `another_module = "0.1.1"` are equivalent, and using both will result in an error.
+
+## 69. What features in general programming languages are equivalent to mixin and protocol in KCL?
+
+Mixins in KCL are similar to:
+
+- Multiple Inheritance: Allows a class to inherit properties and methods from multiple parent classes.
+- Interface Implementation: Provides additional methods and properties to a class.
+- Traits: In languages that support traits (like Rust), they are used to define behaviors that can be shared by multiple types.
+
+KCL's mixins allow you to define a set of reusable properties and methods, which can then be mixed into multiple schemas, enabling code reuse and behavior sharing.
+
+Protocols in KCL are analogous to:
+
+- Interfaces: Define a set of method signatures that types must implement.
+- Abstract Base Classes: Define a set of abstract methods that must be implemented by subclasses.
+- Protocols: In some languages (like Swift), protocols are used to define a blueprint of methods, properties, and other requirements.
+
+KCL's protocols are used to define a set of rules or contracts that schemas can choose to adhere to. They provide a way to ensure that certain schemas have specific structures or behaviors.
+
+Key Differences:
+
+- Flexibility: KCL's mixins and protocols are designed to be more flexible, suitable for configuration and policy definition scenarios.
+- Compile-time Checking: KCL enforces mixin and protocol rules at compile-time, ensuring type safety.
+- Configuration-oriented: These features in KCL are more geared towards building and validating complex configuration structures, rather than just traditional object-oriented programming.
+- Immutability: KCL emphasizes immutability, which influences how mixins and protocols are used, making them more suitable for declarative configurations.
+
+In summary, KCL's mixins and protocols combine concepts from various programming languages but are optimized for configuration management and policy definition, providing a powerful and flexible way to construct and validate complex data structures.