Pooshit.Scripting 0.19.0-preview.1

P00Sh:t Scripting

NuGet

Provides a parser for scripts which execute controlled scripts on a C# backend.

For the full language & extensibility reference see docs/pooscript-language-reference.md.

Environment

To use the script engine effectively it is necessary to add types to instantiate or function providers of which to call methods. The script engine can be used without doing this but only a limited functionality is available then like computing expressions.

Global Variables

The most simple way to extend functionality of the script engine is to provide instances with some functionality using global variables. These variables are read-only and every instance method can be called on that variable using it's keyword.

ScriptParser has only a parameterless constructor. Global variables are bound at execute time, not at parser construction:

// HttpProvider is just an example for a thinkable instance and not available in library
IScriptParser parser = new ScriptParser();
IScript script = parser.Parse("http.get(\"http://www.google.de/\")");

// Option A — VariableProvider wrapping named Variable objects
script.Execute(new VariableProvider(new Variable("http", new HttpProvider())));

// Option B — dictionary
script.Execute(new Dictionary<string, object> { ["http"] = new HttpProvider() });

Add Types

Added types can be instantiated using the new keyword and all instance methods and properties of this type are then available to be called or used in expressions.

IScriptParser parser=new ScriptParser();
parser.Types.AddType<DateTime>();
IScript script=parser.Parse("new datetime(2012,9,4)");
script.Execute();

Extensions

Existing types can be extended with methods. For this a class containing static methods taking an instance of the type to extend as first parameter. Such a method can then be called like it would be an instance method of the extended type. Unlike c# extension methods, the class does not need to be static and the extension parameter does not need to be marked with a this keyword.

IScriptParser parser=new ScriptParser();
parser.Extensions.AddExtensions<StringExtensions>();
IScript script=parser.Parse("\"test\".beautify()");
script.Execute();

Language

Expressions

An expression is a single token or a series of tokens which result in a value. A token can be a literal, operator, method call, variable or basically anything which combined in a meaningful way results in a value.

Operators

These are the default operators provided by the script parser. Operators can be defined freely using the OperatorTree property of the parser.

Note: Shift and Rol operations are executed in a bitwise and not in an arithmetic fashion. This differs in the way C# handles these operations.

Control Flow Statements

If / Else

If allows to execute a statement body based on a condition and optionally allows to execute a statement body when the condition is not met.

Parameters

$condition=true
if($condition)
	statement.execute()
else
	otherstatement.execute()

While

While executes a body until a condition evaluated to false

Parameters

$condition=true
$counter=0
while($condition)
{
	if($counter++>5)
		$condition=false
}

For

For is like a while statement. It only adds an initializing statement and an statement which is executed after every loop.

Parameters

$array=[1,2,3,4,5,6,7]
$sum=0
for($i,$i<$array.length,++$i)
	$sum+=$array[$i]

Foreach

Foreach is used to iterate over items of a collection. Every item is assigned to a variable for which a loop body is executed.

Parameters

$sum=0
foreach($item,[1,2,3,4,5])
	$sum+=$item

Switch

Switch is used to execute one of multiple branches based on the value of an expression. Following the switch there needs to be at least one case or default statement for the switch to make sense. Unlike other in major languages cases in this scripting language can contain multiple expressions which would react similar to multiple case labels with fall through behavior in c#. Case bodies also need no break statement since there is no fallthrough behavior in this language. A break would take effect on a possible enclosing loop.

Parameters

$result=0
switch(rng.next(10))
	case(1,5,8)
		$result=1
	case(6)
		$result=2
	default
		$result=0

Return

Return ends the execution of the script and returns a value. The expression following the return is evaluated to the returned value.

for($i=0,$i<5,++$i)
	if(rng.next(100)<3)
		return true
return false

Break

Breaks ends execution of enclosing loops. Break can optionally be called with a parameter specifying the loop depth to be broken out of.

while(true)
{
	if(rng.next(5)>3)
		break
}

for($i=0,$i<100,++$i)
{
	for($k=0,$k<5,++$k)
	{
		if(rng.next(5)>3)
			break(2)
	}
}

Continue

Continue ends execution of the current loop body and starts the loop again. Like break it can optionally called with a parameter specifying the loop to be continued.

for($i=0,$i<100,++$i)
{
	for($k=0,$k<5,++$k)
	{
		if(rng.next(5)>3)
			continue(2)
	}
}