The Standard Libraries

Currently, Prolix has the following standard libraries:

• utilities library (utils);
• string manipulation (string);
• table manipulation (table);
• mathematical functions (math);
• input and output (io);
• operating system facilities (new in version 2.1.0) (os);
• garbage collection facilities (garbagecollect)
• C dynamic library loader (cdll);

To have access to these libraries, you can create a new class with the same name as that library because those objects are simply pre-defined objects before the program is run.

utils - Utilities Library (Basic Library)

The fundamental library, an integral component of Prolix, serves as the cornerstone by offering essential core functions that lay the groundwork for the entire framework. In the absence of its inclusion in your application, it becomes imperative to conduct a meticulous examination, scrutinizing the need for alternative implementations for specific facilities within the library. This thorough assessment is crucial to ensure that all requisite functionalities are appropriately addressed and seamlessly integrated into your application, thereby upholding the robustness and coherence of the overall system.

utils:exec object

This function supports dynamic execution of Prolix code. object must be either a string. The string is parsed as a suite of Prolix statements which is then executed (unless a syntax error occurs).

utils:tostr object

Receives a value of any type and converts it to a string in a human-readable format.

utils:tonum object

When called with no base, tonum tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns none.

utils:type object

Returns the type of its only argument, coded as a string. The possible results of this function are "none" (a string, not the value none), "num", "str", "group", "table", "file", "userdata", "cdll".

utils:assert object

Raises an error if the value of its argument object is false (i.e., none or empty objects). In case of error, message is "assertion failed".

utils:error message

Raises an error with custom message.

utils:do group

Runs the provided group and catches any error it throws, returning the group's success and its results.

$utils:do {
    $math:div 2 0;
}
$table:get $utils:result 0;
$io:write $table:result; # Expected output: 0
# Because 2 cannot divide with 0 so the "group" report error but the "$utils:do" catch it and store error in entry at index 1.

utils:exit (New in version 2.0.1) (Deprecated in version 2.1)

Exit program instantly.

utils:tick (New in version 2.0.1)

Returns an approximation of the amount in seconds of the program execution and is intended for use in benchmarking.

# Record the initial time:
$utils:tick;
$utils:start $utils:result;

# Do something you want to measure the performance of:
$math:a 0 :b 1;
loop 100 {
    $math:a $math:b :b $math:a;
}

# Measure amount of time this took:
$utils:tick;
$math:sub $utils:result $utils:start;
$io:write "Elapsed time: " :write $math:result;

# Expected output: Elapsed time:  0.020003795623779297
# Actual number may vary

string - String Manipulation

Within this library, housed under the $string object (or string class), an extensive array of generic functions is bestowed upon users, specifically tailored for the meticulous manipulation of strings. These functions encompass a broad spectrum of operations, ranging from the identification and extraction of substrings to the execution of various string-based manipulations, contributing to a heightened level of flexibility and efficiency in string-related tasks.

string:concat object ...

Combine all strings into one string and if the given argument is not a string, it will also be converted to a string and then combined.

string:upper string

Converts a string into upper case.

string:lower string

Converts a string into lower case.

string:reverse string

Converts a string into reversed string.

string:length string (Deprecated in version 2.0.1)

Results a length of string.

string:char string index

Results a character of string by index.

string:repeat string amount

Returns a string that is the concatenation of amount copies of the string string.

string:split string separator

Splits the string at the specified separator, and returns a table.

string:find string value

Searches the string for a specified value and returns the position of where it was found.

string:sub string start end

Returns the substring of string that starts at start and continues until end.

string:string:format string object ...

The Prolix format string is replaced by all '%' contained in the string of each argument.

$string:format "Hello, %!" "World"; # Expected string: "Hello, World!"
$string:format "My name is % and I am % years old." "John" 21; # Expected string: "My name is John and I am 21 years old."
$string:format "The symbol '\%' is %." "cool"; # Expected string: "The symbol '%' is cool."

string:unicode code (New in version 2.0.1)

Used to convert ASCII code into a character.

string:ordinal character (New in version 2.0.1)

Used to convert a character into ASCII code.

table - Table Manipulation

This library, encapsulated within the $table object (or table class), furnishes a comprehensive suite of generic functions meticulously designed for the manipulation of tables. Within the expansive repertoire of functionalities it offers, users can seamlessly engage in diverse operations aimed at enhancing the versatility and efficiency of table-based data management.

table:create

Results a new table populated with many instances of the specified value.

table:set table index value

Create a new entry for the provided table at specified index with specified value.

table:get table index

Get a entry value from the provided table at specified index.

table:remove table index

Remove a entry from the provided table at specified index.

table:push table value

Add a new entry from the provided table at index is the size of the provided table with specified value.

table:combine tableA tableB

Combine two provided tables into one table.

table:find table value

Find the entry index from entry value and results in attribute result.

table:length table (Deprecated in version 2.0.1)

Results the length of the provided table.

table:clear table

Clear all entry in the provided table.

table:foreach table

Execute group for each entry and it is store key and value in attribute key and value.

$table:create;
$table:set $table:result 0 "Hi";
$table:set $table:result 1 "Yo";
$table:set $table:result 2 "Sup";
$table:set $table:result 3 "Hello";
$table:foreach $table:result {
    $io:write $table:key :write ' ' :write $table:value :write '\n';
}

# Expected output:
# 0 Hi
# 1 Yo
# 2 Sup
# 3 Hello

math - Mathematical Functions

Within the confines of this library, an expansive repertoire of fundamental mathematical functions is thoughtfully curated to cater to a diverse array of numerical operations. The mathematical functionalities are encapsulated within the library's structure, providing users with a comprehensive suite of both mathematical and operator functions. Notably, functions annotated as "integer/float" exhibit a dynamic behavior, yielding integer results when supplied with integer arguments and seamlessly transitioning to float results for float or mixed arguments, thereby ensuring adaptability across different numerical domains.

math:abs x

Results the absolute value of x. (integer/float)

math:acos x

Results the arc cosine of x (in radians).

math:add x y

Results the value x + y.

math:asin x

Results the arc sine of x (in radians).

math:atan x

Results the arc tangent of y/1 (in radians).

math:ceil x

Results the smallest integral value larger than or equal to x.

math:cos x

Results the cosine of x (assumed to be in radians).

math:cosh x

Results the hyperbolic cosine of x.

math:deg x

Converts the angle x from radians to degrees.

math:div x y

Results the value x / y.

math:eq x y

Results the value x == y.

math:exp x

Results the value e^x (where e is the base of natural logarithms).

math:factorial x

Returns the factorial of x.

math:floor x

Results the largest integral value smaller than or equal to x.

math:frexp x

Returns the mantissa and the exponent, of x.

math:fmod x y

Result the remainder of the division of x by y that rounds the quotient towards zero. (integer/float).

math:ge x y

Results the value x >= y.

math:gt x y

Results the value x > y.

math:le x y

Results the value x <= y.

math:log x

Result the logarithm of x in the given base. The default for base is e (so that the function result the natural logarithm of x).

math:log10 x

Returns the base-10 logarithm of x.

math:lt x y

Results the value x < y.

math:mod x y

Result the value x % y.

math:modf x

Result the integral part of x and the fractional part of x. Its second result is always a float.

math:mul x y

Results the value x * y.

math:ne x y

Results the value x != y.

math:neg x

Results the value -x.

math:not x

Results the value !x.

math:pow x y

Results the value x^y.

math:rad x

Converts the angle x from degrees to radians.

math:random x y

Result inclusive random integer of between x and y.

math:randomseed x

Sets x as the "seed" for the random number generator: equal seeds produce equal sequences of numbers.

math:round x

Results the rounded value of x.

math:sin x

Results the sine of x (assumed to be in radians).

math:sinh x

Results the hyperbolic sine of x.

math:sqrt x

Results the square root of x.

math:sub x y

Results the value x - y.

math:tan x

Results the tangent of x (assumed to be in radians).

math:tanh x

Results the hyperbolic tangent of x.

io - Input and Output Facilities

The Prolix I/O library simplifies data input/output and file tasks. It streamlines user interaction by providing easy functions for reading input, displaying output, and managing files. Whether handling standard input/output or file operations, this library offers a concise set of features, including error detection, making it a handy tool for efficient and user-friendly Prolix applications.

io:write object

Used to write data to the working file or if there is no working file, write data to the console.

io:append object

Similar to function io:write but only has a different use: if there is a working file, it will add data instead of rewriting all the data.

io:read [mode]

Reading the file and the result of the file data or not will read the user input in the console but there are many different modes.

Reading user input with different modes:

io:open source

Open the file via the provided file path and after being provided it will be converted into a file object and saved into the __cwf__ attribute and if there is an existing working file then will report an error.

io:close

Close the current working file and if there is no current working file, an error message will be reported.

io:popen arguments (New in version 2.1.0)

This function is system dependent and is not available on all platforms.

Starts the program (provided path at start of the arguments) with provided arguments in a separated process and store a file handle (userdata) in __cwf__ attribute that you can use to read data from this program.

os - Operating System Facilities

This library is implemented through object $os (or os class).

os:name (Constant) (New in version 2.1.0)

The name of the operating system dependent module imported. The following names have currently been registered: 'posix', 'nt'.

os:chdir source (New in version 2.1.0)

Change the current working directory to specified path.

os:date format (New in version 2.1.0)

Results a string containing date and time, formatted according to the given string format. The following specifiers are supported: