Skip to content

Commit

Permalink
Merge pull request #486 from kcl-lang/update-faq-plugin-docs
Browse files Browse the repository at this point in the history 
docs: update plugin documents in FAQ
  • Loading branch information
@Peefy
Peefy authored Nov 13, 2024
2 parents c918483 + c1d4d8e commit f56555f
Show file tree
Hide file tree
Showing 4 changed files with 4 additions and 320 deletions.
81 changes: 1 addition & 80 deletions docs/user_docs/support/faq-kcl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2272,86 +2272,7 @@ data_type_list:

## 49. How to develop a KCL plugin?

KCL plugins are installed in the plugins subdirectory of KCL (usually installed in the `$HOME/.kcl/plugins` directory), or set through the `$KCL_PLUGINS_ROOT` environment variable. Besides, the `plugins` directory could also be placed at the `pwd` path. For plugin developers, plugins are managed in the [Git repository](https://github.com/kcl-lang/kcl-plugin), and the plugin repository can be cloned to this directory for development.

KCL has built-in kcl-plugin scaffolding command to assist users to write KCL plug-ins in Python language, so that the corresponding plug-ins can be called in the KCL file to enhance the KCL language itself, such as accessing the network, reading and writing IO, CMDB query and encryption and decryption functions.

```
usage: kcl-plugin [-h] {list,init,info,gendoc,test} ...

positional arguments:
{list,init,info,gendoc,test}
kcl plugin sub commands
list list all plugins
init init a new plugin
info show plugin document
gendoc gen all plugins document
test test plugin

optional arguments:
-h, --help show this help message and exit
```
For example, if you want to develop a plugin named io, you can use the following command to successfully create a new io plugin
```
kcl-plugin init io
```
Then you can use the following command to get the root path of the plugin and cd to the corresponding io plugin directory for development
```
kcl-plugin info
```
For example, if you want to develop a function read_file to read a file, you can write python code in `plugin.py` of `$plugin_root/io`:
```python
# Copyright 2020 The KCL Authors. All rights reserved.
import pathlib
INFO = {
'name': 'io',
'describe': 'my io plugin description test',
'long_describe': 'my io plugin long description test',
'version': '0.0.1',
}
def read_file(file: str) -> str:
"""Read string from file"""
return pathlib.Path(file).read_text()
```

In addition, you can write the corresponding test function in `plugin_test.py`, or you can directly write the following KCL file for testing:

```python
import kcl_plugin.io

text = io.read_file('test.txt')
```

You can also use the info command to view information about the io plugin

```
kcl-plugin info io
```

```
{
"name": "io",
"describe": "my io plugin description test",
"long_describe": "my io plugin long description test",
"version": "0.0.1",
"method": {
"read_file": "Read string from file"
}
}
```

Finally, the plugin that has written the test can be merged with MR in the `kcl_plugins` repository.
See [here](https://www.kcl-lang.io/docs/reference/plugin/overview) for more information.

## 50. How to do basic type conversion in KCL

Expand Down
81 changes: 1 addition & 80 deletions i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-kcl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2284,86 +2284,7 @@ data_type_list:

## 49. 如何通过编写 KCL 插件进行扩展?

KCL 插件在 KCL 的 plugins 子目录（通常安装在 `$HOME/.kcl/plugins` 目录），或者通过 `$KCL_PLUGINS_ROOT` 环境变量设置（环境变量优先级更高）。对于插件开发人员，插件都在 [Git 仓库](https://github.com/kcl-lang/kcl-plugin)管理，可以将插件仓库克隆到该目录进行开发。

KCL 内置了 kcl-plugin 脚手架命令用于辅助用户使用 Python 语言编写 KCL 插件，以便在 KCL 文件当中调用相应的插件对 KCL 语言本身进行增强，比如访问网络，读写 IO，CMDB 查询和加密解密等功能。

```
usage: kcl-plugin [-h] {list,init,info,gendoc,test} ...

positional arguments:
{list,init,info,gendoc,test}
kcl plugin sub commands
list list all plugins
init init a new plugin
info show plugin document
gendoc gen all plugins document
test test plugin

optional arguments:
-h, --help show this help message and exit
```
比如想要开发一个名为 io 插件，就可以使用如下命令成功新建一个 io 插件
```
kcl-plugin init io
```
然后可以使用如下命令获得 plugin 的根路径并 cd 到相应的 io 插件目录进行开发
```
kcl-plugin info
```
比如想要开发一个读文件的函数 read_file，就可以在 `$plugin_root/io` 的 `plugin.py` 中进行 python 代码编写：
```python
# Copyright 2020 The KCL Authors. All rights reserved.
import pathlib
INFO = {
'name': 'io',
'describe': 'my io plugin description test',
'long_describe': 'my io plugin long description test',
'version': '0.0.1',
}
def read_file(file: str) -> str:
"""Read string from file"""
return pathlib.Path(file).read_text()
```

另外可以在 `plugin_test.py` 中编写相应的测试函数，也可以直接编写如下所示 KCL 文件进行测试：

```python
import kcl_plugin.io

text = io.read_file('test.txt')
```

还可以使用 info 命令查看 io 插件的信息

```
kcl-plugin info io
```

```
{
"name": "io",
"describe": "my io plugin description test",
"long_describe": "my io plugin long description test",
"version": "0.0.1",
"method": {
"read_file": "Read string from file"
}
}
```

最后将编写测试完成的插件在 `kcl_plugins` 仓库提 MR 合并即可
查看[这里](https://www.kcl-lang.io/docs/reference/plugin/overview)获得更多信息。

## 50. 如何在 KCL 中进行基本类型转换

Expand Down
81 changes: 1 addition & 80 deletions .../zh-CN/docusaurus-plugin-content-docs/version-0.10/user_docs/support/faq-kcl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2284,86 +2284,7 @@ data_type_list:

## 49. 如何通过编写 KCL 插件进行扩展?

KCL 插件在 KCL 的 plugins 子目录（通常安装在 `$HOME/.kcl/plugins` 目录），或者通过 `$KCL_PLUGINS_ROOT` 环境变量设置（环境变量优先级更高）。对于插件开发人员，插件都在 [Git 仓库](https://github.com/kcl-lang/kcl-plugin)管理，可以将插件仓库克隆到该目录进行开发。

KCL 内置了 kcl-plugin 脚手架命令用于辅助用户使用 Python 语言编写 KCL 插件，以便在 KCL 文件当中调用相应的插件对 KCL 语言本身进行增强，比如访问网络，读写 IO，CMDB 查询和加密解密等功能。

```
usage: kcl-plugin [-h] {list,init,info,gendoc,test} ...

positional arguments:
{list,init,info,gendoc,test}
kcl plugin sub commands
list list all plugins
init init a new plugin
info show plugin document
gendoc gen all plugins document
test test plugin

optional arguments:
-h, --help show this help message and exit
```
比如想要开发一个名为 io 插件，就可以使用如下命令成功新建一个 io 插件
```
kcl-plugin init io
```
然后可以使用如下命令获得 plugin 的根路径并 cd 到相应的 io 插件目录进行开发
```
kcl-plugin info
```
比如想要开发一个读文件的函数 read_file，就可以在 `$plugin_root/io` 的 `plugin.py` 中进行 python 代码编写：
```python
# Copyright 2020 The KCL Authors. All rights reserved.
import pathlib
INFO = {
'name': 'io',
'describe': 'my io plugin description test',
'long_describe': 'my io plugin long description test',
'version': '0.0.1',
}
def read_file(file: str) -> str:
"""Read string from file"""
return pathlib.Path(file).read_text()
```

另外可以在 `plugin_test.py` 中编写相应的测试函数，也可以直接编写如下所示 KCL 文件进行测试：

```python
import kcl_plugin.io

text = io.read_file('test.txt')
```

还可以使用 info 命令查看 io 插件的信息

```
kcl-plugin info io
```

```
{
"name": "io",
"describe": "my io plugin description test",
"long_describe": "my io plugin long description test",
"version": "0.0.1",
"method": {
"read_file": "Read string from file"
}
}
```

最后将编写测试完成的插件在 `kcl_plugins` 仓库提 MR 合并即可
查看[这里](https://www.kcl-lang.io/docs/reference/plugin/overview)获得更多信息。

## 50. 如何在 KCL 中进行基本类型转换

Expand Down
81 changes: 1 addition & 80 deletions versioned_docs/version-0.10/user_docs/support/faq-kcl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2272,86 +2272,7 @@ data_type_list:

## 49. How to develop a KCL plugin?

KCL plugins are installed in the plugins subdirectory of KCL (usually installed in the `$HOME/.kcl/plugins` directory), or set through the `$KCL_PLUGINS_ROOT` environment variable. Besides, the `plugins` directory could also be placed at the `pwd` path. For plugin developers, plugins are managed in the [Git repository](https://github.com/kcl-lang/kcl-plugin), and the plugin repository can be cloned to this directory for development.

KCL has built-in kcl-plugin scaffolding command to assist users to write KCL plug-ins in Python language, so that the corresponding plug-ins can be called in the KCL file to enhance the KCL language itself, such as accessing the network, reading and writing IO, CMDB query and encryption and decryption functions.

```
usage: kcl-plugin [-h] {list,init,info,gendoc,test} ...

positional arguments:
{list,init,info,gendoc,test}
kcl plugin sub commands
list list all plugins
init init a new plugin
info show plugin document
gendoc gen all plugins document
test test plugin

optional arguments:
-h, --help show this help message and exit
```
For example, if you want to develop a plugin named io, you can use the following command to successfully create a new io plugin
```
kcl-plugin init io
```
Then you can use the following command to get the root path of the plugin and cd to the corresponding io plugin directory for development
```
kcl-plugin info
```
For example, if you want to develop a function read_file to read a file, you can write python code in `plugin.py` of `$plugin_root/io`:
```python
# Copyright 2020 The KCL Authors. All rights reserved.
import pathlib
INFO = {
'name': 'io',
'describe': 'my io plugin description test',
'long_describe': 'my io plugin long description test',
'version': '0.0.1',
}
def read_file(file: str) -> str:
"""Read string from file"""
return pathlib.Path(file).read_text()
```

In addition, you can write the corresponding test function in `plugin_test.py`, or you can directly write the following KCL file for testing:

```python
import kcl_plugin.io

text = io.read_file('test.txt')
```

You can also use the info command to view information about the io plugin

```
kcl-plugin info io
```

```
{
"name": "io",
"describe": "my io plugin description test",
"long_describe": "my io plugin long description test",
"version": "0.0.1",
"method": {
"read_file": "Read string from file"
}
}
```

Finally, the plugin that has written the test can be merged with MR in the `kcl_plugins` repository.
See [here](https://www.kcl-lang.io/docs/reference/plugin/overview) for more information.

## 50. How to do basic type conversion in KCL

Expand Down

0 comments on commit f56555f

Please sign in to comment.