Inclusions

This page explains how to use include files in Simple Issue Language (SIL) programs.

The include statement in SIL lets you import and execute code from other SIL files. This can improve readability and make your code more manageable.

You can use the include statement to:

Import entire libraries of User-defined functions (UDFs).
Break down large programs into manageable components.
Share common functionality across multiple scripts.

Contents:

Syntax

Inclusions in SIL use the following syntax:

include "path/to/file.incl";

Here are some key points to remember when using inclusions in your SIL programs:

Include statements must appear at the beginning of your program, before any user-defined functions definitions.
File paths can be relative or absolute.
Relative paths are resolved relative to the defined sil.home environment variable (typically the silprograms directory in the SIL Manager.)
To maintain consistency, consider using the .incl extension for included files.

For more information, see Structure of a SIL™ program.

Variable visibility

There are two categories of variables you can use in the included programs.

You can use two categories of variables in the included files:

Variable category

Definition

Example

Local

These are the variables you define in the body of the included program. They are accessible throughout the included file, the main program, and any other program that uses the included code.

file.incl

// Define a simple increment function
function increment(int x) {
  return x + 1;
}

// Create and initialize a variable using the function
// This variable will be accessible to any program that includes this file
number a = increment(0);  // a is now equal to 1

program.sil

// Import the contents of file.incl
include "file.incl"; //resolved relative to the 'sil.home'

// We can use both the 'a' variable and increment() function defined in file.incl
number b = a + increment(2); 
// Here's what happens:
// 1. 'a' has value 1 from file.incl
// 2. increment(2) returns 3
// 3. b becomes 1 + 3 = 4

Global

These are the variables that are already defined and can be used right away (issue fields and custom fields). You can use these anywhere in your code without having to declare them.

file.incl

function getKey() {
  return key;    // 'key' is a global issue field
}

Header guards

Header guards prevent duplicate inclusion of the same code, which is particularly important when you have complex include relationships. They were introduced in Power Script 5.8.x to automatically handle situations where the same code might be included multiple times (accidentally or intentionally) through different paths.

Here’s how header guards work:

When you include a file, SIL first checks if this file has already been processed.
If it's the first time, the code is included.
If the file has been previously included, SIL skips it.
This happens automatically - no additional syntax is required.

Example

In the scenario illustrated in the image below, the main script includes File A and File B. Also, both File A and File B are using include file C. The inclusions are handled differently with and without header guards.

Here’s what happens in older versions of Power Script and in Power Script 5.8.x and later.

Without header guards, you get an error and must remove one of these includes from your code.
With header guards, even though file C is referenced twice (through both A and B), it will only be loaded once. It's loaded the first time it's encountered and automatically skipped on subsequent includes, preventing any errors.