"Sputnik" help  
Sputnik Help
Try ( resources )
{
statements
...
}
Catch ( $e ) When ( condition )
{
statements
...
}...
Finally
{
statements
...
}

Description

If an exception (a critical error that would normally terminate your program) takes place inside a try you can capture the error and evaulate what went wrong and maybe fix your program from crashing.

Parameters

Try This block is used to simply do a normal operation however if anything goes wrong you will instanty drop into the catch block.
Resources

Optional; This is where you can include statements to automatically get unset() called the second the try statement ends (after the Finally if there is one) this works identical to the Using statement but without having to use that statement saves you some space.

Catch Optional; This block is used to capture the error and see what happened and possibly fix your program or work around the error.

If you add ( Exception $e ) after Catch you can use that variable to get detailed information on what went wrong.

The word "Exception" in the catch is actually a name of a Class you can insert any name you wish however you must inherit the default Exception class to throw your own unique exceptions see examples below.

A catch statement can also be blank just having the word Catch with no () block this type of catch will get executed regardless of what class was triggered.

You can have multiple catch statements or none.

Note - It doesn't need to be $e you can use $moo if you want however $e or $exception is more readable.

When Condition Optional; This is where you place a condition to use to decide if this Catch can be considered at all it works similar an If statement in that the when must be true for this catch to trigger (of course the exception must also match if you included one).
Finally Optional; This block will be executed regardless if you have an exception or not.

Remarks

Try...Catch...Finally statements may be nested.

There are some exceptions in Sputnik that are core critical and will ignore the try/catch and half the script instantly with the error message.

The Try...Catch...Finally statement in Sputnik provides a structured and powerful way to handle exceptions and errors in your code. It allows you to encapsulate code that may potentially throw an exception and define how to handle different types of exceptions or errors that occur.

The Try block is used to enclose the code that you want to execute. If an exception occurs within this block, the program execution jumps to the corresponding Catch block. The Catch block is where you can capture the exception, analyze what went wrong, and take appropriate actions to handle the error. You can specify the type of exception to catch by using the Exception class or creating your own custom exception classes.

In addition to catching specific exceptions, you can also use the When condition to further control which Catch block should be executed. The When condition allows you to specify a condition that must be true for the Catch block to trigger. This provides flexibility in handling different scenarios based on specific conditions.

The Finally block is optional and is executed regardless of whether an exception occurred or not. This block is typically used to perform cleanup operations or release resources that were allocated in the Try block. It ensures that certain actions are taken, regardless of the outcome of the Try block.

You can also include the Resources block, which is similar to the Using statement. It allows you to include statements that automatically call unset() on the specified resources once the Try block ends. This helps manage and clean up resources efficiently.

Nested Try...Catch...Finally statements are supported, allowing for more complex error handling scenarios. You can have multiple Catch blocks to handle different types of exceptions or errors, and the Finally block is executed for each Try block, regardless of nesting levels.

The Try...Catch...Finally statement in Sputnik helps you handle exceptions and errors in a controlled and structured manner. It enables you to catch and analyze exceptions, take appropriate actions, and ensure that necessary cleanup operations are performed. By using this statement, you can effectively handle critical errors and maintain the stability and reliability of your code.

Related

None.

Example

Example of using an exception:

Try
{
    say "This code always executes";
    // None of the exceptions params are required
    // but it helps to at least have a message (First param)
    // The second param is the error code can be anything you want
    // The third param is the PARENT inside a class you would use
    // the $this variable as the parent for obvious reasons
    my $parent = "someClass";
    throw new Exception("My Message", 777, $parent);
    say "This code below the exception will not be executed if there was an exception";
}
Catch ( Exception $e )
{
    say "This code only gets executed if an exception happened";
    say "Message: " . $e->getMessage(); // Gets the default or new message
    say "Code: " . $e->getCode(); // Gets the error code if one exists
    say "Parent: " . $e->getParent(); // Gets the parent if one exists
}
Finally
{
    say "This code gets executed regardless if there was an exception or not";
}
// PRINTS
// This code always executes
// This code only gets executed if an exception happened
// Message: My Message
// Code: 777
// Parent: someClass
// This code gets executed regardless if there was an exception or not

Example of using an exception with Redo:

my $attempt = 0;
Try
{
    say "Lets throw...";
    throw new Exception("My Message", 777, null);
}
Catch ( Exception $e )
{
    say "Exception!!!!! $attempt";
    $attempt++;
    // Begin the whole Try again if
    // we havent made enough attempts at it
    if($attempt < 3)
        redo;
}
Finally
{
    say "Finally complete";
}
// PRINTS
// Lets throw...
// Exception!!!!! 0
// Lets throw...
// Exception!!!!! 1
// Lets throw...
// Exception!!!!! 2
// Finally complete

Example of creating your own Exception class:

Class myException inherits "Exception"
{
    my $myParam;
    Function __Construct($Message, $Code, $Param, $Parent)
    {
        // Assign our special variable
        $myParam = $Param;
        // We do not need to call the base __construct function since
        // it automatically added itself to the prefix of this __Construct
        // using the lovely "^" flag for functions (prefix)
    }
    Function myParam()
    {
        return $myParam;
    }
}
 
Try
{
    say "This code always executes";
    // None of the exceptions params are required
    // but it helps to at least have a message (First param)
    // The second param is the error code can be anything you want
    // The third param is the PARENT inside a class you would use
    // the $this variable as the parent for obvious reasons
    my $parent = "someClass";
    throw new myException("My Message", 777, "my special param", $parent);
    say "This code below the exception will not be executed if there was an exception";
}
Catch ( myException $e )
{
    say "This code only gets executed if an exception happened";
    say "Class: " . $e; // Print what type of class (exception) it is
    say "Message: " . $e->getMessage(); // Gets the default or new message
    say "Code: " . $e->getCode(); // Gets the error code if one exists
    say "MyParam: " . $e->myParam(); // Gets our new param that was extended to exception
    say "Parent: " . $e->getParent(); // Gets the parent if one exists
}
Finally
{
    say "This code gets executed regardless if there was an exception or not";
}
// PRINTS
// This code always executes
// This code only gets executed if an exception happened
// Class: {CLASS:myexception;ID:8}
// Message: My Message
// Code: 777
// MyParam: my special param
// Parent: someClass
// This code gets executed regardless if there was an exception or not

Example of using multiple Catch statements each one triggering ONLY if a specific exception type is given:

Class myException inherits "Exception" { }
Class myException2 inherits "Exception" { }
 
my $i = 0;
begin:{}
 
Try
{
    if($i == 0)
    {
        say "Testing exception class name 'Exception'";
        throw new Exception("My Message", 1);
    }
    if($i == 1)
    {
        say "Testing exception class name 'myException'";
        throw new myException("My Message", 1);
    }
    if($i == 2)
    {
        say "Testing exception class name 'myException2'";
        throw new myException2("My Message", 1);
    }
}
Catch ( Exception $e )
{
    say "EXCEPTION BRACE";
    say "Message: " . $e->getMessage(); // Gets the default or new message
    say "Code: " . $e->getCode(); // Gets the error code if one exists
}
Catch ( myException $e )
{
    say "myException BRACE";
    say "Message: " . $e->getMessage(); // Gets the default or new message
    say "Code: " . $e->getCode(); // Gets the error code if one exists
}
Catch ( myException2 $e )
{
    say "myException2 BRACE";
    say "Message: " . $e->getMessage(); // Gets the default or new message
    say "Code: " . $e->getCode(); // Gets the error code if one exists
}
Finally
{
    say "This code gets executed regardless if there was an exception or not";
}
 
$i++;
if($i == 3)
    continue done;
say "";
continue begin;
done:{}
say "All done.";

// PRINTS
// Testing exception class name 'Exception'
// EXCEPTION BRACE
// Message: My Message
// Code: 1
// This code gets executed regardless if there was an exception or not
// 
// Testing exception class name 'myException'
// myException BRACE
// Message: My Message
// Code: 1
// This code gets executed regardless if there was an exception or not
// 
// Testing exception class name 'myException2'
// myException2 BRACE
// Message: My Message
// Code: 1
// This code gets executed regardless if there was an exception or not
// All done.

Example of using the When condition:

my $value = 10;
try
{
    throw new Exception("Error!");
}
catch when ($value == 10)
{
    say "catch10";
}
catch
{
    say "catch";
}
finally
{
    say "finally!";
}
// PRINTS
// catch10
// finally!
Lets see what happens when $value is not 10:
my $value = 11;
try
{
    throw new Exception("Error!");
}
catch when ($value == 10)
{
    say "catch10";
}
catch
{
    say "catch";
}
finally
{
    say "finally!";
}
// PRINTS
// catch
// finally!

Example of using the resources:

Class test
{
    Function __construct()
    {
        say "Created.";
    }
    Function __destruct()
    {
        say "Destroyed.";
    }
}

try ($a = new test())
{
    throw new Exception("Error!");
}
catch
{
    say "catch";
}
finally
{
    say "finally!";
}
// PRINTS
// Created.
// catch
// finally!
// Destroyed.

As you can see it freed up the class properly.

Here is an example of using no Catch statements at all:

try
{
    throw new Exception("Error!");
}
finally
{
    say "finally!";
}
// PRINTS
// finally!
We can go a step further and not even include a Finally:
try
{
    say "111";
    throw new Exception("Error!");
    say "222";
}
// PRINTS
// 111

This lets you keep the statement tiny if you so wish.

You can also use a Redo statement here to bascially start the entire Try statement over again it works like so:

my $value = 0;
try
{
    $value++;
    throw new Exception("Error!");
}
finally
{
    say "finally?";
    if ($value < 5)
    {
        redo;
    }
}
// PRINTS
// finally?
// finally?
// finally?
// finally?
// finally?

As you can see the Redo statement causes the entire thing to start over.

You can use If/Unless with a throw like so:

my $value = 11;
try
{
    throwIf($value == 11) new Exception("Error!");
}
catch
{
    say "catch";
}
finally
{
    say "finally!";
}
// PRINTS
// catch
// finally!

my $value = 11;
try
{
    throwUnless($value == 11) new Exception("Error!");
}
catch
{
    say "catch";
}
finally
{
    say "finally!";
}
// PRINTS
// finally!

The core Exception class can be found here.


Contact
Cheryl (uberfox@hotmail.com)
Homepage
http://ubersoft.org