Prexonite Script: Commands (1.2.3)

boxed(obj)

Wraps the supplied object in a Prexonite::PValue.

obj	The object to be wrapped. Can be anything, even null.
returns	An instance of `Prexonite::PValue` that wraps `obj`.

boxed is commonly used in the following two scenarios:

To communicate with the Prexonite VM (it used Prexonite::PValue objects internally
As an easy way to display type information. The following snippet
```
var x = 1+0.5;
println("x = ",boxed(x));
```
will print and return x = {1.5~Real}.

char(s~String)

Creates a ~Char value from a string.

s	Any non-empty string. Only the first character is relevant.
returns	The first character in `s` as a `~Char`.

char(i)

Creates a ~Char value from a Unicode codepoint.

i	A valid Unicode codepoint. Will be converted to `~Int`.
returns	A `~Char` that represents the Unicode codepoint `i`.

~Char is one of the built-in data types of Prexonite. ~Char literals are written using a syntax that is identical to calling char.

char("π") // a ~Char literal for the greek character π
char(0x20) // a ~Char literal for the ASCII whitespace.

print(obj, …)

Converts all arguments to strings and prints them to the standard output (STDOUT).

obj…	Any value that supports `?.ToString()`, including `null`.
returns	The string printed to the standard output (STDOUT).

println()

Prints the system-specific newline character (sequence) to the standard output (STDOUT).

returns	The empty string.

println(obj, …)

Converts all arguments to strings and prints them followed by the system-specific newline character (sequence) to the standard output (STDOUT).

obj…	Any value that supports `?.ToString()`, including `null`.
returns	The string printed to the standard output (STDOUT) not including the system-specific newline character (sequence).

new var v

Unbinds a variable from other closures using it.

v	Name of a local variable.
returns	`null`

Prexonite Script, like JavaScript, does not have scoped control-structures. That means that closures that refer to loop variables will in most cases not work as expected.

function main(){
    var n = 15;
    function f1()
    {
        while(n > 4)
            println(n--);
    }
    f1();
    println(n); // "4"
    
    n = 13;
    new var v;
    f1();
    println(n); // "13"
}

After the new var n statement, Prexonite considers n to be a fresh variable that has no relationship with any of the scopes that n was shared with previously (f1 in this case).

The variable n does, however, retain the value of its predecessor.

function main(){
    var xs = [1,2,3,4,5,6,7];
    var fs = [];
    foreach(var x in xs){
        fs[] = y => x + y;
    }
    println(x); // "7"
    println(fs[3].(5)); // "12" == 7+5
    
    fs = [];
    foreach(new var x in xs){
        fs[] = y => x + y;
    }
    println(x); // "7"
    println(fs[3].(5)); // "9" == 4+5
}

While it is possible to use y => new var x + y to achieve a similar effect, it is in most cases not recommended since that causes the variable to be unbound every single time the closure is invoked.

Note that new var v is different from var new v. The latter is used to avoid capturing v in the first place.

abs(x~Int)

Computes the absolute value of an integer number ("strips sign")

x~Int	Any integer.
returns	`x` with the sign stripped. `if(x < 0) -x else x`. Always returns an integer.

abs(x)

Computes the absolute value of a number ("strips sign")

x	Any number, will be converted to `~Real` if necessary.
returns	The real number argument `x` with the sign stripped. `if(x < 0) -x else x`. Always returns a real number.

ceiling(x)

Returns the smallest integer number that is greater than or equal to x.

x	Any number. Will be converted to `~Real`.
returns	The smallest integer number that is greater than or equal to `x`. Still a `~Real`.

cos(x)

Computes the cosine function.

x	The angle in radians. Will be converted to `~Real`.
returns	The ratio adjacent/hypotenuse as a `~Real`.

exp(x)

Raises e (approximately 2.718281828) to the chosen power.

x	The exponent. Will be converted to a `~Real`.
returns	The result of computing `e^x`. Always a `~Real`.

If you just need Euler's number, use exp(1).

floor(x)

Returns the largest integer number that is less than or equal to x.

x	Any number. Will be converted to `~Real`.
returns	The largest integer number that is less than or equal to `x`. Still a `~Real`.

log(x)

Computes the natural logarithm of its argument.

x	The argument. Will be converted to a `~Real`.
returns	The natural logarithm of `x` as a `~Real`.

The natural logarithm is the logarithm with Euler's number as the base.

log(x) == log(x,exp(1))

log(x,b)

Computes an arbitrary logarithm.

x	The argument. Will be converted to a `~Real`.
b	The base for the logarithm. Will be converted to a `~Real`.
returns	The logarithm of `x` with respect to base `b` as a `~Real`.

max(a~Int,b~Int)

Compares two integers and returns the larger of the two.

a	An integer.
b	Another integer.
returns	An integer that is at least as large as `a` and `b`. Always an `~Int`.

max(a,b)

Compares two numbers and returns the larger of the two.

a	A number. Will be converted to `~Real`.
b	Another number. Will be converted to `~Real`.
returns	A number that is at least as large as `a` and `b`. Always a `~Real`.

min(a~Int,b~Int)

Compares two integers and returns the smaller of the two.

a	An integer.
b	Another integer.
returns	An integer that is less than or equal to `a` and `b`. Always an `~Int`.

max(a,b)

Compares two numbers and returns the smaller of the two.

a	A number. Will be converted to `~Real`.
b	Another number. Will be converted to `~Real`.
returns	A number that is less than or equal to `a` and `b`. Always a `~Real`.

pi
The constant π (pi). Roughly 3.14159265358979.

returns 3.14159265358979~Real

round(x)

Rounds a number to the nearest integer number.

x	Any number. Will be converted to `~Real`.
returns	The nearest integer number to `x`. Always a `~Real`.

round(x,d)

Rounds a number to the nearest decimal fraction with a specified number of fractional digits.

x	Any number. Will be converted to `~Real`.
d	The number of digits after the decimal point, you want to retain. Will be converted to `~Int`.
returns	The nearest number with at most `d` decimal digits in the fraction. Always a `~Real`.

round always rounds away from zero.

sin(x)

Computes the sine function.

x	The angle in radians. Will be converted to `~Real`.
returns	The ratio opposite/hypotenuse as a `~Real`.

sqrt(x)

Computes the (real) square root of a number.

x	The number to compute the square root for. Will be converted to `~Real`. Must be positive, otherwise an exception might be thrown.
returns	The square root of `x`.

sqrt(abs(x))^2 == x
sqrt(x^2) == abs(x)

tan(x)

The tangent function. Given an angle x in radians, computes the ratio opposite/adjacent.

x	The angle in radians. Will automatically be converted to `~Real`.
returns	The ratio opposite/adjacent.

setleft(width, text)

Creates a new string with length at least width and text at the beginning ("on the left hand side")

width	The width minimal width of the resulting string in characters.
text	The text to include in the resulting string, left-aligned. May be longer than `width`. `?.ToString()` will be called on `text` if it is not a string.
returns	A string that starts with `text.ToString()` and has at least length `width`. If `text.ToString()` is too short, the result will be padded with spaces (`U+0020`).

The supplied text is not truncated if it is longer than width.

setleft(width, text, filler)

Creates a new string with length at least width and text at the beginning ("on the left hand side"). The remaining space is filled with repetitions of filler

width	The width minimal width of the resulting string in characters.
text	The text to include in the resulting string, left-aligned. May be longer than `width`. `?.ToString()` will be called on `text` if it is not a string.
filler	The string (`?.ToString` is used) that is used to fill the remaining space.
returns	A string that starts with `text.ToString()` and has at least length `width`. If `text.ToString()` is too short, the result will be padded with repetitions of `filler`.

The supplied text is not truncated if it is longer than width. The filler does can consist of multiple characters. In that case, however, the width must be a multiple of filler.Length

setright(width, text)

Creates a new string with length at least width and text at the end ("on the right hand side")

width	The width minimal width of the resulting string in characters.
text	The text to include in the resulting string, right-aligned. May be longer than `width`. `?.ToString()` will be called on `text` if it is not a string.
returns	A string that ends with `text.ToString()` and has at least length `width`. If `text.ToString()` is too short, the result will be padded with spaces (`U+0020`).

The supplied text is not truncated if it is longer than width.

setright(width, text, filler)

Creates a new string with length at least width and text at the end ("on the right hand side"). The remaining space is filled with repetitions of filler

width	The width minimal width of the resulting string in characters.
text	The text to include in the resulting string, right-aligned. May be longer than `width`. `?.ToString()` will be called on `text` if it is not a string.
filler	The string (`?.ToString` is used) that is used to fill the remaining space.
returns	A string that ends with `text.ToString()` and has at least length `width`. If `text.ToString()` is too short, the result will be padded with repetitions of `filler`.

The supplied text is not truncated if it is longer than width. The filler does can consist of multiple characters. In that case, however, the width must be a multiple of filler.Length

setcenter(width, text)

Creates a new string with length at least width and text in the middle.

width	The width minimal width of the resulting string in characters.
text	The text to include in the resulting string, centered. May be longer than `width`. `?.ToString()` will be called on `text` if it is not a string.
returns	A string that contains with `text.ToString()` in the middle and has at least length `width`. If `text.ToString()` is too short, the result will be padded with spaces (`U+0020`).

The supplied text is not truncated if it is longer than width.

setcenter(width, text, filler)

Creates a new string with length at least width and text in the middle. The remaining space is filled with repetitions of filler

width	The width minimal width of the resulting string in characters.
text	The text to include in the resulting string, centered. May be longer than `width`. `?.ToString()` will be called on `text` if it is not a string.
filler	The string (`?.ToString` is used) that is used to fill the remaining space.
returns	A string that contains `text.ToString()` in the middle and has at least length `width`. If `text.ToString()` is too short, the result will be padded with repetitions of `filler`.

The supplied text is not truncated if it is longer than width. The filler does can consist of multiple characters. In that case, however, the width must be a multiple of filler.Length