Stdlib documentation

src/std/array.ab

@@ -1,3 +1,4 @@
+/// Get the index of the first value found in the array specified
 pub fun array_first_index(array, value): Num {
     loop index, element in array {
         if value as Text == element as Text {
@@ -7,6 +8,7 @@ pub fun array_first_index(array, value): Num {
     return -1
 }
 
+/// Get the total of the values found in the array
 pub fun array_search(array, value): [Num] {
     let result = [Num]
     loop index, element in array {
@@ -17,11 +19,13 @@ pub fun array_search(array, value): [Num] {
     return result
 }
 
+/// Check if the value is in the array
 pub fun in_array(array, value): Bool {
     let result = array_first_index(array, value)
     return result >= 0
 }
 
+/// Check if the value is in the array
 pub fun includes(arr, value) {
     loop v in arr {
         if v == value {

src/std/env.ab

@@ -1,6 +1,7 @@
 import * from "std/fs"
 import * from "std/text"
 
+/// Get the variable from the environment, otherwise check from the input file
 pub fun get_env_var(var: Text, file: Text = ".env"): Text {
     let _var = unsafe $echo "\$\{!var}"$
     if _var != "" {
@@ -15,59 +16,71 @@ pub fun get_env_var(var: Text, file: Text = ".env"): Text {
     return ""
 }
 
+/// Load the env file in the environment
 pub fun load_env_file(file: Text = ".env"): Null {
     unsafe $export "\$(xargs < {file})" > /dev/null$
 }
 
+/// ?
 pub fun shell_isset(name: Text): Bool {
     $[[ ! -z \$\{!{nameof name}+z} ]]$ failed {
         return false
     }
     return true
 }
 
+/// Set a constant
 pub fun shell_constant_set(name: Text, val: Text): Null {
     $readonly \${nameof name}="\${nameof val}" 2> /dev/null$?
 }
 
+/// Get a constant
 pub fun shell_constant_get(name: Text): Text {
     return $echo \$\{!{nameof name}}$?
 }
 
+/// Set a variable?
 pub fun shell_var_set(name: Text, val: Text): Null {
     $export \${nameof name}="\${nameof val}" 2> /dev/null$?
 }
 
+/// Get a variable?
 pub fun shell_var_get(name: Text): Text {
     return $echo \$\{!{nameof name}}$?
 }
 
+/// Remove a variable?
 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$
     return "\$REPLY"
 }
 
+/// Check if the command passed fails
 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
@@ -76,52 +89,59 @@ pub fun is_root(): Bool {
     return false
 }
 
+/// ?
 pub fun printf(format: Text, args: [Text] = [""]): Null {
     unsafe ${nameof args}=("{format}" "\$\{{nameof args}[@]}")$
     unsafe $printf "\$\{{nameof args}[@]}"$
 }
 
+/// ?
 pub fun printf_escape(text: Text): Text {
     return unsafe $echo \${nameof text} | sed -e 's/\\\\/\\\\\\\\/g' -e "s/%/%%/g"$
 }
 
+/// Print a string with formatting options
 pub fun text_shell(message: Text, style: Num, fg: Num, bg: Num): Text {
     return "\x1b[{style};{fg};{bg}m{printf_escape(message)}\x1b[0m"
 }
 
+/// Print a string as bold
 pub fun text_bold(message: Text): Text {
     return "\x1b[1m{printf_escape(message)}\x1b[0m"
 }
 
+/// Print a string as italic
 pub fun text_italic(message: Text): Text {
     return "\x1b[3m{printf_escape(message)}\x1b[0m"
 }
 
+/// Print a string as underlined
 pub fun text_underlined(message: Text): Text {
     return "\x1b[4m{printf_escape(message)}\x1b[0m"
 }
 
+/// Print a string 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 string as Info
 pub fun echo_info(message: Text): Null {
     printf("\x1b[1;3;97;44m %s \x1b[0m\n", [message])
 }
 
+/// Print a string as Success
 pub fun echo_success(message: Text): Null {
     printf("\x1b[1;3;97;42m %s \x1b[0m\n", [message])
 }
 
+/// Print a string as Warning
 pub fun echo_warning(message: Text): Null {
     printf("\x1b[1;3;97;43m %s \x1b[0m\n", [message])
 }
 
+/// Print a string as Error
 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)
 }
-
-
-
-

src/std/fs.ab

@@ -1,55 +1,66 @@
+import * from "std/env"
+
+/// 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}"$
         return true
     }
 
-    echo "The file {origin} doesn't exist!"
+    error("The file {origin} doesn't exist!")
     return false
 }
 
+/// Create a directory with the full path
 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}"$
         return true
     }
 
-    echo "The file {path} doesn't exist!"
+    error("The file {path} doesn't exist!")
     return false
 }
 
+/// Change the owner of the file, if the file doesn't exist return a boolean
 pub fun change_owner(user: Text, path: Text): Bool {
     if file_exist(path) or dir_exist(path) {
         unsafe $chown -R "{user}" "{path}"$

src/std/http.ab

@@ -1,5 +1,6 @@
 import * from "std/env"
 
+/// It will download the file using (if present) in the order: `curl`, `wget`, `aria2c`
 pub fun download(url: Text, path: Text): Bool {
     if {
         is_command("curl") {

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

src/std/text.ab

@@ -1,62 +1,73 @@
+/// Replace the content just once
 pub fun replace_once(source, pattern, replacement) {
     return unsafe $echo "\$\{source/{pattern}/{replacement}}"$
 }
 
+// Replace the content multiple times
 pub fun replace(source, pattern, replacement) {
     return unsafe $echo "\$\{source//{pattern}/{replacement}}"$
 }
 
+/// Replace with regex using `sed`
 pub fun replace_regex(source: Text, pattern: Text, replacement: Text): Text {
     return unsafe $echo "{source}" | sed -e "s/{pattern}/{replacement}/g"$
 }
 
-
+/// Split the string and return an array
 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
 }
 
+/// Split a string with newlines
 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")
 }
 
+/// Split by space separator
 pub fun words(text: Text): [Text] {
   return split(text, " ")
 }
 
+/// Merge a string using the delimeter
 pub fun join(list: [Text], delimiter: Text): Text {
     return unsafe $IFS="{delimiter}" ; echo "\$\{{nameof list}[*]}"$
 }
 
+/// Trim the spaces at top of the string using `sed`
 pub fun trim_left(text: Text): Text {
     return unsafe $echo "{text}" | sed -e 's/^[[:space:]]*//'$
 }
 
+/// Trim the spaces at end of the string using `sed`
 pub fun trim_right(text: Text): Text {
     return unsafe $echo "{text}" | sed -e 's/[[:space:]]*\$//'$
 }
 
+/// Trim the spaces from the string input
 pub fun trim(text: Text): Text {
     return trim_left(trim_right(text))
 }
 
+/// Lowercase the string input using `tr`
 pub fun lower(text: Text): Text {
     return unsafe $echo "{text}" | tr '[:upper:]' '[:lower:]'$
 }
 
+/// Lowercase the string input using `tr`
 pub fun upper(text: Text): Text {
     return unsafe $echo "{text}" | tr '[:lower:]' '[:upper:]'$
 }
 
+/// ?
 #[allow_absurd_cast]
 pub fun parse(text: Text): Num {
     $[ -n "{text}" ] && [ "{text}" -eq "{text}" ] 2>/dev/null$?
     return text as Num
 }
 
+/// ?
 pub fun chars(text: Text): [Text] {
     let chars = [Text]
     unsafe $for ((i=0; i<\$\{#{nameof text}}; i++)); do
@@ -65,6 +76,7 @@ pub fun chars(text: Text): [Text] {
     return chars
 }
 
+/// Get the string length
 #[allow_absurd_cast]
 pub fun len(value): Num {
     unsafe {
@@ -75,6 +87,7 @@ pub fun len(value): Num {
     }
 }
 
+/// Check if string contain the value
 pub fun contains(text: Text, phrase: Text): Bool {
   let result = unsafe $if [[ "{text}" == *"{phrase}"* ]]; then
     echo 1