# Standard Library Cosmo comes with a standard library which is broken into separate modules where each can be selectively loaded using the C API. ## Base Library Includes misc. functions. The "junk drawer" of the standard library. Without these functions however, Cosmo would be severely limited in functionality. | Name | Type | Behavior | Example | | ------------ | ------------------------------------------------ | ----------------------------------------------------------- | ---------------- | | print | `(...)` | Writes primitives to stdout, if a `` is passed, tostring() is invoked before outputting | `print("Hello world!")` | | type | `()` -> `` | Returns the passed arguments datatype as a string | `type(1)` -> `""` | | tonumber | `()` -> `` | Converts the datatype to a ``, if a `` is passed `__tonumber` metamethod is invoked | `tonumber("12")` -> `12` | | tostring | `()` -> `` | Converts the datatype to a ``, if a `` is passed `__tostring` metamethod is invoked | `tostring(12)` -> `"12"` | | error | `()` | Throws an error with the passed `` | `error("error!")` | | pcall | `()` -> `, or ` | Tries a protected call on the passed function, if an error is thrown, `` will be false and the 2nd result will be the error message | `pcall(error("Hello world!"))` -> `false, "Hello world!"` | | assert | `(, )` | If the passed `` is false, an error is thrown, optionally uses custom error message | `assert(1 == 1, "Error Message!")` | | loadstring | `()` -> `, or ` | If the `` compiled successfully, 1st result will be true and the 2nd result will be the newly compiled function. If there was a compiler/lexer error, the 1st result will be false and the 2nd result will be the error | `loadstring("print(\"hi\")")()` | > -> means 'returns' ## String Library Includes functions and methods to manipulate strings. When this library is loaded all objects have their proto's set to the string.* object. Enabling you to invoke the API directly on objects without using `string.*`, eg. `"Hello":len()` is the same as `string.len("Hello")`. | Name | Type | Behavior | Example | | ------------ | ------------------------------------------------ | ----------------------------------------------------------- | ---------------- | | string.len | `()` -> `` | Returns the length of the passed string | `"hi":len()` -> `2` | | string.sub | `(str, start[, length])` -> `` | Makes a substring of `str` starting at `start` with length of `length or str:len() - start` | `"Hello World":sub(6)` -> `"World"` | | string.find | `(str, find[, start])` -> `index` | Searches for first occurrence of `find` in `str` starting at `start or 0`. Returns index or -1 if failed | `"Hello world":find("wo")` -> `6` | | string.split | `(str, splitter)` -> `[, ...]` | Splits `str` into substrings using `splitter` as the splitter. Returns an array (table) starting at 0 of the strings. | `"Hello world":split(" ")` -> `["Hello", "world"]` | | string.byte | `(str)` -> `` | Returns the byte of the first character in the string. | `"A":byte()` -> `65` | | string.char | `(byte)` -> `` | Returns a 1 character string of the byte passed. | `string.char(65)` -> `"A"` | | string.rep | `(str, times)` -> `` | Repeats the string and returns the newly allocated string | `("A" .. "B"):rep(2)` -> "ABAB" | > -> means 'returns' ## Math Library Includes functions to do some common algebraic operations. | Name | Type | Behavior | Example | | ------------ | ------------------------------------------------ | --------------------------------------------------- | ------------------------ | | math.abs | `(X)` -> `` | Returns the absolute value of X | `math.abs(-2)` -> `2` | | math.floor | `(X)` -> `` | Rounds down to the nearest integer | `math.floor(5.3)` -> `5` | | math.ceil | `(X)` -> `` | Rounds up to the nearest integer | `math.ceil(5.3)` -> `6` | | math.rad | `(Deg)` -> `` | Converts degrees to radians | `math.rad(180)` -> `3.14159` | | math.deg | `(Rad)` -> `` | Converts radians to degrees | `math.deg(3.14159)` -> `180` | | math.sin | `(Rad)` -> `` | Returns the sine of radian `Rad` | `math.sin(math.rad(90))` -> `1` | | math.cos | `(Rad)` -> `` | Returns the cosine of radian `Rad` | `math.cos(math.rad(180))` -> `-1` | | math.tan | `(Rad)` -> `` | Returns the tangent of radian `Rad` | `math.tan(math.rad(45))` -> `1` | | math.asin | `(sin)` -> `` | Returns the arc sine of radian `Rad` | `math.deg(math.asin(1))` -> `90` | | math.acos | `(cos)` -> `` | Returns the arc cosine of radian `Rad` | `math.deg(math.acos(-1))` -> `180` | | math.atan | `(tan)` -> `` | Returns the arc tangent of radian `Rad` | `math.deg(math.atan(1))` -> `45` | > -> means 'returns' ## OS Library Includes functions that interact with the operating system. | Name | Type | Behavior | Example | | ------------ | ------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------ | | os.open | `(path[, mode])` -> `, ` | Opens a file at `path` and returns a file object. Specify mode to be "r" or "w" optionally, defaults to "r". | `os.open("test.txt")` -> `true, ` | | os.time | `()` -> `` | Returns the system time in Epoch format | `os.time()` -> `1.61691e+09` | | os.system | `(cmd)` -> `` | Runs a system command as if it were a terminal and returns the exit code | `os.system("mkdir test")` -> `0` | > -> means 'returns' File objects have the following methods: | Name | Type | Behavior | Example | | ------------ | ------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------ | | file:read | `(amt or "a")` -> `` | Reads `amt` bytes from the file and returns them as a string. If `"a"` is passed, the entire file is read. | `file:read("a")` -> `"Hello world!"` | | file:write | `(data)` -> `` | Writes `data` to file. | `file:write("hello world!")` -> `` | > -> means 'returns'