Stdlib documentation (amber-lang#339)

* feat(doc): stdlib first incomplete version * feat(doc): stdlib first incomplete version * feat(review): by @CymDeveloppement * feat(review): by @CymDeveloppement * Update src/std/array.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/text.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/text.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/text.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/env.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/env.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/fs.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/fs.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/http.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/text.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/text.ab Co-authored-by: Hubert Jabłoński <[email protected]> * Update src/std/text.ab Co-authored-by: Hubert Jabłoński <[email protected]> * feat(review): by @KrosFire * feat(review): by @KrosFire * feat(review): text and remove in_array * feat(review): by @CymDeveloppement * fix(std): remove dependence so we can merge the documentation in the meantime * fix(test): wip * fix(test): wip * fix(test): wip * fix(test): wip * fix(test): wip * Update text.ab --------- Co-authored-by: Hubert Jabłoński <[email protected]>
Mte90 · Sep 3, 2024 · abfb15f · abfb15f
1 parent addffab
commit abfb15f
Show file tree

Hide file tree

Showing 7 changed files with 69 additions and 28 deletions.
diff --git a/src/std/array.ab b/src/std/array.ab
@@ -1,3 +1,5 @@
+/// Returns index of the first value found in the specified array
+/// If the value is not found, the function returns -1
 pub fun array_first_index(array, value): Num {
     loop index, element in array {
         if value as Text == element as Text {
@@ -7,6 +9,7 @@ pub fun array_first_index(array, value): Num {
     return -1
 }
 
+/// Search the value in array and return an array with the index of the various items
 pub fun array_search(array, value): [Num] {
     let result = [Num]
     loop index, element in array {
@@ -17,16 +20,8 @@ pub fun array_search(array, value): [Num] {
     return result
 }
 
-pub fun in_array(array, value): Bool {
+/// Check if the value is in the array
+pub fun includes(array, value) {
     let result = array_first_index(array, value)
     return result >= 0
 }
-
-pub fun includes(arr, value) {
-    loop v in arr {
-        if v == value {
-            return true
-        }
-    }
-    return false
-}
diff --git a/src/std/env.ab b/src/std/env.ab
@@ -1,58 +1,68 @@
 import * from "std/fs"
 import * from "std/text"
 
+/// Retrieves the value of an environment variable, optionally sourcing it from a file if not already set.
 pub fun get_env_var(var: Text, file: Text = ".env"): Text {
     let _var = unsafe $echo "\$\{!var}"$
     if _var != "" {
         return _var
     }
 
-    if file_exist(".env") {
+    if file_exist(file) {
         unsafe $source "{file}"$
         return unsafe $echo "\$\{!var}"$
     }
 
     return ""
 }
 
+/// Load the env file in the environment, using `xargs`
 pub fun load_env_file(file: Text = ".env"): Null {
     unsafe $export "\$(xargs < {file})" > /dev/null$
 }
 
+/// Check if a variable inside the Shell session exist
 pub fun shell_isset(name: Text): Bool {
     $[[ ! -z \$\{!{nameof name}+z} ]]$ failed {
         return false
     }
     return true
 }
 
+/// Set a constant inside the Shell session
 pub fun shell_constant_set(name: Text, val: Text): Null? {
     $readonly \${nameof name}="\${nameof val}" 2> /dev/null$?
 }
 
+/// Get a constant inside the Shell session
 pub fun shell_constant_get(name: Text): Text? {
     return $echo \$\{!{nameof name}}$?
 }
 
+/// Set a constant inside the Shell session
 pub fun shell_var_set(name: Text, val: Text): Null? {
     $export \${nameof name}="\${nameof val}" 2> /dev/null$?
 }
 
+/// Get a constant inside the Shell session
 pub fun shell_var_get(name: Text): Text? {
     return $echo \$\{!{nameof name}}$?
 }
 
+/// Remove a variable inside the Shell session
 pub fun shell_unset(name: Text): Null? {
     $unset {name}$?
 }
 
+/// Check if the command exist
 pub fun is_command(command: Text): Bool {
     $[ -x "\$(command -v {command})" ]$ failed {
         return false
     }
     return true
 }
 
+/// Create a prompt and return the value
 pub fun input(prompt: Text): Text {
     unsafe $printf "\${nameof prompt}"$
     unsafe $read$
@@ -72,15 +82,18 @@ pub fun confirm(prompt: Text, default_yes: Bool = false): Bool {
     return result == "y" or (result == "" and default_yes)
 }
 
+/// Checks if the command has failed
 pub fun has_failed(command: Text): Bool {
     unsafe silent $eval {command}$
     return status != 0
 }
 
+/// Close the script
 pub fun exit(code: Num): Null {
     unsafe $exit "{code}"$
 }
 
+/// Check if the script is running with a user with root permission
 pub fun is_root(): Bool {
     if unsafe $id -u$ == "0" {
         return true
@@ -89,52 +102,59 @@ pub fun is_root(): Bool {
     return false
 }
 
+/// `printf` the text following the arguments
 pub fun printf(format: Text, args: [Text] = [""]): Null {
     unsafe ${nameof args}=("{format}" "\$\{{nameof args}[@]}")$
     unsafe $printf "\$\{{nameof args}[@]}"$
 }
 
+/// Escape the text to be used with `printf`
 pub fun printf_escape(text: Text): Text {
     return unsafe $echo \${nameof text} | sed -e 's/\\\\/\\\\\\\\/g' -e "s/%/%%/g"$
 }
 
+/// Prepare a text with formatting options for `printf`
 pub fun text_shell(message: Text, style: Num, fg: Num, bg: Num): Text {
     return "\x1b[{style};{fg};{bg}m{printf_escape(message)}\x1b[0m"
 }
 
+/// Return a text as bold
 pub fun text_bold(message: Text): Text {
     return "\x1b[1m{printf_escape(message)}\x1b[0m"
 }
 
+/// Return a text as italic
 pub fun text_italic(message: Text): Text {
     return "\x1b[3m{printf_escape(message)}\x1b[0m"
 }
 
+/// Return a text as underlined
 pub fun text_underlined(message: Text): Text {
     return "\x1b[4m{printf_escape(message)}\x1b[0m"
 }
 
+/// Print a text with a specified color
 pub fun color_echo(message: Text, color: Num): Null {
     printf("\x1b[{color as Text}m%s\x1b[0m\n", [message])
 }
 
+/// Print a text as Info
 pub fun echo_info(message: Text): Null {
     printf("\x1b[1;3;97;44m %s \x1b[0m\n", [message])
 }
 
+/// Print a text as Success
 pub fun echo_success(message: Text): Null {
     printf("\x1b[1;3;97;42m %s \x1b[0m\n", [message])
 }
 
+/// Print a text as Warning
 pub fun echo_warning(message: Text): Null {
     printf("\x1b[1;3;97;43m %s \x1b[0m\n", [message])
 }
 
+/// Print a text as Error and exit if the status code is greater than 0
 pub fun error(message: Text, exit_code: Num = 1): Null {
     printf("\x1b[1;3;97;41m %s \x1b[0m\n", [message])
     if exit_code > 0 : exit(exit_code)
 }
-
-
-
-
diff --git a/src/std/fs.ab b/src/std/fs.ab
@@ -1,29 +1,38 @@
+/// Check if directory exists
 pub fun dir_exist(path) {
     $[ -d "{path}" ]$ failed {
         return false
     }
     return true
 }
 
+/// Check if file exists
 pub fun file_exist(path) {
     $[ -f "{path}" ]$ failed {
         return false
     }
     return true
 }
 
+/// Get the file content
 pub fun file_read(path) {
     return $< "{path}"$?
 }
 
+/// Write the content to the file
+/// Doesn't check if the file exist
 pub fun file_write(path, content) {
     return $echo "{content}" > "{path}"$?
 }
 
+/// Append the content to the file
+/// Doesn't check if the file exist
 pub fun file_append(path, content) {
     return $echo "{content}" >> "{path}"$?
 }
 
+/// Create a symbolic link
+/// If the file doens't exist return a boolean and print a message
 pub fun create_symbolic_link(origin: Text, destination: Text): Bool {
     if file_exist(origin) {
         unsafe $ln -s "{origin}" "{destination}"$
@@ -34,12 +43,15 @@ pub fun create_symbolic_link(origin: Text, destination: Text): Bool {
     return false
 }
 
+/// Create a directory with all intermediate directories as required
 pub fun create_dir(path: Text): Null {
     if not dir_exist(path) {
         unsafe $mkdir -p "{path}"$
     }
 }
 
+/// Set the file as executable
+/// If the file doesn't exist return a boolean and print a message
 pub fun make_executable(path: Text): Bool {
     if file_exist(path) {
         unsafe $chmod +x "{path}"$
@@ -50,6 +62,8 @@ pub fun make_executable(path: Text): Bool {
     return false
 }
 
+/// Change the owner of the file
+/// If the file doesn't exist return false
 pub fun change_owner(user: Text, path: Text): Bool {
     if file_exist(path) or dir_exist(path) {
         unsafe $chown -R "{user}" "{path}"$

diff --git a/src/std/http.ab b/src/std/http.ab
@@ -1,5 +1,10 @@
 import * from "std/env"
 
+/// Downloads a file from a given URL and saves it to a specified path using available command-line tools.
+///
+/// This function attempts to download a file from the provided URL and save it to the specified path.
+/// It checks for the availability of common command-line tools (`curl`, `wget`, and `aria2c`) and uses the first available tool to perform the download.
+/// If none of the tools are available, the function returns `false`.
 pub fun download(url: Text, path: Text): Bool {
     if {
         is_command("curl") {

diff --git a/src/std/math.ab b/src/std/math.ab
@@ -1,3 +1,4 @@
+/// Sum the array content
 #[allow_absurd_cast]
 pub fun sum(list: [Num]): Num {
     return unsafe $echo "{list}" | awk '\{s=0; for (i=1; i<=NF; i++) s+=\$i; print s}'$ as Num

diff --git a/src/std/text.ab b/src/std/text.ab
@@ -1,62 +1,75 @@
+/// Finds the first occurrence of a pettern in the content and replaces it with provided replacement text
 pub fun replace_once(source, pattern, replacement) {
     return "\$\{source/{pattern}/{replacement}}"
 }
 
+/// Replaces all occurences of a pattern in the content with provided replacement text
 pub fun replace(source, pattern, replacement) {
     return "\$\{source//{pattern}/{replacement}}"
 }
 
+/// Replaces all occurences of a regex pattern in the content with provided replacement text
+///
+/// Function uses `sed`
 pub fun replace_regex(source: Text, pattern: Text, replacement: Text): Text {
     return unsafe $echo "{source}" | sed -e "s/{pattern}/{replacement}/g"$
 }
 
-
+/// This function splits the input `text` into an array of substrings using the specified `delimiter`. 
 pub fun split(text: Text, delimiter: Text): [Text] {
     let result = [Text]
     unsafe $IFS="{delimiter}" read -rd '' -a {nameof result} < <(printf %s "\${nameof text}")$
     return result
 }
 
+/// Splits a `text` into an array of substrings based on newline characters.
 pub fun lines(text: Text): [Text] {
-    let result = [Text]
-    unsafe $IFS=\$'\n' read -rd '' -a {nameof result} <<<"\${nameof text}"$
-    return result
+    return split(text, "\n")
 }
 
+/// Splits a `text` into an array of substrings based on space character.
 pub fun words(text: Text): [Text] {
   return split(text, " ")
 }
 
+/// Merge a text using the delimeter specified
 pub fun join(list: [Text], delimiter: Text): Text {
     return unsafe $IFS="{delimiter}" ; echo "\$\{{nameof list}[*]}"$
 }
 
+/// Trim the spaces at top of the text using `sed`
 pub fun trim_left(text: Text): Text {
     return unsafe $echo "{text}" | sed -e 's/^[[:space:]]*//'$
 }
 
+/// Trim the spaces at end of the text using `sed`
 pub fun trim_right(text: Text): Text {
     return unsafe $echo "{text}" | sed -e 's/[[:space:]]*\$//'$
 }
 
+/// Trim the spaces from the text input
 pub fun trim(text: Text): Text {
     return trim_left(trim_right(text))
 }
 
+/// Lowercase the text input using `tr`
 pub fun lower(text: Text): Text {
     return unsafe $echo "{text}" | tr '[:upper:]' '[:lower:]'$
 }
 
+/// Lowercase the text input using `tr`
 pub fun upper(text: Text): Text {
     return unsafe $echo "{text}" | tr '[:lower:]' '[:upper:]'$
 }
 
+/// Attempts to parse a given text into a number, returning the parsed number or zero if parsing fails.
 #[allow_absurd_cast]
 pub fun parse(text: Text): Num? {
     $[ -n "{text}" ] && [ "{text}" -eq "{text}" ] 2>/dev/null$?
     return text as Num
 }
 
+/// Splits a text into an array of individual characters.
 pub fun chars(text: Text): [Text] {
     let chars = [Text]
     unsafe $for ((i=0; i<\$\{#{nameof text}}; i++)); do
@@ -65,6 +78,7 @@ pub fun chars(text: Text): [Text] {
     return chars
 }
 
+/// Get the text or array length
 #[allow_absurd_cast]
 pub fun len(value): Num {
     unsafe {
@@ -75,6 +89,7 @@ pub fun len(value): Num {
     }
 }
 
+/// Check if text contain the value
 pub fun contains(text: Text, phrase: Text): Bool {
   let result = unsafe $if [[ "{text}" == *"{phrase}"* ]]; then
     echo 1

diff --git a/src/tests/stdlib/in_array.ab b/src/tests/stdlib/in_array.ab