From 076aab725afe59269a131f9dff0dbe997199fb43 Mon Sep 17 00:00:00 2001 From: Peefy Date: Thu, 7 Nov 2024 14:32:47 +0800 Subject: [PATCH] docs: add more system package examples Signed-off-by: Peefy --- .../index.md | 2 +- docs/reference/model/base64.md | 12 ++ docs/reference/model/crypto.md | 54 +++++++++ docs/reference/model/datetime.md | 30 +++++ docs/reference/model/file.md | 96 +++++++++++++++ docs/reference/model/json.md | 61 ++++++++++ docs/reference/model/math.md | 113 ++++++++++++++++++ docs/reference/model/net.md | 98 +++++++++++++++ docs/reference/model/regex.md | 36 ++++++ docs/reference/model/runtime.md | 2 +- docs/reference/model/template.md | 4 +- docs/reference/model/units.md | 19 +++ docs/reference/model/yaml.md | 95 ++++++++++++++- docs/reference/xlang-api/lua-api.md | 2 +- docs/reference/xlang-api/wasm-api.md | 2 +- .../index.md | 2 +- .../current/reference/model/base64.md | 12 ++ .../current/reference/model/crypto.md | 54 +++++++++ .../current/reference/model/datetime.md | 30 +++++ .../current/reference/model/file.md | 84 +++++++++++++ .../current/reference/model/json.md | 61 ++++++++++ .../current/reference/model/math.md | 113 ++++++++++++++++++ .../current/reference/model/net.md | 98 +++++++++++++++ .../current/reference/model/regex.md | 35 ++++++ .../current/reference/model/runtime.md | 2 +- .../current/reference/model/template.md | 4 +- .../current/reference/model/units.md | 19 +++ .../current/reference/model/yaml.md | 95 ++++++++++++++- .../current/reference/xlang-api/lua-api.md | 2 +- .../current/reference/xlang-api/wasm-api.md | 2 +- .../version-0.10/reference/model/base64.md | 12 ++ .../version-0.10/reference/model/crypto.md | 54 +++++++++ .../version-0.10/reference/model/datetime.md | 30 +++++ .../version-0.10/reference/model/file.md | 84 +++++++++++++ .../version-0.10/reference/model/json.md | 61 ++++++++++ .../version-0.10/reference/model/math.md | 113 ++++++++++++++++++ .../version-0.10/reference/model/net.md | 98 +++++++++++++++ .../version-0.10/reference/model/regex.md | 35 ++++++ .../version-0.10/reference/model/runtime.md | 2 +- .../version-0.10/reference/model/template.md | 4 +- .../version-0.10/reference/model/units.md | 19 +++ .../version-0.10/reference/model/yaml.md | 95 ++++++++++++++- .../reference/xlang-api/lua-api.md | 2 +- .../reference/xlang-api/wasm-api.md | 2 +- .../version-0.8/reference/model/template.md | 4 +- .../version-0.9/reference/model/runtime.md | 2 +- .../version-0.9/reference/model/template.md | 4 +- .../version-0.10/reference/model/base64.md | 12 ++ .../version-0.10/reference/model/crypto.md | 54 +++++++++ .../version-0.10/reference/model/datetime.md | 30 +++++ .../version-0.10/reference/model/file.md | 96 +++++++++++++++ .../version-0.10/reference/model/json.md | 61 ++++++++++ .../version-0.10/reference/model/math.md | 113 ++++++++++++++++++ .../version-0.10/reference/model/net.md | 98 +++++++++++++++ .../version-0.10/reference/model/regex.md | 36 ++++++ .../version-0.10/reference/model/runtime.md | 2 +- .../version-0.10/reference/model/template.md | 4 +- .../version-0.10/reference/model/units.md | 19 +++ .../version-0.10/reference/model/yaml.md | 95 ++++++++++++++- .../reference/xlang-api/lua-api.md | 2 +- .../reference/xlang-api/wasm-api.md | 2 +- .../version-0.8/reference/model/template.md | 4 +- .../version-0.9/reference/model/runtime.md | 2 +- .../version-0.9/reference/model/template.md | 4 +- 64 files changed, 2458 insertions(+), 36 deletions(-) diff --git a/blog/2023-02-27-kcl-0.4.5-release-blog/index.md b/blog/2023-02-27-kcl-0.4.5-release-blog/index.md index 9244a9dd..ff1b31f5 100644 --- a/blog/2023-02-27-kcl-0.4.5-release-blog/index.md +++ b/blog/2023-02-27-kcl-0.4.5-release-blog/index.md @@ -222,7 +222,7 @@ config: Config { Before KCL v0.4.5, executing the above code (main.k) will get unexpected configuration values because the KCL compiler incorrectly optimized the following form of equivalent merge configuration blocks: -```python3 +```python config: Config { resource: r resource: Resource { diff --git a/docs/reference/model/base64.md b/docs/reference/model/base64.md index 615b7f48..7fa35732 100644 --- a/docs/reference/model/base64.md +++ b/docs/reference/model/base64.md @@ -12,8 +12,20 @@ weight: 100 Encode the string `value` using the codec registered for encoding. +```python +import base64 + +abcd_base64 = base64.encode("abcd") +``` + ## decode `decode(value: str) -> str` Decode the string `value` using the codec registered to the utf8 string for encoding. + +```python +import base64 + +decode = base64.decode("MC4zLjA=") +``` diff --git a/docs/reference/model/crypto.md b/docs/reference/model/crypto.md index 34d8629a..c826aafc 100644 --- a/docs/reference/model/crypto.md +++ b/docs/reference/model/crypto.md @@ -12,50 +12,104 @@ weight: 100 Encrypt the string `value` using `MD5` and the codec registered for encoding. +```python +import crypto + +md5 = crypto.md5("ABCDEF") +``` + ## sha1 `sha1(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA1` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha1("ABCDEF") +``` + ## sha224 `sha224(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA224` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha224("ABCDEF") +``` + ## sha256 `sha256(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA256` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha256("ABCDEF") +``` + ## sha384 `sha384(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA384` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha384("ABCDEF") +``` + ## sha512 `sha512(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA512` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha512("ABCDEF") +``` + ## blake3 `blake3(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `BLAKE3` and the codec registered for encoding. +```python +import crypto + +blake3 = crypto.blake3("ABCDEF") +``` + ## uuid `uuid() -> str` Generate a random UUID string. +```python +import crypto + +a = crypto.uuid() +``` + ## filesha256 `filesha256(filepath: str) -> str` Calculate the SHA256 hash of the file `filepath`. + +```python +import crypto + +sha = crypto.filesha256("test.txt") +``` diff --git a/docs/reference/model/datetime.md b/docs/reference/model/datetime.md index 2448be45..f65edbcd 100644 --- a/docs/reference/model/datetime.md +++ b/docs/reference/model/datetime.md @@ -12,26 +12,56 @@ weight: 100 Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them. +```python +import datetime + +ticks = datetime.ticks() +``` + ## date `date() -> str` Return the `%Y-%m-%d %H:%M:%S` format date. +```python +import datetime + +date = datetime.date() +``` + ## now `now(format: str = "%a %b %d %H:%M:%S %Y") -> str` Return the local time format. e.g. 'Sat Jun 06 16:26:11 1998' or format the combined date and time per the specified format string, and the default date format is `%a %b %d %H:%M:%S %Y`. +```python +import datetime + +date = datetime.now() +``` + ## today `today() -> str` Return the `%Y-%m-%d %H:%M:%S.%{ticks}` format date. +```python +import datetime + +date = datetime.today() +``` + ## validate `validate(date: str, format: str) -> bool` Validate whether the provided date string matches the specified format. + +```python +import datetime + +result = datetime.validate("2024-08-26", "%Y-%m-%d") # Valid date +``` diff --git a/docs/reference/model/file.md b/docs/reference/model/file.md index c2b02308..60ff91b9 100644 --- a/docs/reference/model/file.md +++ b/docs/reference/model/file.md @@ -12,68 +12,164 @@ weight: 100 Read the contents of the file `filepath` and return a string instance. +```python +import file + +a = file.read("test.txt") +``` + ## glob `glob(pattern: str) -> str` Return a list containing all file names that match `pattern`. +```python +import file + +json_files = file.glob("./*.json") +``` + ## modpath `modpath() -> str` Return the root path of the current KCL module (kcl.mod file path or single \*.k file path). +```python +import file + +modpath = file.modpath() +``` + ## workdir `workdir() -> str` Return the path of the current working directory. +```python +import file + +workdir = file.workdir() +``` + ## exists `exists(filepath: str) -> bool` Whether this file path exists. Returns true if the path points at an existing entity. This function will traverse symbolic links to query information about the destination file. +```python +import file + +file_exists = file.exists("test.txt") +``` + ## abs `abs(filepath: str) -> str` Returns the canonical, absolute form of the path with all intermediate components normalized and symbolic links resolved. +```python +import file + +abs_file_path = file.abs("test.txt") +``` + ## mkdir `mkdir(directory: str, exists: bool=False)` Create a new directory at the specified path if it doesn't already exist. +```python +import file + +file.mkdir("path") +``` + ## delete `delete(directory: str)` Delete a file or an empty directory at the specified path. +```python +import file + +file.delete("test.txt") +``` + ## cp `cp(src: str, dest: str)` Copy a file or directory from the source path to the destination path. +```python +import file + +file.cp("src", "dest") +``` + ## mv `mv(src: str, dest: str)` Move a file or directory from the source path to the destination path. +```python +import file + +file.mv("src", "dest") +``` + +## size + +`size(filepath: str)` + +Get the size of a file at the specified path. + +```python +import file + +size = file.size("test.txt") +``` + +## write + +`write(filepath: str, content: str)` + +Write content to a file at the specified path. If the file doesn't exist, it will be created. If it does exist, its content will be replaced. + +```python +import file + +file.size("test.txt", "content") +``` + ## read_env `read_env(key: str) -> str` Read the environment variable `key` from the current process. +```python +import file + +value = file.read_env("ENV_VAR") +``` + ## current `current() -> str` Read the path of the current script or module that is being executed. + +```python +import file + +value = file.current() +``` diff --git a/docs/reference/model/json.md b/docs/reference/model/json.md index cd844903..10af823b 100644 --- a/docs/reference/model/json.md +++ b/docs/reference/model/json.md @@ -20,12 +20,34 @@ encode( Serialize a KCL object `data` to a JSON formatted str. +```python +import json + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = json.encode(data) +``` + ## decode `decode(value: str) -> any` Deserialize `value` (a string instance containing a JSON document) to a KCL object. +```python +import file +import json + +data_string = json.decode(file.read(file.modpath()+"/test.json")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## dump_to_file ```python @@ -41,6 +63,23 @@ dump_to_file( Serialize a KCL object `data` to a JSON formatted str and write it into the file `filename`. +```python +import json + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.json" +json.dump_to_file(person, filename, indent=4, ignore_private=True, ignore_none=True) +``` + ## validate ```python @@ -48,3 +87,25 @@ validate(value: str) -> bool ``` Validate whether the given string is a valid JSON. + +```python +import json + +# Right cases + +resultRight1: bool = json.validate("1") +resultRight2: bool = json.validate("true") +resultRight3: bool = json.validate("1.20") +resultRight4: bool = json.validate("null") +resultRight5: bool = json.validate("[0, 1, 2]") +resultRight6: bool = json.validate('{"key": "value"}') + +# Wrong cases + +resultWrong1: bool = json.validate("1@") +resultWrong2: bool = json.validate("True") +resultWrong3: bool = json.validate("1.20.23+1") +resultWrong4: bool = json.validate("None") +resultWrong5: bool = json.validate("[0, 1, 2,]") +resultWrong6: bool = json.validate(r'''{"key": 'value'}''') +``` diff --git a/docs/reference/model/math.md b/docs/reference/model/math.md index e48b0ad1..656ea119 100644 --- a/docs/reference/model/math.md +++ b/docs/reference/model/math.md @@ -12,92 +12,205 @@ weight: 100 Return the ceiling of `x` as an Integral. This is the smallest integer >= x. +```python +import math + +a = math.ceil(-45.17) +b = math.ceil(100.12) +``` + ## factorial `factorial(x) -> int` Return `x!`. Raise a error if `x` is negative or non-integral. +```python +import math + +a = math.factorial(5) +``` + ## floor `floor(x) -> int` Return the floor of `x` as an Integral. This is the largest integer <= x. +```python +import math + +a = math.floor(-45.17) +b = math.floor(100.12) +``` + ## gcd `gcd(a: int, b: int) -> int` Return the greatest common divisor of `x` and `y` +```python +import math + +a = math.gcd(60, 48) +``` + ## isfinite `isfinite(x) -> bool` Return `True` if `x` is neither an infinity nor a `NaN`, and `False` otherwise. +```python +import math + +a = math.isfinite(1) +b = math.isfinite(0) +c = math.isfinite(float("nan")) +``` + ## isinf `isinf(x) -> bool` Return `True` if `x` is a positive or negative infinity, and `False` otherwise. +```python +import math + +a = math.isinf(1) +b = math.isinf(0) +c = math.isinf(float("nan")) +``` + ## isnan `isnan(x) -> bool` Return `True` if `x` is a `NaN` (not a number), and `False` otherwise. +```python +import math + +a = math.isnan(1) +b = math.isnan(0) +c = math.isnan(float("nan")) +``` + ## modf `modf(x) -> List[float, float]` Return the fractional and integer parts of `x`. Both results carry the sign of `x` and are floats. +```python +import math + +a = math.modf(100.12) +b = math.modf(100.72) +``` + ## exp `exp(x) -> float` Return `e` raised to the power of `x`. +```python +import math + +a = math.exp(2) +b = math.exp(-6.89) +``` + ## expm1 `expm1(x) -> float` Return `exp(x) - 1`. This function avoids the loss of precision involved in the direct evaluation of `exp(x) - 1` for small `x`. +```python +import math + +a = math.expm1(32) +b = math.expm1(-10.89) +``` + ## log `log(x, base=2.71828182845904523536028747135266250) -> float` Return the logarithm of `x` to the base `e`. +```python +import math + +a = math.log10(100) # 2 +``` + ## log1p `log1p(x) -> float` Return the natural logarithm of `1+x` (base `e`). The result is computed in a way which is accurate for `x` near zero. +```python +import math + +a = math.log1p(2.7183) +b = math.log1p(2) +c = math.log1p(1) +``` + ## log2 `log2(x) -> float` Return the base 2 logarithm of `x`. +```python +import math + +a = math.log2(2.7183) +b = math.log2(2) +c = math.log2(1) +``` + ## log10 `log10(x) -> float` Return the base 10 logarithm of `x`. +```python +import math + +a = math.log10(2.7183) +b = math.log10(2) +c = math.log10(1) +``` + ## pow `pow(x, y) -> float` Return `x**y` (`x` to the power of `y`). +```python +import math + +a = math.pow(1, 1) +``` + ## sqrt `sqrt(x) -> float` Return the square root of `x`. + +```python +import math + +a = math.sqrt(9) +``` diff --git a/docs/reference/model/net.md b/docs/reference/model/net.md index a4e83659..9ec0194e 100644 --- a/docs/reference/model/net.md +++ b/docs/reference/model/net.md @@ -12,92 +12,190 @@ weight: 100 Split the `host` and `port` from the `ip_end_point`. +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## join_host_port `join_host_port(host, port) -> str` Merge the `host` and `port`. +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## fqdn `fqdn(name: str = '') -> str` Return Fully Qualified Domain Name (FQDN). +```python +import net + +fqdn = net.fqdn() +``` + ## parse_IP `parse_IP(ip) -> str` Parse `ip` to a real IP address +```python +import net + +ip = net.parse_IP("192.168.0.1") +``` + ## to_IP4 `to_IP4(ip) -> str` Get the IP4 form of `ip`. +```python +import net + +ip = net.to_IP4("192.168.0.1") +``` + ## to_IP16 `to_IP16(ip) -> int` Get the IP16 form of `ip`. +```python +import net + +ip = net.to_IP16("192.168.0.1") +``` + ## IP_string `IP_string(ip: str | int) -> str` Get the IP string. +```python +import net + +ip = net.IP_string("192.168.0.1") +``` + ## is_IPv4 `is_IPv4(ip: str) -> bool` Whether `ip` is a IPv4 one. +```python +import net + +ip = net.is_IPv4("192.168.0.1") +``` + ## is_IP `is_IP(ip: str) -> bool` Whether `ip` is a valid ip address. +```python +import net + +ip = net.is_IP("192.168.0.1") +``` + ## is_loopback_IP `is_loopback_IP(ip: str) -> bool` Whether `ip` is a loopback one. +```python +import net + +isip = net.is_loopback_IP("127.0.0.1") +``` + ## is_multicast_IP `is_multicast_IP(ip: str) -> bool` Whether `ip` is a multicast one. +```python +import net + +isip = net.is_multicast_IP("239.255.255.255") +``` + ## is_interface_local_multicast_IP `is_interface_local_multicast_IP(ip: str) -> bool` Whether `ip` is a interface, local and multicast one. +```python +import net + +isip = net.is_interface_local_multicast_IP("239.255.255.255") +``` + ## is_link_local_multicast_IP `is_link_local_multicast_IP(ip: str) -> bool` Whether `ip` is a link local and multicast one. +```python +import net + +isip = net.is_link_local_multicast_IP("224.0.0.0") +``` + ## is_link_local_unicast_IP `is_link_local_unicast_IP(ip: str) -> bool` Whether `ip` is a link local and unicast one. +```python +import net + +isip = net.is_link_local_unicast_IP("fe80::2012:1") +``` + ## is_global_unicast_IP `is_global_unicast_IP(ip: str) -> bool` Whether `ip` is a global and unicast one. +```python +import net + +isip = net.is_global_unicast_IP("220.181.108.89") +``` + ## is_unspecified_IP `is_unspecified_IP(ip: str) -> bool` Whether `ip` is a unspecified one. + +```python +import net + +isip = net.is_unspecified_IP("0.0.0.0") +``` diff --git a/docs/reference/model/regex.md b/docs/reference/model/regex.md index adde0630..599ab1cf 100644 --- a/docs/reference/model/regex.md +++ b/docs/reference/model/regex.md @@ -12,32 +12,68 @@ weight: 100 Return the string obtained by replacing the leftmost non-overlapping occurrences of the pattern in string by the replacement. +```python +import regex + +regex_replace = regex.replace(regex_source, ",", "|") +``` + ## match `match(string: str, pattern: str) -> bool` Try to apply the pattern at the start of the string, returning a bool value `True` if any match was found, or `False` if no match was found. +```python +import regex + +regex_result = regex.match("192.168.0.1", "^(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|[1-9])\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)$") +``` + ## compile `compile(pattern: str) -> bool` Compile a regular expression pattern, returning a bool value denoting whether the pattern is valid. +```python +import regex + +regex_compile = regex.compile("$^") +``` + ## findall `findall(string: str, pattern: str) -> List[str]` Return a list of all non-overlapping matches in the string. +```python +import regex + +regex_find_all = regex.findall("aaaa", "a") +``` + ## search `search(string: str, pattern: str) -> bool` Scan through string looking for a match to the pattern, returning a bool value `True` if any match was found, or `False` if no match was found. +```python +import regex + +regex_search = regex.search("aaaa", "a") +``` + ## split `split(string: str, pattern: str, maxsplit=0) -> List[str]` Return a list composed of words from the string, splitting up to a maximum of `maxsplit` times using `pattern` as the separator. + +```python +import regex + +regex_split = regex.split(regex_source, ",") +``` diff --git a/docs/reference/model/runtime.md b/docs/reference/model/runtime.md index b65ed4b6..9eab8115 100644 --- a/docs/reference/model/runtime.md +++ b/docs/reference/model/runtime.md @@ -12,7 +12,7 @@ weight: 100 Executes the provided function and catches any potential runtime errors. Returns undefined if execution is successful, otherwise returns an error message in case of a runtime panic. -```python3 +```python import runtime schema Person: diff --git a/docs/reference/model/template.md b/docs/reference/model/template.md index 0c2115fb..5a04bb6a 100644 --- a/docs/reference/model/template.md +++ b/docs/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 Applies a parsed template to the specified data object and returns the string output. See https://handlebarsjs.com/ for more documents and examples. -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ Replaces the characters `&"<>` with the equivalent html / xml entities. -```python3 +```python import template diff --git a/docs/reference/model/units.md b/docs/reference/model/units.md index 34465a53..d58168d0 100644 --- a/docs/reference/model/units.md +++ b/docs/reference/model/units.md @@ -39,3 +39,22 @@ weight: 100 Int literal to string with `Ti` suffix - `to_Pi(num: int) -> str` Int literal to string with `Pi` suffix + +```python +import units +# SI +n = units.to_n(1e-9) +u = units.to_u(1e-6) +m = units.to_m(1e-1) +K = units.to_K(1000) +M = units.to_M(1000000) +G = units.to_G(1000000000) +T = units.to_T(1000000000000) +P = units.to_P(1000000000000000) +# IEC +Ki = units.to_Ki(1024) +Mi = units.to_Mi(1024 ** 2) +Gi = units.to_Gi(1024 ** 3) +Ti = units.to_Ti(1024 ** 4) +Pi = units.to_Pi(1024 ** 5) +``` diff --git a/docs/reference/model/yaml.md b/docs/reference/model/yaml.md index e2615f58..0807a2a2 100644 --- a/docs/reference/model/yaml.md +++ b/docs/reference/model/yaml.md @@ -19,6 +19,17 @@ encode( Serialize a KCL object `data` to a YAML formatted str. +```python +import yaml + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = yaml.encode(data) +``` + ## encode_all ```python @@ -32,18 +43,45 @@ encode( Serialize a sequence of KCL objects into a YAML stream str. +```python +import yaml + +yamlStr = yaml.encode_all([1, 2, 3]) +``` + ## decode `decode(value: str) -> any` Deserialize `value` (a string instance containing a YAML document) to a KCL object. +```python +import yaml +import file + +data_string = yaml.decode(file.read("test.yaml")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## decode_all `decode_all(value: str) -> [any]` Parse all YAML documents in a stream and produce corresponding KCL objects. +```python +import yaml + +yamlStr = """\ +key: value +""" +data = yaml.decode(yamlStr) +dataList = yaml.decode_all(yamlStr) +``` + ## dump_to_file ```python @@ -57,7 +95,24 @@ dump_to_file( Serialize a KCL object `data` to a YAML formatted str and write it into the file `filename`. -## dump_to_file +```python +import yaml + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.yaml" +yaml.dump_to_file(person, filename, ignore_private=True, ignore_none=True) +``` + +## dump_all_to_file ```python dump_all_to_file( @@ -70,6 +125,20 @@ dump_all_to_file( Serialize a sequence of KCL objects into a YAML stream str and write it into the file `filename`. +```python +import yaml + +yamlStrList = [ + 'key: value', + '- 1\n- 2\n- 3', + '1', + '1.1', + 'null', + 'true', +] +yaml.dump_all_to_file(yamlStrList, "0.yaml") +``` + ## validate ```python @@ -77,3 +146,27 @@ validate(value: str) -> bool ``` Validate whether the given string is a valid YAML or YAML stream document. + +```python +import yaml + +# Right cases + +resultRight1: bool = yaml.validate("1") +resultRight2: bool = yaml.validate("true") +resultRight3: bool = yaml.validate("1.20") +resultRight4: bool = yaml.validate("null") +resultRight5: bool = yaml.validate("[0, 1, 2]") +resultRight6: bool = yaml.validate('{"key": "value"}') +resultRight7: bool = yaml.validate('a:1\n---\nb:2') + +# Wrong cases + +resultWrong1: bool = yaml.validate("a:\n1") +resultWrong2: bool = yaml.validate("a:\n1\n - 2") +resultWrong3: bool = yaml.validate("a:\n-1") +resultWrong4: bool = yaml.validate("1a : \n1") +resultWrong5: bool = yaml.validate("a:\n- 1\n-----\na:\n- 1") +resultWrong6: bool = yaml.validate(r'''{"key" + 'value'}''') +resultWrong7: bool = yaml.validate("a:1\n-----\nb:\n-2") +``` diff --git a/docs/reference/xlang-api/lua-api.md b/docs/reference/xlang-api/lua-api.md index 08d6dda2..cb73e392 100644 --- a/docs/reference/xlang-api/lua-api.md +++ b/docs/reference/xlang-api/lua-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 12 --- # Lua API diff --git a/docs/reference/xlang-api/wasm-api.md b/docs/reference/xlang-api/wasm-api.md index 0424ad91..f07ec78c 100644 --- a/docs/reference/xlang-api/wasm-api.md +++ b/docs/reference/xlang-api/wasm-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 --- # WASM API diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-02-27-kcl-0.4.5-release-blog/index.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-02-27-kcl-0.4.5-release-blog/index.md index 4de050a3..e67f00fa 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-02-27-kcl-0.4.5-release-blog/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-02-27-kcl-0.4.5-release-blog/index.md @@ -222,7 +222,7 @@ config: Config { 在 KCL v0.4.5 版本之前，执行上述代码 (main.k) 会得到非预期的配置值，是因为 KCL 编译器错误地优化了如下形式等效合并配置块 -```python3 +```python config: Config { resource: r resource: Resource { diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/base64.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/base64.md index 37092e7c..71d70481 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/base64.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/base64.md @@ -12,8 +12,20 @@ weight: 100 使用注册的编码器对字符串 `value` 进行编码。 +```python +import base64 + +abcd_base64 = base64.encode("abcd") +``` + ## decode `decode(value: str) -> str` 使用注册的编码器对字符串 `value` 进行解码，解码的结果是一个 utf8 字符串 + +```python +import base64 + +decode = base64.decode("MC4zLjA=") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/crypto.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/crypto.md index 243c150e..e6d7b482 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/crypto.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/crypto.md @@ -12,50 +12,104 @@ weight: 100 使用注册编码器和 `MD5` 算法对字符串 `value` 进行加密。 +```python +import crypto + +md5 = crypto.md5("ABCDEF") +``` + ## sha1 `sha1(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA1` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha1("ABCDEF") +``` + ## sha224 `sha224(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA224` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha224("ABCDEF") +``` + ## sha256 `sha256(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA256` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha256("ABCDEF") +``` + ## sha384 `sha384(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA384` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha384("ABCDEF") +``` + ## sha512 `sha512(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA512` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha512("ABCDEF") +``` + ## blake3 `sha512(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `BLAKE3` 算法对字符串 `value` 进行加密。 +```python +import crypto + +blake3 = crypto.blake3("ABCDEF") +``` + ## uuid `uuid() -> str` 生成一个随机 UUID 字符串。 +```python +import crypto + +a = crypto.uuid() +``` + ## filesha256 `filesha256(filepath: str) -> str` 计算文件 `filepath` 的 SHA256 哈希。 + +```python +import crypto + +sha = crypto.filesha256("test.txt") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/datetime.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/datetime.md index 67a5b48f..fae58f41 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/datetime.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/datetime.md @@ -12,26 +12,56 @@ weight: 100 返回从 1970 年 1 月 1 日 0 时 0 分 0 秒（Epoch）开始到当前时间经过的秒数。如果系统时钟能提供更精确的时间，则秒数后可能会有小数部分。 +```python +import datetime + +ticks = datetime.ticks() +``` + ## date `date() -> str` 返回以 `%Y-%m-%d %H:%M:%S` 格式表示的时间。 +```python +import datetime + +date = datetime.date() +``` + ## now `now(format: str = "%a %b %d %H:%M:%S %Y") -> str` 返回本地时间格式。例如：`Sat Jun 06 16:26:11 1998`，或者根据指定的格式字符串格式化组合的日期和时间，默认日期格式为 `%a %b %d %H:%M:%S %Y`。 +```python +import datetime + +date = datetime.now() +``` + ## today `today() -> str` 返回以 `%Y-%m-%d %H:%M:%S.%{ticks}` 格式表示的时间。 +```python +import datetime + +date = datetime.today() +``` + ## validate `validate(date: str, format: str) -> bool` 验证提供的日期字符串是否与指定格式匹配。 + +```python +import datetime + +result = datetime.validate("2024-08-26", "%Y-%m-%d") # Valid date +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/file.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/file.md index 90e3d518..c194becf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/file.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/file.md @@ -12,80 +12,164 @@ weight: 100 读取文件 `filepath` 中的内容，并返回一个字符串实例。 +```python +import file + +a = file.read("test.txt") +``` + ## glob `glob(pattern: str) -> str` 返回一个包含所有匹配 `pattern` 的文件名的列表。 +```python +import file + +json_files = file.glob("./*.json") +``` + ## modpath `modpath() -> str` 返回当前模块的根路径（kcl.mod 文件路径或单个 \*.k 文件路径）。 +```python +import file + +modpath = file.modpath() +``` + ## workdir `workdir() -> str` 返回当前工作目录的路径。 +```python +import file + +workdir = file.workdir() +``` + ## exists `exists(filepath: str) -> bool` 判断文件路径是否存在。如果路径指向一个存在的实体，则返回 True。此函数会遍历符号链接以查询目标文件的信息。 +```python +import file + +file_exists = file.exists("test.txt") +``` + ## abs `abs(filepath: str) -> str` 返回路径的规范化绝对形式，其中所有中间路径均已规范化并解析为符号链接。 +```python +import file + +abs_file_path = file.abs("test.txt") +``` + ## mkdir `mkdir(directory: str, exists: bool=False)` 如果指定路径上不存在目录，则创建一个新目录。 +```python +import file + +file.mkdir("path") +``` + ## delete `delete(directory: str)` 在指定路径上删除一个文件或空目录。 +```python +import file + +file.delete("test.txt") +``` + ## cp `cp(src: str, dest: str)` 将文件或目录从源路径复制到目标路径。 +```python +import file + +file.cp("src", "dest") +``` + ## mv `mv(src: str, dest: str)` 将文件或目录从源路径移动到目标路径。 +```python +import file + +file.mv("src", "dest") +``` + ## size `size(filepath: str) -> int` 获取指定路径上文件的大小。 +```python +import file + +size = file.size("test.txt") +``` + ## write `write(filepath: str, content: str)` 将内容写入指定路径的文件。如果文件不存在，将会被创建。如果文件存在，其内容将被替换。 +```python +import file + +file.size("test.txt", "content") +``` + ## read_env `read_env(key: str) -> str` 从当前进程中读取环境变量 `key` 的值。 +```python +import file + +value = file.read_env("ENV_VAR") +``` + ## current `current() -> str` 读取正在执行的当前 KCL 代码文件或模块的路径。 + +```python +import file + +value = file.current() +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/json.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/json.md index 633692f6..da7a338e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/json.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/json.md @@ -20,12 +20,34 @@ encode( 将 KCL 对象 `data` 序列化为 JSON 格式的字符串。 +```python +import json + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = json.encode(data) +``` + ## decode `decode(value: str) -> any` 反序列化 `value`（一个包含 JSON 格式文档的字符串实例）为一个 KCL 对象。 +```python +import file +import json + +data_string = json.decode(file.read(file.modpath()+"/test.json")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## dump_to_file ```python @@ -41,6 +63,23 @@ dump_to_file( 将 KCL 对象 `data` 序列化为 JSON 格式的字符串，并将其写入文件 `filename` 中。 +```python +import json + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.json" +json.dump_to_file(person, filename, indent=4, ignore_private=True, ignore_none=True) +``` + ## validate ```python @@ -48,3 +87,25 @@ validate(value: str) -> bool ``` 验证给定的字符串是否是一个合法的 JSON 字符串。 + +```python +import json + +# Right cases + +resultRight1: bool = json.validate("1") +resultRight2: bool = json.validate("true") +resultRight3: bool = json.validate("1.20") +resultRight4: bool = json.validate("null") +resultRight5: bool = json.validate("[0, 1, 2]") +resultRight6: bool = json.validate('{"key": "value"}') + +# Wrong cases + +resultWrong1: bool = json.validate("1@") +resultWrong2: bool = json.validate("True") +resultWrong3: bool = json.validate("1.20.23+1") +resultWrong4: bool = json.validate("None") +resultWrong5: bool = json.validate("[0, 1, 2,]") +resultWrong6: bool = json.validate(r'''{"key": 'value'}''') +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/math.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/math.md index 3b2ff0cc..e16558b2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/math.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/math.md @@ -12,92 +12,205 @@ weight: 100 返回 `x` 向上取整得到的整数，这是大于等于 `x` 的最小整数。 +```python +import math + +a = math.ceil(-45.17) +b = math.ceil(100.12) +``` + ## factorial `factorial(x) -> int` 返回 `x` 的阶乘（即 `x!`），如果 `x` 是负数或者不是整数，则会引发一个错误。 +```python +import math + +a = math.factorial(5) +``` + ## floor `floor(x) -> int` 返回 `x` 向下取整得到的整数，这是小于等于 `x` 的最大整数。 +```python +import math + +a = math.floor(-45.17) +b = math.floor(100.12) +``` + ## gcd `gcd(a: int, b: int) -> int` 返回 `x` 和 `y` 的最大公约数。 +```python +import math + +a = math.gcd(60, 48) +``` + ## isfinite `isfinite(x) -> bool` 如果 `x` 既不是无穷大也不是 `NaN` 返回 `True`，否则返回 `False`。 +```python +import math + +a = math.isfinite(1) +b = math.isfinite(0) +c = math.isfinite(float("nan")) +``` + ## isinf `isinf(x) -> bool` 如果 `x` 是正无穷或负无穷返回 `True`，否则返回 `False`。 +```python +import math + +a = math.isinf(1) +b = math.isinf(0) +c = math.isinf(float("nan")) +``` + ## isnan `isnan(x) -> bool` 如果 `x` 是 `NaN` 返回 `True`，否则返回 `False`。 +```python +import math + +a = math.isnan(1) +b = math.isnan(0) +c = math.isnan(float("nan")) +``` + ## modf `modf(x) -> List[float, float]` 返回 `x` 的整数和小数部分，两个结果均与 `x` 的正负号相同，并且均为浮点数。 +```python +import math + +a = math.modf(100.12) +b = math.modf(100.72) +``` + ## exp `exp(x) -> float` 返回以 `e` 为底数， `x` 的幂。 +```python +import math + +a = math.exp(2) +b = math.exp(-6.89) +``` + ## expm1 `expm1(x) -> float` 返回 `e` 的 `x` 次方减去 1，该函数能够避免由于直接计算 `exp(x) - 1` 而引起的精度损失。 +```python +import math + +a = math.expm1(32) +b = math.expm1(-10.89) +``` + ## log `log(x, base=2.71828182845904523536028747135266250) -> float` 返回以 `e` 为底数，`x` 的对数。 +```python +import math + +a = math.log10(100) # 2 +``` + ## log1p `log1p(x) -> float` 返回以 `e` 为底数，`1 + x` 的自然对数，该函数能够在 `x` 靠近 0 时精确计算结果。 +```python +import math + +a = math.log1p(2.7183) +b = math.log1p(2) +c = math.log1p(1) +``` + ## log2 `log2(x) -> float` 返回 `x` 的以 2 为底的对数。 +```python +import math + +a = math.log2(2.7183) +b = math.log2(2) +c = math.log2(1) +``` + ## log10 `log10(x) -> float` 返回 `x` 的以 10 为底的对数。 +```python +import math + +a = math.log10(2.7183) +b = math.log10(2) +c = math.log10(1) +``` + ## pow `pow(x, y) -> float` 返回 `x` 的 `y` 次幂（即 `x` 的 `y` 次方）。 +```python +import math + +a = math.pow(1, 1) +``` + ## sqrt `sqrt(x) -> float` 返回 `x` 的平方根。 + +```python +import math + +a = math.sqrt(9) +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/net.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/net.md index 1050d16d..607466db 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/net.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/net.md @@ -12,92 +12,190 @@ weight: 100 从 `ip_end_point` 分离出 `host` 和 `port`。 +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## join_host_port `join_host_port(host, port) -> str` 合并 `host` 和 `port`。 +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## fqdn `fqdn(name: str = '') -> str` 返回完全限定域名（FQDN）。 +```python +import net + +fqdn = net.fqdn() +``` + ## parse_IP `parse_IP(ip) -> str` 将 `ip` 解析为真实的 IP 地址。 +```python +import net + +ip = net.parse_IP("192.168.0.1") +``` + ## to_IP4 `to_IP4(ip) -> str` 获取 `ip` 的 IPv4 表示形式。 +```python +import net + +ip = net.to_IP4("192.168.0.1") +``` + ## to_IP16 `to_IP16(ip) -> int` 获取 `ip` 的 IPv6 表示形式。 +```python +import net + +ip = net.to_IP16("192.168.0.1") +``` + ## IP_string `IP_string(ip: str | int) -> str` 返回 IP 字符串。 +```python +import net + +ip = net.IP_string("192.168.0.1") +``` + ## is_IPv4 `is_IPv4(ip: str) -> bool` 判断 `ip` 是否为 IPv4。 +```python +import net + +ip = net.is_IPv4("192.168.0.1") +``` + ## is_IP `is_IP(ip: str) -> bool` 判断 `ip` 是否为有效的 IP 地址。 +```python +import net + +ip = net.is_IP("192.168.0.1") +``` + ## is_loopback_IP `is_loopback_IP(ip: str) -> bool` 判断 `ip` 是否为回环地址。 +```python +import net + +isip = net.is_loopback_IP("127.0.0.1") +``` + ## is_multicast_IP `is_multicast_IP(ip: str) -> bool` 判断 `ip` 是否为组播地址。 +```python +import net + +isip = net.is_multicast_IP("239.255.255.255") +``` + ## is_interface_local_multicast_IP `is_interface_local_multicast_IP(ip: str) -> bool` 判断 `ip` 是否为接口、本地和组播地址。 +```python +import net + +isip = net.is_interface_local_multicast_IP("239.255.255.255") +``` + ## is_link_local_multicast_IP `is_link_local_multicast_IP(ip: str) -> bool` 判断 `ip` 是否为链路本地和组播地址。 +```python +import net + +isip = net.is_link_local_multicast_IP("224.0.0.0") +``` + ## is_link_local_unicast_IP `is_link_local_unicast_IP(ip: str) -> bool` 判断 `ip` 是否为链路本地和单播地址。 +```python +import net + +isip = net.is_link_local_unicast_IP("fe80::2012:1") +``` + ## is_global_unicast_IP `is_global_unicast_IP(ip: str) -> bool` 判断 `ip` 是否为全局单播地址。 +```python +import net + +isip = net.is_global_unicast_IP("220.181.108.89") +``` + ## is_unspecified_IP `is_unspecified_IP(ip: str) -> bool` 判断 `ip` 是否为 `unspecified` 地址。 + +```python +import net + +isip = net.is_unspecified_IP("0.0.0.0") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/regex.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/regex.md index e7b0c25c..380df50b 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/regex.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/regex.md @@ -12,11 +12,22 @@ weight: 100 替换字符串 `string`中最左边、不重叠并且匹配模式 `pattern` 的部分替换为指定的字符串 `replace`，并返回替换后的字符串 +```python +import regex + +regex_replace = regex.replace(regex_source, ",", "|") +``` + ## match `match(string: str, pattern: str) -> bool` 尝试在字符串开头应用模式 `pattern`，找到了任何匹配项则返回 `True`，返回 `False` 表示没有找到匹配项 +```python +import regex + +regex_result = regex.match("192.168.0.1", "^(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|[1-9])\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)$") +``` ## compile @@ -24,20 +35,44 @@ weight: 100 编译正则表达式模式 `pattern`，并返回一个布尔值，表示该模式是否有效 +```python +import regex + +regex_compile = regex.compile("$^") +``` + ## findall `findall(string: str, pattern: str) -> List[str]` 查找 `pattern` 在 `string` 中的所有非重叠匹配，并以字符串列表的形式返回 +```python +import regex + +regex_find_all = regex.findall("aaaa", "a") +``` + ## search `search(string: str, pattern: str) -> bool` 扫描字符串 `string` 以查找与模式匹配的项，如果找到任何匹配项，则返回布尔值 `True`，否则返回 `False` +```python +import regex + +regex_search = regex.search("aaaa", "a") +``` + ## split `split(string: str, pattern: str, maxsplit=0) -> List[str]` 返回一个由字符串内单词组成的列表，使用 `pattern` 作为分隔字符串，最多进行 `maxsplit` 次拆分 + +```python +import regex + +regex_split = regex.split(regex_source, ",") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/runtime.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/runtime.md index e24bcc30..3d14e4cc 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/runtime.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/runtime.md @@ -12,7 +12,7 @@ weight: 100 `catch` 函数可以执行代码块并捕获任何潜在的运行时错误。如果代码块中没有发生异常，`catch` 函数返回 `Undefined`，否则返回异常信息。 -```python3 +```python import runtime schema Person: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/template.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/template.md index 0094544b..65c58dbf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/template.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 将解析过的模板应用于指定的数据对象，并返回字符串输出。查看 https://handlebarsjs.com/ 获取更多文档和示例。 -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ 将字符 `&"<>` 替换为等效的 html / xml实体。 -```python3 +```python import template diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/units.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/units.md index 8c862d0e..ccc10c49 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/units.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/units.md @@ -39,3 +39,22 @@ weight: 100 将 int 转换为以 `Ti` 作为后缀的字符串 - `to_Pi(num: int) -> str` 将 int 转换为以 `Pi` 作为后缀的字符串 + +```python +import units +# SI +n = units.to_n(1e-9) +u = units.to_u(1e-6) +m = units.to_m(1e-1) +K = units.to_K(1000) +M = units.to_M(1000000) +G = units.to_G(1000000000) +T = units.to_T(1000000000000) +P = units.to_P(1000000000000000) +# IEC +Ki = units.to_Ki(1024) +Mi = units.to_Mi(1024 ** 2) +Gi = units.to_Gi(1024 ** 3) +Ti = units.to_Ti(1024 ** 4) +Pi = units.to_Pi(1024 ** 5) +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/yaml.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/yaml.md index c3aa76ca..a1df604f 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/yaml.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/yaml.md @@ -19,6 +19,17 @@ encode( 将 KCL 对象 `data` 序列化为 YAML 格式的字符串。 +```python +import yaml + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = yaml.encode(data) +``` + ## encode_all ```python @@ -32,18 +43,45 @@ encode( 将 KCL 对象列表 `data` 序列化为包含 `---` 分隔符的 YAML Stream 格式的字符串。 +```python +import yaml + +yamlStr = yaml.encode_all([1, 2, 3]) +``` + ## decode `decode(value: str) -> any` 反序列化 `value`（一个包含 YAML 格式文档的字符串实例）为一个 KCL 对象。 +```python +import yaml +import file + +data_string = yaml.decode(file.read("test.yaml")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## decode_all `decode_all(value: str) -> [any]` 反序列化 `value`（一个包含 `---` 分隔符的 YAML Stream 格式文档的字符串实例）为一个 KCL 对象列表。 +```python +import yaml + +yamlStr = """\ +key: value +""" +data = yaml.decode(yamlStr) +dataList = yaml.decode_all(yamlStr) +``` + ## dump_to_file ```python @@ -58,7 +96,24 @@ dump_to_file( 将 KCL 对象 `data` 序列化为 YAML 格式的字符串，并将其写入文件 `filename` 中。 -## dump_to_file +```python +import yaml + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.yaml" +yaml.dump_to_file(person, filename, ignore_private=True, ignore_none=True) +``` + +## dump_all_to_file ```python dump_all_to_file( @@ -71,6 +126,20 @@ dump_all_to_file( 将 KCL 对象列表序列化为 YAML Stream 格式，并将其写入文件 `filename` 中。 +```python +import yaml + +yamlStrList = [ + 'key: value', + '- 1\n- 2\n- 3', + '1', + '1.1', + 'null', + 'true', +] +yaml.dump_all_to_file(yamlStrList, "0.yaml") +``` + ## validate ```python @@ -78,3 +147,27 @@ validate(value: str) -> bool ``` 验证给定的字符串是否是一个合法的 YAML 或者 YAML Stream 格式的字符串。 + +```python +import yaml + +# Right cases + +resultRight1: bool = yaml.validate("1") +resultRight2: bool = yaml.validate("true") +resultRight3: bool = yaml.validate("1.20") +resultRight4: bool = yaml.validate("null") +resultRight5: bool = yaml.validate("[0, 1, 2]") +resultRight6: bool = yaml.validate('{"key": "value"}') +resultRight7: bool = yaml.validate('a:1\n---\nb:2') + +# Wrong cases + +resultWrong1: bool = yaml.validate("a:\n1") +resultWrong2: bool = yaml.validate("a:\n1\n - 2") +resultWrong3: bool = yaml.validate("a:\n-1") +resultWrong4: bool = yaml.validate("1a : \n1") +resultWrong5: bool = yaml.validate("a:\n- 1\n-----\na:\n- 1") +resultWrong6: bool = yaml.validate(r'''{"key" + 'value'}''') +resultWrong7: bool = yaml.validate("a:1\n-----\nb:\n-2") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/lua-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/lua-api.md index e443ed79..a2b7f8bb 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/lua-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/lua-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 12 --- # Lua API diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/wasm-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/wasm-api.md index 32c06058..b8f3c2d3 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/wasm-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/wasm-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 --- # WASM API diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/base64.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/base64.md index 37092e7c..71d70481 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/base64.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/base64.md @@ -12,8 +12,20 @@ weight: 100 使用注册的编码器对字符串 `value` 进行编码。 +```python +import base64 + +abcd_base64 = base64.encode("abcd") +``` + ## decode `decode(value: str) -> str` 使用注册的编码器对字符串 `value` 进行解码，解码的结果是一个 utf8 字符串 + +```python +import base64 + +decode = base64.decode("MC4zLjA=") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/crypto.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/crypto.md index 243c150e..e6d7b482 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/crypto.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/crypto.md @@ -12,50 +12,104 @@ weight: 100 使用注册编码器和 `MD5` 算法对字符串 `value` 进行加密。 +```python +import crypto + +md5 = crypto.md5("ABCDEF") +``` + ## sha1 `sha1(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA1` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha1("ABCDEF") +``` + ## sha224 `sha224(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA224` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha224("ABCDEF") +``` + ## sha256 `sha256(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA256` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha256("ABCDEF") +``` + ## sha384 `sha384(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA384` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha384("ABCDEF") +``` + ## sha512 `sha512(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `SHA512` 算法对字符串 `value` 进行加密。 +```python +import crypto + +sha = crypto.sha512("ABCDEF") +``` + ## blake3 `sha512(value: str, encoding: str = "utf-8") -> str` 使用注册编码器和 `BLAKE3` 算法对字符串 `value` 进行加密。 +```python +import crypto + +blake3 = crypto.blake3("ABCDEF") +``` + ## uuid `uuid() -> str` 生成一个随机 UUID 字符串。 +```python +import crypto + +a = crypto.uuid() +``` + ## filesha256 `filesha256(filepath: str) -> str` 计算文件 `filepath` 的 SHA256 哈希。 + +```python +import crypto + +sha = crypto.filesha256("test.txt") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/datetime.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/datetime.md index 67a5b48f..fae58f41 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/datetime.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/datetime.md @@ -12,26 +12,56 @@ weight: 100 返回从 1970 年 1 月 1 日 0 时 0 分 0 秒（Epoch）开始到当前时间经过的秒数。如果系统时钟能提供更精确的时间，则秒数后可能会有小数部分。 +```python +import datetime + +ticks = datetime.ticks() +``` + ## date `date() -> str` 返回以 `%Y-%m-%d %H:%M:%S` 格式表示的时间。 +```python +import datetime + +date = datetime.date() +``` + ## now `now(format: str = "%a %b %d %H:%M:%S %Y") -> str` 返回本地时间格式。例如：`Sat Jun 06 16:26:11 1998`，或者根据指定的格式字符串格式化组合的日期和时间，默认日期格式为 `%a %b %d %H:%M:%S %Y`。 +```python +import datetime + +date = datetime.now() +``` + ## today `today() -> str` 返回以 `%Y-%m-%d %H:%M:%S.%{ticks}` 格式表示的时间。 +```python +import datetime + +date = datetime.today() +``` + ## validate `validate(date: str, format: str) -> bool` 验证提供的日期字符串是否与指定格式匹配。 + +```python +import datetime + +result = datetime.validate("2024-08-26", "%Y-%m-%d") # Valid date +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/file.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/file.md index 90e3d518..c194becf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/file.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/file.md @@ -12,80 +12,164 @@ weight: 100 读取文件 `filepath` 中的内容，并返回一个字符串实例。 +```python +import file + +a = file.read("test.txt") +``` + ## glob `glob(pattern: str) -> str` 返回一个包含所有匹配 `pattern` 的文件名的列表。 +```python +import file + +json_files = file.glob("./*.json") +``` + ## modpath `modpath() -> str` 返回当前模块的根路径（kcl.mod 文件路径或单个 \*.k 文件路径）。 +```python +import file + +modpath = file.modpath() +``` + ## workdir `workdir() -> str` 返回当前工作目录的路径。 +```python +import file + +workdir = file.workdir() +``` + ## exists `exists(filepath: str) -> bool` 判断文件路径是否存在。如果路径指向一个存在的实体，则返回 True。此函数会遍历符号链接以查询目标文件的信息。 +```python +import file + +file_exists = file.exists("test.txt") +``` + ## abs `abs(filepath: str) -> str` 返回路径的规范化绝对形式，其中所有中间路径均已规范化并解析为符号链接。 +```python +import file + +abs_file_path = file.abs("test.txt") +``` + ## mkdir `mkdir(directory: str, exists: bool=False)` 如果指定路径上不存在目录，则创建一个新目录。 +```python +import file + +file.mkdir("path") +``` + ## delete `delete(directory: str)` 在指定路径上删除一个文件或空目录。 +```python +import file + +file.delete("test.txt") +``` + ## cp `cp(src: str, dest: str)` 将文件或目录从源路径复制到目标路径。 +```python +import file + +file.cp("src", "dest") +``` + ## mv `mv(src: str, dest: str)` 将文件或目录从源路径移动到目标路径。 +```python +import file + +file.mv("src", "dest") +``` + ## size `size(filepath: str) -> int` 获取指定路径上文件的大小。 +```python +import file + +size = file.size("test.txt") +``` + ## write `write(filepath: str, content: str)` 将内容写入指定路径的文件。如果文件不存在，将会被创建。如果文件存在，其内容将被替换。 +```python +import file + +file.size("test.txt", "content") +``` + ## read_env `read_env(key: str) -> str` 从当前进程中读取环境变量 `key` 的值。 +```python +import file + +value = file.read_env("ENV_VAR") +``` + ## current `current() -> str` 读取正在执行的当前 KCL 代码文件或模块的路径。 + +```python +import file + +value = file.current() +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/json.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/json.md index 633692f6..da7a338e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/json.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/json.md @@ -20,12 +20,34 @@ encode( 将 KCL 对象 `data` 序列化为 JSON 格式的字符串。 +```python +import json + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = json.encode(data) +``` + ## decode `decode(value: str) -> any` 反序列化 `value`（一个包含 JSON 格式文档的字符串实例）为一个 KCL 对象。 +```python +import file +import json + +data_string = json.decode(file.read(file.modpath()+"/test.json")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## dump_to_file ```python @@ -41,6 +63,23 @@ dump_to_file( 将 KCL 对象 `data` 序列化为 JSON 格式的字符串，并将其写入文件 `filename` 中。 +```python +import json + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.json" +json.dump_to_file(person, filename, indent=4, ignore_private=True, ignore_none=True) +``` + ## validate ```python @@ -48,3 +87,25 @@ validate(value: str) -> bool ``` 验证给定的字符串是否是一个合法的 JSON 字符串。 + +```python +import json + +# Right cases + +resultRight1: bool = json.validate("1") +resultRight2: bool = json.validate("true") +resultRight3: bool = json.validate("1.20") +resultRight4: bool = json.validate("null") +resultRight5: bool = json.validate("[0, 1, 2]") +resultRight6: bool = json.validate('{"key": "value"}') + +# Wrong cases + +resultWrong1: bool = json.validate("1@") +resultWrong2: bool = json.validate("True") +resultWrong3: bool = json.validate("1.20.23+1") +resultWrong4: bool = json.validate("None") +resultWrong5: bool = json.validate("[0, 1, 2,]") +resultWrong6: bool = json.validate(r'''{"key": 'value'}''') +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/math.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/math.md index 3b2ff0cc..e16558b2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/math.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/math.md @@ -12,92 +12,205 @@ weight: 100 返回 `x` 向上取整得到的整数，这是大于等于 `x` 的最小整数。 +```python +import math + +a = math.ceil(-45.17) +b = math.ceil(100.12) +``` + ## factorial `factorial(x) -> int` 返回 `x` 的阶乘（即 `x!`），如果 `x` 是负数或者不是整数，则会引发一个错误。 +```python +import math + +a = math.factorial(5) +``` + ## floor `floor(x) -> int` 返回 `x` 向下取整得到的整数，这是小于等于 `x` 的最大整数。 +```python +import math + +a = math.floor(-45.17) +b = math.floor(100.12) +``` + ## gcd `gcd(a: int, b: int) -> int` 返回 `x` 和 `y` 的最大公约数。 +```python +import math + +a = math.gcd(60, 48) +``` + ## isfinite `isfinite(x) -> bool` 如果 `x` 既不是无穷大也不是 `NaN` 返回 `True`，否则返回 `False`。 +```python +import math + +a = math.isfinite(1) +b = math.isfinite(0) +c = math.isfinite(float("nan")) +``` + ## isinf `isinf(x) -> bool` 如果 `x` 是正无穷或负无穷返回 `True`，否则返回 `False`。 +```python +import math + +a = math.isinf(1) +b = math.isinf(0) +c = math.isinf(float("nan")) +``` + ## isnan `isnan(x) -> bool` 如果 `x` 是 `NaN` 返回 `True`，否则返回 `False`。 +```python +import math + +a = math.isnan(1) +b = math.isnan(0) +c = math.isnan(float("nan")) +``` + ## modf `modf(x) -> List[float, float]` 返回 `x` 的整数和小数部分，两个结果均与 `x` 的正负号相同，并且均为浮点数。 +```python +import math + +a = math.modf(100.12) +b = math.modf(100.72) +``` + ## exp `exp(x) -> float` 返回以 `e` 为底数， `x` 的幂。 +```python +import math + +a = math.exp(2) +b = math.exp(-6.89) +``` + ## expm1 `expm1(x) -> float` 返回 `e` 的 `x` 次方减去 1，该函数能够避免由于直接计算 `exp(x) - 1` 而引起的精度损失。 +```python +import math + +a = math.expm1(32) +b = math.expm1(-10.89) +``` + ## log `log(x, base=2.71828182845904523536028747135266250) -> float` 返回以 `e` 为底数，`x` 的对数。 +```python +import math + +a = math.log10(100) # 2 +``` + ## log1p `log1p(x) -> float` 返回以 `e` 为底数，`1 + x` 的自然对数，该函数能够在 `x` 靠近 0 时精确计算结果。 +```python +import math + +a = math.log1p(2.7183) +b = math.log1p(2) +c = math.log1p(1) +``` + ## log2 `log2(x) -> float` 返回 `x` 的以 2 为底的对数。 +```python +import math + +a = math.log2(2.7183) +b = math.log2(2) +c = math.log2(1) +``` + ## log10 `log10(x) -> float` 返回 `x` 的以 10 为底的对数。 +```python +import math + +a = math.log10(2.7183) +b = math.log10(2) +c = math.log10(1) +``` + ## pow `pow(x, y) -> float` 返回 `x` 的 `y` 次幂（即 `x` 的 `y` 次方）。 +```python +import math + +a = math.pow(1, 1) +``` + ## sqrt `sqrt(x) -> float` 返回 `x` 的平方根。 + +```python +import math + +a = math.sqrt(9) +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/net.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/net.md index 1050d16d..607466db 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/net.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/net.md @@ -12,92 +12,190 @@ weight: 100 从 `ip_end_point` 分离出 `host` 和 `port`。 +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## join_host_port `join_host_port(host, port) -> str` 合并 `host` 和 `port`。 +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## fqdn `fqdn(name: str = '') -> str` 返回完全限定域名（FQDN）。 +```python +import net + +fqdn = net.fqdn() +``` + ## parse_IP `parse_IP(ip) -> str` 将 `ip` 解析为真实的 IP 地址。 +```python +import net + +ip = net.parse_IP("192.168.0.1") +``` + ## to_IP4 `to_IP4(ip) -> str` 获取 `ip` 的 IPv4 表示形式。 +```python +import net + +ip = net.to_IP4("192.168.0.1") +``` + ## to_IP16 `to_IP16(ip) -> int` 获取 `ip` 的 IPv6 表示形式。 +```python +import net + +ip = net.to_IP16("192.168.0.1") +``` + ## IP_string `IP_string(ip: str | int) -> str` 返回 IP 字符串。 +```python +import net + +ip = net.IP_string("192.168.0.1") +``` + ## is_IPv4 `is_IPv4(ip: str) -> bool` 判断 `ip` 是否为 IPv4。 +```python +import net + +ip = net.is_IPv4("192.168.0.1") +``` + ## is_IP `is_IP(ip: str) -> bool` 判断 `ip` 是否为有效的 IP 地址。 +```python +import net + +ip = net.is_IP("192.168.0.1") +``` + ## is_loopback_IP `is_loopback_IP(ip: str) -> bool` 判断 `ip` 是否为回环地址。 +```python +import net + +isip = net.is_loopback_IP("127.0.0.1") +``` + ## is_multicast_IP `is_multicast_IP(ip: str) -> bool` 判断 `ip` 是否为组播地址。 +```python +import net + +isip = net.is_multicast_IP("239.255.255.255") +``` + ## is_interface_local_multicast_IP `is_interface_local_multicast_IP(ip: str) -> bool` 判断 `ip` 是否为接口、本地和组播地址。 +```python +import net + +isip = net.is_interface_local_multicast_IP("239.255.255.255") +``` + ## is_link_local_multicast_IP `is_link_local_multicast_IP(ip: str) -> bool` 判断 `ip` 是否为链路本地和组播地址。 +```python +import net + +isip = net.is_link_local_multicast_IP("224.0.0.0") +``` + ## is_link_local_unicast_IP `is_link_local_unicast_IP(ip: str) -> bool` 判断 `ip` 是否为链路本地和单播地址。 +```python +import net + +isip = net.is_link_local_unicast_IP("fe80::2012:1") +``` + ## is_global_unicast_IP `is_global_unicast_IP(ip: str) -> bool` 判断 `ip` 是否为全局单播地址。 +```python +import net + +isip = net.is_global_unicast_IP("220.181.108.89") +``` + ## is_unspecified_IP `is_unspecified_IP(ip: str) -> bool` 判断 `ip` 是否为 `unspecified` 地址。 + +```python +import net + +isip = net.is_unspecified_IP("0.0.0.0") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/regex.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/regex.md index e7b0c25c..380df50b 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/regex.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/regex.md @@ -12,11 +12,22 @@ weight: 100 替换字符串 `string`中最左边、不重叠并且匹配模式 `pattern` 的部分替换为指定的字符串 `replace`，并返回替换后的字符串 +```python +import regex + +regex_replace = regex.replace(regex_source, ",", "|") +``` + ## match `match(string: str, pattern: str) -> bool` 尝试在字符串开头应用模式 `pattern`，找到了任何匹配项则返回 `True`，返回 `False` 表示没有找到匹配项 +```python +import regex + +regex_result = regex.match("192.168.0.1", "^(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|[1-9])\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)$") +``` ## compile @@ -24,20 +35,44 @@ weight: 100 编译正则表达式模式 `pattern`，并返回一个布尔值，表示该模式是否有效 +```python +import regex + +regex_compile = regex.compile("$^") +``` + ## findall `findall(string: str, pattern: str) -> List[str]` 查找 `pattern` 在 `string` 中的所有非重叠匹配，并以字符串列表的形式返回 +```python +import regex + +regex_find_all = regex.findall("aaaa", "a") +``` + ## search `search(string: str, pattern: str) -> bool` 扫描字符串 `string` 以查找与模式匹配的项，如果找到任何匹配项，则返回布尔值 `True`，否则返回 `False` +```python +import regex + +regex_search = regex.search("aaaa", "a") +``` + ## split `split(string: str, pattern: str, maxsplit=0) -> List[str]` 返回一个由字符串内单词组成的列表，使用 `pattern` 作为分隔字符串，最多进行 `maxsplit` 次拆分 + +```python +import regex + +regex_split = regex.split(regex_source, ",") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/runtime.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/runtime.md index e24bcc30..3d14e4cc 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/runtime.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/runtime.md @@ -12,7 +12,7 @@ weight: 100 `catch` 函数可以执行代码块并捕获任何潜在的运行时错误。如果代码块中没有发生异常，`catch` 函数返回 `Undefined`，否则返回异常信息。 -```python3 +```python import runtime schema Person: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/template.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/template.md index 0094544b..65c58dbf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/template.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 将解析过的模板应用于指定的数据对象，并返回字符串输出。查看 https://handlebarsjs.com/ 获取更多文档和示例。 -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ 将字符 `&"<>` 替换为等效的 html / xml实体。 -```python3 +```python import template diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/units.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/units.md index 8c862d0e..ccc10c49 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/units.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/units.md @@ -39,3 +39,22 @@ weight: 100 将 int 转换为以 `Ti` 作为后缀的字符串 - `to_Pi(num: int) -> str` 将 int 转换为以 `Pi` 作为后缀的字符串 + +```python +import units +# SI +n = units.to_n(1e-9) +u = units.to_u(1e-6) +m = units.to_m(1e-1) +K = units.to_K(1000) +M = units.to_M(1000000) +G = units.to_G(1000000000) +T = units.to_T(1000000000000) +P = units.to_P(1000000000000000) +# IEC +Ki = units.to_Ki(1024) +Mi = units.to_Mi(1024 ** 2) +Gi = units.to_Gi(1024 ** 3) +Ti = units.to_Ti(1024 ** 4) +Pi = units.to_Pi(1024 ** 5) +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/yaml.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/yaml.md index c3aa76ca..a1df604f 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/yaml.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/model/yaml.md @@ -19,6 +19,17 @@ encode( 将 KCL 对象 `data` 序列化为 YAML 格式的字符串。 +```python +import yaml + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = yaml.encode(data) +``` + ## encode_all ```python @@ -32,18 +43,45 @@ encode( 将 KCL 对象列表 `data` 序列化为包含 `---` 分隔符的 YAML Stream 格式的字符串。 +```python +import yaml + +yamlStr = yaml.encode_all([1, 2, 3]) +``` + ## decode `decode(value: str) -> any` 反序列化 `value`（一个包含 YAML 格式文档的字符串实例）为一个 KCL 对象。 +```python +import yaml +import file + +data_string = yaml.decode(file.read("test.yaml")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## decode_all `decode_all(value: str) -> [any]` 反序列化 `value`（一个包含 `---` 分隔符的 YAML Stream 格式文档的字符串实例）为一个 KCL 对象列表。 +```python +import yaml + +yamlStr = """\ +key: value +""" +data = yaml.decode(yamlStr) +dataList = yaml.decode_all(yamlStr) +``` + ## dump_to_file ```python @@ -58,7 +96,24 @@ dump_to_file( 将 KCL 对象 `data` 序列化为 YAML 格式的字符串，并将其写入文件 `filename` 中。 -## dump_to_file +```python +import yaml + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.yaml" +yaml.dump_to_file(person, filename, ignore_private=True, ignore_none=True) +``` + +## dump_all_to_file ```python dump_all_to_file( @@ -71,6 +126,20 @@ dump_all_to_file( 将 KCL 对象列表序列化为 YAML Stream 格式，并将其写入文件 `filename` 中。 +```python +import yaml + +yamlStrList = [ + 'key: value', + '- 1\n- 2\n- 3', + '1', + '1.1', + 'null', + 'true', +] +yaml.dump_all_to_file(yamlStrList, "0.yaml") +``` + ## validate ```python @@ -78,3 +147,27 @@ validate(value: str) -> bool ``` 验证给定的字符串是否是一个合法的 YAML 或者 YAML Stream 格式的字符串。 + +```python +import yaml + +# Right cases + +resultRight1: bool = yaml.validate("1") +resultRight2: bool = yaml.validate("true") +resultRight3: bool = yaml.validate("1.20") +resultRight4: bool = yaml.validate("null") +resultRight5: bool = yaml.validate("[0, 1, 2]") +resultRight6: bool = yaml.validate('{"key": "value"}') +resultRight7: bool = yaml.validate('a:1\n---\nb:2') + +# Wrong cases + +resultWrong1: bool = yaml.validate("a:\n1") +resultWrong2: bool = yaml.validate("a:\n1\n - 2") +resultWrong3: bool = yaml.validate("a:\n-1") +resultWrong4: bool = yaml.validate("1a : \n1") +resultWrong5: bool = yaml.validate("a:\n- 1\n-----\na:\n- 1") +resultWrong6: bool = yaml.validate(r'''{"key" + 'value'}''') +resultWrong7: bool = yaml.validate("a:1\n-----\nb:\n-2") +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/lua-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/lua-api.md index e443ed79..a2b7f8bb 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/lua-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/lua-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 12 --- # Lua API diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/wasm-api.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/wasm-api.md index 32c06058..b8f3c2d3 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/wasm-api.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/xlang-api/wasm-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 --- # WASM API diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.8/reference/model/template.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.8/reference/model/template.md index 0094544b..65c58dbf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.8/reference/model/template.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.8/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 将解析过的模板应用于指定的数据对象，并返回字符串输出。查看 https://handlebarsjs.com/ 获取更多文档和示例。 -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ 将字符 `&"<>` 替换为等效的 html / xml实体。 -```python3 +```python import template diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/runtime.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/runtime.md index e24bcc30..3d14e4cc 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/runtime.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/runtime.md @@ -12,7 +12,7 @@ weight: 100 `catch` 函数可以执行代码块并捕获任何潜在的运行时错误。如果代码块中没有发生异常，`catch` 函数返回 `Undefined`，否则返回异常信息。 -```python3 +```python import runtime schema Person: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/template.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/template.md index 0094544b..65c58dbf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/template.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 将解析过的模板应用于指定的数据对象，并返回字符串输出。查看 https://handlebarsjs.com/ 获取更多文档和示例。 -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ 将字符 `&"<>` 替换为等效的 html / xml实体。 -```python3 +```python import template diff --git a/versioned_docs/version-0.10/reference/model/base64.md b/versioned_docs/version-0.10/reference/model/base64.md index 615b7f48..7fa35732 100644 --- a/versioned_docs/version-0.10/reference/model/base64.md +++ b/versioned_docs/version-0.10/reference/model/base64.md @@ -12,8 +12,20 @@ weight: 100 Encode the string `value` using the codec registered for encoding. +```python +import base64 + +abcd_base64 = base64.encode("abcd") +``` + ## decode `decode(value: str) -> str` Decode the string `value` using the codec registered to the utf8 string for encoding. + +```python +import base64 + +decode = base64.decode("MC4zLjA=") +``` diff --git a/versioned_docs/version-0.10/reference/model/crypto.md b/versioned_docs/version-0.10/reference/model/crypto.md index 34d8629a..c826aafc 100644 --- a/versioned_docs/version-0.10/reference/model/crypto.md +++ b/versioned_docs/version-0.10/reference/model/crypto.md @@ -12,50 +12,104 @@ weight: 100 Encrypt the string `value` using `MD5` and the codec registered for encoding. +```python +import crypto + +md5 = crypto.md5("ABCDEF") +``` + ## sha1 `sha1(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA1` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha1("ABCDEF") +``` + ## sha224 `sha224(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA224` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha224("ABCDEF") +``` + ## sha256 `sha256(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA256` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha256("ABCDEF") +``` + ## sha384 `sha384(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA384` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha384("ABCDEF") +``` + ## sha512 `sha512(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `SHA512` and the codec registered for encoding. +```python +import crypto + +sha = crypto.sha512("ABCDEF") +``` + ## blake3 `blake3(value: str, encoding: str = "utf-8") -> str` Encrypt the string `value` using `BLAKE3` and the codec registered for encoding. +```python +import crypto + +blake3 = crypto.blake3("ABCDEF") +``` + ## uuid `uuid() -> str` Generate a random UUID string. +```python +import crypto + +a = crypto.uuid() +``` + ## filesha256 `filesha256(filepath: str) -> str` Calculate the SHA256 hash of the file `filepath`. + +```python +import crypto + +sha = crypto.filesha256("test.txt") +``` diff --git a/versioned_docs/version-0.10/reference/model/datetime.md b/versioned_docs/version-0.10/reference/model/datetime.md index 2448be45..f65edbcd 100644 --- a/versioned_docs/version-0.10/reference/model/datetime.md +++ b/versioned_docs/version-0.10/reference/model/datetime.md @@ -12,26 +12,56 @@ weight: 100 Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them. +```python +import datetime + +ticks = datetime.ticks() +``` + ## date `date() -> str` Return the `%Y-%m-%d %H:%M:%S` format date. +```python +import datetime + +date = datetime.date() +``` + ## now `now(format: str = "%a %b %d %H:%M:%S %Y") -> str` Return the local time format. e.g. 'Sat Jun 06 16:26:11 1998' or format the combined date and time per the specified format string, and the default date format is `%a %b %d %H:%M:%S %Y`. +```python +import datetime + +date = datetime.now() +``` + ## today `today() -> str` Return the `%Y-%m-%d %H:%M:%S.%{ticks}` format date. +```python +import datetime + +date = datetime.today() +``` + ## validate `validate(date: str, format: str) -> bool` Validate whether the provided date string matches the specified format. + +```python +import datetime + +result = datetime.validate("2024-08-26", "%Y-%m-%d") # Valid date +``` diff --git a/versioned_docs/version-0.10/reference/model/file.md b/versioned_docs/version-0.10/reference/model/file.md index c2b02308..60ff91b9 100644 --- a/versioned_docs/version-0.10/reference/model/file.md +++ b/versioned_docs/version-0.10/reference/model/file.md @@ -12,68 +12,164 @@ weight: 100 Read the contents of the file `filepath` and return a string instance. +```python +import file + +a = file.read("test.txt") +``` + ## glob `glob(pattern: str) -> str` Return a list containing all file names that match `pattern`. +```python +import file + +json_files = file.glob("./*.json") +``` + ## modpath `modpath() -> str` Return the root path of the current KCL module (kcl.mod file path or single \*.k file path). +```python +import file + +modpath = file.modpath() +``` + ## workdir `workdir() -> str` Return the path of the current working directory. +```python +import file + +workdir = file.workdir() +``` + ## exists `exists(filepath: str) -> bool` Whether this file path exists. Returns true if the path points at an existing entity. This function will traverse symbolic links to query information about the destination file. +```python +import file + +file_exists = file.exists("test.txt") +``` + ## abs `abs(filepath: str) -> str` Returns the canonical, absolute form of the path with all intermediate components normalized and symbolic links resolved. +```python +import file + +abs_file_path = file.abs("test.txt") +``` + ## mkdir `mkdir(directory: str, exists: bool=False)` Create a new directory at the specified path if it doesn't already exist. +```python +import file + +file.mkdir("path") +``` + ## delete `delete(directory: str)` Delete a file or an empty directory at the specified path. +```python +import file + +file.delete("test.txt") +``` + ## cp `cp(src: str, dest: str)` Copy a file or directory from the source path to the destination path. +```python +import file + +file.cp("src", "dest") +``` + ## mv `mv(src: str, dest: str)` Move a file or directory from the source path to the destination path. +```python +import file + +file.mv("src", "dest") +``` + +## size + +`size(filepath: str)` + +Get the size of a file at the specified path. + +```python +import file + +size = file.size("test.txt") +``` + +## write + +`write(filepath: str, content: str)` + +Write content to a file at the specified path. If the file doesn't exist, it will be created. If it does exist, its content will be replaced. + +```python +import file + +file.size("test.txt", "content") +``` + ## read_env `read_env(key: str) -> str` Read the environment variable `key` from the current process. +```python +import file + +value = file.read_env("ENV_VAR") +``` + ## current `current() -> str` Read the path of the current script or module that is being executed. + +```python +import file + +value = file.current() +``` diff --git a/versioned_docs/version-0.10/reference/model/json.md b/versioned_docs/version-0.10/reference/model/json.md index cd844903..10af823b 100644 --- a/versioned_docs/version-0.10/reference/model/json.md +++ b/versioned_docs/version-0.10/reference/model/json.md @@ -20,12 +20,34 @@ encode( Serialize a KCL object `data` to a JSON formatted str. +```python +import json + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = json.encode(data) +``` + ## decode `decode(value: str) -> any` Deserialize `value` (a string instance containing a JSON document) to a KCL object. +```python +import file +import json + +data_string = json.decode(file.read(file.modpath()+"/test.json")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## dump_to_file ```python @@ -41,6 +63,23 @@ dump_to_file( Serialize a KCL object `data` to a JSON formatted str and write it into the file `filename`. +```python +import json + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.json" +json.dump_to_file(person, filename, indent=4, ignore_private=True, ignore_none=True) +``` + ## validate ```python @@ -48,3 +87,25 @@ validate(value: str) -> bool ``` Validate whether the given string is a valid JSON. + +```python +import json + +# Right cases + +resultRight1: bool = json.validate("1") +resultRight2: bool = json.validate("true") +resultRight3: bool = json.validate("1.20") +resultRight4: bool = json.validate("null") +resultRight5: bool = json.validate("[0, 1, 2]") +resultRight6: bool = json.validate('{"key": "value"}') + +# Wrong cases + +resultWrong1: bool = json.validate("1@") +resultWrong2: bool = json.validate("True") +resultWrong3: bool = json.validate("1.20.23+1") +resultWrong4: bool = json.validate("None") +resultWrong5: bool = json.validate("[0, 1, 2,]") +resultWrong6: bool = json.validate(r'''{"key": 'value'}''') +``` diff --git a/versioned_docs/version-0.10/reference/model/math.md b/versioned_docs/version-0.10/reference/model/math.md index e48b0ad1..656ea119 100644 --- a/versioned_docs/version-0.10/reference/model/math.md +++ b/versioned_docs/version-0.10/reference/model/math.md @@ -12,92 +12,205 @@ weight: 100 Return the ceiling of `x` as an Integral. This is the smallest integer >= x. +```python +import math + +a = math.ceil(-45.17) +b = math.ceil(100.12) +``` + ## factorial `factorial(x) -> int` Return `x!`. Raise a error if `x` is negative or non-integral. +```python +import math + +a = math.factorial(5) +``` + ## floor `floor(x) -> int` Return the floor of `x` as an Integral. This is the largest integer <= x. +```python +import math + +a = math.floor(-45.17) +b = math.floor(100.12) +``` + ## gcd `gcd(a: int, b: int) -> int` Return the greatest common divisor of `x` and `y` +```python +import math + +a = math.gcd(60, 48) +``` + ## isfinite `isfinite(x) -> bool` Return `True` if `x` is neither an infinity nor a `NaN`, and `False` otherwise. +```python +import math + +a = math.isfinite(1) +b = math.isfinite(0) +c = math.isfinite(float("nan")) +``` + ## isinf `isinf(x) -> bool` Return `True` if `x` is a positive or negative infinity, and `False` otherwise. +```python +import math + +a = math.isinf(1) +b = math.isinf(0) +c = math.isinf(float("nan")) +``` + ## isnan `isnan(x) -> bool` Return `True` if `x` is a `NaN` (not a number), and `False` otherwise. +```python +import math + +a = math.isnan(1) +b = math.isnan(0) +c = math.isnan(float("nan")) +``` + ## modf `modf(x) -> List[float, float]` Return the fractional and integer parts of `x`. Both results carry the sign of `x` and are floats. +```python +import math + +a = math.modf(100.12) +b = math.modf(100.72) +``` + ## exp `exp(x) -> float` Return `e` raised to the power of `x`. +```python +import math + +a = math.exp(2) +b = math.exp(-6.89) +``` + ## expm1 `expm1(x) -> float` Return `exp(x) - 1`. This function avoids the loss of precision involved in the direct evaluation of `exp(x) - 1` for small `x`. +```python +import math + +a = math.expm1(32) +b = math.expm1(-10.89) +``` + ## log `log(x, base=2.71828182845904523536028747135266250) -> float` Return the logarithm of `x` to the base `e`. +```python +import math + +a = math.log10(100) # 2 +``` + ## log1p `log1p(x) -> float` Return the natural logarithm of `1+x` (base `e`). The result is computed in a way which is accurate for `x` near zero. +```python +import math + +a = math.log1p(2.7183) +b = math.log1p(2) +c = math.log1p(1) +``` + ## log2 `log2(x) -> float` Return the base 2 logarithm of `x`. +```python +import math + +a = math.log2(2.7183) +b = math.log2(2) +c = math.log2(1) +``` + ## log10 `log10(x) -> float` Return the base 10 logarithm of `x`. +```python +import math + +a = math.log10(2.7183) +b = math.log10(2) +c = math.log10(1) +``` + ## pow `pow(x, y) -> float` Return `x**y` (`x` to the power of `y`). +```python +import math + +a = math.pow(1, 1) +``` + ## sqrt `sqrt(x) -> float` Return the square root of `x`. + +```python +import math + +a = math.sqrt(9) +``` diff --git a/versioned_docs/version-0.10/reference/model/net.md b/versioned_docs/version-0.10/reference/model/net.md index a4e83659..9ec0194e 100644 --- a/versioned_docs/version-0.10/reference/model/net.md +++ b/versioned_docs/version-0.10/reference/model/net.md @@ -12,92 +12,190 @@ weight: 100 Split the `host` and `port` from the `ip_end_point`. +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## join_host_port `join_host_port(host, port) -> str` Merge the `host` and `port`. +```python +import net + +host_and_port = net.split_host_port("B-K0NZJGH6-0048.local:80") +host_port = net.join_host_port("B-K0NZJGH6-0048.local", 80) +``` + ## fqdn `fqdn(name: str = '') -> str` Return Fully Qualified Domain Name (FQDN). +```python +import net + +fqdn = net.fqdn() +``` + ## parse_IP `parse_IP(ip) -> str` Parse `ip` to a real IP address +```python +import net + +ip = net.parse_IP("192.168.0.1") +``` + ## to_IP4 `to_IP4(ip) -> str` Get the IP4 form of `ip`. +```python +import net + +ip = net.to_IP4("192.168.0.1") +``` + ## to_IP16 `to_IP16(ip) -> int` Get the IP16 form of `ip`. +```python +import net + +ip = net.to_IP16("192.168.0.1") +``` + ## IP_string `IP_string(ip: str | int) -> str` Get the IP string. +```python +import net + +ip = net.IP_string("192.168.0.1") +``` + ## is_IPv4 `is_IPv4(ip: str) -> bool` Whether `ip` is a IPv4 one. +```python +import net + +ip = net.is_IPv4("192.168.0.1") +``` + ## is_IP `is_IP(ip: str) -> bool` Whether `ip` is a valid ip address. +```python +import net + +ip = net.is_IP("192.168.0.1") +``` + ## is_loopback_IP `is_loopback_IP(ip: str) -> bool` Whether `ip` is a loopback one. +```python +import net + +isip = net.is_loopback_IP("127.0.0.1") +``` + ## is_multicast_IP `is_multicast_IP(ip: str) -> bool` Whether `ip` is a multicast one. +```python +import net + +isip = net.is_multicast_IP("239.255.255.255") +``` + ## is_interface_local_multicast_IP `is_interface_local_multicast_IP(ip: str) -> bool` Whether `ip` is a interface, local and multicast one. +```python +import net + +isip = net.is_interface_local_multicast_IP("239.255.255.255") +``` + ## is_link_local_multicast_IP `is_link_local_multicast_IP(ip: str) -> bool` Whether `ip` is a link local and multicast one. +```python +import net + +isip = net.is_link_local_multicast_IP("224.0.0.0") +``` + ## is_link_local_unicast_IP `is_link_local_unicast_IP(ip: str) -> bool` Whether `ip` is a link local and unicast one. +```python +import net + +isip = net.is_link_local_unicast_IP("fe80::2012:1") +``` + ## is_global_unicast_IP `is_global_unicast_IP(ip: str) -> bool` Whether `ip` is a global and unicast one. +```python +import net + +isip = net.is_global_unicast_IP("220.181.108.89") +``` + ## is_unspecified_IP `is_unspecified_IP(ip: str) -> bool` Whether `ip` is a unspecified one. + +```python +import net + +isip = net.is_unspecified_IP("0.0.0.0") +``` diff --git a/versioned_docs/version-0.10/reference/model/regex.md b/versioned_docs/version-0.10/reference/model/regex.md index adde0630..599ab1cf 100644 --- a/versioned_docs/version-0.10/reference/model/regex.md +++ b/versioned_docs/version-0.10/reference/model/regex.md @@ -12,32 +12,68 @@ weight: 100 Return the string obtained by replacing the leftmost non-overlapping occurrences of the pattern in string by the replacement. +```python +import regex + +regex_replace = regex.replace(regex_source, ",", "|") +``` + ## match `match(string: str, pattern: str) -> bool` Try to apply the pattern at the start of the string, returning a bool value `True` if any match was found, or `False` if no match was found. +```python +import regex + +regex_result = regex.match("192.168.0.1", "^(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|[1-9])\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)\\."+"(1\\d{2}|2[0-4]\\d|25[0-5]|[1-9]\\d|\\d)$") +``` + ## compile `compile(pattern: str) -> bool` Compile a regular expression pattern, returning a bool value denoting whether the pattern is valid. +```python +import regex + +regex_compile = regex.compile("$^") +``` + ## findall `findall(string: str, pattern: str) -> List[str]` Return a list of all non-overlapping matches in the string. +```python +import regex + +regex_find_all = regex.findall("aaaa", "a") +``` + ## search `search(string: str, pattern: str) -> bool` Scan through string looking for a match to the pattern, returning a bool value `True` if any match was found, or `False` if no match was found. +```python +import regex + +regex_search = regex.search("aaaa", "a") +``` + ## split `split(string: str, pattern: str, maxsplit=0) -> List[str]` Return a list composed of words from the string, splitting up to a maximum of `maxsplit` times using `pattern` as the separator. + +```python +import regex + +regex_split = regex.split(regex_source, ",") +``` diff --git a/versioned_docs/version-0.10/reference/model/runtime.md b/versioned_docs/version-0.10/reference/model/runtime.md index b65ed4b6..9eab8115 100644 --- a/versioned_docs/version-0.10/reference/model/runtime.md +++ b/versioned_docs/version-0.10/reference/model/runtime.md @@ -12,7 +12,7 @@ weight: 100 Executes the provided function and catches any potential runtime errors. Returns undefined if execution is successful, otherwise returns an error message in case of a runtime panic. -```python3 +```python import runtime schema Person: diff --git a/versioned_docs/version-0.10/reference/model/template.md b/versioned_docs/version-0.10/reference/model/template.md index 0c2115fb..5a04bb6a 100644 --- a/versioned_docs/version-0.10/reference/model/template.md +++ b/versioned_docs/version-0.10/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 Applies a parsed template to the specified data object and returns the string output. See https://handlebarsjs.com/ for more documents and examples. -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ Replaces the characters `&"<>` with the equivalent html / xml entities. -```python3 +```python import template diff --git a/versioned_docs/version-0.10/reference/model/units.md b/versioned_docs/version-0.10/reference/model/units.md index 34465a53..d58168d0 100644 --- a/versioned_docs/version-0.10/reference/model/units.md +++ b/versioned_docs/version-0.10/reference/model/units.md @@ -39,3 +39,22 @@ weight: 100 Int literal to string with `Ti` suffix - `to_Pi(num: int) -> str` Int literal to string with `Pi` suffix + +```python +import units +# SI +n = units.to_n(1e-9) +u = units.to_u(1e-6) +m = units.to_m(1e-1) +K = units.to_K(1000) +M = units.to_M(1000000) +G = units.to_G(1000000000) +T = units.to_T(1000000000000) +P = units.to_P(1000000000000000) +# IEC +Ki = units.to_Ki(1024) +Mi = units.to_Mi(1024 ** 2) +Gi = units.to_Gi(1024 ** 3) +Ti = units.to_Ti(1024 ** 4) +Pi = units.to_Pi(1024 ** 5) +``` diff --git a/versioned_docs/version-0.10/reference/model/yaml.md b/versioned_docs/version-0.10/reference/model/yaml.md index e2615f58..0807a2a2 100644 --- a/versioned_docs/version-0.10/reference/model/yaml.md +++ b/versioned_docs/version-0.10/reference/model/yaml.md @@ -19,6 +19,17 @@ encode( Serialize a KCL object `data` to a YAML formatted str. +```python +import yaml + +data = { + "key1": "value1" + "key2": "value2" + "data": [1, 2, 3] +} +data_string = yaml.encode(data) +``` + ## encode_all ```python @@ -32,18 +43,45 @@ encode( Serialize a sequence of KCL objects into a YAML stream str. +```python +import yaml + +yamlStr = yaml.encode_all([1, 2, 3]) +``` + ## decode `decode(value: str) -> any` Deserialize `value` (a string instance containing a YAML document) to a KCL object. +```python +import yaml +import file + +data_string = yaml.decode(file.read("test.yaml")) + +key1 = data_string.key1 +key2 = data_string.key2 +data = data_string.data +``` + ## decode_all `decode_all(value: str) -> [any]` Parse all YAML documents in a stream and produce corresponding KCL objects. +```python +import yaml + +yamlStr = """\ +key: value +""" +data = yaml.decode(yamlStr) +dataList = yaml.decode_all(yamlStr) +``` + ## dump_to_file ```python @@ -57,7 +95,24 @@ dump_to_file( Serialize a KCL object `data` to a YAML formatted str and write it into the file `filename`. -## dump_to_file +```python +import yaml + +schema Person: + name?: str + age?: int + school?: str + data?: [int] = [1, 2, None] + +person = Person { + name: "Alice" + age: 18 +} +filename = "out.yaml" +yaml.dump_to_file(person, filename, ignore_private=True, ignore_none=True) +``` + +## dump_all_to_file ```python dump_all_to_file( @@ -70,6 +125,20 @@ dump_all_to_file( Serialize a sequence of KCL objects into a YAML stream str and write it into the file `filename`. +```python +import yaml + +yamlStrList = [ + 'key: value', + '- 1\n- 2\n- 3', + '1', + '1.1', + 'null', + 'true', +] +yaml.dump_all_to_file(yamlStrList, "0.yaml") +``` + ## validate ```python @@ -77,3 +146,27 @@ validate(value: str) -> bool ``` Validate whether the given string is a valid YAML or YAML stream document. + +```python +import yaml + +# Right cases + +resultRight1: bool = yaml.validate("1") +resultRight2: bool = yaml.validate("true") +resultRight3: bool = yaml.validate("1.20") +resultRight4: bool = yaml.validate("null") +resultRight5: bool = yaml.validate("[0, 1, 2]") +resultRight6: bool = yaml.validate('{"key": "value"}') +resultRight7: bool = yaml.validate('a:1\n---\nb:2') + +# Wrong cases + +resultWrong1: bool = yaml.validate("a:\n1") +resultWrong2: bool = yaml.validate("a:\n1\n - 2") +resultWrong3: bool = yaml.validate("a:\n-1") +resultWrong4: bool = yaml.validate("1a : \n1") +resultWrong5: bool = yaml.validate("a:\n- 1\n-----\na:\n- 1") +resultWrong6: bool = yaml.validate(r'''{"key" + 'value'}''') +resultWrong7: bool = yaml.validate("a:1\n-----\nb:\n-2") +``` diff --git a/versioned_docs/version-0.10/reference/xlang-api/lua-api.md b/versioned_docs/version-0.10/reference/xlang-api/lua-api.md index 08d6dda2..cb73e392 100644 --- a/versioned_docs/version-0.10/reference/xlang-api/lua-api.md +++ b/versioned_docs/version-0.10/reference/xlang-api/lua-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 12 --- # Lua API diff --git a/versioned_docs/version-0.10/reference/xlang-api/wasm-api.md b/versioned_docs/version-0.10/reference/xlang-api/wasm-api.md index 0424ad91..f07ec78c 100644 --- a/versioned_docs/version-0.10/reference/xlang-api/wasm-api.md +++ b/versioned_docs/version-0.10/reference/xlang-api/wasm-api.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 --- # WASM API diff --git a/versioned_docs/version-0.8/reference/model/template.md b/versioned_docs/version-0.8/reference/model/template.md index 0c2115fb..5a04bb6a 100644 --- a/versioned_docs/version-0.8/reference/model/template.md +++ b/versioned_docs/version-0.8/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 Applies a parsed template to the specified data object and returns the string output. See https://handlebarsjs.com/ for more documents and examples. -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ Replaces the characters `&"<>` with the equivalent html / xml entities. -```python3 +```python import template diff --git a/versioned_docs/version-0.9/reference/model/runtime.md b/versioned_docs/version-0.9/reference/model/runtime.md index b65ed4b6..9eab8115 100644 --- a/versioned_docs/version-0.9/reference/model/runtime.md +++ b/versioned_docs/version-0.9/reference/model/runtime.md @@ -12,7 +12,7 @@ weight: 100 Executes the provided function and catches any potential runtime errors. Returns undefined if execution is successful, otherwise returns an error message in case of a runtime panic. -```python3 +```python import runtime schema Person: diff --git a/versioned_docs/version-0.9/reference/model/template.md b/versioned_docs/version-0.9/reference/model/template.md index 0c2115fb..5a04bb6a 100644 --- a/versioned_docs/version-0.9/reference/model/template.md +++ b/versioned_docs/version-0.9/reference/model/template.md @@ -12,7 +12,7 @@ weight: 100 Applies a parsed template to the specified data object and returns the string output. See https://handlebarsjs.com/ for more documents and examples. -```python3 +```python import template content = template.execute("""\ @@ -34,7 +34,7 @@ content = template.execute("""\ Replaces the characters `&"<>` with the equivalent html / xml entities. -```python3 +```python import template