Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/T_REF.ZIP/T-REFCH2.DOC

Text File | 1987-01-15 | 12.8 KB | 331 lines

                      Chapter II - The Source Lister

     This  chapter  deals primarily with the Source Listing  program:  how  to
print  the information you want and how to interpret the listing.  The  Source
Listing  program  is  activated  by positioning the cursor  over  the  'Source
Listing' field,  and striking the space bar until the word "ON" appears within
the cursor.   To deactivate the source lister, hit the space bar again and the
word "OFF" will appear.   The nine fields that appear on the screen below  the
'Source  Listing'  field relate to specific information to be included or  not
included  in the source listing.   They are all updated in the same manner  as
the  'Source  Listing' field:  by placing the block cursor over the field  and
striking  the  space  bar until the desired value appears  within  the  cursor
block.  The fields are as follows:

     The  'Reserve  Words' field is used to tell the program how  the  reserve
words  are  to  be  formatted to the output.   You can  specify  one  of  four
different formats: "UPPER" capitalizes all letters, "LOWER" prints all letters
in lower-case,  "FORML" follows formal naming conventions,  and "AS IS" prints
the letters as they are read.  The following are examples of different reserve
words  and  how the output would be formatted;  the first column  is  how  the
reserve word would be hypothetically read from the input file:

       Input          UPPER          LOWER          FORML          AS IS
       -----          -----          -----          -----          -----
       begin          BEGIN          begin          Begin          begin
        FOR            FOR            for            For            FOR
       wITH           WITH           with           With           wITH
       Array          ARRAY          array          Array          Array

     The  'Identifiers'  field's  function is similar to the  'Reserve  Words'
field described above:  it formats the style of lettering for all  identifiers
to that requested.  The same four formatting styles listed above are available
for  this  field.   However,  here we must describe a feature of  the  "FORML"
format not mentioned above.   Since most Pascal compilers allow the use of the
underline  symbol (_) within an identifier (to make the source code more read-
able),  the "FORML" style makes use of this:  not only is the first letter  in
the identifier capitalized,  but each letter following the underline symbol is
also  capitalized.   Therefore,  'hot_item' becomes 'Hot_Item',  'not_so_fast'
becomes 'Not_So_Fast', and 'ab_ra_ca_da_bra' becomes 'Ab_Ra_Ca_Da_Bra'.
     The  purpose  of  having four formats is to provide a  large  variety  of
choices.  Even given these variations, you will most likely select and use one
format  for reserve words (i.e.,  "UPPER") and another format for  identifiers
(i.e.,  "FORML")  that best suits your specific purposes.

     The  'Line  Numbers' field activates ("ON") or  deactivates  ("OFF")  the
printing  of  source  line numbers to the left of each  line  of  output.   If
activated,  each  source  line on the output will have a line  number  printed
ahead of it.   There are two formats the line numbers may appear in, depending
on  whether  the  'Include Files' field is activated during the  listing  (see
page 10 for a description of this field).
     If  the 'Include Files' field is activated,  the line numbers will appear
in two columns:  the line number of the main input file and the line number of
the include file.   The line number of the main input file is incremented  for
each  line  read from the 'Active Input File' as specified at the top  of  the
screen.  When an include file compiler directive, such as '{$i extra.prc}', is


                                6








scanned from the main input file,  the program will begin printing the include
file  source  code starting immediately after printing the line in  which  the
include  file compiler directive is on.   At this point (until the end of  the
include file is reached),  the line number of the main input file will  remain
the  same and the line number of the include file will begin (starting from 1)
incrementing.   The  line  number of the include file,  when  the  program  is
reading from the main input file,  is not printed.  For example, the following
shows  how,  when the compiler directive '{$I this.prc}' is scanned,  the file
'THIS.PRC' is sent directly to the output.

   1       PROGRAM Sample;
   2         VAR I:Integer;
   3
   4         {$I This.Prc}
   4    1    PROCEDURE This;
   4    2      BEGIN
   4    3        Write('This is just a sample.');
   4    4      END;
   5
   6         BEGIN
   7           FOR I:=1 to 10 DO This;
   8           Writeln;
   9         END.

     The  use of separate line numbers on the listing becomes evident when you
bring  either  the main file or any of the include files up  under  the  Turbo
editor.   Since the Turbo  editor prints the cursor's location on the top line
of  the screen,  the line number you are searching for is the same line number
on  the listing.  If the 'Include Files' field is not activated (e.g.,  "No"),
only the line number of the main input file is printed.   For example,  if the
above main file were printed without the include file activated (set to "No"),
it would look like:

   1 PROGRAM Sample;
   2   VAR I:Integer;
   3
   4   {$I This.Prc}
   5
   6   BEGIN
   7     FOR I:=1 to 10 DO This;
   8     Writeln;
   9   END.

     The 'Lexical Levels' field,  when activated ("ON"),  will print for  each
source  line  a value representing the lexical,  or procedural,  depth of  the
program.   Therefore,  as  the program scans the beginning of a  procedure  or
function, the lexical level of the program is incremented; the level is decre-
mented when the procedure or function is exited.









                                7








   1  PROGRAM Sample;
   1    VAR I:Integer;
   1
   2    PROCEDURE This;
   2
   3      PROCEDURE Now_That;
   3        BEGIN
   3          Writeln;
   3        END;
   2
   2      BEGIN
   2        Write('This is just a sample.');
   2        Now_That;
   2      END;
   1
   1    BEGIN
   1      FOR I:=1 to 10 DO This;
   1    END.

     The  'Block  Levels' field,  when activated ("ON"),  will print  a  value
representing  the structured statement depth within the procedure or  function
being scanned.   The value is printed on each line of the output.   Whenever a
structured statement (e.g.,  the IF,  the FOR, the REPEAT, the CASE, the WITH,
the WHILE,  or the compound BEGIN-END statement) is entered during the scan of
the  source  code,  the block depth of the procedure is  incremented,  and  is
decremented upon exiting the structured statement.

   0  PROGRAM Sample;
   0    VAR I:Integer;
   0
   0    PROCEDURE This;
   1      BEGIN
   1        Write('This is just a sample.');
   1      END;
   0
   1    BEGIN
   2      FOR I:=1 to 10 DO
   2        This;
   1      Writeln;
   1    END.

     The 'Active Procedures' field, when activated ("ON"), will print the name
of  the  procedure or function (presently being scanned) to the right  of  the
output source code.  The name is enclosed in brackets (between '{' and '}') to
increase  the documentation effects of the source and to make it  possible  to
recompile the output source.

     The  following  is an example of the program's output if this  field  was
activated.  (This  is also an excellent way to recognize new lines in  version
updates  to source files.   Those lines added after a version is complete  and
updated by T-Ref would not have this field at the end of the lines.)






                               8








PROGRAM Sample;                                        { SAMPLE }
  VAR I:Integer;                                       { SAMPLE }
                                                       { SAMPLE }
  PROCEDURE This;                                      { THIS }
    BEGIN                                              { THIS }
      Write('This is just a sample.');                 { THIS }
    END;                                               { THIS }
                                                       { SAMPLE }
  BEGIN                                                { SAMPLE }
    FOR I:=1 to 10 DO This;                            { SAMPLE }
    Writeln;                                           { SAMPLE }
  END.                                                 { SAMPLE }


     Any  of  the listable information described above may be combined in  any
combination.  Since the 'Line Numbers' field,  the 'Lexical Levels' field, and
the 'Block Levels' field are printed to the left of the source for each  line,
a  combination of more than one of these will create a column for each one  in
that  specific order.   For example,  if all three fields are  activated,  the
output would be as follows:

   1        1   0  PROGRAM Sample;
   2        1   0    VAR I:Integer;
   3        1   0
   4        1   0    {$I This.Prc}
   4    1   2   0    PROCEDURE This;
   4    2   2   0
   4    3   3   0      PROCEDURE Now_That;
   4    4   3   1        BEGIN
   4    5   3   1          Writeln;
   4    6   3   1        END;
   4    7   2   0
   4    8   2   1      BEGIN
   4    9   2   1        Write('This is just a sample.');
   4   10   2   1        Now_That;
   4   11   2   1      END;
   5        1   0
   6        1   1    BEGIN
   7        1   2      FOR I:=1 to 10 DO This;
   8        1   1    END.

     The  'Header' field is used to activate ("ON") the inclusion of a  header
to  be  printed at the top of each page of source output.   The header can  be
from two to five lines and each line can be up to 75 columns in  length.   The
F3 function key creates the header to be printed.  If a header is printed, the
program  will automatically buffer 3 blank lines before the header (the  first
line of the new page) and 2 blank lines after the header (before the next line
of source code),  so it is not necessary to buffer the header with blank lines
within the header itself.

     The  'Page Numbering' field will,  when activated  ("ON"),  automatically
number the pages of the output source (whether it is going to a file or to the
printer).  A  date/time tag is printed on the page  number  line,  also.   The
number of lines per page is set by the F6 function key.   If page numbering is
deactivated  ("OFF") and the output is going to a file,  the source is contin-


                                9








uous with no blank lines between pages.   If page numbering is deactivated and
the  output is to the printer,  the listing will automatically  include  three
blank lines at the end of each page and one blank line at the head.

     NOTE: When both the 'Header' and 'Page Numbering' fields are turned "Off"
and  the output is routed to a specified file (the 'Active Output File'  field
is  not blank),  paging,  that is blank lines between pages,  will not  occur.
Therefore, the output source is continuous.  If either or both of these fields
are "On", paging will occur; whether output is to the printer or to a file.

     NOTE:  There  are separate switches on headers and page numbering for the
source  lister and the cross referencer.   This feature was provided to  allow
more  flexible  customized listing when run separately.   When both  a  source
listing and cross reference listing are desired, we recommend you set these to
the same values.  Since it is difficult to accurately assess all combinations.
Therefore,  the  output characteristics may differ from the desired results of
the listing if the above stated recommendation is not adhered to.

     The  'Include  File' field informs the program whether or  not  to  print
external  files  (normally  included in compilation through  an  include  file
compiler  directive (i.e.,  '{$I THIS.PRC}')) directly in with the main source
code.  When activated ("YES"), include files are automatically placed into the
output's  source listing immediately after the include file compiler directive
is  interpreted.   There  is additionally an OPTIONAL  setting  ("OPT")  which
allows you to selectively decide which include files are to be printed.   When
this  setting  is used,  a message is sent to the message area of  the  screen
every  time an include file compiler directive is scanned,  asking for  deter-
mination  as  to  whether the file is to be included in  the  source  listing.
Responding  "Y"es will route the include file source to the output;  "N"o will
cause the include file source listing to be skipped.



























                               10