Sputnik Wiki - New pages [en-gb]

Core Function StrTr

2015-09-19T18:46:19Z

UberFoX: Created page with "<pre> StrTr( <str>, <from>, <to> ) StrTr( <str>, <replace_pairs> ) </pre> === Description === If given three arguments, this function returns a copy of str where all occurrence..."

<pre>
StrTr( <str>, <from>, <to> )
StrTr( <str>, <replace_pairs> )
</pre>

=== Description ===

If given three arguments, this function returns a copy of str where all occurrences of each character in from have been translated to the corresponding character in to, i.e., every occurrence of $from[$n] has been replaced with $to[$n], where $n is a valid offset in both arguments.

If from and to have different lengths, the extra characters in the longer of the two are ignored. The length of str will be the same as the return value's.

If given two arguments, the second should be an array in the form array('from' => 'to', ...). The return value is a string where all the occurrences of the array keys have been replaced by the corresponding values. The longest keys will be tried first. Once a substring has been replaced, its new value will not be searched again.

In this case, the keys and the values may have any length, provided that there is no empty key; additionally, the length of the return value may differ from that of str. However, this function will be the most efficient when all the keys have the same size.

=== Parameters ===

==== str ====

The string being translated.

==== from ====

The string being translated to to.

==== to ====

The string replacing from.

==== replace_pairs ====

The replace_pairs parameter may be used instead of to and from, in which case it's an array in the form array('from' => 'to', ...).

=== Return Value ===

Success: Returns the translated string.

Failure: Returns NULL

=== Remarks ===

None.

=== Example ===

Basic Example

<syntaxhighlight lang="sputnik">
say strtr("Hilla Warld","ia","eo");
// PRINTS
// Hello World
</syntaxhighlight>

Replace Pairs Example

<syntaxhighlight lang="sputnik">
$trans = array("h" => "-", "hello" => "hi", "hi" => "hello");
say strtr("hi all, I said hello", $trans);
// PRINTS
// hello all, I said hi
</syntaxhighlight>

[[Category:Core Function]]

Core Function TrimToNull

2015-09-19T10:14:35Z

UberFoX: Created page with "<pre> TrimToNull( <string> ) </pre> === Description === Strip all zero chars (nulls) from the end of a string. === Parameters === ==== string ==== The string to trim. === R..."

<pre>
TrimToNull( <string> )
</pre>

=== Description ===

Strip all zero chars (nulls) from the end of a string.

=== Parameters ===

==== string ====

The string to trim.

=== Return Value ===

Success: Returns trimmed string.

Failure: Returns old string.

=== Remarks ===

None.

=== Example ===

<syntaxhighlight lang="sputnik">
$Str = StrNew(@'\0', 15);
$Str[0] = 'A'; // Set first char to A
$Str[1] = 'B'; // Set second char to B
say $Str; // Prints: AB
say StrLen($Str); // 15

// Lets fix the string so its no longer 15 in size
// but fits all way to null term so 2 in size
say "Trimming...";
$Str = TrimToNull($Str);
say $Str; // Prints: AB
say StrLen($Str); // 2
</syntaxhighlight>

[[Category:Core Function]]

Core Function InStrRev

2015-09-17T12:06:16Z

UberFoX: /* Remarks */

<pre>
InStrRev( <string>, <substirng>, <casesense>, <occurrence>, <start>, <length> )
</pre>

=== Description ===

Same as InStr() but searches from right to left instead of left to right.

=== Parameters ===

==== string ====

The string to evaluate.

==== substring ====

The substring to search for.

==== ignoreCase ====

Optional; Flag to indicate if the operations should be case insensitive.

true = not case sensitive

false = case sensitive

Default: true

==== occurrence ====

Optional; Which occurrence of the substring to find in the string. Use a negative occurrence to search from the right side.

The default value is 1 (finds first occurrence).

==== start ====

Optional; The starting position of the search.

OR

If the start is a negative value the character position will work backwards from the length of the string.

Default: 0

==== length ====

Optional; The number of characters to search. By default the entire remainder of the string.

If length is given and is negative, then that many characters will be omitted from the end of string (after the start position has been calculated when a start is negative). If start denotes the position of this truncation or beyond, -1 will be returned.

=== Return Value ===

Success: Returns the position of the substring.

Failure: Returns -1.

=== Remarks ===

The first character position is 0.

You might think you set the start to say 10 (in a string of size 20) then expect InStrRev() to search backwards from that point but you will be mistaken as InStrRev() will search from the END of the string to the start you mentioned (10). To solve this issue you should set the start to 0 and the length to 10 then it will correctly search from position 10 to the start (0).

This is because InStrRev() works similar to InStr() and SubStr() in how it handles start/length in that the start+length defines WHAT will be searched (the entire search content is defined in the start+length).

=== Example ===

<syntaxhighlight lang="sputnik">
$TestString = "the quick brown fox jumps over the lazy dog";

$TestNumber = InStrRev($TestString, "the"); // 31
say $TestNumber . " | " . substr($TestString, $TestNumber, 3);

$TestNumber = InStrRev($TestString, "the", true, 1, 0, 16); // 0
say $TestNumber . " | " . substr($TestString, $TestNumber, 3);

// PRINTS
// 31 | the
// 0 | the
</syntaxhighlight>

[[Category:Core Function]]

Core Function HasFlagAny

2015-09-15T08:01:55Z

UberFoX:

<pre>
HasFlag( <enumInst>, <flags>... )
</pre>

=== Description ===

Check if any flag is enabled in a given enum instance.

=== Parameters ===

==== enumInst ====

Instance of an enum (or any integer will do)

==== flags ====

One or more enum flags (or integers)

=== Return Value ===

Success: Returns true

Failure: Returns false

=== Remarks ===

This is just an easier way to do bit flags.

=== Example ===

<syntaxhighlight lang="sputnik">
enum Options {
$OPT_A = 0x01,
$OPT_B = 0x02,
$OPT_C = 0x04,
$OPT_H = 0x08
};

$opt = Options->$OPT_A;
say "HasFlagAny 'A' or 'C' : " . HasFlagAny($opt, Options->$OPT_A, Options->$OPT_C);
say "HasFlagAny 'C' or 'B' : " . HasFlagAny($opt, Options->$OPT_C, Options->$OPT_B);

// PRINTS
// HasFlagAny 'A' or 'C' : true
// HasFlagAny 'C' or 'B' : false
</syntaxhighlight>

[[Category:Core Function]]

Core Function SetFlag

2015-09-15T07:49:51Z

UberFoX: /* Remarks */

<pre>
SetFlag( <enumInst>, <flag/flags>, <state> )
</pre>

=== Description ===

Enable or Disable a flag (or array of flags) in a given enum instance.

=== Parameters ===

==== enumInst ====

Instance of an enum (or any integer will do)

==== flag ====

Either:

An enum flag (or any integer)

OR

An array of enum flags.

==== state ====

Optional; The state to set the flag to should be a boolean of true or false.

Default: true

=== Return Value ===

Returns the current value of the enumInst (a copy of it)

=== Remarks ===

This is just an easier way to do bit flags.

This will not set a flag to a value it is already set to for example if you try enable a flag that's already enabled it will ignore the request (same goes for disabling a flag) this will ensure your enumInst doesn't get incorrect values even if you spam it.

This modifies the original enumInst and it's return value can be ignored.

<syntaxhighlight lang="sputnik">
// Since SetFlag modifies the enumInst directly
// it can be used stand alone like this:
SetFlag($enumInst, $OPT_H, true); // modifies $enumInst on the spot
// This keeps your code cleaner since you do not
// need to do this:
$enumInst = SetFlag($enumInst, $OPT_H, true);
// since that would be rather pointless
</syntaxhighlight>

=== Example ===

See [[Core Function HasFlag|HasFlag( )]] for examples.

[[Category:Core Function]]

Core Function HasFlag

2015-09-15T07:48:19Z

UberFoX: Created page with "<pre> HasFlag( <enumInst>, <flag/flags> ) </pre> === Description === Check if a flag (or array of flags) is enabled in a given enum instance. === Parameters === ==== enumInst..."

<pre>
HasFlag( <enumInst>, <flag/flags> )
</pre>

=== Description ===

Check if a flag (or array of flags) is enabled in a given enum instance.

=== Parameters ===

==== enumInst ====

Instance of an enum (or any integer will do)

==== flag ====

Either:

An enum flag (or any integer)

OR

An array of enum flags.

=== Return Value ===

Success: Returns true

Failure: Returns false

=== Remarks ===

This is just an easier way to do bit flags.

=== Example ===

Basic example

<syntaxhighlight lang="sputnik">
enum {
$OPT_A = 0x01,
$OPT_B = 0x02,
$OPT_C = 0x04,
$OPT_H = 0x08
};

$opt = $OPT_A;
say "HasFlag 'A' : " . HasFlag($opt, $OPT_A);
say "HasFlag 'C' : " . HasFlag($opt, $OPT_C);
say "HasFlag 'H' : " . HasFlag($opt, $OPT_H);

say "Turning H on";
SetFlag($opt, $OPT_H, true);

say "HasFlag 'H' (again) : " . HasFlag($opt, $OPT_H);

say "Turning H off";
SetFlag($opt, $OPT_H, false);

say "HasFlag 'H' (again) : " . HasFlag($opt, $OPT_H);

// PRINTS
// HasFlag 'A' : true
// HasFlag 'C' : false
// HasFlag 'H' : false
// Turning H on
// HasFlag 'H' (again) : true
// Turning H off
// HasFlag 'H' (again) : false
</syntaxhighlight>

Basic example using a literal enum

<syntaxhighlight lang="sputnik">
enum Options {
$OPT_A = 0x01,
$OPT_B = 0x02,
$OPT_C = 0x04,
$OPT_H = 0x08
};

$opt = Options->$OPT_A;
say "HasFlag 'A' : " . HasFlag($opt, Options->$OPT_A);
say "HasFlag 'C' : " . HasFlag($opt, Options->$OPT_C);
say "HasFlag 'H' : " . HasFlag($opt, Options->$OPT_H);

say "Turning H on";
SetFlag($opt, Options->$OPT_H, true);

say "HasFlag 'H' (again) : " . HasFlag($opt, Options->$OPT_H);

say "Turning H off";
SetFlag($opt, Options->$OPT_H, false);

say "HasFlag 'H' (again) : " . HasFlag($opt, Options->$OPT_H);

// PRINTS
// HasFlag 'A' : true
// HasFlag 'C' : false
// HasFlag 'H' : false
// Turning H on
// HasFlag 'H' (again) : true
// Turning H off
// HasFlag 'H' (again) : false
</syntaxhighlight>

Example of using arrays as the flags

<syntaxhighlight lang="sputnik">
enum {
$OPT_A = 0x01,
$OPT_B = 0x02,
$OPT_C = 0x04,
$OPT_H = 0x08
};

$opt = $OPT_A;
say "HasFlag 'A' : " . HasFlag($opt, $OPT_A);
say "HasFlag 'C' : " . HasFlag($opt, $OPT_C);
say "HasFlag 'H' : " . HasFlag($opt, $OPT_H);

say "Turning H and C on";
SetFlag($opt, array($OPT_H, $OPT_C));

say "HasFlag 'C' (again) : " . HasFlag($opt, $OPT_C);
say "HasFlag 'H' (again) : " . HasFlag($opt, $OPT_H);
say "HasFlag 'H AND C' (again) : " . HasFlag($opt, array($OPT_H, $OPT_C));

say "Turning H and C off";
SetFlag($opt, array($OPT_H, $OPT_C), false);

say "HasFlag 'C' (again) : " . HasFlag($opt, $OPT_C);
say "HasFlag 'H' (again) : " . HasFlag($opt, $OPT_H);
say "HasFlag 'H AND C' (again) : " . HasFlag($opt, array($OPT_H, $OPT_C));

say "Finally check A";
say "HasFlag 'A' : " . HasFlag($opt, $OPT_A);

// PRINTS
// HasFlag 'A' : true
// HasFlag 'C' : false
// HasFlag 'H' : false
// Turning H and C on
// HasFlag 'C' (again) : true
// HasFlag 'H' (again) : true
// HasFlag 'H AND C' (again) : true
// Turning H and C off
// HasFlag 'C' (again) : false
// HasFlag 'H' (again) : false
// HasFlag 'H AND C' (again) : false
// Finally check A
// HasFlag 'A' : true
</syntaxhighlight>

[[Category:Core Function]]

Core Function BinaryConcat

2015-09-14T10:33:23Z

UberFoX: /* Example */

<pre>
BinaryConcat( <destination/array>, <values> )
</pre>

=== Description ===

Mass append a ton of Binary variables in an extremely fast and efficient way.

=== Parameters ===

==== destination/array ====

IF this param is NOT an array then it expects a binary variable or something it can as such.

IF this param IS an array then the element [0] must be a reference to a binary variable and [1] must be the separator as a binary variable or something that can be converted to it.

==== values ====

One of more values to be concatenated.

=== Return Value ===

Success: Returns true.

Failure: Returns false.

=== Remarks ===

None.

=== Example ===

<syntaxhighlight lang="sputnik">
// Make a binary var we will concat onto it
my $a = Pack("A*", "Hello");
// Make binary stuff to concat to it
my $b = Pack("A*", "Hehe");
my $c = Pack("A*", "Test");
my $d = Pack("A*", "Cat");
my $e = Pack("A*", "Dog");
// Do the concat
BinaryConcat($a, $b, $c, $d, $e);
say $a;
// PRINTS
// HelloHeheTestCatDog
</syntaxhighlight>

Using the separator to do that we must use an array with first element referenced using &

<syntaxhighlight lang="sputnik">
// Make a binary var we will concat onto it
my $a = Pack("A*", "Hello");
// Make a binary var we will use as the separator
my $sep = Pack("A*", ", ");
// Make binary stuff to concat to it
my $b = Pack("A*", "Hehe");
my $c = Pack("A*", "Test");
my $d = Pack("A*", "Cat");
my $e = Pack("A*", "Dog");
// Do the concat
BinaryConcat(array(&$a, $sep), $b, $c, $d, $e);
say $a;
// PRINTS
// Hello, Hehe, Test, Cat, Dog
</syntaxhighlight>

[[Category:Core Function]]

Core Function OffsetCalc

2015-09-04T22:07:50Z

UberFoX: /* Return Value */

<pre>
OffsetCalc( <size>, <start>, <length> )
</pre>

=== Description ===

Calculate the START and LENGTH of an array index.

=== Parameters ===

==== size ====

The size of the array/string you wish to calculate the start/length from.

==== start ====

Optional; The position to start. (0 = first)

OR

If the start is a negative value the position will work backwards from the *size*.

Default: 0

==== length ====

Optional; The number to extract. By default the entire remainder.

If count is given and is negative, then that many will be omitted from the *size* (after the start position has been calculated when a start is negative). If start denotes the position of this truncation or beyond, null is returned.

=== Return Value ===

Success: A two element array with the following:
<pre>
[0] = Start position (index)
[1] = Length
</pre>

Failure: NULL

=== Remarks ===

It works using same thing SubStr() uses so if start is negative it counts from end and so on etc this allows you to include the same offset calculation for start/length of things that Sputnik does for your own needs.

=== Example ===

<syntaxhighlight lang="sputnik">
my $Str = "UberFoX";
my $diff = OffsetCalc(StrLen($Str), -3, 3);
say SubStr($Str, $diff[0], $diff[1]);
// PRINTS
// FoX
</syntaxhighlight>

[[Category:Core Function]]

Core Function DiffCalc

2015-09-04T21:59:29Z

UberFoX: Created page with "<pre> DiffCalc( <first>, <second>, <useDouble> ) </pre> === Description === Calculate the difference between two values and return the diff type Same/Add/Sub with a raw diff wh..."

<pre>
DiffCalc( <first>, <second>, <useDouble> )
</pre>

=== Description ===

Calculate the difference between two values and return the diff type Same/Add/Sub with a raw diff which can be added to the base value to make it become the second and a non-raw diff that must be added or subbed for first to become second

=== Parameters ===

==== first ====

The first value to calculate (source value).

==== second ====

The second value to calculate (destination value).

==== useDouble ====

Optional; If TRUE then the calculation will be made using Double instead of Int64

Default: False

=== Return Value ===

Success: A three element array with the following:
<pre>
[0] = Type (Same/Add/Sub)
[1] = Difference (to be used with Type so if type if Sub you -= the difference
[2] = Raw Difference can be applied directly to the first value with += or -=
</pre>

=== Remarks ===

None.

=== Example ===

<syntaxhighlight lang="sputnik">
// get a diff on double using the double flag
PrintDiff(100.0, 50.0, true);
// now get the diff on some ints
PrintDiff(0x411C88, 0x40230F);
PrintDiff(0x40230F, 0x411C88);

Function PrintDiff($first, $second)
{
// Get the diff
my List($Type, $Diff, $RawDiff) = DiffCalc($first, $second);
// Print its info
say "Type: $Type | Diff: $Diff | RawDiff: $RawDiff";
// To make the second from first we do
my $remade = $first + $RawDiff;
say "Remade: " . $remade . " | InHex: " . Hex($remade);
}
// PRINTS
// Type: Sub | Diff: 50 | RawDiff: -50
// Remade: 50 | InHex: 32
// Type: Sub | Diff: 63865 | RawDiff: -63865
// Remade: 4203279 | InHex: 40230F
// Type: Add | Diff: 63865 | RawDiff: 63865
// Remade: 4267144 | InHex: 411C88
</syntaxhighlight>

[[Category:Core Function]]

Core Function VarList

2015-06-23T12:55:11Z

UberFoX: Created page with "<pre> VarList( <varScope/class> ) </pre> === Description === Obtain information on all variables that exist in a given scope or class. ==== <varScope/class> ==== A variable s..."

<pre>
VarList( <varScope/class> )
</pre>

=== Description ===

Obtain information on all variables that exist in a given scope or class.

==== <varScope/class> ====

A variable scope (see [[Macros|Macros]]) or a class variable to scan for variables

=== Return Value ===

Success: Returns array of all found variables (Their name and information NOT their content).

Failure: Returns null.

=== Remarks ===

This is useful to grav information about variables and see how things tick a bit.

=== Example ===

Read all information about Local variables

<syntaxhighlight lang="sputnik">
// Define an *object* based variable
my $fox = sbNew();
{
// Define an *binary* based variable
my $dog = bin();
{
// Define an *string* based variable
my $cat = "meow";
// Define an *integer* based variable
my $test = 777;
// Get all local variables
my $vList = VarList(@ScopeLocal);
// Loop through and print their information
foreach($vList as my $varName => my $varInfo)
{
// Extract information using KEY based List() since
// the information is stored in KEYS and not just pushed
// onto the array
my List(@$Type, @$Depth, @$VarScope, @$ScopeType) = $varInfo;
say "### Variable '$varName' BELOW ###";
my $TypeStr = VarTypeToString($Type);
my $VarScopeStr = VarScopeToString($VarScope);
my $ScopeTypeStr = ScopeToString($ScopeType);
say "Type '$Type' (as String '$TypeStr')";
if ($Type == @typeObject)
{
my $ObjType = $varInfo['ObjectType'];
my $ObjTypeStr = VarObjTypeToString($ObjType);
say "Object Type '$ObjType' (as String '$ObjTypeStr')";
}
say "Depth '$Depth'";
say "VarScope '$VarScope' (as string '$VarScopeStr')";
say "ScopeType '$ScopeType' (as string '$ScopeTypeStr')";
say "### Variable '$varName' ABOVE ###";
say;
}
}
}
// PRINTS
// ### Variable 'cat' BELOW ###
// Type '14' (as String 'String')
// Depth '0'
// VarScope '2' (as string 'Local')
// ScopeType '3' (as string 'Block')
// ### Variable 'cat' ABOVE ###
//
// ### Variable 'test' BELOW ###
// Type '8' (as String 'Int64')
// Depth '0'
// VarScope '2' (as string 'Local')
// ScopeType '3' (as string 'Block')
// ### Variable 'test' ABOVE ###
//
// ### Variable 'varname' BELOW ###
// Type '1' (as String 'Null')
// Depth '0'
// VarScope '2' (as string 'Local')
// ScopeType '3' (as string 'Block')
// ### Variable 'varname' ABOVE ###
//
// ### Variable 'varinfo' BELOW ###
// Type '1' (as String 'Null')
// Depth '0'
// VarScope '2' (as string 'Local')
// ScopeType '3' (as string 'Block')
// ### Variable 'varinfo' ABOVE ###
//
// ### Variable 'dog' BELOW ###
// Type '17' (as String 'Binary')
// Depth '1'
// VarScope '2' (as string 'Local')
// ScopeType '3' (as string 'Block')
// ### Variable 'dog' ABOVE ###
//
// ### Variable 'fox' BELOW ###
// Type '20' (as String 'Object')
// Object Type '5' (as String 'Object')
// Depth '2'
// VarScope '2' (as string 'Local')
// ScopeType '1' (as string 'InterpInit')
// ### Variable 'fox' ABOVE ###
</syntaxhighlight>

Read all information about Global variables

Note that sometimes stuff will appear in Globals such as @argv and other things these are Sputnik internal Global variables

<syntaxhighlight lang="sputnik">
// Define some global variables
Global $cat = "Hello";
Global $dog = bin();
Global $fox = sbNew();

// Get all global variables
my $vList = VarList(@ScopeGlobal);
// Loop through and print their information
foreach($vList as my $varName => my $varInfo)
{
// Extract information using KEY based List() since
// the information is stored in KEYS and not just pushed
// onto the array
my List(@$Type, @$VarScope, @$ScopeType) = $varInfo;
say "### Variable '$varName' BELOW ###";
my $TypeStr = VarTypeToString($Type);
my $VarScopeStr = VarScopeToString($VarScope);
my $ScopeTypeStr = ScopeToString($ScopeType);
say "Type '$Type' (as String '$TypeStr')";
if ($Type == @typeObject)
{
my $ObjType = $varInfo['ObjectType'];
my $ObjTypeStr = VarObjTypeToString($ObjType);
say "Object Type '$ObjType' (as String '$ObjTypeStr')";
}
say "VarScope '$VarScope' (as string '$VarScopeStr')";
say "ScopeType '$ScopeType' (as string '$ScopeTypeStr')";
say "### Variable '$varName' ABOVE ###";
say;
}
// PRINTS
// ### Variable '@argv' BELOW ###
// Type '19' (as String 'Array')
// VarScope '2' (as string 'Local')
// ScopeType '0' (as string 'None')
// ### Variable '@argv' ABOVE ###
//
// ### Variable 'cat' BELOW ###
// Type '14' (as String 'String')
// VarScope '2' (as string 'Local')
// ScopeType '0' (as string 'None')
// ### Variable 'cat' ABOVE ###
//
// ### Variable 'dog' BELOW ###
// Type '17' (as String 'Binary')
// VarScope '2' (as string 'Local')
// ScopeType '0' (as string 'None')
// ### Variable 'dog' ABOVE ###
//
// ### Variable 'fox' BELOW ###
// Type '20' (as String 'Object')
// Object Type '5' (as String 'Object')
// VarScope '2' (as string 'Local')
// ScopeType '0' (as string 'None')
// ### Variable 'fox' ABOVE ###
</syntaxhighlight>

[[Category:Core Function]]

Preprocessor

2015-06-22T12:39:08Z

UberFoX: /* #predef */

= Preprocessor =

=== Description ===

The Sputnik preprocessor scans source files and changes them based on special # defined stuff such as #if before sending the source to the parser to deal with.

For any of these to work the # must be the FIRST thing on the line (white space is allowed).

=== #include-once ===

This is used to make a source file is only included once (regardless of how many other source files request its inclusion)

<syntaxhighlight lang="sputnik">
#include-once
</syntaxhighlight>

=== #require-once ===

This is used to make a source file is only required once (regardless of how many other source files request its inclusion)

<syntaxhighlight lang="sputnik">
#require-once
</syntaxhighlight>

=== #include "???" ===

This is used to make a source file get included directly in the current source file

<syntaxhighlight lang="sputnik">
#include "OtherFile.spk"
</syntaxhighlight>

Warning - You must make note that this will ALWAYS include the file at the TOP of the source code it does NOT include where you place the #include statement.

So if you do this

<syntaxhighlight lang="sputnik">
say "111";
#include "OtherFile.spk"
say "222";
</syntaxhighlight>

The console will print 111 then 222 THEN it will do the actions from the "OtherFile.spk".

This means you should always place #include statements at the top of your file to keep it obvious where they are being included.

Of course #include statements ARE included in ORDER for example

<syntaxhighlight lang="sputnik">
say "111";
#include "OtherFile.spk"
#include "OtherFile2.spk"
#include "OtherFile3.spk"
#include "OtherFile4.spk"
say "222";
</syntaxhighlight>

This will print 111 then 222 THEN it will execute the actions of "OtherFile.spk" followed byt "OtherFile2.spk" then "OtherFile3.spk" then "OtherFile4.spk".

So order does matter.

=== #predef ===

This is used to pre define a variable for use with #if etc

<syntaxhighlight lang="sputnik">
#predef $Test = true
#if ($Test)
say "True";
#else
say "False";
#endif
// PRINTS
// TRUE
</syntaxhighlight>

You may also omit the = and let it assign true for you example

<syntaxhighlight lang="sputnik">
#predef $Test
#if ($Test)
say "It is true";
#else
say "It is false";
#endif
// PRINTS
// It is true
</syntaxhighlight>

=== #predefwipe ===

Delete all previously assigned preprocessor variables

<syntaxhighlight lang="sputnik">
#predef $Test = 11
#unpredef $Test
#if ($Test == 10)
say "It is 10";
#elsif ($Test == 11)
say "It is 11";
#else
say "No idea what it is";
#endif
// PRINTS
// No idea what it is
</syntaxhighlight>

=== #unpredef ===

Delete a previously assigned preprocessor variable

<syntaxhighlight lang="sputnik">
#predef $Test = 11
#unpredef $Test
#if ($Test == 10)
say "It is 10";
#elsif ($Test == 11)
say "It is 11";
#else
say "No idea what it is";
#endif
// PRINTS
// No idea what it is
</syntaxhighlight>

=== #if, #else, #elsif ===

This is used to define a conditional statement in your code where you can decide to omit entire sections of your source code from ever being parsed (and thus not run) if the condition is not met.

<syntaxhighlight lang="sputnik">
#predef $Test = 11
#if ($Test == 10)
say "It is 10";
#elsif ($Test == 11)
say "It is 11";
#else
say "No idea what it is";
#endif
// PRINTS
// It is 11
</syntaxhighlight>

Example of using #unpredef to delete a previously assigned preprocessor variable

<syntaxhighlight lang="sputnik">
#predef $Test = 11
#unpredef $Test
#if ($Test == 10)
say "It is 10";
#elsif ($Test == 11)
say "It is 11";
#else
say "No idea what it is";
#endif
// PRINTS
// No idea what it is
</syntaxhighlight>

You can check using the "#predef $varname" directly which will act like a boolean

<syntaxhighlight lang="sputnik">
#predef $Test
#if ($Test)
say "It is true";
#else
say "It is false";
#endif
// PRINTS
// It is true
</syntaxhighlight>

=== #define ===

This is used to create a Sputnik @Macro or a function etc.

Lets define a string macro

<syntaxhighlight lang="sputnik">
#define Test "Hello"
say @Test;
// PRINTS
// Hello
</syntaxhighlight>

Lets define a static (static in terms of the string itself isnt parsed for variables etc) string macro

<syntaxhighlight lang="sputnik">
#define Test 'Hello'
say @Test;
// PRINTS
// Hello
</syntaxhighlight>

Lets define a boolean macro

<syntaxhighlight lang="sputnik">
#define Test true
say @Test;
// PRINTS
// true
</syntaxhighlight>

Lets define a char macro

<syntaxhighlight lang="sputnik">
#define Test @'A'
say @Test;
// PRINTS
// A
</syntaxhighlight>

Lets define an integer macro

<syntaxhighlight lang="sputnik">
#define Test 100
say @Test;
// PRINTS
// 100
</syntaxhighlight>

Lets define a hex integer macro

<syntaxhighlight lang="sputnik">
#define Test 0x7A
say @Test;
// PRINTS
// 122
</syntaxhighlight>

Lets define an floating point macro

<syntaxhighlight lang="sputnik">
#define Test 100.77
say @Test;
// PRINTS
// 100.77
</syntaxhighlight>

Lets define a link to another function (an alias)

<syntaxhighlight lang="sputnik">
// Make "Meep" become a link/alias to the "say" function
// To do this we must place TWO spaces after the first )
// otherwise Sputnik will not take note of this as a function
#define Meep() say
// Call meep which will in turn call "say"
meep "hello";
// PRINTS
// hello

// For a value to be a Function macro the following must be true:
// * It must start with an Identifier with ( ) such as MinValue()
// * There must be TWO yes 2 spaces after the ) of the MinValue()
// * There must be at least ONE character for the body immediately
// after the two spaces
//
// This is how a function is defined
</syntaxhighlight>

Lets define to create a function in a shorthand way

<syntaxhighlight lang="sputnik">
// Create the old C/C++ min/max functions using #define
// To do this we must place TWO spaces after the first )
// otherwise Sputnik will not take note of this as a function
#define c_min($a, $b) ($a < $b ? $a : $b)
#define c_max($a, $b) ($a > $b ? $a : $b)
// Try them out
say c_min(10, 20);
say c_max(10, 20);
// PRINTS
// 10
// 20

// For a value to be a Function macro the following must be true:
// * It must start with an Identifier with ( ) such as c_min()
// * There must be TWO yes 2 spaces after the ) of the c_max()
// * Then there mustbe a ( followed by the function body code
// * and finally ended by a )
// * The function body does not return a return and a ; since that
// * Is placed automatically for you
//
// This is how a function is defined
</syntaxhighlight>

=== Remarks ===

N/A.

[[Category:Core Function]]

Core Function Unserialize

2015-06-21T09:59:09Z

UberFoX: Created page with "<pre> Unserialize( <string> ) </pre> === Description === Convert a string (Created with Serialize()) into its original variable/class/array etc. === Parameters === ==== strin..."

<pre>
Unserialize( <string> )
</pre>

=== Description ===

Convert a string (Created with Serialize()) into its original variable/class/array etc.

=== Parameters ===

==== string ====

The string to unserialize back into a variable.

=== Return Value ===

Success: Returns new variable.

Failure: Returns null.

=== Remarks ===

Go See [[Core Function Serialize|Serialize( )]] for Remarks.

=== Example ===

Go See [[Core Function Serialize|Serialize( )]] for Examples.

[[Category:Core Function]]

Core Function Serialize

2015-06-21T09:57:46Z

UberFoX: /* Remarks */

<pre>
Serialize( <variable> )
</pre>

=== Description ===

Convert a variable, array, class etc a string you can save to file or transfer over the internet.

=== Parameters ===

==== variable ====

The variable to serialize.

=== Return Value ===

Success: Returns serialized variable.

Failure: Returns null.

=== Remarks ===

This can be used as a very fast effective way to dump arrays/classes to a file and read it back later.

It is faster than the JSON stuff however it is not as portable and will only work within Sputnik.

To read this in another language you would need to first read it into Sputnik then dump it as JSON.

It is worth noting that Sputniks serializer has been *finalized* and will not change in the future however new data types may be added to it making older versions of Sputnik unable to unserialize something from a newer version.

The serializer in Sputnik shares some similarities with the one with PHP in terms of how it lays out the value this means simple types like *String* may convert to PHP but more complex types like Arrays etc will not.

If you are unserializing a string that contains a class and a class with that name cannot be located it will create an instance of IncompleteClass instead you can check for this by doing:
<pre>
IsVarClass($a, 'IncompleteClass');
</pre>

=== Example ===

Serialize a string

<syntaxhighlight lang="sputnik">
// Make a value
$a = "Hello";
// Serialize it
my $s = Serialize($a);
// Print the serialized
say $s;
// PRINTS
// p:5:"Hello";

// Unserialize is
my $b = Unserialize($s);
// Print it
say $b;
// PRINTS
// Hello
</syntaxhighlight>

Serialize a number

<syntaxhighlight lang="sputnik">
// Make a value
$a = 777;
// Serialize it
my $s = Serialize($a);
// Print the serialized
say $s;
// PRINTS
// l:777;

// Unserialize is
my $b = Unserialize($s);
// Print it
say $b;
// PRINTS
// 777
</syntaxhighlight>

Serialize an array

<syntaxhighlight lang="sputnik">
// Make an array
// Note - You could include multiple arrays inside arrays and so on
$a = array(100, "Cat", "Dog");
// Serialize it
my $s = Serialize($a);
// Print the serialized
say $s;
// PRINTS
// a:l:3;l:0;l:3;i:0;:{l:0;l:100;l:1;p:3:"Cat";l:2;p:3:"Dog";}

// Unserialize is
my $b = Unserialize($s);
// Print it
printr $b;
// PRINTS
// Array
// (
// [0] => 100
// [1] => Cat
// [2] => Dog
// )
</syntaxhighlight>

Serialize a class

<syntaxhighlight lang="sputnik">
// Make a Class
Class Test
{
my $cat;
my $dog;
// This function is called when you create a class
Function __Construct($catGoes, $dogGoes)
{
$cat = $catGoes;
$dog = $dogGoes;
say "Class 'Test' made";
}
// This function is called when you serialize a class
Function __Sleep()
{
say "Class 'Test' sleeps";
}
// This function is called when you unserialize a class
Function __WakeUp()
{
say "Class 'Test' woken up";
}
};
// Create class instance
$a = new Test('meow', 'woof');
// Serialize it
my $s = Serialize($a);
// Print the serialized
say $s;
// PRINTS
// oc:p:4:"test";{a:l:2;l:0;l:0;i:2;:{p:3:"cat";p:4:"meow";p:3:"dog";p:4:"woof";}}

// Unserialize is
my $b = Unserialize($s);
// Print it
printr $b;
// PRINTS
// test Class
// (
// [cat] => meow
// [dog] => woof
// )

// Lets double check it worked by calling the classes variables
say "Cat goes? : " . $b->$cat;
say "Dog goes? : " . $b->$dog;

// PRINTS
// Cat goes? : meow
// Dog goes? : woof
</syntaxhighlight>

[[Category:Core Function]]

Core Function LineInfo

2015-06-21T09:43:56Z

UberFoX: /* Example */

<pre>
LineInfo( )
</pre>

=== Description ===

Get a vast amount of *behind the scene* information the current line of source code being executed.

=== Return Value ===

Success: Returns an array of information.

Failure: Returns null.

=== Remarks ===

More information will be added as time goes by but the array should remain in same format and provide the same info in future versions so it should be safe to rely on it.

=== Example ===

Note I used LineInfo with a bit more stuff commented out above it so thats why the line is saying 6 instead of 2.

<syntaxhighlight lang="sputnik">
// Get the line info
printr LineInfo();
// Array
// (
// [SymbolName] => Normal Stm
// [SymbolKind] => 0
// [SymbolKindStr] => Nonterminal
// [SymbolXmlName] => NormalStm
// [SymbolIndex] => 199
// [SymbolInfo] => <Normal Stm>
// [PositionFileName] => f:\sputnik\bin\main.spk
// [PositionColumn] => 1
// [PositionIndex] => 72
// [PositionLine] => 6
// [PositionLineText] => printr LineInfo();
// [PositionText] => printr
// [PositionInfo] => 6:1
// )
</syntaxhighlight>

[[Category:Core Function]]

Core Function ClassInfo

2015-06-21T09:32:15Z

UberFoX: Created page with "<pre> ClassInfo( <class-name> ) </pre> === Description === Get a vast amount of *behind the scene* information on a class and its functions, properties and so on. ==== class-n..."

Core Function FunctionInfo

2015-06-21T09:29:09Z

UberFoX: /* Example */

<pre>
FunctionInfo( <function-name> )
</pre>

=== Description ===

Get a vast amount of *behind the scene* information on a function.

==== function-name ====

The function name to get information on.

=== Return Value ===

Success: Returns an array of information.

Failure: Returns null.

=== Remarks ===

More information will be added as time goes by but the array should remain in same format and provide the same info in future versions so it should be safe to rely on it.

=== Example ===

<syntaxhighlight lang="sputnik">
// make a function
Function cat($cat = "dog", &$dog, $fox)
{
}

// Print information about the function
printr FunctionInfo('cat');

// PRINTS
// Array
// (
// [Id] => cat
// [IdOrig] => cat
// [ParamCount] => 3
// [Params] => Array
// (
// [0] => Array
// (
// [Type] => SV
// [HasObjectId] => false
// [HasDefault] => true
// [Name] => cat
// )
// [1] => Array
// (
// [Type] => REF SV
// [HasObjectId] => false
// [HasDefault] => false
// [Name] => dog
// )
// [2] => Array
// (
// [Type] => SV
// [HasObjectId] => false
// [HasDefault] => false
// [Name] => fox
// )
// )
// [UseArgVariable] => false
// [ReturnType] => 0
// [Scope] => Public
// [IsAbstract] => false
// [IsOverride] => false
// [AddOnce] => false
// [RuleCount] => 0
// [Rules] => Array
// (
// )
// )
</syntaxhighlight>

[[Category:Core Function]]

Core Function GetRelativePath

2015-06-18T10:59:56Z

UberFoX: /* Return Value */

<pre>
GetRelativePath( <Path1>, <path2> )
</pre>

=== Description ===

Try makes a path relative to another.

=== Parameters ===

==== path1 : pathToWhichToMakeRelativeTo ====

The path to which to make relative to.

==== path2 : pathToMakeRelative ====

The path to make relative.

=== Return Value ===

Success: Returns the relative path.

Failure: Returns a copy of the pathToMakeRelative.

=== Remarks ===

None

=== Example ===

<syntaxhighlight lang="sputnik">
// Path To Which To MakeRelative To
my $first = @"c:\folder1\folder2\folder4";
// Path To Make Relative
my $second = @"c:\folder1\folder2\folder3\file1.txt";
// Get the relative path
my $path = GetRelativePath($first, $second);
// Print it
say $path;
// PRINTS:
// ..\folder3\file1.txt
</syntaxhighlight>

[[Category:Core Function]]

Core Function FileAppendLines

2015-06-18T10:38:50Z

UberFoX: Created page with "<pre> FileAppendLines( <file>, <array>, <lineBreak>, <useAscii> ) </pre> === Description === Append an array of lines to the end of previously opened file. === Parameters === ..."

<pre>
FileAppendLines( <file>, <array>, <lineBreak>, <useAscii> )
</pre>

=== Description ===

Append an array of lines to the end of previously opened file.

=== Parameters ===

==== file ====

A variable containing the File handle.

==== array ====

The array to write to the file.

Each element in the array will be considered a new line for the file.

==== lineBreak ====

Optional; The line break to use.

Default: "\n"

==== useAscii ====

Optional: Flag to decide if ASCII encoding should be used

True = Save using ASCII encoding

False = Save using UNICODE encoding

Default: false (All strings in Sputnik are Unicode to save them to file you must specifically request ASCII encoding)

=== Return Value ===

Success: Returns true

Failure: Returns false if error occurs.

=== Remarks ===

N/A

=== Example ===

<syntaxhighlight lang="sputnik">
$File = FileOpen("a.txt", "a");
If(isVarObj($File, "file"))
{
FileAppendLines( $File, array("One", "Two", "Three", "Four") );
FileClose( $File );
}

</syntaxhighlight>

Lets use "<br>" for the line breaks

<syntaxhighlight lang="sputnik">
$File = FileOpen("a.txt", "a");
If(isVarObj($File, "file"))
{
FileAppendLines( $File, array("One", "Two", "Three", "Four"), "<br>" );
FileClose( $File );
}
</syntaxhighlight>

[[Category:Core Function]]

Core Function FileWriteLines

2015-06-18T10:30:37Z

UberFoX: /* Example */

<pre>
FileWriteLines( <file>, <array>, <lineBreak>, <useAscii> )
</pre>

=== Description ===

Write an array of lines to previously opened file at the current File Steam pointer location.

=== Parameters ===

==== file ====

A variable containing the File handle.

==== array ====

The array to write to the file.

Each element in the array will be considered a new line for the file.

==== lineBreak ====

Optional; The line break to use.

Default: "\n"

==== useAscii ====

Optional: Flag to decide if ASCII encoding should be used

True = Save using ASCII encoding

False = Save using UNICODE encoding

Default: false (All strings in Sputnik are Unicode to save them to file you must specifically request ASCII encoding)

=== Return Value ===

Success: Returns true

Failure: Returns false if error occurs.

=== Remarks ===

You can set the File Steam pointer location with [[Core Function FileSeek|FileSeek( )]].

Warning this will not write to the end of the file unless you tell it to with seek so if you want to write to end of the file you should use [[Core Function FileAppendLines|FileAppendLines( )]] instead.

=== Example ===

<syntaxhighlight lang="sputnik">
$File = FileOpen("a.txt", "w");
If(isVarObj($File, "file"))
{
FileWrite( $File, "Test\n" );
FileWrite( $File, "Test2\n" );
FileWriteLines( $File, array("One", "Two", "Three", "Four") );
FileClose( $File );
}

</syntaxhighlight>

Lets use "<br>" for the line breaks

<syntaxhighlight lang="sputnik">
$File = FileOpen("a.txt", "w");
If(isVarObj($File, "file"))
{
FileWrite( $File, "Test\n" );
FileWrite( $File, "Test2\n" );
FileWriteLines( $File, array("One", "Two", "Three", "Four"), "<br>" );
FileClose( $File );
}
</syntaxhighlight>

[[Category:Core Function]]

Core Function FileReadText

2015-06-18T09:19:56Z

UberFoX: Created page with "<pre> FileReadText( <file>, <format>, <length> ) </pre> === Description === Read text from a file opened by FileOpenText() using the format and length params . === Parameters ..."

<pre>
FileReadText( <file>, <format>, <length> )
</pre>

=== Description ===

Read text from a file opened by FileOpenText() using the format and length params .

=== Parameters ===

==== file ====

The text file "handle" to read from. (The one you got from FileOpenText())

==== format ====

Mode to read the choices are:

* "c" = Read a single char
* "l" = Read a single line
* "e" = Read to the end of the file

Note if you use "c" you may also supply a number of chars you wish to wish after it

=== Return Value ===

Success: Returns the string containing hte information you asked for.

Failure: Returns an empty string.

=== Remarks ===

N/A

=== Example ===

<syntaxhighlight lang="sputnik">
// Open the file and return the handle
my $f = FileOpenText("Main.spk");
if ($f)
{
// Read the first line
say FileReadText($f, 'l');
// Read the second line
say FileReadText($f, 'l');
// Read a char
say FileReadText($f, 'c');
// Read a 8 char
say FileReadText($f, 'c', 8);
// Read to the end of the file
say FileReadText($f, 'e');
}
// free the handle
FileClose($f);
</syntaxhighlight>

[[Category:Core Function]]

Core Function FileOpenText

2015-06-18T09:16:26Z

UberFoX: /* Example */

<pre>
FileOpenText( <filename> )
</pre>

=== Description ===

Opens a file for reading only (text files only) .

=== Parameters ===

==== filename ====

Name of the text file to open.

=== Return Value ===

Success: Returns a text file "handle" for use with subsequent file functions

Failure: Returns null if error occurs.

=== Remarks ===

This does NOT return the same "handle" used by FileOpen() so you cannot use it in the same places as that however the following functions do support the handled returned from FileOpenText().

FilePos(), FileSeek(), FileReadText()

=== Example ===

<syntaxhighlight lang="sputnik">
// Open the file and return the handle
my $f = FileOpenText("Main.spk");
if ($f)
{
// Read the first line
say FileReadText($f, 'l');
// Read the second line
say FileReadText($f, 'l');
// Read a char
say FileReadText($f, 'c');
// Read a 8 char
say FileReadText($f, 'c', 8);
// Read to the end of the file
say FileReadText($f, 'e');
}
// free the handle
FileClose($f);
</syntaxhighlight>

[[Category:Core Function]]

Core Function SSBufferPut

2015-06-15T07:25:37Z

UberFoX: Created page with "<pre> SSBufferPut( <netBuffer>, <type>, <data> ) </pre> === Description === Add data to a net buffer. === Parameters === ==== <netBuffer> ==== The net buffer to write to. =..."

<pre>
SSBufferPut( <netBuffer>, <type>, <data> )
</pre>

=== Description ===

Add data to a net buffer.

=== Parameters ===

==== <netBuffer> ====

The net buffer to write to.

==== <data type> ====

The type of data to write to the message buffer valid options are:

<pre>
[CODE] [TYPE]
"v" Binary (Writes an Int32 for size then writes the bytes)
"V" Binary (Writes all bytes)
"b" Byte (signed)
"B" Byte (unsigned)
"s" Int16
"i" Int32
"l" Int64
"S" UInt16
"I" UInt32
"L" UInt64
"f" Float
"d" Double
"p" String
</pre>

=== Return Value ===

Success: Returns true.

Failure: Returns false.

=== Remarks ===

This is NOT a generic socket toolset; You can't use this to connect to anything instead it is used to connect Sputnik clients with Sputnik servers in a very easy to use way.

=== Example ===

See the Listen() and Connect() for examples

[[Category:Core Function]]

Core Function SSBufferNew

2015-06-15T06:28:55Z

UberFoX: Created page with "<pre> SSBufferNew( <nothing/server/client> ) </pre> === Description === Create a new net buffer to store data to send to the client/server. === Parameters === ==== <nothing/..."

<pre>
SSBufferNew( <nothing/server/client> )
</pre>

=== Description ===

Create a new net buffer to store data to send to the client/server.

=== Parameters ===

==== <nothing/server/client> ====

Optional; The client/server object to request the new buffer from.

If this param is not given then the net buffer will created stand alone and can be still be sent just fine.

=== Return Value ===

Success: Returns message buffer object.

Failure: Returns null.

=== Remarks ===

This is NOT a generic socket toolset; You can't use this to connect to anything instead it is used to connect Sputnik clients with Sputnik servers in a very easy to use way.

=== Example ===

See the Listen() and Connect() for examples

[[Category:Core Function]]