Skip to content

Latest commit

 

History

History
187 lines (117 loc) · 6.88 KB

Preprocessor.md

File metadata and controls

187 lines (117 loc) · 6.88 KB

Pnut reimplementation in TypeScript (Pnut-TS)
The PNut-TS Preprocessor

Project Maintenance

License: MIT

NodeJS

Release

GitHub issues

PNut-TS Preprocessor Command line options

A couple of command line options affect the preprocessing:

Option Effect
-D <symbol>
Defines a symbol that can be tested with the #ifdef, #ifndef, #elseifdef or #elseifndef statements
-U <symbol>
Prevents a subsequent #define <symbol> found in the .spin2 code from having any effect
-I <directory>
Specify the folder to search within for `#include "filename(.spin2)" statements
-- Diagnostic Use --
-i, --intermediate
Generate *-pre.spin2 after preprocessing - so you can review what preprocessed source was fed to the compiler

NOTE: These directives apply to all .spin2 files processed in the compile effort, not just the top-level file. This means that the compilation of all #included files and all files specified in the OBJ block of each object will be affected by these -D and -U options.

Preprocessor Directives

PNut-TS has a pre-processor that understands a few primitive directives:

  • #define
  • #undef
  • #ifdef / #ifndef / #else / #endif
  • #elseifdef / #elseifndef
  • #error / #warn
  • #include

Here's more detail on each of the supported directives

If you see the similarity to the FlexSpin directive set, you are correct! This capability was patterned after the directives supported by FlexSpin so that there will be fewer compatibility issues when utilizing spin2 code with either compiler.

Directives

#define {symbol} {value}

#define FOO hello

Defines a new symbol FOO with the value hello. Whenever the symbol FOO appears in the text, the preprocessor will substitute hello.

Note that, unlike the traditional preprocessors, this preprocessor does not accept arguments. Only simple defines are permitted.

Also note that this preprocessor is case insensitive, just like spin.

If no value is given, e.g.:

#define BAR

then the symbol BAR is defined as the string 1. This is generally useful when symbol presence is being used, not the value. That is to say that the symbol is being tested by following preprocessor directives and is not expected to be replacing text within the containing file.

#ifdef {symbol}

Introduces a conditional compilation section, which is only compiled if the symbol after the #ifdef is in fact defined. For example:

#ifdef __P2__
'' propeller 2 code goes here
#else
'' propeller 1 code goes here
#endif

#ifndef {symbol}

Introduces a conditional compilation section, which is only compiled if the symbol after the #ifndef is not defined.

#ifndef __P2__
'' propeller 1 code goes here
#else
'' propeller 2 code goes here
#endif

Pardon this non-traditional example, but you get the point, right?

#else

Switches the meaning of conditional compilation. Must be preceded by a #ifdef or a #ifndef.

#endif

Ends the conditional compilation #ifdef or #ifndef clause.

#elseifdef {symbol}

A combination of #else and #ifdef. Must be preceded by a #ifdef or a #ifndef.

#elseifndef {symbol}

A combination of #else and #ifndef. Must be preceded by a #ifdef or a #ifndef.

#error {msg}

Prints an error message. Mainly used in conditional compilation to report an unhandled condition. Everything after the #error directive is printed. Example:

#ifndef __P2__
#error This code only works on Propeller 2
#endif

#include "{filename}"

Includes a file. The contents of the file are placed in the compilation just as if everything in that file was typed into the original file instead.

#include "foo.spin2"
#include "bar"

Included files are searched for in the same directory as the file that contains the #include. Or, alternatively, in an include directory provided by the compilation -I <dir> clause on the command line. If one or more include directories are specified, then they will be searched first.

NOTE: if the .spin2 suffix is not present on the filename provide in the include statement it will be appended to the name given before opening the file. Meaning all included files will only be .spin2 files. If any suffix is provided that is not .spin2 this will generate an error and stop the compile.

#warn {msg}

#warn prints a warning message; otherwise it is similar to #error.

#undef {symbol}

Removes a prior definition of a symbol, e.g., to undefine FOO do:

#undef FOO

Removes the user-defined symbol FOO if it was defined.

Note that #undef will not do anything if one of our built-in symbols was named.

Predefined Symbols

There are several predefined symbols:

Symbol When Defined
__propeller__ defined as 2 (for Propeller 2)
__P2__ defined as 1 (compiling for Propeller 2)
__propeller2__ defined as 1 (compiling for Propeller 2)
__PNUTTS__ defined as 1, indicating that the PNut-TS compiler is used
__DATE__ a string containing the date when compilation was begun
__FILE__ a string giving the current file being compiled
__TIME__ a string containing the time when compilation was begun
__VERSION__ a string containing the full version of PNut-TS in use (e.g., 'v1.43.0')
__DEBUG__ defined as 1 only if compiling debug() statements is enabled (-d given)

If you like my work and/or this has helped you in some way then feel free to help me out for a couple of ☕'s or 🍕 slices or support my work by contributing at Patreon!

coffee    -OR-    PatreonPatreon.com/IronSheep


License

Licensed under the MIT License.

Follow these links for more information: