harbour-core/harbour/doc/pragma.txt

/*
 * $Id$
 */

INTRODUCTION
============
This file explains what is and how to use the #pragma directive
with Harbour. Primarily, it gives you control over the compiler's
command-line switches within your source code.


WHAT IS
=======
The #pragma is a directive used inside the source code in many compilers
to change the behavior of the compiler at compile time.


USAGE
=====
Currently the #pragma directive can be used in two ways: the switch mode
and the command mode.

The syntax is:  #pragma <Expression>[=On/Off] or
                #pragma -CompilerFlag[+|-]

You can use both modes mixed in the same module and upper/lower case
without worry.

To enable or disable a command or a switch you simply do:

  * Command mode                      Switch mode
  --------------------------------------------------------------
  * #pragma <CommandName>=On/Off      #pragma /<SwitchName>+/-

   Example: #pragma AddDebugInfo=Off  /* Suppress debug info */
            #pragma /B+               /* Add debug info from here */


IMPLEMENTATION
==============

This is the list of the supported commands and switches:

  * Command                           Switch
  -----------------------------------------------
  * AUTOMEMVARS         =<On/Off>     /A<+/->
  * DEBUGINFO           =<On/Off>     /B<+/->
  * ENABLEWARNINGS      =<On/Off>     /W<+/->
  * EXITSEVERITY        =<nLevel>     /E<nLevel>
  * FORCEMEMVARS        =<On/Off>     /V<+/->
  * LINEINFO            =<On/Off>     /L<+/->
  * NOSTARTPROC         =<On/Off>     /N<+/->
  * PREPROCESSING       =<On/Off>     /P<+/->
  * WARNINGLEVEL        =<nLevel>     /W<nLevel>
  * SHORTCUTTING        =<On/Off>     /Z<+/->

  The switches have the same behavior as the corresponding compiler ones
  and the commands are synonyms for the switches.

  * TRACEPRAGMAS
  This command shows pragma activity at compile time when enabled.

  NOTE: You can use the abbreviated command mode by typing only the
        first eight chars.


NOTES
=====
This directive is not supported in the standalone version of the Harbour
preprocessor.


EXAMPLES
========

#pragma NoStartProc=Off
/* #pragma /N- */

function Test()
return nil

This is the same as calling Harbour with the -n switch in the command line,
but with the great benefit that if you forgot to pass the switch, it will
be used anyway because it is included inside the source.

===========
Dec 1, 1999
Regards,
Jose Lalin <dezac@corevia.com>


SPECIAL PRAGMAS
===============
  These pragmas allows to control the processing of PRG source within
the preprocessor. The special handling is done with a text enclosed
betwen the '#pragma <type>' and '#pragma __endtext'

#pragma __text
--------------
Syntax:
  #pragma __text '|' [LineOutputCode] '|' [FinallyCode] '|' [StartupCode]

  Every line of text is stringified using '[' and ']' markers and is
  passed to 'LineOutputCode' using C '%s' formating code. The result
  text is passed further to the syntax analyzer. The 'StartupCode'
  is returned at the very beginning of procesing. The 'FinallyCode'
  is returned at the end. If 'LineOutputCode' is ommited then all
  lines are ignored.

  For example, this pragma is used to implement TEXT/ENDTEXT command

  #command TEXT => #pragma __text|Qout(%s)|QQout()
  #command TEXT TO PRINTER => ;
           #pragma __text|Qout(%s)|__TextRestore()|__TextSave("PRINTER")
  #command TEXT TO FILE <file> => ;
           #pragma __text|Qout(%s)|__TextRestore()|__TextSave(<"file">)


?
#xcommand TEXT INTO <v> => #pragma __text|<v>+=%s+HB_OSNEWLINE();<v>:=""
?

#pragma __stream
----------------
Syntax:
  #pragma __stream '|' [JoinLineCode] '|' [EndingCode] '|' [StartingCode]

  All lines are joined together. The result text is stringified and is
  appended to 'StartingCode'. Finally the 'EndingCode' is appended.
  The resulting text is returned for further syntax analysis.

  For example:

  #command TEXT TO VAR <var> => ;
           #pragma __stream|%s||<var>:=


?
#xcommand TEXT TO VAR <var> => #pragma __stream|<var>:=%s
?

  TEXT TO VAR v
  This is 'example' text with ''""[] embeded
  ENDTEXT

  The above example is preprocessed into:
  v:=[This is 'example' text with ''""[] embeded]

#pragma __cstream
----------------
Syntax:
  #pragma __cstream '|' [JoinLineCode] '|' [EndingCode] '|' [StartingCode]

  This is simmilar to '#pragma __stream' with the additional convertion
  of C esc sequences e.g \n \t \r \b

  For example:

  #command TEXT TO VAR <var> => ;
           #pragma __cstream|%s||<var>:=

  TEXT TO VAR v
  This is 'example' text with ''""[] embeded and C \n
  sequence
  ENDTEXT
  ? v

  The above example is preprocessed into:
  v:=[This is 'example' text with ''""[] embeded and C \nsequence]
  qout(v)

  and at runtime the following is printed:

  This is 'example' text with ''""[] embeded and C
  sequence

#pragma __endtext
-----------------
Syntax:
  #pragma __endtext

  This pragma is used to finish the special processing defined with
  #pragma [__text | __stream | __cstream]

  The following command is hardcoded in the preprocessor:

  #xcommand ENDTEXT => #pragma __endtext

#pragma RECURSELEVEL
--------------------
Syntax:
  #pragma RECURSELEVEL <nNumberOfIterations>

  This pragma sets the maximum number of preprocess iterations during
  the source code translation. The default value is 1024.
  This is the same as /r= command line switch

  For example:

  #pragma   RECURSELEVEL 2048