Language Reference

Revision as of 11:00, 27 January 2013

Language Reference

Datatypes

Brief

In Sputnik there is only one datatype called an SV. A SV can numeric or string data (And more advanced arrays/hashes) and decides how to use the data depending on the situation it is being used in. For example, if you try and multiply two SV variables they will be treated as numbers, if you try and concatenate (join) two variants they will be treated as strings.

Some examples:

$var = 100; // equals the number 100 
 
$var = 100 * 20; // equals the number 2000 
 
$var = 100 + (100 / 2); // equals the number 150
 
$var = 10 . 20; // equals the string "1020" (. is used to join strings) 
 
$var = 10 * "omg"; // equals 0 since if a string is used as a number, it will be converted to a number; If it doesn't contain a valid number, it will be assumed to equal 0.
 
// Example of variable conversions.....
10 / 20 // This action will two Int64 and they will remain Int64s
10 / 20.0 // We have defined one of them as a double so it will convert them both to a double when it does the conversion
// What this means is if you want to make sure your math is indeed using doubles add the . to it such 20.0
// Why? Consider this "$y = 1 % 3/4;" it wil return NaN ie fail... But if we do "$y = 1 % 3.0/4.0;" it will work as expected.

Numbers

Numbers can be standard decimal numbers like 2, 4.566, and -7.

Scientific notation is also supported; therefore, you could write 1.5e3 instead of 1500.

Integers (whole numbers) can also be represented in hexadecimal notation by preceding the integer with 0x as in 0x409 or 0x4fff (when using hex notation only 32-bit/64-bit integers numbers are valid not floats/doubles).

Strings

Sputniks strings are ALL UNICODE you can only print UNICODE specific symbols to the console if you change the front to Consolas or something.

Strings are enclosed in double-quotes like "this". If you want a string to actually contain a double-quote use it twice like:

// "This type of string is parsed for escapes"
// 'This type of string is static and is never parsed'
// @"This type of string is also never parsed"

$var = "here is a \"double-quote\" - ok?"; // the \n is an escape charactor to cause a special symbol to be placed inside a string in this case it will place a double quote " inside a string.

You can mix quote types to make for easier working and to avoid having to double-up your quotes to get what you want. For example if you want to use a lot of double-quotes in your strings then you should use single-quotes for declaring them:

'This "sentence" contains "lots" of "double-quotes" does it not?'

However if you choose to use to define your strings and then you want to place a ' inside the string it must be done like this:

'Hello this is my string'

In this case is used to place a ' inside a string made of chars.

The "" strings can place variables inside them for example:

"Hello the variable is $val ok"

And Arrays:

"Hello the variable is $val[77] ok"

And Hashes:

"Hello the variable is $val[test] ok"

Warning - Strings made using 'string' are STATIC this means you cannot place variables inside the string like you can with a regular "string"

Note - "" string allows escapes such as \n to form newline however strings do not resolve escapes.

/*
Escape Sequence		Represents
\$			Dollar sign
\@			At Sign
\a			Bell (alert)
\b			Backspace
\f			Formfeed
\n			New line
\r			Carriage return
\t			Horizontal tab
\v			Vertical tab
\'			Single quotation mark
\"			Double quotation mark
\\			Backslash
\?			Literal question mark
\xhh			ASCII character in hexadecimal notation
\xhhhh			UNICODE character in hexadecimal notation
*/

Multiline Strings

All string can use multiple lines for example:

println(@"

This is a multiline string\n

");

This type of string does not resolve escapes such as \n so the \n in this string will really be seen as \n literally.

If you wish to place a " inside the @"" string you must place 2 of them like this

println(@"

This is a multiline string and im ""quoted"" ok

");

It also does not need to be on multiple lines example

println(@"Hello world!");

You can also use the normal "" and strings across multiple lines.

Booleans

Booleans are logical values. Only two Boolean values exist: true and false.

They can be used in variable assignments, together with the Boolean operators and, or and not.

Examples:

$Boolean1 = true;
$Boolean2 = false;

If you use arithmetics together with Boolean values (which is not advisable!), the following rules apply:

A Boolean true will be converted into the numeric value 1

A Boolean false will be converted into the numeric value 0

Example:

$Boolean1 = true;
$Number1 = 100;
$Number2 = $Boolean1 + $Number1;
println( $Number2 ); // This will result in $Number2 to be the numeric value 101
 
$Boolean1 = true;
$String1 = "Test is: ";
$String2 = $String1 . $Boolean1;
println( $String2 ) // This will result in $String2 being the string value "Test is: True"

Arrays

Variables can also be arrays storing multiple variables in a single variable accessible by its [] index.

(Its worth noting a variable can contain both an array and a hash at the same time)

// WARNING - A variable will only act like an array
// if you are using a NUMERIC value in the [] bracket for example
$lol[10] // this is an array....
$lol["10"] // this is an array...
$lol["moo"] // this is not an array now...
 
// If your $variable is NOT numeric it will act like a "" dictionary
// Note - This is only true if teh $variable cannot be converted to
// a numeric.
 
// You can check if it is numeric like so:
if( IsNumeric($value) )
// This will tell you if the variable will be used as an array index
// or a dictionary key

Heres a simple example:

$lol = array(1, 2, 3, 4); // Create a simple array with 4 elements
 
// Print the details of the array
println("lol :" . $lol);
println("lol[0] :" . $lol[0]);
println("lol[1] :" . $lol[1]);
println("lol[2] :" . $lol[2]);
println("lol[3] :" . $lol[3]);

An example of adding stuff to end and beginning of an array:

$lol = array(1, 2, 3, 4); // Create a simple array with 4 elements
$lol .= array(5, 6); // Add 2 Elements to end of the array
$lol ..= array(0); // Add 1 Element to start of the array
 
// Print the details of the array
println("lol :" . $lol);
println("lol[0] :" . $lol[0]);
println("lol[1] :" . $lol[1]);
println("lol[2] :" . $lol[2]);
println("lol[3] :" . $lol[3]);
println("lol[4] :" . $lol[4]);
println("lol[5] :" . $lol[5]);
println("lol[6] :" . $lol[6]);

To delete an array you can simply define it as anything including strings but the best way is:

$lol = array(1, 2, 3, 4); // Create a simple array with 4 elements
$lol = array(); // Delete the array
 
// Print the details of the array
println("lol :" . $lol);
println("lol[0] :" . $lol[0]);
println("lol[1] :" . $lol[1]);

Copying an array is simple too example:

$lol = array(1, 2, 3, 4); // Create a simple array with 4 elements
 
$test = $lol;
 
// Print the details of the array
println("lol :" . $lol);
println("lol[0] :" . $lol[0]);
println("lol[1] :" . $lol[1]);
 
println("test :" . $test);
println("test[0] :" . $test[0]);
println("test[1] :" . $test[1]);

That was a full COPY of the array changing elements in one array will not effect the other unless your first array contained references but we will get into that later.

Arrays can also be modified directly example:

$lol = array(1, 2, 3, 4); // Create a simple array with 4 elements
 
$lol[2] = "Hello";
$lol[1] = "hmmm";
$lol[99] = "hi there!";
 
// Print the details of the array
println("lol :" . $lol);
println("lol[0] :" . $lol[0]);
println("lol[1] :" . $lol[1]);
println("lol[2] :" . $lol[2]);
println("lol[98] :" . $lol[98]);
println("lol[99] :" . $lol[99]);

In the above example you can see simply typing $var[index] = will cause it to create that index (part of the array) and fill it with what you type, The array will be automatically expanded to the size you request all the elements in the gap that it fills in will be empty strings ready for use (As seen in index 98).

Example of Multi-dimensional array

$lol = array(0 => array(3, 4), 1 => array(3 =>array(8, 9))); // Create a simple array with 4 elements
 
$lol[0][0] = "Hello";
 
// Print the details of the array
println( "lol :" . $lol );
println( "lol[0] :" . $lol[0] );
println( "lol[0][0] :" . $lol[0][0] );
println( "lol[0][1] :" . $lol[0][1] );
println( "lol[1][3] :" . $lol[1][3] );
println( "lol[1][3][0] :" . $lol[1][3][0] );
println( "lol[1][3][1] :" . $lol[1][3][1] );

You can also use the qw// to produce simple arrays example

// the qw// accepts only alphanumeric letters separated by spaces
$arr = qw/test omg lol/;
foreach($arr as $lol)
{
	println("First test :" . $lol);
}
 
// Is equal to
$arr = array("test", "omg", "lol");
foreach($arr as $lol)
{
	println("Second test :" . $lol);
}

Comparing arrays

// Compare the full array and all elements requiring a perfect match
if($firstarray == $secondarray)
// Reverse of above
if($firstarray != $secondarray)
// Compare the full array and all elements requiring a even more perfect match
if($firstarray === $secondarray)
// Reverse of above
if($firstarray !== $secondarray)
// Compare the full array and all elements requiring a perfect match
if($firstarray eq $secondarray)
// Reverse of above
if($firstarray neq $secondarray)
// Compare the full array and all elements requiring a perfect match (case insensitive)
if($firstarray eqi $secondarray)
// Reverse of above
if($firstarray neqi $secondarray)
 
// Note if you use < > <= >= <> etc
// the arrays will be converted into their index size
// so a 10 element array becomes the number 10 in such an IF
// only the == etc can be used to compare the whole array

Theres a lot more arrays can be used for and theres a lot of functions to use with them but that will be shown in another part of this wiki.

Hashes (Dictionary)

A Hash (Dictionary) is used to store variables under a key name this is useful for creating a kind of key/value system and is more useful then arrays in situations where you need this.

(Its worth noting a variable can contain both an array and a hash at the same time for example if you use a string "" to access the variable like $lol["100"] it will be using the HASH but if you use a number such as $lol[100] it will be using the array instead.

Also this rule applies to variables too for example if you want to make sure your using a number to access the array and not the hash you could do a cast like $lol[(int)$value] this will make sure you are indeed accessing the array and not the hash even if $value contains a string of numbers.

This keeps the array separated from the hash which makes the array work faster.)

// WARNING - A variable will only act like an hash(dictionary) key
// if you are using a STRING value that cannot be converted to a number
// in the [] bracket for example
$lol["10"] // this is not an hash key....
$lol[10] // this is not an hash key...
$lol["test"] // this is an hash key....

The key in a hash is case insensitive.

Heres a brief example:

$cc = array("One" => "cat", "Two" => "dog", "Three" => "mouse");
 
println("cc :" . $cc);
println("cc[one] :" . $cc["One"]);
println("cc[two] :" . $cc["Two"]);
println("cc[three] :" . $cc["Three"]);

You can also add more elements to the Hash using the ..= example:

$cc = array("One" => "cat", "Two" => "dog", "Three" => "mouse");
$cc .= array("Four" => "woman", "Five" => "man");
 
println("cc :" . $cc);
println("cc[one] :" . $cc["One"]);
println("cc[two] :" . $cc["Two"]);
println("cc[three] :" . $cc["Three"]);
println("cc[four] :" . $cc["Four"]);
println("cc[five] :" . $cc["Five"]);

A more simple approach to adding new values is to simply modify the value directly example:

$cc = array("One" => "cat", "Two" => "dog", "Three" => "mouse");
$cc .= array("Four" => "woman", "Five" => "man");
 
$cc["Six"] = "Sheep";
$cc["One"] = "Not a cat!";
$cc["Seven"] = "Donkey";
 
println("cc :" . $cc);
println("cc[one] :" . $cc["One"]);
println("cc[two] :" . $cc["Two"]);
println("cc[three] :" . $cc["Three"]);
println("cc[four] :" . $cc["Four"]);
println("cc[five] :" . $cc["Five"]);
println("cc[six] :" . $cc["Six"]);
println("cc[seven] :" . $cc["Seven"]);

Example of Multi-dimensional hash

$lol = array("One" => array(3, 4), "Two" => array(3 =>array(8, 9))); // Create a simple array with 4 elements
 
$lol['One'][0] = "Hello";
 
// Print the details of the array
println( "lol :" . $lol );
println( "lol['One'] :" . $lol['One'] );
println( "lol['One'][0] :" . $lol['One'][0] );
println( "lol['One'][1] :" . $lol['One'][1] );
println( "lol['Two'][3] :" . $lol['Two'][3] );
println( "lol['Two'][3][0] :" . $lol['Two'][3][0] );
println( "lol['Two'][3][1] :" . $lol['Two'][3][1] );
 
// Note you can mix array index and hash strings to create all kinds of MD arrays

There is a lot more you can do with hashes including functions to make using them easier but that will be shown in another part of the wiki.

Enum

Enums are a variable that lets you get a number from it and each one is unique.

A local scope MY enum

my enum
{
	$Cat,
	$Dog,
	$Fox,
	$Cow,
	$Pig
};
println("Cat: " . $Cat); // Prints 0
println("Dog: " . $Dog); // Prints 1
println("Fox: " . $Fox); // Prints 2
println("Cow: " . $Cow); // Prints 3
println("Pig: " . $Pig); // Prints 4

Another local scope but this time with a few base variables

my enum
{
	$Cat,
	$Dog = 20,
	$Fox,
	$Cow = 55,
	$Pig
};
 
println("Cat: " . $Cat); // Prints 0
println("Dog: " . $Dog); // Prints 20
println("Fox: " . $Fox); // Prints 21
println("Cow: " . $Cow); // Prints 55
println("Pig: " . $Pig); // Prints 56

Global scope enum accessible by all

enum Countries
{
	$England,
	$France,
	$Germany,
	$Netherlands,
	$Portugal = 50,
	$Italy,
	$Russia
};
 
println("England: " . Countries->$England); // Prints 0
println("France: " . Countries->$France); // Prints 1
println("Germany: " . Countries->$Germany); // Prints 2
println("Netherlands: " . Countries->$Netherlands); // Prints 3
println("Portugal: " . Countries->$Portugal); // Prints 50
println("Italy: " . Countries->$Italy); // Prints 51
println("Russia: " . Countries->$Russia); // Prints 52

Variables

A variable is a place to store information in a way that is easy to get and change.

Declaring Variables

There are 2 ways to create variables either scoped or unscoped example:

$var = 100;

That will either modify an existing variable called $var and change its value to 100 or it will create the variable on the stack in this case it will create a GLOBAL scope variable.

The second way to create variables is to define its scope example:

my $var = 100;

That will either modify an existing LOCAL variable called $var and change its value to 100 or it will create the variable on the stack in this case it will create a LOCAL scope variable.

Global $var = 100

That will either modify an existing GLOBAL variable called $var and change its value to 100 or it will create the variable on the stack in this case it will create a GLOBAL scope variable.

Scope

A variable's scope is controlled by when and how you declare the variable. In most cases your variables will be Global unless you specifically set them to Local. Global scope and can be read or changed from anywhere in the script.

If you declare a variable inside a function and you made it Local scope it can only be used within that same function. Variables created inside functions are automatically destroyed when the function ends.

The same is true for classes.

So inside a function you only have the function/class(and class function) itself as a LOCAL scope to use and outside a function your local scope is the actual script itself.

However if you "really" need a new local scope any any point you can use the {...} statement example:

my $lol = 100;
{
	my $lol = 88;
	println("lol is: " . $lol);
}
println("lol is: " . $lol);

Every local variable defined inside the block exists only in the block.

You can also stack blocks inside each other.

Casting

There are 2 ways to cast a value as something else the first:

println( "The cast is : " . Int(777.42) )

This will cause everything inside the Int() to be converted to an int this uses the function Int32( $variable ) (Alias: Int( $variable )).

The second way is similar to C and works like this:

println( "The cast is : " . (int)777.42 )

The "(int)value" type will only convert what it *touches* so if you want to convert a large expression you must cover with () example:

$a = 11.6
println( "The cast is : " . (int)(777.42 + $a) )

Casting is very useful since there will be times when you really need to be using only INTs or FLOATs and by casting you will make sure that you do.

Its worth noting the actual "(type)value" cast supports casting overloading on Classes where as the function "type(value)" does not.

Macros

Sputnik has an number of Macros that are special read-only variables. Macros start with the @ character instead of the usual $ so are easy to tell apart. As with normal variables you can use macros in expressions but you cannot assign a value to them.

The pre-defined macros are generally used to provide easy access to information and constants such as @PI etc.

Go here for a complete list.

Classes

Sputnik does support some pbject-oriented programming however its too big for this page alone so its best to go see the classes page

Classes

Operators

Operator []

Append to end of array. e.g.

my $myArray = array("One", "Two", "Three");
 
$myArray[] = "Four";
$myArray[] = "Five";
 
printr($myArray);

Operator []!

Append to beginning of array. e.g.

my $myArray = array("One", "Two", "Three");
 
$myArray[]! = "Zero";
$myArray[] = "Four";
 
printr($myArray);

Operator is

Type checking. e.g.

// Used to check if a variable is a certain type
$a = (int32)1;
 
if($a is Int32)
{
	println(@"$a is an Int32");
}
else
{
	println(@"$a is NOT an Int32");
}
 
// Can be used for classes and other objects too
Class Testy
{
};
 
$b = new Testy();
 
if($b is Testy)
{
	println(@"$a is an instance of class Testy");
}
else
{
	println(@"$a is NOT an instance of class Testy");
}

Operator isnot

Type checking. e.g.

// Used to check if a variable is not a certain type
$a = (int32)1;
 
if($a isnot Int32)
{
	println(@"$a is NOT an Int32");
}
else
{
	println(@"$a is an Int32");
}

Operator =

Assignment. e.g.

$var = 5;     (assigns the number 5 to $var)

Operator ++

Increase assignment. e.g.

$var++;     (adds 1 to $var)
++$var;     (adds 1 to $var)

Operator ++

Decrease assignment. e.g.

$var--;     (subs 1 from $var)

Operator +=

Addition assignment. e.g.

$var += 1;     (adds 1 to $var)

Operator -=

Subtraction assignment.

$var -= 1;     (subs 1 to $var)

Operator /=

Division assignment. e.g.

$var /= 2;     (divive $var by 2)

Operator *=

Multiplication assignment. e.g.

$var /= 2;     (multiply $var by 2)

Operator **=

Raises a number to the power assignment. e.g.

$var **= 2;     (raise $var by 2)

Operator |=

BitwiseOR assignment. e.g.

$var |= 2;

Operator ^=

BitwiseExclusiveOR assignment. e.g.

$var |= 2;

Operator %=

BitwiseAND assignment. e.g.

$var |= 2;

Operator >>=

BitwiseSHIFT RIGHT assignment. e.g.

$var >>= 2;

Operator <<=

BitwiseSHIFT LEFT assignment. e.g.

$var <<= 2;

Operator .=

Concatenates/joins two strings (Adds text to end of variable) assignment. e.g.

$var .= "Hello";

Operator ..=

Concatenates/joins two strings (Adds text to beginning of variable) assignment. e.g.

$var ..= "Hello";

Operator +

Adds two numbers. e.g.

10 + 20;    (equals 30)

Operator -

Subtracts two numbers. e.g.

20 - 10;    (equals 10)

Operator *

Multiplies two numbers. e.g.

20 * 10;    (equals 200)

Operator /

Divides two numbers. e.g.

20 / 10;    (equals 2)

Operator **

Raises a number to the power. e.g.

2 ** 4;    (equals 16) 

Operator <<

BitwiseSHIFT Left. e.g.

14 << 2;    (equals 56 because 1110b left-shifted twice is 111000b == 56) 

Operator >>

BitwiseSHIFT Right. e.g.

14 >> 2;    (equals 3 because 1110b right-shifted twice is 11b == 3) 

Operator ~

BitwiseNOT. e.g.

~ 5;
    ; Result is -6 because for 32-bit numbers
    ; 5 == 00000000000000000000000000000101 binary
    ; -6 == 11111111111111111111111111111010 binary
    ; and the first bit is signed

Operator .

Concatenates/joins two strings. e.g.

"one" . 10;    (equals "one10")

Operator ==

Tests if two values are equal (case sensitive if used with strings)

Operator ===

Tests if two values are equal an same type (case sensitive if used with strings)

//define variables..  
$str = '9';  
$int = 9;  
 
//Returns true since both variable contains the same value..  
$res = ($str==$int); 
println("Str '9' == Int 9; " . ($res ? "True" : "False"));
 
//Returns false since the two variables are not of the same type..  
$res = ($str===$int);
println("Str '9' === Int 9; " . ($res ? "True" : "False"));

Operator !=

Tests if two values are not equal (case sensitive if used with strings)

Operator !==

Tests if two values are not equal and not the same type (case sensitive if used with strings)

Operator <

Tests if the first value is less than the second.

Operator <=

Tests if the first value is less than or equal to the second.

Operator >

Tests if the first value is greater than the second.

Operator >=

Tests if the first value is greater than or equal to the second.

Operator <>

Test if two values are not equal.

Operator eq

Tests if two strings are equal (case sensitive)

Operator eqi

Tests if two strings are equal (case insensitive)

Operator neq

Tests if two strings are not equal (case sensitive)

Operator neqi

Tests if two strings are not equal (case insensitive)

Operator &&

Logical AND operation. e.g.

If($var == 5 && $var2 > 6)    (True if $var equals 5 and $var2 is greater than 6)

Operator ||

Logical OR operation. e.g.

If($var == 5 || $var2 > 6)    (True if $var equals 5 or $var2 is greater than 6)

Operator !

Logical NOT operation. e.g.

If(!$var == 5)

Operator ??

Boolean expression TRUE or switch. eg.

$a = false;
println( $a ?? "The variable is not true" );

Operator ? :

Boolean expression TRUE or FALSE switch. eg.

Println ( 1 == 2 ? "True" : "False" );


// Heres an example of why it looks better
if( $a == 100 )
{
	println ( "True" );
}
else
{
	println ( "False" );
}

// Is best written like so
println ( $a == 100 ? "True" : "False" );

Operator !? :

Booleon expression TRUE or FALSE switch. eg.

Println ( 1 == 2 !? "False" : "True" );


// Heres an example of why it looks better
unless( $a == 100 )
{
	println ( "False" );
}
else
{
	println ( "True" );
}

// Is best written like so
println ( $a == 100 !? "False" : "True" );

Operator <stm> if( <expression> )

Execute code if expression TRUE. eg.

$test = 200;
println( "Hello World" ) if( $test == 100 );
println( "Goodbye World" ) if( $test == 200 );

Operator <stm> if( <expression> ) else <stm>

Execute code if expression TRUE else execute other code. eg.

$test = 200;
println( "Hello World" ) if( $test == 100 ) else println( "Goodbye World" );

Conditional Statements

• If...Else
• Unless...Then...Else
• Select...Case..Default
• Switch...Case..Default

Loop Statements

• For
• For...As
• For...As...Key...Value
• While
• Until
• Do..While
• Do..Until

Exception Handling

• Try..Catch..Finally

User Defined & Core Language Functions

There is many functions built into language for easy use for a list go here

• Function Reference

There are also functions created using Sputnik that you can include in your projects and use.

To create your own funtions see the Function page.

• User Defined Functions

Character Sets

There are many macros that contain character sets go here for a complete list.

This takes numeric values same as AscW() and returns a string or array

$a = c65..c70;
print($a); // Prints ABCDEF
 
$b = array(c65..c70);
foreach($b as $c)
{
	print("$c,"); // Prints A,B,C,D,E,F,
}

This takes 2 chars returns a string or array

$a = 'A'..'F';
print($a); // Prints ABCDEF
 
$a = 'A'..'F' . 'a'..'f' . '0'..'9';
print($a); // Prints ABCDEFabcdef0123456789
 
$a = '0'..'9';
print($a); // Prints 0123456789
 
$a = 'z'..'a';
print($a); // Prints zyxwvutsrqponmlkjihgfedcba
 
$b = array('A'..'F');
foreach($b as $c)
{
	print("$c,"); // Prints A,B,C,D,E,F,
}
 
$b = array('A'..'F','a'..'f','0'..'9');
foreach($b as $c)
{
	print("$c,"); // Prints A,B,C,D,E,F,a,b,c,d,e,f,0,1,2,3,4,5,6,7,8,9,
}

Takes decimals and returns string

$a = 0..20;
print($a); // Prints 01234567891011121314151617181920
 
$b = array(0..20);
foreach($b as $c)
{
	print("$c,"); // Prints 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,
}

Comments