Vanilla

Vanilla is a de facto package of functions for PapajScript. This package contains all basic functions for PS. It was 'released' on May 28, 2020, however it existed since the birth of RPN Calculator in 2014.

List of Vanilla functions

Note:

• The vanilla functions do not require attaching them by @use(Vanilla) and they cannot be unattached. Moreover, they don't require the prefix Vanilla. – just type toString instead of Vanilla.toString.

Constants

Package Function	Output type	Purpose
TRUE	Boolean	A logical value of TRUE
FALSE	Boolean	A logical value of FALSE
NULL	Null	Null
[]	Array	An empty array
EXC	Exception	An empty exception
INF	Number	Positive Infinity
-INF	Number	Negative Infinity
+INF	Number	Positive Infinity
NaN	Number	Not a Number (yep, it sounds weird)
+i	Number	Imaginary unit (since 0.5.4, must be written with + char)
-i	Number	Negative imaginary unit (must be written with - char)

Type casting

Package Function	Syntax	Output type	Purpose
type	ENT1 function	String	Check the type of the value being on the top of the stack
toString	ENT1 function	String	convert to a string
toNumber	ENT1 function	Number	convert to a number
toBoolean	ENT1 function	Boolean	convert to a logical value (TRUE or FALSE)
toArray	ENT1 function	Array	build an array from N elements of the stack
toException	ENT1 function	Exception	build an exception (if X is a string, then it creates an unraised exception with this string message)
raiseException	ENT1 function	Exception	same as above, but it raises exception too
isNumber	ENT1 function	Boolean	return TRUE or FALSE whether entity type is Number or not
isBoolean	ENT1 function	Boolean	return TRUE or FALSE whether entity type is Boolean or not
isString	ENT1 function	Boolean	return TRUE or FALSE whether entity type is String or not
isArray	ENT1 function	Boolean	return TRUE or FALSE whether entity type is Array or not
isNull	ENT1 function	Boolean	return TRUE or FALSE whether entity type is Null or not
isException	ENT1 function	Boolean	return TRUE or FALSE whether entity type is Exception or not
isLogicalExpression	ENT1 function	Boolean	return TRUE or FALSE whether entity type is LogicalExpression or not
isFunction	ENT1 function	Boolean	return TRUE or FALSE whether entity type is Function or not
isDateTime	ENT1 function	Boolean	return TRUE or FALSE whether entity type is DateTime or not

Mathematical functions

Package Function	Syntax	Output type	Purpose
+	ENT1 ENT2 function	Entity	add
-	ENT1 ENT2 function	Entity	substract
*	ENT1 ENT2 function	Entity	multiply
/	ENT1 ENT2 function	Entity	divide
^	NUM1 NUM2 function	Number	power
pow	NUM1 NUM2 function	Number	power
root	NUM1 NUM2 function	Number	root
realroot	NUM1 NUM2 function	Number	real root of a real number (since 0.5.4)
complexroot	NUM1 NUM2 function	Number	primary complex root of any number (since 0.5.4)
div	NUM1 NUM2 function	Number	integer division (-5 3 div returns -1)
mod	NUM1 NUM2 function	Number	modulo (-5 3 mod returns -2)
++	NUM1 function	Number	increment
inc	NUM1 function	Number	increment
--	NUM1 function	Number	decrement
dec	NUM1 function	Number	decrement
sqrt	NUM1 function	Number	square root
exp	NUM1 function	Number	N1-th power of Euler's number
ln	NUM1 function	Number	Natural logarithm
trunc	NUM1 function	Number	truncate
frac	NUM1 function	Number	extract the fractional part (since 0.5.1.2)
random	NUM1 function	Number	Return a random integer from a range [0; N1-1]
rand	(no args) function	Number	Return a random real from a range [0; 1)
shl	NUM1 NUM2 function	Number	Binary shift left
shr	NUM1 NUM2 function	Number	Binary shift right
abs	NUM1 function	Number	Absolute value
re	NUM1 function	Number	Real part of complex number (since 0.5.4)
im	NUM1 function	Number	Imaginary part of complex number (since 0.5.4)
arg	NUM1 function	Number	Argument of complex number (since 0.5.4)

Available arithmetics:

• Number Number +, Number Number -, Number Number *, Number Number /
• String String +, String String -, String String /
• String Number -, String Number *, String Number /
• Number String *

Conditionals and loops

More about conditionals here.
More about loops here

Package Function	Syntax	Output type	Purpose
times	NUM1 function	none	Do the next thing N1 times
callIf	BOO1 FUN1 function	none	Calls a function FUN1 whether BOO1 = TRUE
callUnless	BOO1 FUN1 function	none	Calls a function FUN1 whether BOO1 = FALSE
callTimes	FUN1 NUM1 function	none	Calls a function FUN1 NUM1 times
callWhile	EXP1 FUN1 function	none	Checks for a condition expression and repeats the procedure as long as the condition is true (equivalent of C-like while loop, since 0.5.2)
callWhile	FUN1 EXP1 function	none	Repeats the procedure as long as the condition contained in the expression is true (equivalent of C-like do-while loop, since 0.5.2)
callUntil	EXP1 FUN1 function	none	Checks for a condition expression and repeats the procedure as long as the condition is false (since 0.5.2)
callUntil	FUN1 EXP1 function	none	Repeats the procedure as long as the condition contained in the expression is false (since 0.5.2)

The old-style conditional

Syntax: B1 ? if: I1 else: I2 The question mark checks if an expression B1 is true or its numerical value is equal to 0. The if: launches the next instruction only when the recent ?-check was successful. The else: launches the next instruction only when the recent ?-check was unsuccessful.

This style of conditionals is not supported since the 0.5.3 version anymore

Examples:

• scan toNumber 2 mod ? if: { "This number is even." println } else: { "This number is odd." println }
• scan toNumber 5 > ? if: { "This number is greater than 5" println }
• scan toNumber 5 <= ? else: { "This number is greater than 5" println }

The C-like conditional

The if checks the conditional expression and launches the next instruction only when the check is successful. The else launches the next instruction only when the recent condition check was unsuccesful. The elif checks the conditional expression (just like if) if a check of the previous one was not successful.

The C-like syntax of conditionals and loops

• if ( B1 ) I1
• if ( B1 ) I1 else I2
• if ( B1 ) I1 elif ( B2 ) I2
• if ( B1 ) I1 elif ( B2 ) I2 else I3
• if ( B1 ) I1 elif ( B2 ) I2 elif ( B3 ) I3 ... else IN
• if ( B1 ) I1 elif ( B2 ) I2 elif ( B3 ) I3 ... elif ( BN ) IN

Loops

• N1 times { I1 }
• while (B1) { I1 }
• do { I1 } while ( B1 )
• do { I1 } until ( B1 )
• for ( I1 ; B1 ; I2 ) { I3 }
• for ( ENT1 : ARR1 ) { I1 }

Stack aggregating functions

Package Function	Syntax	Output type	Purpose
sum	N1 function	Number	sum of the last N1 values of the stack
product	N1 function	Number	product of the last N1 values of the stack
count	N1 function	Number	amount of the last N1 values of the stack (stack's size)
size	N1 function	Number	as above, but don't clear the stack
all	N1 function	Number	as above
avg	N1 function	Number	mean of the last N1 values of the stack
mean	N1 function	Number	mean of the last N1 values of the stack
max	N1 function	Number	maximum value of the last N1 values of the stack
min	N1 function	Number	minimum value of the last N1 values of the stack
median	N1 function	Number	median of the last N1 values of the stack
variance	N1 function	Number	variance of the last N1 values of the stack
stddev	N1 function	Number	stddev of the last N1 values of the stack

Stack manipulating functions

Package Function	Syntax	Output type	Purpose
rev	N1 function	none	reverse the last N1 values of the stack
reverse	(no args) function	none	reverses the entire stack
clone	N1 function	set of Entity	Clone the last N1 values of the stack
keep	N1 function	none	Keep the last N1 values of the stack
copy	N1 function	set of Entity	Copy the last N1 values of the stack
sort	N1 function	none	Sort the values of the last N1 values of the stack numerically
numsort	N1 function	none	Sort the values of the last N1 values of the stack numerically (since 0.5.2)
strsort	N1 function	none	Sort the strings of the last N1 values of the stack alphabetically
mcopy	N1 function	none	Copy the top n values on the stack and put them on the stack in reversed order
rem	(no args) function	none	Remove a value from the top of the stack
frontrem	(no args) function	none	Remove a value from the stack front
qshift	(no args) function	Entity	Move a value from the stack front to the top
clear	(no args) function	none	Clear entire stack
swapAt	NUM1 function	none	Swap the N+1th stack entity with the previous one (N >= 1)
swapAt2	NUM1 NUM2 function	none	Swap the entities with indexes of N1 and N2 (zero-indexed)

Stack generating functions

Package Function	Syntax	Output type	Purpose
seq	NUM1 NUM2 NUM3 function	set of Number	generate an arithmetical sequence from NUM1 to NUM3 by step of NUM2 and put it on the stack
gseq	NUM1 NUM2 NUM3 function	set of Number	generate a geometrical sequence from NUM1 to NUM3 by quotient of NUM2 and put it on the stack
seql	NUM1 NUM2 NUM3 function	set of Number	generate an arithmetical sequence of NUM3 numbers, starting with NUM1 and having step of NUM2, and put it on the stack
gseql	NUM1 NUM2 NUM3 function	set of Number	generate a geometrical sequence of NUM3 numbers, starting with NUM1 and having quotient of NUM2, and put it on the stack

Input and output functions

Package Function	Syntax	Output type	Purpose
scan	(no args) function	Entity	Scan 1 value from an input (e.g. standard input) and add it on the top of the stack of values
scannum	(no args) function	Number	Scan 1 numerical value from input
scanstr	(no args) function	String	Scan 1 string value from input
print	ENT1 function	none	Print a value being on the top of the stack
println	ENT1 function	none	Same as above and end the line.
rprint	ENT1 function	none	Print a value being on the top of the stack and remove it from this stack.
rprintln	ENT1 function	none	Same as above and end the line. (not recommended unless you turned off @autoclear)
status	(no args) function	none	Print the stack.
statusln	(no args) function	none	Same as above and end the line.
statusfull	(no args) function	none	Print the stack in a more "beautiful" and detailed way.
newln	(no args) function	none	Start a new line

Logical operations

Package Function	Syntax	Output type	Purpose
not	BOO1 function	Boolean	negation
or	BOO1 BOO2 function	Boolean	alternative
and	BOO1 BOO2 function	Boolean	conjunction
xor	BOO1 BOO2 function	Boolean	exclusive disjunction
>	ENT1 ENT2 function	Boolean	check if E1 is greater than E2
<	ENT1 ENT2 function	Boolean	check if E1 is less than E2
<=	ENT1 ENT2 function	Boolean	check if E1 is less than or equal to E2
>=	ENT1 ENT2 function	Boolean	check if E1 is greater than or equal to E2
=	ENT1 ENT2 function	Boolean	check if E1 is equal to E2
!=	ENT1 ENT2 function	Boolean	check if E1 is not equal to E2

Variables

• "abc" "xyz" vset or abc >xyz or abc ->xyz – Move an "abc" to a var "xyz". If the variable does not exist, then create it with this value.
• "xyz" vget or $xyz – Put either the var "xyz" or NULL on the stack, depending if the variable exists or not.
• "xyz" vexists or ?xyz – Return true or false, depending if var "xyz" exists.
• "xyz" vdestroy or ~xyz – Destroy a variable "xyz" if exists.
• "xyz" vcall or @@xyz – If the var is a function, then call it directly.

Note: Calling xyz without any prefix or command does the following:

• if xyz is a function, then call it (act like @@xyz)
• otherwise (if xyz is not a function) put the variable on the stack (act like $xyz)

Parsing directives

Operand	Purpose
@silent(BOOL)	Don't print the final stack output (when BOOL=TRUE). BOOL=false by default.
@silent	The same as @silent(TRUE)
@real	Output is a decimal (set by default)
@milli	Output is a decimal with fixed precision of 3 digits
@float	Output is a decimal with fixed precision of 6 digits
@double	Output is a decimal with fixed precision of 15 digits
@int	Output is rounded to an integer value.
@decimal	Output is a decimal number with thousands separator
@scientific	Output is in a scientific notation (e.g. 2,137 -> 2.137E+03)
@scientific1	Output is in a scientific notation (fixed precision of 15 digits, e.g. 2,137 -> 2.1370000000000000E+03)
@money	Output is a decimal with fixed precision of 2 digits
@amoney	Output is a decimal with thousands separator and a fixed precision of 2 digits
@autoclear(BOOL)	Stack is wisely cleared after every operation (BOOL=true by default, obsolete since 0.5.3)
@infmode(BOOL)	Allow infinity, NaN and division by zero
@sorttype(STYPE)	Set a type of sorting a stack
@casesensitive(BOOL)	Whether it does matter if you type a command like THIS, or this, or tHiS
@useshell(SHELL)	Specify what shell do you want to use
@use(PACKAGE)	Use a package
@unuse(PACKAGE)	Stop using a package
@stringstart(SSTART)	Determine if strings are zero-based or one-based
@stringmode(SMODE)	Determine if strings are interpreted a C-like way or Pascal way
@fixprecision(X)	Set fixed decimal precision to X digits (X is a non-negative integer)
@maxprecision(X)	Set max decimal precision to X digits (X is a non-negative integer)
//	One-line comment (only parsing text files)

BOOL – available values are TRUE or FALSE (or also true/false, for compatibility with older scripts)

STYPE – available values:

• BUBBLESORT or BSORT or 0 - bubblesort
• QUICKSORT or QSORT or 1 - quicksort (set by default)
• MERGESORT or MSORT or 2 - mergesort
• RANDOMSORT or RSORT or 3 or BOGOSORT - random sort/bogosort (for devils and masochists only, use at your own risk)

SHELL – available values:

• BASH - use /bin/bash shell (set by default on UNIX systems)
• CMD - use cmd.exe shell (set by default on Windows systems)
• PWSH or POWERSHELL - use PowerShell
• SH - use /bin/sh shell
• ZSH - use /bin/zsh shell

PACKAGE – available packages:

• String with string functions (see more here)
• Math with mathematical functions (see more here)
• Array with array functions (see more here)
• Console with utilities for console-run scripts (see more here)
• 'Date' with utilities for datetime management (see more here)
• Number with numbers handling functions (coming soon)
• Assert with assertion mechanisms (coming soon)
• File with file I/O functions (coming soon)
• System with system functions (coming soon maybe)

SSTART – available options:

• 0 - zero-based strings (default)
• 1 - one-based strings
• DEFAULT- zero-based strings (default)

SMODE – available modes:

• CLIKE - C-like mode (zero-based strings with backslash sequences, default)
• PASCAL - Pascal mode (one-based strings)
• DEFAULT- C-like mode (default)

Other

Package Function	Syntax	Output type	Purpose
makeChar	NUM1 function	String	assuming N1 is an ASCII code, it returns a char from the ASCII table
getAscii	STR1 function	Number	Return an ASCII code number of a char S1 (it must be a single char)

Examples and protips

Examples:

• 2 3 + gives 5
• 10 times rand gives 10 random numbers of a range [0,1)
• 5 times 2 sum sums five 2's
• 5 times scan all sum sums five numbers scanned by an input
• 2 3 4 5 6 2 avg brings a result of 5.5, as avg(5,6) = 5.5. The bottom values stay on the stack and now the stack looks like 2 3 4 5.5.
• 2 3 4 5 6 all avg brings a result of 4, as avg(2,3,4,5,6) = 4.
• 5 3 8 10 32.5 4 Math.sin 2 2 + 5 10 all sum sums all values previously put on the stack
• 1 1 8 seq generates "1 2 3 4 5 6 7 8"
• 1 3 8 seql generates "1 4 7 10 13 16 19 22"
• 8 2 1 gseq generates "8 4 2 1"
• 8 -1 10 gseql generates "8 -8 8 -8 8 -8 8 -8 8 -8"
• 1 2 3 4 reverse transforms into "4 3 2 1"
• 5 10 times clone generates "5 5 5 5 5 5 5 5 5 5 5"
• 5 4 3 2 1 2 keep results in a stack of "2 1"
• 5 4 3 2 1 2 copy results in a stack of "5 4 3 2 1 2 1"
• 5 4 3 2 1 2 mcopy results in a stack of "5 4 3 2 1 1 2"
• 5 4 3 2 1 2 all sort results in a stack of "1 2 2 3 4 5"
• 5 4 3 1 7 2 3 rev results in a stack of "5 4 3 2 7 1"
• if ( scan toNumber 2 mod ) { "This number is even." println } else { "This number is odd." println }
• if ( scan toNumber 5 > ) { "This number is greater than 5" println }
• if ( scan toNumber 5 <= not ) { "This number is greater than 5" println }
• if ( scan toNumber 10 mod ) 1 else 0
• if ( x 1 = ) { "X is equal to 1" println } elif ( x 2 = ) { "X is equal to 2" println } else { "X is neither equal to 1 nor equal to 2" println }
• 10 times { 100 random } which generates 10 numbers from a range [0..99] (note: we must know the exact amount of iterations here)
• 1 >i while ( i 10 <= ) { 100 random i ++ >i } which also generates 10 numbers from a range [0..99]
• 1 >i do { 100 random i ++ >i } while ( i 10 <= ) which also generates 10 numbers from a range [0..99]
• 1 >i do { 100 random i ++ >i } until ( i 10 > ) which also generates 10 numbers from a range [0..99]
• for ( 1 >i ; i 10 <= ; i ++ >i ) { 100 random } which also generates 10 numbers from a range [0..99]
• for ( item : [ 1 1 10 seq ] ) { i println } prints a sequence from 1 to 10
• scan scan + scans 2 values and adds them
• scan 3 random + scans a value, generates a random number from a range [0..3] and adds the numbers
• "Hello world!" type puts "string" on the top of the stack
• "Hello world!" println prints "Hello world!"
• 21 37 > returns FALSE, as 21 > 37 is not a true statement.
• 5 ++ >x $x puts 6 as the value of x variable
• 5 ++ >x x puts 6 as the value of x variable
• fun{ 3 + } >x 5 @@x puts 8 as the returned value of x function
• fun{ 3 + } >x 5 $x puts 5 and x function
• fun{ 3 + } >x 5 x puts 8 as the returned value of x function
• 2+3i -5-4i + gives -3-1i

Protips:

• size copy (or all copy) replicates the stack (e.g. 1 2 3 4 size copy results in "1 2 3 4 1 2 3 4"), and size 2 / keep halves the stack and lets the new one stay, e.g. after you don't need a replication anymore. If you want to keep the "old stack", just use reverse size 2 / keep reverse - assuming the sizes of "old stack" and the "new stack" are the same.
• size mcopy creates a mirrored stack (e.g. 1 2 3 4 size mcopy results in "1 2 3 4 4 3 2 1")
• @int 14.89 prints a stack with "15"
• @int 14.89 trunc prints stack with "14"
• @silent @int 14.89 trunc doesn't print the stack
• 2 3 + prints a stack with "5"
• @use(String) allows using String commands with their shorter forms, e.g. concat instead of String.concat.