Program Segmentation and Source Merging

When your code base becomes very large, dividing it into smaller sections can greatly aid in code maintenance. The %include directive is designed for this purpose. It tells the compiler to insert the contents of another file at that point in the program.

The %include directive supports two optional modifiers:

• continue — Tells the compiler to proceed even if the include file is missing or cannot be opened. This enables conditional inclusion of platform-specific or optional modules.
• once — Ensures that the file is included only once, even if referenced multiple times (directly or indirectly). This avoids duplicate declarations during nested includes.

Include files can also be nested—an include file can itself contain additional %include directives. This allows you to create reusable, modular layers of code for better organization.

Simple Include Example

Suppose we have a file named safe_common.spinc that defines some shared data and a utility routine:

You can include this file in your main program like this:

Large business applications can easily contain hundreds of thousands of lines of code. These applications are greatly simplified by using many include directives. Typically, each include file contains all the variables and routines needed to perform a specific subtask.

Example: Nested Includes with once

The following example demonstrates how include files can reference other include files. We use the once modifier to ensure that files are not included more than once, even when nested.

When main.spsrc is compiled, it automatically brings in both common.inc and logging.inc. Thanks to once, even if logging.inc is included from multiple files, it is compiled only once.

Analyzing Programs with the /MERGE Compiler Option

When large applications use many %include files, it can be helpful to view the program as a single expanded source file. This is especially useful for AI analysis and static code inspection, where tools benefit from seeing the entire program in one place. The Sheerpower compiler provides a command-line option for generating this expanded view.

Running the compiler with the /merge option tells Sheerpower to write a new source file that contains the main program with all %include files expanded directly into the output.

When this option is used, the compiler produces a file named programname_merge.spsrc. This file contains the original program with every included file inserted at the exact location where the %include directive appeared.

The generated file is intended for inspection and analysis. It allows developers to view the entire program structure in one place, even when the real project is split across many include files.

Example

Suppose a program contains the following directive:

When compiled with /merge, the contents of tax_rules.inc will appear inline in the generated programname_merge.spsrc file exactly where the %include statement occurs.

Nested includes are also expanded. If an include file itself contains additional %include directives, those files are expanded as well. The result is a fully flattened source listing that represents the complete program seen by the compiler.