SparForte - Reference - Block Statements and Subprograms

Intro

Tutorials

Reference

Packages

Examples

Contributors

Block Statements and Subprograms

Bush scripts can be organized using declare blocks, procedures and functions. This enables pieces of a program to be easily reused. A procedure is a routine that can be called but returns no value. For example, put_line is a procedure. A function always returns a value so it can be used as part of an expression. strings.length is an example of a function which responds with the length of a string.

Overall Structure

An AdaScript script consists of a sequence of executable statements. These statements can appear as a simple list or can be enclosed in a "library" unit. The basic library unit is a main procedure (or sometimes called a main program or main subprogram). Other library units may be introduced in the future (such as packages).

If pragma ada_95 is used, the statements must be enclosed in a library unit.

Some features may not be available with a simple list of statements.

Declare Block

Declare blocks (also called block statements) contains a sequence of statements or commands that can include locally declared variables. Declare blocks are located in the executable part of a script. Between declare and begin, declarations can be made. Between begin and end are executable statements. The declarations are visible to these executable statements.

A new block can be created without declaration any variables by using begin...end without the declare section.

declare
i : integer := 5;
begin
? i;
end;

Example: The Declare Block Statement

Procedure and Function Blocks

Repeatable blocks of a series of instructions (like Perl sub or Python def) can be created with the word procedure or function. A procedure is a set of instructions with a name. A function is a set of instructions with a name that computes and returns a value and can be used in an expression. Like a declare block, local variables can be declared before the word begin. Procedure and function subprograms must finish with end and the name of the subprogram: this is to clarify the structure of the program.

Ada: In Ada, the name of the subprogram is optional after end. In AdaScript, the name is required.

procedure print_title is
begin
put_line( "Script to Process New Orders" );
new_line;
end print_title;

Example: The Procedure Subprogram Statement

Procedures and functions may be nested: you can declare them in the declaration parts of another procedure, function or declare block. These nested subprograms only exist for the scope of this parent block.

A procedure may be terminated early using a return statement. A function uses return to return back a value.

Ada: AdaScript doesn't support creating new arithmetic operators by defining functions with operator symbols.

Procedure and Function Parameters

Both procedures and functions can have parameters. If a procedure or function has no parameters, do not include any parantheses. If there are parameters, they are listed with a name, a mode and a type. All parameters are "in" mode parameters: they give additional information to a subprogram and are treated as constants. The word "in" is optional before the type of parameter.

function add_two( number : integer ) return integer is
begin
return number+2;
end add_two;

Example: The Function Subprogram Statement

Procedures and functions can only declared inside the declaration section of a script's main procedure block (or declared nested inside other subprograms or declare blocks).

procedure my_script is
procedure my_proc is -- OK
...
end my_script;

Example: A Main Program Procedure

That is, they must be in a script that has a main procedure block.

i : integer;
i := 5;
procedure my_proc is -- BAD...use a main procedure block
...

The built-in procedures and functions found in the SparForte packages may include parameters with other modes. in out mode means the value of the parameter is used by the subprogram and may be changed. out mode means the parameter is not read by the subprogram but a value will be returned using the parameter. Functions may only use in mode. The modes are described on the front page of the Packages section of this documentation.

Ada: in out, out and access mode parameters are not supported for user-defined subprograms. Named parameters are not supported. Default values are not supported.

Forward Subprograms and Recursion

Forward declarations and recursion are planned but not yet implemented.

Separate Subprograms

Procedures and functions maybe loaded from a separate file. (This is referred to as a "subunit": a feature of a script stored in a separate file).

Copy your subprogram (or create a new one) and put it in a file with the name of the subprogram. For example, if you have a separate procedure called "t2", put it in a file called "t2.sp". The filename must match the name of the subprogram.

Separate subprograms must begin with a separate statement as the first line in the file. This indicates that the file is not an executable script. The separate statement should include the name of the parent script. Each separate subprogram belongs to a single, specific parent script.

-- t2.sp is a separate procedure
separate( t );
procedure t2 is
begin
put_line( "t2 was called!" );
end t2;

Example: t2.sp is a loadable by a script named t.sp

In the parent script (the one that will load the subprogram), declare the subprogram but replace the body of the subprogram with the word separate.

procedure t is
procedure t2 is separate;
begin
t2;
end t;

Example: t.sp loads t2.sp and executes t2

SparForte will search for the separate subprogram using the SparForte library path. The path is specified using the -L command option or using the environment variable SPAR_LIBRARY_PATH. By default, SparForte will search the current directory. The separate subprogram must exist and be readable in order to load it.

In SparForte, procedures and functions can be nested. Support for separate nested subprograms is planned but not yet implemented.

Separate subprogram blocks are similar to include files in other languages except that the separate block is a part of a specific main script.

Ada: GCC Ada also has separate subunits. They are implemented in the same way.

Separate Declarations

A separate declaration file is the SparForte equivalent of an include file. It is an set of declaration statements stored in a separate file. The file can include variables, constants, types, functions, procedures, pragmas, etc. A declaration file is used to share common declarations across many scripts.

The separate declaration file is inserted into another script using "with separate". Since the declaration file is inserted, they have the same scope as the declaration block they are used in. Any subscript pragmas will also affect the file loading the declaration file. The with separate statement can occur in a declaration section of any block (a main procedure, procedures, functions or a declare block).

procedure main is
with separate "globals.sp";
begin
? company_name; -- displays "PegaSoft"
end main;

Example: Loading a separate declaration file

Unlike separate procedures / functions, declaration files are not tied to a particular script. The subscript fragment must have "separate" as its first statement. This identifies it as a separate declaration file.

-- This is the file named globals.sp
separate;
company_name : constant string := "PegaSoft";

Example: A very short separate declaration file containing one constant

Like separate subprograms, SparForte will search for the declaration file using the SparForte library path. The path is specified using the -L command option or using the environment variable SPAR_LIBRARY_PATH. By default, SparForte will search the current directory. The declaration file must exist and be readable in order to load it.

The separate declaration file may contain more "with separate" statements. If the same file is included twice in the same scope, duplicate declaration errors will occur. Having a file include itself, or having a nested with separate include the file, will result in a loop and SparForte will report an error.

Subscripts are loaded before a script starts execution. If you do something unusual such as to create a for loop containing a declare block with a "with separate", the with separate only executes once. However, the subprograms contained in the separate declaration file will access the new variable values as the for loop iterates, just as if they were declared without the with separate.

Subscripts are permitted with pragma ada_95, even though they are not a part of the Ada 95 standard, to allow large scripts to be broken up.

Subscripts are permitted in a restricted shell to allow large scripts to be broken up.

Implementation Note: with separate has a string literal as a parameter. Because the separate file is loaded before the program is running, any variables that might contain the file path cannot exist when the file is loaded. So you're stuck with a string literal.

Rationale: Subscripts are intended as a simple mechanism to break up large scripts until loadable user-defined packages are completed.