Skip to content

docs: polish intro documents #362

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 13, 2024
Merged

docs: polish intro documents #362

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0ad52a9
docs: polish intro documents
Peefy May 13, 2024
d027de5
docs: add more instructions in the guide index page
Peefy May 13, 2024
8548620
chore: remove release components
Peefy May 13, 2024
d1e90ea
fix: kcl mod graph command reference title
Peefy May 13, 2024
7fdbb8d
docs: update system module documents in the spec
Peefy May 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions docs/community/release-policy/kcl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,6 @@ The KCL project version release strategy is as follows:
- Release Documentation: Detailed documentation, including release notes, update logs, API documentation, and usage guides, is provided during the release to help users understand and use the new version. In KCL, this documentation is maintained on the KCL website.
- Version Compatibility: When releasing a new version, compatibility is maintained as much as possible to minimize the need for modifications and adaptations by users. Since KCL has not reached version 1 yet, there are no compatibility guarantees at the moment. The goal of KCL is to minimize major changes unless they provide significant benefits, such as solving problems in the target scenarios or improving the overall user experience. For features or changes that may introduce compatibility issues, appropriate prompts and solutions will be provided. Gradual upgrade guides or automated migration tools will be offered to help users smoothly transition to the new version.

## Release Components

![](/img/docs/community/release-policy/kcl-components.png)

For each version release, all related components of KCL depend on the same major version of the KCL core. The dependencies are organized in a tree structure and released and regression tested in a specific order until the release testing is completed, with efforts made to avoid triangular dependencies and prohibit circular dependencies.

## Lifecycle of a Feature

- Design and Documentation: Clearly answer the motivations, problems to be solved, and goals of the feature through issues. Define user requirements and user stories. Specify what the feature does, how it is implemented, its difficulty level, estimated time, dependencies, and testing requirements. (Tips: Split large designs into smaller ones, find a simple and sustainable solution through trade-offs and extensive research, and ensure scalability to adapt to future business or technical changes. Finalize the design through continuous discussions and design reviews).
Expand Down
281 changes: 1 addition & 280 deletions docs/reference/lang/spec/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,286 +84,7 @@ Searching by location path should be supported by the kcl compiler, which needs

## Standard System Packages

KCL supports a few standard system modules. The following is the full list of these standard system modules:

<table>
<tr>
<td><b>Package</b></td>
<td><b>Member</b></td>
</tr>
<tr>
<td rowspan="4">datetime</td>
<td>today</td>
</tr>
<tr><td>now</td></tr>
<tr><td>ticks</td></tr>
<tr><td>date</td></tr>
<tr>
<td rowspan="16">math</td>
<td>ceil</td>
</tr>
<tr><td>exp</td></tr>
<tr><td>expm1</td></tr>
<tr><td>factorial</td></tr>
<tr><td>floor</td></tr>
<tr><td>gcd</td></tr>
<tr><td>isfinite</td></tr>
<tr><td>isinf</td></tr>
<tr><td>isnan</td></tr>
<tr><td>log</td></tr>
<tr><td>log1p</td></tr>
<tr><td>log2</td></tr>
<tr><td>log10</td></tr>
<tr><td>modf</td></tr>
<tr><td>pow</td></tr>
<tr><td>sqrt</td></tr>
<tr>
<td rowspan="6">regex</td>
<td>replace</td>
</tr>
<tr><td>match</td></tr>
<tr><td>compile</td></tr>
<tr><td>findall</td></tr>
<tr><td>search</td></tr>
<tr><td>split</td></tr>
<tr>
<td rowspan="27">units</td>
<td>n</td>
</tr>
<tr><td>u</td></tr>
<tr><td>m</td></tr>
<tr><td>k</td></tr>
<tr><td>K</td></tr>
<tr><td>M</td></tr>
<tr><td>G</td></tr>
<tr><td>T</td></tr>
<tr><td>P</td></tr>
<tr><td>Ki</td></tr>
<tr><td>Mi</td></tr>
<tr><td>Gi</td></tr>
<tr><td>Ti</td></tr>
<tr><td>Pi</td></tr>
<tr><td>to_n</td></tr>
<tr><td>to_u</td></tr>
<tr><td>to_m</td></tr>
<tr><td>to_K</td></tr>
<tr><td>to_M</td></tr>
<tr><td>to_G</td></tr>
<tr><td>to_T</td></tr>
<tr><td>to_P</td></tr>
<tr><td>to_Ki</td></tr>
<tr><td>to_Mi</td></tr>
<tr><td>to_Gi</td></tr>
<tr><td>to_Ti</td></tr>
<tr><td>to_Pi</td></tr>
<tr>
<td rowspan="3">json</td>
<td>encode</td>
</tr>
<tr><td>decode</td></tr>
<tr><td>dump_to_file</td></tr>
<tr>
<td rowspan="3">yaml</td>
<td>encode</td>
</tr>
<tr><td>decode</td></tr>
<tr><td>dump_to_file</td></tr>
<tr>
<td rowspan="16">net</td>
<td>split_host_port</td>
</tr>
<tr><td>join_host_port</td></tr>
<tr><td>fqdn</td></tr>
<tr><td>parse_IP</td></tr>
<tr><td>to_IP4</td></tr>
<tr><td>to_IP16</td></tr>
<tr><td>IP_string</td></tr>
<tr><td>is_IPv4</td></tr>
<tr><td>is_IP</td></tr>
<tr><td>is_loopback_IP</td></tr>
<tr><td>is_multicast_IP</td></tr>
<tr><td>is_interface_local_multicast_IP</td></tr>
<tr><td>is_link_local_multicast_IP</td></tr>
<tr><td>is_link_local_unicast_IP</td></tr>
<tr><td>is_global_unicast_IP</td></tr>
<tr><td>is_unspecified_IP</td></tr>
<tr>
<td rowspan="2">base64</td>
<td>encode</td>
</tr>
<tr><td>decode</td></tr>
<tr>
<td rowspan="6">crypto</td>
<td>md5</td>
</tr>
<tr><td>sha1</td></tr>
<tr><td>sha224</td></tr>
<tr><td>sha256</td></tr>
<tr><td>sha384</td></tr>
<tr><td>sha512</td></tr>
</table>

- datetime
- ticks() -> float
Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.
- date() -> str
return the `%Y-%m-%d %H:%M:%S` format date.
- now() -> str
return the local time. e.g. `'Sat Jun 06 16:26:11 1998'`
- today() -> str
return the `%Y-%m-%d %H:%M:%S.%{ticks}` format date.
- math
- ceil(x) -> int
Return the ceiling of x as an Integral. This is the smallest integer >= x.
- factorial(x) -> int
Return x!. Raise a error if x is negative or non-integral.
- floor(x) -> int
Return the floor of x as an Integral. This is the largest integer <= x.
- gcd(a: int, b: int) -> int
Return the greatest common divisor of x and y
- isfinite(x) -> bool
Return True if x is neither an infinity nor a NaN, and False otherwise.
- isinf(x) -> bool
Return True if x is a positive or negative infinity, and False otherwise.
- isnan(x) -> bool
Return True if x is a NaN (not a number), and False otherwise.
- modf(x) -> Listfloat, float]
Return the fractional and integer parts of x. Both results carry the sign of x and are floats.
- exp(x) -> float
Return e raised to the power of x.
- 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.
- log(x, base=2.71828182845904523536028747135266250) -> float
Return the logarithm of x to the base e.
- 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.
- log2(x) -> float
Return the base 2 logarithm of x.
- log10(x) -> float
Return the base 10 logarithm of x.
- pow(x, y) -> float
Return x\*\*y (x to the power of y).
- sqrt(x) -> float
Return the square root of x.
- regex
- replace(string: str, pattern: str, replace: str, count=0) -> str
Return the string obtained by replacing the leftmost non-overlapping occurrences of the pattern in string by the replacement.
- 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.
- compile(pattern: str) -> bool
Compile a regular expression pattern, returning a bool value denoting whether the pattern is valid.
- findall(string: str, pattern: str) -> List[str]
Return a list of all non-overlapping matches in the string.
- 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.
- split(string: str, pattern: str, maxsplit=0) -> List[str]
Scan through string looking for a match to the pattern, returning a Match object, or None if no match was found.
- units
- Unit constants
- Fixed point: `n`, `u`, `m`, `k`, `K`, `G`, `T` and `P`.
- Power of 2: `Ki`, `Mi`, `Gi`, `Ti` and `Pi`.
- Functions
- to_n(num: int) -> str
Int literal to string with `n` suffix
- to_u(num: int) -> str
Int literal to string with `u` suffix
- to_m(num: int) -> str
Int literal to string with `m` suffix
- to_K(num: int) -> str
Int literal to string with `K` suffix
- to_M(num: int) -> str
Int literal to string with `M` suffix
- to_G(num: int) -> str
Int literal to string with `G` suffix
- to_T(num: int) -> str
Int literal to string with `T` suffix
- to_P(num: int) -> str
Int literal to string with `P` suffix
- to_Ki(num: int) -> str
Int literal to string with `Ki` suffix
- to_Mi(num: int) -> str
Int literal to string with `Mi` suffix
- to_Gi(num: int) -> str
Int literal to string with `Gi` suffix
- to_Ti(num: int) -> str
Int literal to string with `Ti` suffix
- to_Pi(num: int) -> str
Int literal to string with `Pi` suffix
- json
- encode(data: any, sort_keys: bool = False, indent: int = None, ignore_private: bool = False, ignore_none: bool = False) -> str
Serialize a KCL object `data` to a JSON formatted str.
- decode(value: str) -> any
Deserialize `value` (a string instance containing a JSON document) to a KCL object.
- dump_to_file(data: any, filename: str, ignore_private: bool = False, ignore_none: bool = False) -> None
Serialize a KCL object `data` to a JSON formatted str and write it into the file `filename`.
- validate(data: any) -> bool
Validate whether the given string is a valid JSON.
- yaml
- encode(data: any, sort_keys: bool = False, ignore_private: bool = False, ignore_none: bool = False) -> str
Serialize a KCL object `data` to a YAML formatted str.
- encode_all(data: [any], sort_keys: bool = False, ignore_private: bool = False, ignore_none: bool = False) -> str
Serialize a sequence of KCL objects into a YAML stream str.
- decode(value: str) -> any
Deserialize `value` (a string instance containing a YAML document) to a KCL object.
- decode_all(value: str) -> [any]
- dump_to_file(data: any, filename: str, ignore_private: bool = False, ignore_none: bool = False) -> None
Serialize a KCL object `data` to a YAML formatted str and write it into the file `filename`.
Parse all YAML documents in a stream and produce corresponding KCL objects.
- validate(value: str) -> str
Validate whether the given string is a valid YAML or YAML stream document.
- net
- split_host_port(ip_end_point: str) -> List[str]
Split the 'host' and 'port' from the ip end point.
- join_host_port(host, port) -> str
Merge the 'host' and 'port'.
- fqdn(name: str = '') -> str
Return Fully Qualified Domain Name (FQDN).
- parse_IP(ip) -> str
Parse 'ip' to a real IP address
- to_IP4(ip) -> str
Get the IP4 form of 'ip'.
- to_IP16(ip) -> int
Get the IP16 form of 'ip'.
- IP_string(ip: str | int) -> str
Get the IP string.
- is_IPv4(ip: str) -> bool
Whether 'ip' is a IPv4 one.
- is_IP(ip: str) -> bool
Whether ip is a valid ip address.
- is_loopback_IP(ip: str) -> bool
Whether 'ip' is a loopback one.
- is_multicast_IP(ip: str) -> bool
Whether 'ip' is a multicast one.
- is_interface_local_multicast_IP(ip: str) -> bool
Whether 'ip' is a interface, local and multicast one.
- is_link_local_multicast_IP(ip: str) -> bool
Whether 'ip' is a link local and multicast one.
- is_link_local_unicast_IP(ip: str) -> bool
Whether 'ip' is a link local and unicast one.
- is_global_unicast_IP(ip: str) -> bool
Whether 'ip' is a global and unicast one.
- is_unspecified_IP(ip: str) -> bool
Whether 'ip' is a unspecified one.
- base64
- encode(value: str, encoding: str = "utf-8") -> str
Encode the string `value` using the codec registered for encoding.
- decode(value: str, encoding: str = "utf-8") -> str
Decode the string `value` using the codec registered for encoding.
- crypto
- md5(value: str, encoding: str = "utf-8") -> str
Encrypt the string `value` using `MD5` and the codec registered for encoding.
- sha1(value: str, encoding: str = "utf-8") -> str
Encrypt the string `value` using `SHA1` and the codec registered for encoding.
- sha224(value: str, encoding: str = "utf-8") -> str
Encrypt the string `value` using `SHA224` and the codec registered for encoding.
- sha256(value: str, encoding: str = "utf-8") -> str
Encrypt the string `value` using `SHA256` and the codec registered for encoding.
- sha384(value: str, encoding: str = "utf-8") -> str
Encrypt the string `value` using `SHA384` and the codec registered for encoding.
- sha512(value: str, encoding: str = "utf-8") -> str
Encrypt the string `value` using `SHA512` and the codec registered for encoding.
- manifests
- `yaml_stream(values: [any], opts: {str:} = {sort_keys = False, ignore_private = True, ignore_none = False, sep = "---"}`. This function is used to serialize the KCL object list into YAML output with the `---` separator
KCL supports a few standard system modules. [Here](docs/reference/model/overview) is the full list of these standard system modules.

### The Built-in System Package

Expand Down
Loading
Loading