====== The BASIC Preprocessor ======

The BASIC preprocessor is a macro processor that is used automatically by
the compiler to transform your program before compilation. It is called a
macro processor because it allows you to define macros, which are brief
abbreviations for longer constructs.

Cubloc BASIC uses a preprocessor similar to the C language. Preprocessor
directives like #include and #define can be used to include files and
process code before compiling.

===== #include "filename" =====

Reuse code by including source files. For files in the same directory as the
current source file, you can write the following:

<code xbasic>
#include "MYLIB.cub"
</code>

For files in other directories, you will need to include the full path name as
shown here:

<code xbasic>
#include "c:\mysource\CUBLOC\lib\mylib.cub"
</code>

Using include files, you can store all of your common subroutines in a
separate file. In this case, please make sure to #include the subroutine
file at the very end of your program, after the End statement.

===== #define name constants =====

By using #define, you can assign names to values before compiling.

<code xbasic>
#define motorport 4
Low motorport
</code>

In the example above, motorport will be compiled as 4. You can also use
CONST for similar tasks. However, CONST will use data memory; #define will
only use program memory.

<code xbasic>
CONST motorport = 4
Low motorport
</code>

The following example uses #define for replacing a line of code:

<code xbasic>
#define FLAGREG1 2
#define f_led FLAGREG1.BIT0
#define calc (4+i)*256
f_led = 1 ' Set FLAGREG1’s bit zero to 1.
If f_led = 1 Then f_led = 0 ' Make it easier to read.
j = calc 'Calculations can be simplified
</code>

===== NOTE =====
The "name" argument in a #define statement is not case-sensitive. For
example, #define ALPHA 0 and #define alpha 0 do not define different
constants. They both define the same constant.

{{ :cubloc:the_basic_preprocessor:define.png?nolink |}}

====== Conditional Directives ======

A conditional directive is a directive that instructs the preprocessor to select
whether or not to include a part of code before compilation. Preprocessor
conditional directives can test arithmetic expressions, or whether a name is
defined as a macro.

Here are some reasons to use a conditional.

A program may need to use different code depending on the module it is
to run on. In some cases the code for one module may be different
on another module. With a conditional directive, a BASIC program
may be programmed to compile on any of the Cubloc/Cutouch
modules without making changes to the source code.

If you want to be able to compile the same source file into two different
programs. For example one version might be compiled with
debugging statements, and one without.


===== #if constant ... #endif =====

The preprocessor directive #if will compare a constant declared with CONST
to another constant. If the #if statement is true, the statements inside
the #if…#endif block will be compiled, otherwise the statements will be
discarded.

<code xbasic>
Const Device = CB280
Delay 500
' Device only returns the decimal number
#If Device = 220
 Debug "CB220 module used!"
#endif
</code>

The above example illustrates how, depending on the type of
Cubloc/Cutouch declared, you can decide to include a command in the final
compilation of your program. Using conditional directives, you will be able
to write applications for different Cubloc/Cutouch modules with just one
source file.

Using the preprocessor directive #elseif or #else, you can create more
complex #if…#endif expressions.

<code xbasic>
Const Device = CB220
Delay 500
' Device only returns the decimal number
#If Device = 220
  Debug "CB220 module used!"
#elseif device = 280
Debug "CB280 module used!"
#elseif device = 290
Debug "CB290 module used!"
#elseif device = 1720
Debug "CT1720 module used!"
#endif
</code>

#else may only be used ONCE in an #if expression. Also, you can only
compare constants declared with the CONST statement in a #if directive.

===== #ifdef name ... #endif =====

You can use #ifdef to check if a constant was previously defined with a
#define directive or CONST statment. If the constant has been previously
defined, the statements inside the #if…#endif block will be compiled,
otherwise they will be discarded.

<code xbasic>
#define LOWMODEL 0
#ifdef LOWMODEL
Low 0
#endif
</code>

In the above example, since LOWMODEL is defined, the statement LOW 0 is
compiled.

#else #elseifdef may be used for more complex expressions as shown below:

<code xbasic>
#ifdef LOWMODEL
    Low 0
#elseifdef HIGHMODEL
    High 0
#else
    Low 1
#endif
</code>

===== #ifndef name ... #endif =====

#ifndef is the opposite of the #ifdef directive. If a constant has not been
defined, the statements inside a #ifndef…#endif block will be compiled,
otherwise the statements will be discarded.

<code xbasic>
#define LOWMODEL 0
#ifndef LOWMODEL
    Low 0
#endif
</code>

#elseifndef and #else may be used for more complex expressions as
shown below:

<code xbasic>
#ifndef LOWMODEL
    Low 0
#elseifndef HIGHMODEL
    High 0
#else
    Low 1
#endif
</code>

Finally, the directives may be mixed as shown below:

<code xbasic>
#if MODELNO = 0
    Low 0
#elseifdef HIGHMODEL
    High 0
#else
    Low 1
#endif
</code>

Nested #if directives are not supported; #if may not be used inside
another #if.

[[cubloc:index:|Go CUBLOC home]]