Stdlib documentation (#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]>
amber-lang · 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