Harbour/xharbour Diff :13/57 - USING [] OPERATOR FOR STRING ITEMS - Przemyslaw Czerpak

###    USING [] OPERATOR FOR STRING ITEMS    ###
================================================
xHarbour supports using [] operator to access single characters in
string items. Harbour doesn't by default but it has strong enough
OOP API to allow adding such extension without touching core code
even by user at .prg level. It was implemented in Harbour in XHB.LIB.
This code can be compiled and executed by both compilers:
      #ifndef __XHARBOUR__
         #include "xhb.ch" // add xHarbour emulation to Harbour
      #endif
      proc main()
         local s := "ABCDEFG"
         ? s, "=>", s[2], s[4], s[6]
         s[2] := lower( s[2] )
         s[4] := lower( s[4] )
         s[6] := lower( s[6] )
         ?? " =>", s
      return

Warning!. There is one difference in above implementation introduced
intentionally to Harbour. xHarbour never generates errors for wrong
indexes in [] operator used for string items but simply returns "",
f.e. add to above code:
      ? ">" + s[0] + "<", ">" + s[1000] + "<"
If [] operator is used for other type of items RTE is generated.
Harbour will generate RTE in all cases. If someone needs strict XHB
compatibility here then he should adopt code overloading [] operator
for strings in XHB.LIB for his own preferences removing the RTE.

Harbour/xharbour Diff :12/57 - MULTIVALUE MACROS by Przemyslaw Czerpak

In the early Harbour days was added basic support for multivalue macros
which can be evaluated to list of values, f.e.:
      ? &("1,2,3")
should show:
      1,  2,  3
The implementation of this extension was not accepted by many of Harbour
developers and it was one of the main reasons of the xHarbour fork.
In Harbour it was later fully removed and implemented from scratch using
different internal algorithms and structures. Now Harbour supports multivalue
macros in code like:
      proc main()
         local s1 := "'a', 'b', 'c'", s2 := "1,3", a
         ? &s1
         a := { { "|", &s1, 'x', &s2, 'y' }, 'x', &s2 }
         ? "a[1] items:"
         aeval( a[1], { |x,i| qout( i, x ) } )
         ? "a["+s2+"] =>", a[ &s2 ]
      return

xHarbour which inherited the original implementation after over 6 years
still cannot execute correctly above code.

Harbour/xharbour Diff : 11/57 -MACRO MESSAGES by Przemyslaw Czerpak

###    MACRO MESSAGES    ###
============================
Both compilers Harbour and xHarbour supports macros as messages.
Clipper does not. This example shows such macro messages usage:

      proc main()
         memvar var
         local o := errorNew(), msg := "cargo"
         private var := "CAR"

         o:&msg := ""
         o:&( upper( msg ) ) += ""
         ? o:&var.go

Users who want to test it in xHarbour should change:
      o:&( upper( msg ) ) += ""
to:
      o:&( upper( msg ) ) := o:&( upper( msg ) ) + ""
because using macro messages with = operators or pre/post
incrementation/decrementation causes that xHarbour compiler GPFs during
compilation.

Harbour/xharbour Diff :10/57 - HB_ARRAYTOPARAMS() FUNCTION by Przemyslaw Czerpak

###    HB_ARRAYTOPARAMS() FUNCTION    ###
=========================================
Harbour has special function which allows to convert array into
list of items which can be used as function parameters, array
values or array indexes in the same way as '...' operator:
   hb_arrayToParams(  ) -> [ 1 ] [, [ N ] ]
i.e.:
      proc main( ... )
         local aParams := hb_aParams(), n
         /* remove parameters starting with "--" */
         n := 1
         while n < len( aParams )
            if left( aParams[ n ], 2 ) == "--"
               hb_adel( aParams, n, .t. )
            else
               ++n
            endif
         enddo
         ? "Public parameters:", hb_arrayToParams( aParams )
      return

Note for Clipper users: 'hb_adel( aParams, n, .t. )' in above example
works like 'adel( aParams, n ); asize( aParams, len( aParams ) - 1 )'.

This functionality is unique to Harbour and xHarbour does not support
hb_arrayToParams() or similar function.

Harbour/xharbour Diff : 9/57 - FUNCTIONS WITH VARIABLE NUMBER OF PARAMETERS by Przemyslaw Czerpak

### FUNCTIONS WITH VARIABLE NUMBER OF PARAMETERS ###
==========================================================
Both compilers supports them though xHarbour is limited to all parameters
and does not support unnamed parameters. In Harbour you can declare some
named parameters and then unnamed just like in many other languages, f.e.:
func f( p1, p2, p3, ... )
The unnamed parameters can be used in different statements passing them
by '...' operator, f.e. as array items:
proc main()
AEval( F( "1", "2", "A", "B", "C" ), {|x, i| qout( i, x ) } )
func f( p1, p2, ... )
? "P1:", p1
? "P2:", p2
? "other parameters:", ...
return { "X", ... , "Y", ... "Z" }
or as array indexes:
proc main()
local a := { { 1, 2 }, { 3, 4 }, 5 }
? aget( a, 1, 2 ), aget( a, 2, 1 ), aget( a, 3 )
func aget( aVal, ... )
return aVal[ ... ]

or as function parameters:
proc main()
info( "test1" )
info( "test2", 10, date(), .t. )
proc info( msg, ... )
qout( "[" + msg +"]: ", ... )

The '...' operator saves references when push parameters and it can be
used also in codeblocks, f.e.:
bCode := { | a, b, c, ... | qout( a, b, c ), qout( "[", ..., "]" ) }

All parameters can be accessed also using hb_aParams() function but
in xHarbour it works correctly only for functions which does not use
any local parameters or declared with variable number of parameters
or when number of declared parameters is not smaller then number of
passed parameters. This code illustrates it:
proc main()
p1("A","B","C")
p2("A","B","C")
p3("A","B","C")
p4("A","B","C")
p5("A","B","C")
proc p1
? procname()+"(), parameters:", pcount()
aeval( hb_aParams(), {|x,i| qout(i,"=>",x) } )
proc p2
local l
? procname()+"(), parameters:", pcount()
aeval( hb_aParams(), {|x,i| qout(i,"=>",x) } )
proc p3(x)
? procname()+"(), parameters:", pcount()
aeval( hb_aParams(), {|x,i| qout(i,"=>",x) } )
proc p4(...)
? procname()+"(), parameters:", pcount()
aeval( hb_aParams(), {|x,i| qout(i,"=>",x) } )
proc p5(a,b,c,d,e)
? procname()+"(), parameters:", pcount()
aeval( hb_aParams(), {|x,i| qout(i,"=>",x) } )

In xHarbour it's only possible to declare all parameters as unnamed, f.e.:
func f( ... )
and then access them using hb_aParams() or PVALUE() (in Harbour it's called
HB_PVALUE()) function. There is no support for named parameters and ...
operator.

In xHarbour due to reverted behavior of references stored in array items
assign operation to items in array returned by hb_aParams() changes
corresponding parameters passed by reference. It does not happen in
Harbour where item references stored in arrays work like in Clipper.

Harbour/xharbour Diff : 8/57 - DETACHED LOCALS AND REFERENCES by Przemyslaw Czerpak

When local variables are used in codeblocks then it's possible that
the codeblocks will exist after leaving the function when they were
created. It's potentially very serious problem which have to be resolved
to avoid internal VM structure corruption. In Clipper, Harbour and
xHarbour special mechanism is used in such situation. Local variables
are "detached" from VM stack so they are still accessible after leaving
the function, f.e.:
      proc make_cb()
         local n := 123
         return {|| ++n  }
We call such variables "detached locals".
Here there are two important differences between Clipper and [x]Harbour.
In Clipper variables are detached when function exits (returns) and it
does not know which variables were used but simply detach whole local
variable frame from VM stack. It's very important to know that because
it can be source of serious memory problems in OS like DOS.
This simple code illustrates it:

      // link using RTLINK and run with //e:0 //swapk:0
      // repeat test second time with additional non empty parameter 
      #define N_LOOPS 15
      #xcommand FREE MEMORY => ? 'free memory: ' + ;
                                 AllTrim( Str( Memory( 104 ) ) )
      proc main( x )
         local n, a
         a := array( N_LOOPS )
         FREE MEMORY
         for n := 1 to N_LOOPS
            a[n] := f( x )
            FREE MEMORY
         next
      return
      func f(x)
         local cb, tmp, ref
         tmp := space( 60000 )
         if empty( x )
            cb := {|| .t. }
         else
            cb := {|| ref }
         endif
      return cb

If you execute above program with non empty parameter then 'tmp' variable
is detached with codeblock which uses 'ref' variable and not released as
long as codeblock is still accessible. It means that in few iterations
all memory are allocated and program crashes. Clipper's programmers should
know that and be careful when use detached local and if necessary clear
explicitly other local variables before returning from the function by
setting NIL to them.
In Harbour and xHarbour only variables explicitly used in codeblocks
are detached and detaching is done when codeblock is created and original
local variables are replaced by references. It is possible because Harbour
and xHarbour support multilevel references chains so it works correctly
also for local parameters passed be reference from parent functions.
In Clipper only one level references are supported what creates second
important differences. When Clipper detaches frame with local parameters
then it has to unreference all existing references breaking them. This code
illustrates it:

      proc main()
         local cb, n := 100
         mk_block( @cb, @n )
         ? "after detaching:"
         ? eval( cb ), n
      return
      proc mk_block( cb, n )
         n := 100
         cb := {|| ++n }
         ? "before detaching:"
         ? eval( cb ), n
      return

Above code compiled by Clipper shows:

      before detaching:
             101        101
      after detaching:
             102        101

so after detaching the references to 'n' variable is broken and codeblocks
access his own copy of this variables.
In Harbour it works correctly so the results are correct and it shows:

      before detaching:
             101        101
      after detaching:
             102        102

In xHarbour ( for unknown to me reasons ) Clipper bug is explicitly emulated
though it was possible to fix it because xHarbour inherited from Harbour
the same early detaching mechanism with multilevel references so just like
in Clipper xHarbour programmers have to carefully watch for possibly broken
references by detached locals and add workarounds for it if necessary.

Harbour/xharbour Diff : 7/57 - PASSING OBJECT VARIABLES BY REFERENCEby Przemyslaw Czerpak

Both compilers support passing object variables by reference though this functionality in xHarbour 

is limited to pure instance or class variables only and does not work for SETGET methods. 

In Harbour it works correctly.

This code illustrates the problem:

      proc main()
         local oBrw := tbrowseNew()
         ? oBrw:autoLite
         oBrw:autoLite := !oBrw:autoLite
         ?? "=>", oBrw:autoLite
         p( @oBrw:autoLite )
         ?? "=>", oBrw:autoLite

      proc p( x )
         x := !x

Harbour prints:
      .T.=> .F.=> .T.
but xHarbour prints:
      .T.=> .F.=> .F.
without generating any compile or run time errors.

Harbour/xharbour Diff : 6/57 - PASSING ARRAY AND HASH ITEMS BY REFERENCE by Przemyslaw Czerpak

### PASSING ARRAY AND HASH ITEMS BY REFERENCE ###
=======================================================
Harbour supports passing array and hash items by reference, f.e.:
proc main()
local aVal := { "abc", "klm", "xyz" }, ;
hVal := { "qwe"=>"123", "asd"=>"456", "zxc"=>"789" }
? aVal[1], aVal[2], aVal[3], hVal["qwe"], hVal["asd"], hVal["zxc"]
p( @aVal[2], @hVal["asd"] )
? aVal[1], aVal[2], aVal[3], hVal["qwe"], hVal["asd"], hVal["zxc"]

proc p( p1, p2 )
p1 := '[1]'
p2 := '[2]'

Compiled by Harbour above code shows:
abc klm xyz 123 456 789
abc [1] xyz 123 [2] 789

In xHarbour only passing array items by reference works but does not work
passing hash items by reference though it does not generate either
compile time or run time errors so the above code can be compiled and
executed but it shows:
abc klm xyz 123 456 789
abc [1] xyz 123 456 789

Harbour/xharbour Diff (5/57) - REFERENCES TO VARIABLES STORED IN ARRAYS by Przemyslaw Czerpak

In xHarbour the behavior of references stored in array is reverted in
comparison to Clipper or Harbour.

In Clipper and Harbour VM executing code like:
         aVal[ 1 ] := 100
clears unconditionally 1-st item in aVal array and assigns to it value 100.
xHarbour checks if aVal[ 1 ] is an reference and in such case it resolves
the reference and then assign 100 to the destination item.
On access Clipper and Harbour VM executing code like:
         x := aVal[ 1 ]
copy to x the exact value stored in aVal[ 1 ]. xHarbour checks is aVal[ 1 ]
is an reference and in such case it resolves the reference and then copy to x
the value of reference destination item.
It can be seen in code like:
      proc main
         local p1 := "A", p2 := "B", p3 := "C"
         ? p1, p2, p3
         p( { @p1, p2, @p3 } )
         ? p1, p2, p3

      proc p( aParams )
         local x1, x2, x3

         x1 := aParams[ 1 ]
         x2 := aParams[ 2 ]
         x3 := aParams[ 3 ]

         x1 := lower( x1 ) + "1"
         x2 := lower( x2 ) + "2"
         x3 := lower( x3 ) + "3"

Harbour and Clipper shows:
      A B C
      a1 B c3
but xHarbour:
      A B C
      A B C

It's not Clipper compatible so in some cases it may cause portability
problems. F.e. code like above was used in Clipper as workaround for
limited number of parameters (32 in Clipper). But it allows to directly
assign items of arrays returned by hb_aParams() and updating corresponding
variables passed by references (see functions with variable number of
parameters below).
Anyhow the fact that xHarbour does not have '...' operator which can
respect existing references in passed parameters and does not support
named parameters in functions with variable number of parameters causes
that reverted references introduce limitation, f.e. it's not possible
to make code like:
   func f( ... )
      local aParams := hb_aParams()
      if len( aParams ) == 1
         return f1( aParams[ 1 ] )
      elseif len( aParams ) == 2
         return f2( aParams[ 1 ], aParams[ 2 ] )
      elseif len( aParams ) >= 3
         return f3( aParams[ 1 ], aParams[ 2 ], aParams[ 3 ] )
      endif
   return 0

which will respect references in parameters passed to f() function.

Harbour/xharbour Diff (4/57) - HASH ARRAYS by Przemyslaw Czerpak

Both compilers have support for hash arrays. They are similar to normal arrays but also allow to use non integer values as indexes like string, date, non integer number or pointer (in Harbour) items.

They can be created using => for list of keys and values enclosed
inside {}, f.e.:
hVal := { "ABC" => 123.45, ;
100.1 => date(), ;
100.2 => 10, ;
100 => 5, ;
date()-1 => .t. }
and then items can be accessed using [] operator, f.e.:
? hVal[ "ABC" ] // 123.45
? hVal[ 100 ] // 5
? hVal[ date()-1 ] // .t.
? hVal[ 100.2 ] // 10
? hVal[ 100.1 ] // date()

By default hash items in both compiler support automatic adding new elements
on assign operation. It can be disabled using one of hash item functions.
Harbour has additional extension which allows to enable autoadd with default
values also for access operation and reference operator. It also supports
well passing hash array items by reference and has some other minor
extensions.

xHarbour does not support autoadd on access or reference operations and
passing hash array items by reference does not work (see passing array and
hash item by reference).

Both compilers have set of functions to make different operations on hash
arrays which give similar functionality. In Harbour they use HB_H prefix
(f.e. HB_HSCAN()) in xHarbour H prefix (f.e. HSCAN())

xHarbour has additional functionality which can be enabled for each hash
array using HSetAACompatibility() function. It's an index where is stored
information about the order in which items were added to hash array and
set of functions with HAA prefix to operate on hash array items using this
index instead of real position in hash array, i.e. HAAGETVALUEAT() which
works like HGETVALUEAT().

In Harbour such functionality also exists and it's enabled by HB_HKEEPORDER() function but the internal implementation is completely different. Harbour does not emulate associative arrays by special index which keeps assign order but it uses real natural order in hash array. It means that associative array indexes are equal to regular hash indexes so it does not need any translation between them and Harbour users can use regular hash array functions for associative array indexes. So separated functions for accessing by other index are not necessary. The Harbour implementation is also more efficient because it does not introduce linear index updated each time new key is added to hash array.

Harbour emulates HAA*() xHarbour functions in XHB library but only for
compatibility with existing xHarbour code.

Harbour/xharbour Diff (3/57) - EXTENDED CODEBLOCKS by Przemyslaw Czerpak

Both compilers support compile time extended codeblocks which allow to use statements but with a little bit different syntax. Harbour uses standard Clipper codeblock delimiters {}, f.e.:

      ? eval( { | p1, p2, p3 |
                ? p1, p2, p3
                return p1 + p2 + p3
              }, 1, 2, 3 )

and xHarbour <>, f.e.:
      ? eval( < | p1, p2, p3 |
                ? p1, p2, p3
                return p1 + p2 + p3
              >, 1, 2, 3 )

In Harbour extended codeblocks works like nested functions and support all functions attributes, f.e. they can have own static variables or other declarations which are local to extended codeblocks only and do not effect upper function body.

In xHarbour the compiler was not fully updated for such functionality and extended codeblocks were added to existing compiler structures what causes that not all language constructs work in extended codeblocks and creates a set of very serious compiler bugs, f.e., like in this code with syntax errors but which is compiled by xHarbour without even single warning giving unexpected results at runtime:

      #ifndef __XHARBOUR__
         #xtranslate \<|[]| => {||
         #xcommand > [<*x*>]       => } 
      #endif
      proc main()
         local cb, i
         for i:=1 to 5
            cb := <| p |
                     ? p
                     exit
                     return p * 10
                  >
            ?? eval( cb, i )
         next
      return

It's possible to create many other similar examples which are mostly caused by missing in the compiler infrastructure for nested functions support.

This can be fixed if someone invest some time to clean xHarbour compiler.

Harbour/xharbour Diff (2/57) -NEW LANGUAGE STATEMENTS by Przemyslaw Czerpak

1. FOR EACH 

Harbour support all xHarbour functionality and it offers also additional
   features which are not available in xHarbour.
   a) it allows to iterate more then one variable
         FOR EACH a, b, c IN aVal, cVal, hVal
            ? a, b, c
         NEXT
   b) it allows to set descending order by DESCEND flag, f.e.:
         FOR EACH a, v IN aVal, cVal DESCEND
            ? a, b
         NEXT
   c) it has native support for hashes:
         FOR EACH x IN { "ABC" => 123, "ASD" => 456, "ZXC" => 789 }
            ? x, "@", x:__enumKey()
         NEXT
   d) it allows to assign string items, f.e.:
         s := "abcdefghijk"
         FOR EACH c IN @s
            IF c $ "aei"
               c := UPPER( c )
            ENDIF
         NEXT
         ? s      // AbcdEfghIjk
   e) it gives OOP interface to control enumerator variables what
      is very important when more then one variable is iterated or
      when FOR EACH is called recursively, f.e.:
         hVal := { "ABC" => 123, "ASD" => 456, "ZXC" => 789 }
         FOR EACH x IN hVal
            ? x:__enumIndex(), ":", x:__enumKey(), "=>", x:__enumValue(), ;
              "=>", x:__enumBase()[ x:__enumKey() ]
         NEXT
   f) it gives very flexible OOP mechanism to overload FOR EACH behavior
      for user define objects adding to above enumerator methods also
      __enumStart(), __enumStop(), __enumSkip() methods what allows to
      implement many different enumeration algorithms depending on used
      data
   g) it does not have any hardcoded limitations for recursive calls
      (it's limited only by available memory and HVM stack size), f.e.:
         proc main()
            p( 0 )
         return
         proc p( n )
            local s := "a", x
            ? n
            if n < 1000
               for each x in s
                  p( n + 1 )
               next
            endif
         return
   In xHarbour there is function HB_ENUMINDEX() which is supported by
   Harbour in XHB library.

2. WITH OBJECT / END[WITH]3. SWITCH / [ CASE / [EXIT] / ... ] OTHERWISE / END[SWITCH]4. BEGIN SEQUENCE [ WITH  ]
   In Harbour it does not have any hardcoded limitations for recursive
   calls (it's limited only by available memory and HVM stack size), f.e.:
      proc main()
         p( 0 )
      return
      proc p( n )
         ? n
         if n < 1000
            with object n
               p( n + 1 )
            end
         endif
      return
   It also uses OOP interface just like FOR EACH, so it's possible to
   use :__withObject() to access / assign current WITH OBJECT value.
   In xHarbour there are functions HB_QWITH(), HB_WITHOBJECTCOUNTER()
   and HB_RESETWITH() which are supported by Harbour in XHB library.


   In Harbour it uses jump table with predefined values what gives
   significant speed improvement in comparison to sequential PCODE
   evaluation just like in DO CASE statements.
   In xHarbour SWITCH does not use such jump table and generated
   PCODE is similar to the one used for DO CASE or IF / ELSEIF
   and only the main switch value calculation is optimized and
   reused for all statements so speed improvement is relatively
   small.
   In xHarbour instead of OTHERWISE the DEFAULT clause is used.
   As SWITCH values Harbour supports integer numbers and strings, f.e.:
      switch x
         case 1         ; [...]
         case 10002     ; [...]
         case "data"    ; [...]
         otherwise      ; [...]
      endswitch
   xHarbour supports only integer numbers and one character length strings
   like "A", "!", "x", " ", ...


   [ RECOVER [ USING  ] ]
   [ ALWAYS ]
   END SEQUENCE

   It's unique to Harbour. In xHarbour limited version of above statement
   exists as:
      TRY
      [ CATCH [] ]
      [ FINALLY ]
      END
   TRY gives exactly the same functionality as:
      BEGIN SEQUENCE WITH { |e| break(e) }

With the exception to SWITCH implementation, in all other statements
described above, xHarbour causes performance reduction in PCODE evaluation
even if user does not use them at all. In Harbour they are implemented in
different way which does not cause any overhead and slowness for other code. 

More at http://harbour-project.svn.sourceforge.net/viewvc/harbour-project/trunk/harbour/doc/xhb-diff.txt

Harbour/xharbour Diff (1/57) - COMPILE TIME SUPPORT FOR MERGING MULTIPLE .PRG MODULES by Przemyslaw Czerpak

Clipper allows to compile many .prg modules included by @.clp and/or SET PROCEDURE TO ... / DO ... [ WITH ... ] into single output object. In such compilation it supports, separated for each .prg file, file wide declarations when -n switch is used and allows to use more then one static function with the same name if each of them is declared in different .prg modules. This code illustrates such situation:

/***** t1. prg *****/
static s := "t01:s"
static s1 := "t01:s1"
proc main()
? "===="
? s, s1
p1();p2();p3()
? "===="
do t2
? "===="
return
proc p1 ; ? "t01:p1"
static proc p2 ; ? "t01:p2"
static proc p3 ; ? "t01:p3"
init proc pi ; ? "init t01:pi"
exit proc pe ; ? "exit t01:pe"

/***** t2. prg *****/
static s := "t02:s"
static s2 := "t02:s2"
proc t2()
? s, s2
p1();p2();p3()
return
static proc p1 ; ? "t02:p1"
proc p2 ; ? "t02:p2"
static proc p3 ; ? "t02:p3"
init proc pi ; ? "init t02:pi"
exit proc pe ; ? "exit t02:pe"

It needs -n switch for file wide declarations and uses static/init/exit functions with the same names but declared in different modules. It can be compiled and linked by Clipper and Harbour, i.e.:

cl t1.prg /n/w/es2
or:
hbmk2 t1.prg -n -w -es2
and then executed.

xHarbour does not have such functionality and above code has to be adopted to work with this compiler. Additionally it does not work well with case sensitive file systems what can be seen in above example where it converts "t1" to "T1" and then tries to include "T1.prg".

For users which have old Clipper code written for DOS file systems with mixed upper and lower letters in file names used directly or indirectly by procedure name, Harbour provides compile time switches which enable automatic filename conversions for all files opened by compiler:

-fn[:[l|u]|-] set filename casing (l=lower u=upper)
-fd[:[l|u]|-] set directory casing (l=lower u=upper)
-fp[:] set path separator
-fs[-] turn filename space trimming on or off (default)
 
This functionality is also local to Harbour so cannot be used with xHarbour as workaround for above problem though it should be easy to add it to this compiler in the future.

Both compilers support runtime switches for file name conversions.
 
SET FILECASE LOWER | UPPER | MIXED
SET DIRCASE LOWER | UPPER | MIXED
SET DIRSEPARATOR
set( _SET_TRIMFILENAME, )

which can be used in programs not intended to work with different file system(s) and with different OS(s).

More at http://harbour-project.svn.sourceforge.net/viewvc/harbour-project/trunk/harbour/doc/xhb-diff.txt