Cosmo/docs/stdlib.md

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 <ref> is passed, tostring() is invoked before outputting	print("Hello world!")
type	(<ANY>) -> <string>	Returns the passed arguments datatype as a string	type(1) -> "<number>"
tonumber	(<ANY>) -> <number>	Converts the datatype to a <number>, if a <ref> is passed __tonumber metamethod is invoked	tonumber("12") -> 12
tostring	(<ANY>) -> <string>	Converts the datatype to a <string>, if a <ref> is passed __tostring metamethod is invoked	tostring(12) -> "12"
error	(<string>)	Throws an error with the passed <string>	error("error!")
pcall	(<callable>) -> <bool>, <error> or <ANY>	Tries a protected call on the passed function, if an error is thrown, <bool> will be false and the 2nd result will be the error message	pcall(error("Hello world!")) -> false, "Hello world!"
assert	(<bool>, <string>)	If the passed <bool> is false, an error is thrown, optionally uses custom error message	assert(1 == 1, "Error Message!")
loadstring	(<string>) -> <boolean>, <function> or <error>	If the <string> 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	(<string>) -> <number>	Returns the length of the passed string	"hi":len() -> 2
string.sub	(str<string>, start<number>[, length<number>]) -> <string>	Makes a substring of str starting at start with length of length or str:len() - start	"Hello World":sub(6) -> "World"
string.find	(str<string>, find<string>[, start<number>]) -> index<number>	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<string>, splitter<string>) -> [<string>, ...]	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<string>) -> <number>	Returns the byte of the first character in the string.	"A":byte() -> 65
string.char	(byte<number>) -> <string>	Returns a 1 character string of the byte passed.	string.char(65) -> "A"
string.rep	(str<string>, times<number>) -> <string>	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<number>) -> <number>	Returns the absolute value of X	math.abs(-2) -> 2
math.floor	(X<number>) -> <number>	Rounds down to the nearest integer	math.floor(5.3) -> 5
math.ceil	(X<number>) -> <number>	Rounds up to the nearest integer	math.ceil(5.3) -> 6
math.rad	(Deg<number>) -> <number>	Converts degrees to radians	math.rad(180) -> 3.14159
math.deg	(Rad<number>) -> <number>	Converts radians to degrees	math.deg(3.14159) -> 180
math.sin	(Rad<number>) -> <number>	Returns the sine of radian Rad	math.sin(math.rad(90)) -> 1
math.cos	(Rad<number>) -> <number>	Returns the cosine of radian Rad	math.cos(math.rad(180)) -> -1
math.tan	(Rad<number>) -> <number>	Returns the tangent of radian Rad	math.tan(math.rad(45)) -> 1
math.asin	(sin<number>) -> <number>	Returns the arc sine of radian Rad	math.deg(math.asin(1)) -> 90
math.acos	(cos<number>) -> <number>	Returns the arc cosine of radian Rad	math.deg(math.acos(-1)) -> 180
math.atan	(tan<number>) -> <number>	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<string>[, mode<string>]) -> <bool>, <obj>	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, <file>
os.time	() -> <number>	Returns the system time in Epoch format	os.time() -> 1.61691e+09
os.system	(cmd<string>) -> <number>	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<number> or "a") -> <string>	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<string>) -> <nil>	Writes data to file.	file:write("hello world!") -> <nil>

-> means 'returns'