Added stdlib documentation and updated builtins

README.md

@@ -21,6 +21,8 @@ Happy scripting with Amber!
 ```sh
 # Install dependencies
 npm install
+# Generate the stdlib documentation
+./sync-stdlib-doc.ab
 # Start the development server
 npm run dev
 ```

docs/advanced_syntax/builtins.md

@@ -0,0 +1,50 @@
+# Builtins
+
+Builtins are native methods (built in the compiler itself) and they are also reserved keywords in Amber.  
+
+Similar to the standard library, they generate valid [Shellcheck](https://www.shellcheck.net/) code (though full support for this in Amber is still in progress).
+
+## Cd
+
+Transpile to `cd` which changes the current directory, requires a `Text` parameter.
+
+```ab
+cd "/tmp"
+```
+
+## Echo
+
+Transpile to `echo` which print text to the console, requires a `Text` parameter.
+
+```ab
+echo "Hello World!"
+```
+
+## Mv
+
+If you need to move files you can use the `mv` builtin, requires two `Text` parameters.
+
+```ab
+mv "/tmp/a" "/tmp/b"
+```
+
+This builtin is `failable`, meaning you can handle errors like this:
+```ab
+mv "/tmp/a" "/tmp/b" failed {
+    echo "Error"
+}
+```
+
+## Nameof
+
+For more advanced commands, you might need the name of the variable in the compiled script. The `nameof` keyword provides this functionality.  
+
+For example, this allows you to perform operations like:
+
+```ab
+let variable = null
+
+unsafe ${nameof variable}=12$
+// Which is the same as:
+let variable = 12
+```

docs/index.json

@@ -65,8 +65,8 @@
                     "title": "As Cast"
                 },
                 {
-                    "path": "advanced_syntax/nameof",
-                    "title": "Nameof"
+                    "path": "advanced_syntax/builtins",
+                    "title": "Builtins"
                 },
                 {
                     "path": "advanced_syntax/type_condition",
@@ -78,6 +78,44 @@
                 }
             ]
         },
+        {
+            "path": "stdlib/doc",
+            "title": "Standard Library",
+            "docs": [
+                {
+                    "path": "stdlib/doc",
+                    "title": "Documentation"
+                },
+                {
+                    "path": "stdlib/doc/array",
+                    "title": "Array"
+                },
+                {
+                    "path": "stdlib/doc/date",
+                    "title": "Date"
+                },
+                {
+                    "path": "stdlib/doc/env",
+                    "title": "Environment"
+                },
+                {
+                    "path": "stdlib/doc/fs",
+                    "title": "FileSystem"
+                },
+                {
+                    "path": "stdlib/doc/http",
+                    "title": "HTTP"
+                },
+                {
+                    "path": "stdlib/doc/math",
+                    "title": "Math"
+                },
+                {
+                    "path": "stdlib/doc/text",
+                    "title": "Text"
+                }
+            ]
+        },
         {
             "path": "by_example/examples",
             "title": "Amber by Example",

docs/stdlib/doc.md

@@ -0,0 +1,45 @@
+## Builtin VS StdLib
+
+[Builtins](/advanced_syntax/builtins) are method that are included in the Amber compiler and don't need to be imported in the code.
+
+In contrast, the standard library (stdlib) is a collection of Amber functions that are embedded in every Amber release. Each version of Amber may include changes to the standard library and you need to import these functions in your code. These functions are more advanced and can accept various parameters.
+
+## Standard library and Shellcheck
+Just like the Amber's compiled Bash output, all standard library functions are built from the ground up to be shellcheck compliant. This means that you can focus more on building the logic and spend less time on keeping the code predictable and valid.
+
+## How to use it
+
+Below is an example of how to use the standard library to generate documentation (using the [script](https://github.com/amber-lang/amber-docs/sync-stdlib-doc.ab) provided on the Amber Documentation repository):
+
+```ab
+import { download } from "std/http"
+import { split, contains } from "std/text"
+import { file_exist } from "std/fs"
+
+unsafe $rm -fr /tmp/amber-git$
+if silent download("https://github.com/amber-lang/amber/archive/refs/heads/master.zip", "/tmp/amber-git.zip") {
+    unsafe $unzip "/tmp/amber-git.zip" -d /tmp/amber-git$
+
+    let std = unsafe $/usr/bin/ls "/tmp/amber-git/amber-master/src/std/"$
+    let stdlib = split(std, "\n")
+
+    loop v in stdlib {
+        if (contains(v, ".ab") and file_exist("/tmp/amber-git/amber-master/src/std/{v}")) {
+            unsafe $amber --docs "/tmp/amber-git/amber-master/src/std/{v}" "./docs/stdlib/doc"$
+            echo "\n"
+        }
+    }
+}
+```
+
+> WARNING: Each Amber release may have a different version of the standard library, so make sure to verify compatibility with the specific release you are using.
+
+### Importing a library
+
+You can also import all functions from a module by using the following syntax:
+
+```ab
+import { * } from "std/http"
+```
+
+However, only the functions that are used in the script will be included in the generated Bash code, ensuring efficiency.

docs/stdlib/doc/array.md

@@ -0,0 +1,26 @@
+## `array_first_index`
+```ab
+pub fun array_first_index(array, value): Num 
+```
+
+Returns index of the first value found in the specified array.
+
+If the value is not found, the function returns -1.
+
+
+## `array_search`
+```ab
+pub fun array_search(array, value): [Num] 
+```
+
+Searches for a value in an array and returns an array with the index of the various items.
+
+
+## `includes`
+```ab
+pub fun includes(array, value) 
+```
+
+Checks if a value is in the array.
+
+

docs/stdlib/doc/date.md

@@ -0,0 +1,125 @@
+## `date_add`
+```ab
+pub fun date_add(add: Text, date: Text = "", utc: Bool = false): Text ? 
+```
+
+### EXPERIMENTAL
+
+Adds a value to a date.
+
+If no date is specified, the current date is used.
+
+Example : `date_add("+3 days")`
+
+You can use (+/-):
+
+- years
+- months
+- days
+- hours
+- minutes
+- seconds
+
+
+## `date_compare`
+```ab
+pub fun date_compare(date_a: Text, date_b: Text = "", utc: Bool = false): Num ? 
+```
+
+### EXPERIMENTAL
+Compares two dates.
+
+Returns 1 if date_a is after date_b.
+
+Returns 0 if date_a and date_b is the same.
+
+Returns -1 if date_b is after date_a.
+
+If date_b is not provided, current date will be used.
+
+
+## `date_posix`
+```ab
+pub fun date_posix(format: Text = "", date: Text = "", utc: Bool = false): Text ? 
+```
+
+### EXPERIMENTAL
+
+Formats a date with a special format.
+
+If no date is specified, the current date is used.
+
+If no format is specified, "%FT%T%Z" format is used.
+
+For more info about format type "man date" on your shell or go to <https://www.gnu.org/software/coreutils/date>.
+
+Format :
+```
+%%     a literal %
+%a     locale's abbreviated weekday name (e.g., Sun)
+%A     locale's full weekday name (e.g., Sunday)
+%b     locale's abbreviated month name (e.g., Jan)
+%B     locale's full month name (e.g., January)
+%c     locale's date and time (e.g., Thu Mar  3 23:05:25 2005)
+%C     century; like %Y, except omit last two digits (e.g., 20)
+%d     day of month (e.g., 01)
+%D     date; same as %m/%d/%y
+%e     day of month, space padded; same as %_d
+%F     full date; like %+4Y-%m-%d
+%g     last two digits of year of ISO week number (see %G)
+%G     year of ISO week number (see %V); normally useful only with %V
+%h     same as %b
+%H     hour (00..23)
+%I     hour (01..12)
+%j     day of year (001..366)
+%k     hour, space padded ( 0..23); same as %_H
+%l     hour, space padded ( 1..12); same as %_I
+%m     month (01..12)
+%M     minute (00..59)
+%n     a newline
+%N     nanoseconds (000000000..999999999)
+%p     locale's equivalent of either AM or PM; blank if not known
+%P     like %p, but lower case
+%q     quarter of year (1..4)
+%r     locale's 12-hour clock time (e.g., 11:11:04 PM)
+%R     24-hour hour and minute; same as %H:%M
+%s     seconds since the Epoch (1970-01-01 00:00 UTC)
+%S     second (00..60)
+%t     a tab
+%T     time; same as %H:%M:%S
+%u     day of week (1..7); 1 is Monday
+%U     week number of year, with Sunday as first day of week (00..53)
+%V     ISO week number, with Monday as first day of week (01..53)
+%w     day of week (0..6); 0 is Sunday
+%W     week number of year, with Monday as first day of week (00..53)
+%x     locale's date representation (e.g., 12/31/99)
+%X     locale's time representation (e.g., 23:13:48)
+%y     last two digits of year (00..99)
+%Y     year
+%z     +hhmm numeric time zone (e.g., -0400)
+%:z    +hh:mm numeric time zone (e.g., -04:00)
+%::z   +hh:mm:ss numeric time zone (e.g., -04:00:00)
+%:::z  numeric time zone with : to necessary precision (e.g., -04, +05:30)
+%Z     alphabetic time zone abbreviation (e.g., EDT)
+```
+
+By default, date pads numeric fields with zeroes.  The following optional flags may follow '%':
+
+```
+-      (hyphen) do not pad the field
+_      (underscore) pad with spaces
+0      (zero) pad with zeros
++      pad with zeros, and put '+' before future years with >4 digits
+^      use upper case if possible
+#      use opposite case if possible
+```
+
+
+## `now`
+```ab
+pub fun now(): Num 
+```
+
+Returns the current timestamp (seconds since the Epoch (1970-01-01 00:00 UTC)).
+
+