---
title: "Structure of a SIL program"
canonical: "https://support.appfire.com/space/PSJ/15488481/Structure%20of%20a%20SIL%20program"
format: markdown
---
> Macro (aura-html)


> ℹ️ This page provides a foundational overview of how Simple Issue Language (SIL™) programs are organized and gives a concrete example of the structure of a SIL program. Understanding the basic components of the structure will help you contextualize all other concepts introduced later in this guide.

## Structural components

### Inclusions

Include statements must appear first or after use declarations. 

- They use the `#include` directive.
- They allow you to import libraries of user-defined functions or add code fragments to your program.
- Imported files' names typically end with the `.sil` extension.

> ℹ️ #### Learn more
> ℹ️ 
> ℹ️ For more information, see [Inclusions](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15487128).

### Use declarations

SIL uses packages to streamline function naming and usage and make code more concise. 

- Packages allow functions to be called by short names, reducing typing effort.
- To use short names for functions, you must declare package uses.

> ℹ️ #### Learn more
> ℹ️ 
> ℹ️ For more information and usage, see [Packages](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15480537).

### Variable declarations

In this section of the SIL program, you declare global variables available throughout the program. 

- You can declare various types of variables, such as `string`, `number`, and `array`.
- Variables can be initialized with default values.
- It is a best practice to group related variables together.

> ℹ️ #### Learn more
> ℹ️ 
> ℹ️ For more information and usage, see the [Variables](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15487006/SIL+Syntax+and+types+introduction#Variables) section on the [SIL Syntax and types introduction](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15487006/SIL+Syntax+and+types+introduction) page.

### User-defined functions declarations

In this section of your SIL program, you can define any functions you want to use in the main code. These user-defined functions (UDFs) can considerably improve the readability and maintainability of the code.

- UDRs must be defined before use, and their names cannot contain spaces.
- Each function should have:
  - Clear name indicating its purpose
  - Defined parameter types
  - Return type specification
  - Proper documentation

> ℹ️ #### Learn more
> ℹ️ 
> ℹ️ For more information, see  [User-defined functions (UDFs)](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15487631).

### Actual code

This is the main body of the program, which contains the primary logic. This is where you input the modifications you want the program to accomplish. The main body can also contain the definition of local variables and calls to the imported or user-defined functions in the steps above. It should end with a `return` statement.

---

## SIL program example

This SIL program example demonstrates the basic structure of a SIL program while performing a common task: 

- Process an issue record to ensure its description field doesn't exceed a maximum length.
- Truncate the text and add an ellipsis if the description field exceeds the maximum length.

```
// ================== INCLUSIONS ==================
include "custom_utils.incl"

// ================== USE DECLARATIONS ==================
use "file";

// ================== VARIABLE DECLARATIONS ==================
const int max_length = 50;

// ================== USER-DEFINED functionS ==================
function truncateDescription(string desc) {
    if (length(desc) > max_length) {
        return substring(desc, 0, max_length) + "...";
    }
    return desc;
}

// ================== ACTUAL CODE (MAIN BODY) ==================
description = truncateDescription(description);

int fid = open(key + "-file.txt");
write(fid, description);
close(fid);
```

The use of inclusions, standard packages, global variables, and custom functions in this example demonstrates the structural organization and modularity of SIL programs.

This breakdown highlights how the different sections of the SIL program work together to achieve the overall goal of truncating long issue descriptions:

| **Component** | **Description** |
| --- | --- |
| **Inclusions** | The `#include "custom_utils.incl"` statement allows the program to access custom functions defined in an external file named `custom_utils.incl`. This is a common way to organize and reuse functionality across multiple SIL programs. We do not impose extensions, but we recommend using `.incl` for includes and `.sil` for SIL files.<br>Files must exist in the root of the hierarchy (that is *silprograms* directory). |
| **Package declarations** | - The `use "file";` statement brings in the standard file package, providing access to text manipulation functions like `open()` and `write()`, used in the program in their short form. They still exist in the library of standard functions, but their full name is `fileOpen()` and `fileWrite()`. Using packages is just a convenience or a shrothand. |
| **Variable declarations** | The `const int max_length = 50` declaration defines a global variable that stores the maximum allowed length for issue descriptions. This can be adjusted as needed. Note that this is a constant and cannot be altered. |
| **User-defined functions ** | The `truncateDescription()` function is a custom function created within this SIL program. It takes a string parameter `desc` and returns a truncated version of the description if it exceeds the `max_length` limit. |
| **Actual code (main body) ** | - The main body tells us that this script must be run in an issue context.
- `description` is never declared because it’s an implicit field in an issue. The line`description = truncateDescription(description); `calls the `truncateDescription()` function and saves the truncated value back in the current issue.
- Finally, we open a file, write the new description from the issue into it, and close it. `int fid = open(key + "-file.txt");` represents a declaration of the file identifier, initialized with the return of the call to open the file. `key` is another standard field of the issue, read-only,  and is not declared, because it is injected into the script at runtime. `key + "-file.txt"` is a concatenation operation between two strings. |