Locating Macros and Include files

Contents of Article

Introduction

As stated previously, macros are stored in the SPFLite MACROS folder, which will be

C:\Users\username\My Documents\SPFLite\MACROS

If you are writing a simple, one-file macro, that is all you need to know. If you are writing a large macro in a modular fashion, or are writing a series of related macros having code in common, you would benefit from using #INCLUDE statements to organize your macro code into smaller and more manageable pieces.

The macro engine we use, called thinBasic, allows for #INCLUDE statements. However, in earlier versions of SPFLite, these were not convenient to use. According to the thinBasic documentation, an #INCLUDE statement with no explicit path is searched for in the following order:

the current script path
\thinBasic\inc
any #INCLUDEDIR paths in effect

When thinBasic is integrated into other software like SPFLite, step 2 becomes "\Program Files\SPFLite\inc". That can be a problem. Putting changeable user data under the Program Files directory is not a good idea, and starting with Windows 7, you may need Administrator privileges to do that. Since SPFLite has already set aside the MACROS folder, it makes more sense to be looking for included macro files there.

Automatic modification of the #INCLUDE statement at run time

To make this process simpler, SPFLite now will modify your #INCLUDE statements, so that if it detects a file name that has no "path qualifier" at the beginning of the name, the location of the SPFLite MACROS folder is added to the file name. That way, any "simple" names you use on #INCLUDE statements will automatically be searched for in the same place that your main macro is located.

This "modification" to your #INCLUDE statements only involves altering an internal copy of these statements in memory, as they are being processed. Your #INCLUDE file itself on disk is not changed. SPFLite will never modify your macro or include files.

In deciding when to apply this modification, the beginning of the file name is examined. If that name begins with / or \ or . or if the second character of the name has a : colon, it is assumed to have an "explicit path", and the file name is not modified.

Note that included file names do not have to end with .macro but can be anything you wish. A common extension is .inc but that is entirely up to you.

This automatic modification of #INCLUDE statements is done only in the main macro file, not in nested files included by the main macro file. That is because these are read by thinBasic directly, and SPFlite does not "see" them.

For instance, if you write an #INCLUDE statement like this,

#INCLUDE "myfile.inc"

The name "myfile.inc" does not begin with / or \ or . or a drive letter like C:. SPFLite will see that there is no path qualifier on the file name, and will internally change the statement to something like this:

#INCLUDE "C:\Users\username\My Documents\SPFLite\MACROS\myfile.inc"

Automatic insertion of #INCLUDEDIR directive at run time

Like many languages, thinBasic allows #INCLUDE statements to be nested. When you do this, thinBasic itself reads those nested files. SPFLite is not involved in that process, and does not read or see nested #INCLUDE statements. Because of this, the special handling described above is not done for such nested includes.

To help with this situation, SPFLite will automatically insert an #INCLUDEDIR directive just prior to the first #INCLUDE statement it detects in your main macro file (again, this is done internally - not to your macro file on disk). The "created" #INCLUDEDIR directive will specify the path to the SPFLite MACROS folder, so that nested includes will be searched for there.

The #INCLUDE and #INCLUDEDIR statements are documented in the thinBasic Help. Issue a HELP BASIC command from SPFLite to bring up this Help.

Suppose you wanted you write your own #INCLUDEDIR directives as well. Will that work? Yes. You need to specify any desired #INCLUDEDIR directives prior to your first #INCLUDE statement. This will cause thinBasic to look for included files in the locations you specify, in the order you write them. SPFLite will simply ensure that, if an included file is not found in any of those locations, it will look in the SPFLite MACROS folder as a "last resort" search location.

This process should be taken into account if you are planning on creating some complicated search-path for a very involved macro or set of macros, that might also involve multiple versions of files (like, "test" vs. "production" versions). If you put a copy of an included file in the SPFLite MACROS folder, and you issue an #INCLUDE statement that, for whatever reason, does not find this file elsewhere, it will look the file in the SPFLite MACROS folder as the default search location. If that is not what you want, you should not put files in that default folder, but only in the explicit locations you need them to be in.

If your macro never issues an #INCLUDE statement, it will not insert this #INCLUDEDIR directive.

Support for SET names in #INCLUDE statements

You may wish to organize your included files into folders other than the default SPFLite MACROS folder, but you also would probably not like to use absolute path names embedded in your #INCLUDE statements. SPFLite now allows you do to this.

If you write an #INCLUDE statement like this,

#INCLUDE "=abc\myfile.inc"

SPFLite will look up the SET name you specify ("abc" in the example) and substitute the value of the SET variable into your #INCLUDE statement. SET names are defined by the SET primary command.

Suppose you issued the following SET primary command:

SET abc = "C:\mypath"

Then, when you run your macro that has the #INCLUDE statement above, the SET name is detected and looked up, and it value is substituted prior to thinBasic processing it. So, the file that actually gets included is:

#INCLUDE "C:\mypath\myfile.inc"

If your SET name "abc" happens to be undefined when you run your macro that has the #INCLUDE statement above, SPFLite will not attempt to modify it. You will then get a syntax error message from thinBasic that the name "=abc\myfile.inc" could not be found.

This modification of #INCLUDE statements to substitute SET name values is done only in the main macro file, not in nested files included by the main macro file. That is because these are read by thinBasic directly, and SPFlite does not "see" them.

Using relative paths for included files

If you want to organize a group of included files into its own folder, but you'd like to keep the process simple, you can use relative paths to accomplish this.

Suppose you wanted a set of included files to be stored under a folder called "xyz". To do this, create a folder with the name "xyz" under the SPFLite\Macros directory. Then, you would write your #INCLUDE statements like this:

#INCLUDE "xyz\myfile.inc"

The name "xyz\myfile.inc" does not itself begin with / or \ or . or a drive letter, even though there is a backslash after the "xyz" part. SPFLite will see that there is no path qualifier on the file name, and will internally change the statement to something like this:

#INCLUDE "C:\Users\username\My Documents\SPFLite\MACROS\xyz\myfile.inc"

Created with the Personal Edition of HelpNDoc: Free EBook and documentation generator