## page was copied from APLXCompareWss
= Comparing code in Workspaces and Files in APL2000 =

~-<<SeeSaw(section="table-of-contents", show="true", seesaw="false", toshow="<<(Show>> table-of-contents)", tohide="<<(Hide>> table-of-contents)", speed="Slow")>>-~
<<TableOfContents>>

== Overview ==
This page shows how to compare 2 workspaces or component files, including simulated packages, in APL2000. This method uses the session and works on 2 workspaces on file.

== Method ==

)LOAD the workspace compare.w3.
 

      This ws will provide useful info between 2 objects, that is the difference between them. There are 3 main programs:
||`r← p1 compack p2`||||       compares 2 overlays, calls||
||`r← c1 compfn  c2`||||       compares 2 programs; returns empty list if identical.                       c1 and c2 are the `⎕cr` of programs.||
||`r← v1 compvar v2`||||    compares 2 variables; returns empty list if same.||
                       v1 (or v2) may be an "packages" (simulated in APL2000)                       in which case  <compack>  will be called
                       and so on.  Enclosed arrays are detailed
                       only if they are vectors of same shape.
                       Differences are shown on simple objects of
                       rank 2 or less or if they are small enough.

    The format of <compfn> is as follow: the program on the left is assumed to be the one which has changed. The program on the right is assumed to be the replacing one. The output is based on these assumptions. Each line of the program on the left is preceded by its line number [xx]. Where the line has been deleted a symbol appears (-) before the line number. Where a new line has been inserted there is no line numbering and a symbol (+) will appear.

Example:
{{{
           ∇fna                  ∇fnb
       [1] same line         [1] same line
       [2] fna line 2        [2] fnb line 2
       [3] same line 3       [3] same line 3
       [4] ⍝ comment deleted [4] new common line
       [5] new common line   [5] ⍝ new comment
           ∇                     ∇
    (⎕cr 'fna') compfn ⎕cr 'fnb'
-[0]  fna
+     fnb
 [1]  same line
-[2]  fna line 2
+     fnb line 2
 [3]  same line 3
-[4]  ⍝ comment deleted
 [5]  new common line
+     ⍝ new comment
}}}
Note that in order to avoid lengthy output of big programs with little
difference only sections of the function are shown, those where the changes
occurred plus a couple of lines before and after (see var ZONE).

== Comparing entire workspaces ==

In order to compare entire workspaces it is necessary to send them on file and to use the <compfile> program as follow:

{{{
      )xload ws1
      )copy compare tws
      tws        ⍝ transfer the ws
      )xload ws2
      )copy compare tws
      tws
      )load compare
      compfile ''
      clearfile  ⍝ if wanted so
}}}
<tws> is the Transfer WS function. It moves the variables and functions of the workspace onto file preceded by some info. If the file does not
exist it is created. After <compfile> has been run, <clearfile> should be run
in order to get rid of the file easily.

NOTES:  <compfile> may not work fine for very large objects (WS FULL); `⎕pw` is used to delimit output

Since APL2000 has `⎕INBUF` it might be easier to use the
program <compare> as follow:
{{{
      'ws1'  compare  'ws2'
}}}
Note: this will create another task and execute all the commands for you

== Output specifications ==

The amount of information displayed is determined by a few globals. One of
them, SHOW, contains 3 values for each one of the sections of the report,
that is the 2 "unique symbols" sections and the "common symbols" section,
i.e.

- the symbols found ONLY in the first object/ws

- those found ONLY in the second one

- those found in both each section has 3 properties:

 the number of symbols,

 their names,

 their contents (or difference)

The first one is always displayed. the last 2 ones depend on the
relative value in SHOW: if

 0: nothing is shown,

 1: the names only are displayed,

 2: their contents/difference only is displayed,

 3: both

The default value is 1 1 3, that is the first 2 sections have their names displayed only and the third one is all shown. To change temporarily this setting do
{{{
      'ws1' compare 'ws2 /show=2' ⍝ to show names only for example
}}}
Another global affecting display is NLINES which shows the first N lines of a variable in the "unique symbols" area.

Yet another one is ZONE which affect display of differences between objects. This is the number of lines shown before and after the differences found.

=== Comparing Files ===

To compare 2 files use

{{{
       'file1' comparefiles 'file2'
}}}

This will compare each component with same number, i.e. if <file1> ranges from components 10 to 20 and <file2> ranges from 15 to 45 then only components 15 to 20 will be compared.

=== Globals ===

DELINS 2 chars for display of program lines differences to the left

NLINES maximum number of lines shown for variables

SHOW   display code per section

ZONE   number of lines to keep after changes in program (window size before and after changes)
----CategoryApl2000