From 8b3ca0354c4c75efef141f7196e0f30648117e4c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Przemys=C5=82aw=20Czerpak?= <druzus@poczta.onet.pl>
Date: Mon, 16 Sep 2013 15:00:28 +0200
Subject: [PATCH] 2013-09-16 15:00 UTC+0200 Przemyslaw Czerpak
 (druzus/at/poczta.onet.pl)   + doc/pp_prg.txt     + added description for
 preprocessor PRG API - __PP_*() functions

---
 ChangeLog.txt  |  4 +++
 doc/pp_prg.txt | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 doc/pp_prg.txt

diff --git a/ChangeLog.txt b/ChangeLog.txt
index 508a4e27a3..bae1b50632 100644
--- a/ChangeLog.txt
+++ b/ChangeLog.txt
@@ -10,6 +10,10 @@
      * Change, ! Fix, % Optimization, + Addition, - Removal, ; Comment
  */
 
+2013-09-16 15:00 UTC+0200 Przemyslaw Czerpak (druzus/at/poczta.onet.pl)
+  + doc/pp_prg.txt
+    + added description for preprocessor PRG API - __PP_*() functions
+
 2013-09-16 11:25 UTC+0200 Przemyslaw Czerpak (druzus/at/poczta.onet.pl)
   * doc/cmpopt.txt
   * doc/xhb-diff.txt
diff --git a/doc/pp_prg.txt b/doc/pp_prg.txt
new file mode 100644
index 0000000000..9571232804
--- /dev/null
+++ b/doc/pp_prg.txt
@@ -0,0 +1,98 @@
+Przemyslaw Czerpak (druzus/at/priv.onet.pl)
+
+In Harbour preprocessor can be used in PRG code.
+This is list of PRG functions available for programmer.
+
+   REQUEST __PP_STDRULES
+      It forces including standard std.ch rules in static binaries.
+      Dynamic binaries linked with harbour dynamic library always
+      includes standard PP rules.
+
+
+   __PP_INIT( [<cIncludePath>] [, <cStdChFile> ] ) -> <pPP>
+      Initialize new PP context and return pointer to it.
+      when <cStdChFile> is empty string ("") then no default rules are
+      used and only the dynamically created #defines like __HARBOUR__,
+      __DATE__, __TIME__, __PLATFORM__* are registered.
+      If <cStdChFile> is missing or NIL and standard PP rules from
+      std.ch are included in binaries (REQUEST __PP_STDRULES) then
+      they are used.
+
+   __PP_PATH( <pPP>, <cPath> [, <lClearPrev>] ) -> NIL
+      Add new (or replace previous) include paths.
+
+   __PP_RESET( <pPP> )
+      Reset the PP context (remove all rules added by user or
+      preprocessed code)
+
+   __PP_ADDRULE( <pPP>, <cDirective> )
+      Preprocess and execute new preprocessor directive
+
+   __PP_PROCESS( <pPP>, <cCode> ) -> <cPreprocessedCode>
+      Preprocess given code and return result
+
+User can create more then one PP context and then use each of them
+separately. Any modifications in one context have no effect in other
+so different PP contexts can be used simultaneously in MT programs.
+To free allocated PP context is enough to clear <pPP> variable.
+When last instance of this variable in user code is cleared then
+automatic destructor frees PP context with its all internal data
+so even if variable is not explicitly cleared by assigning NIL but
+is out of scope (e.g. local variable when program leaves the function)
+PP context is freed.
+
+Below is simple test program which preprocess file and executes
+it's lines by macro compiler:
+
+
+   /*** macro.dat ***/
+   #define VALUE 123.45
+   #xcommand INFO <data> => Alert( <data> )
+   ? "Hello!"
+   WAIT
+   INFO "Let's test simple calculation."
+   pow := 2
+   ? "value =", VALUE
+   ? "pow =", pow
+   ? "value * pow =", VALUE * pow
+   WAIT
+   ? VALUE2 // generate RTE
+
+
+   /*** testpp.prg ***/
+   REQUEST __PP_STDRULES
+   PROC Main()
+      local cLine, pPP, oErr
+      pPP := __PP_INIT()
+      BEGIN SEQUENCE WITH {|oErr| BREAK( oErr ) }
+         FOR EACH cLine IN hb_ATokens( StrTran( __PP_Process( pPP, ;
+               hb_MemoRead( "macro.dat" ) ), Chr( 13 ) ), Chr( 10 ) )
+            BEGIN SEQUENCE
+               IF !Empty( cLine )
+                  &cLine
+               ENDIF
+            RECOVER USING oErr
+               ? "MacroCompiler error at line:", ;
+                 hb_ntos( cLine:__enumIndex() )
+               ? cLine
+               ? ErrMsg( oErr )
+            END SEQUENCE
+         NEXT
+      RECOVER USING oErr
+         ? ErrMsg( oErr )
+      END SEQUENCE
+      ?
+   RETURN
+
+   STATIC FUNCTION ErrMsg( oErr )
+   RETURN "Error " + ;
+          iif( HB_ISSTRING( oErr:subsystem ), ;
+               oErr:subsystem, "???" ) + ;
+          iif( HB_ISNUMERIC( oErr:subCode ), ;
+               "/" + hb_ntos( oErr:subCode ), "/???" ) + ;
+          iif( HB_ISSTRING( oErr:description ), ;
+               " " + oErr:description, "" ) + ;
+          iif( ! Empty( oErr:filename ), ;
+               " " + oErr:filename, ;
+               iif( ! Empty( oErr:operation ), ;
+                    " " + oErr:operation, "" ) )