home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / turbopas / tshell12.arc / TSHELL.DOC < prev   
Text File  |  1987-05-12  |  12KB  |  325 lines
  1.  
  2.  
  3.  
  4.                                    TSHELL
  5.  
  6.  
  7.                       Turbo Pascal Preprocessor Shell
  8.  
  9.  
  10.                           Version 1.2 (16-Apr-87)
  11.  
  12.  
  13.  
  14.   
  15.         Copyright (C) 1987 by Samuel H. Smith;  All Rights Reserved.
  16.  
  17.  
  18.  
  19.       You may copy and distribute this program freely, provided that:
  20.          1)   No fee is charged for such copying and distribution, and
  21.          2)   It is distributed ONLY in its original, unmodified state.
  22.  
  23.  
  24.           If you like this program, and find it of use, then your 
  25.           contribution of $10 will be appreciated.  
  26.  
  27.  
  28.           Please refer all inquiries to:
  29.                Samuel H. Smith         The Tool Shop BBS, 
  30.                5119 N. 11th Ave 332    (602) 279-2673
  31.                Phoenix, AZ 85013
  32.                             
  33.  
  34.  
  35.  
  36.     This program allows you to use a number of C-like preprocessor 
  37.     statements in a Turbo Pascal source file.  It interprets the 
  38.     statements and passes the processed text on to the Turbo compiler 
  39.     for further processing.  TSHELL is a preprocessor capable of macro 
  40.     substitution, conditional compilation, and nested inclusion of 
  41.     files. 
  42.  
  43.     The TSHELL program will load TURBO.COM into memory, install the 
  44.     preprocessor shell, and enter the Turbo main menu.   At this point, 
  45.     Turbo Pascal can be used as always, except that the new preprocessor 
  46.     commands can be used in any source file. 
  47.  
  48.     To start a Turbo Pascal session with the preprocessor shell, enter: 
  49.        TSHELL
  50.     on the DOS command line.
  51.  
  52.     
  53.     A stand-alone (batch) version of the preprocessor is also available.  
  54.     A large tshell-turbo source file can be preprocessed and prepared 
  55.     for compilation with plain-turbo with this command: 
  56.        TPP file.in >temp
  57.        TSPLIT temp out
  58.  
  59.     This reads file.in, preprocesses it and writes the result to 
  60.     out.pas.   Extra include files, out.P0n will also be generated if 
  61.     the source is larger than 50k.  This command is useful when you want 
  62.     to convert a file that uses the TSHELL preprocessor back into a 
  63.     normal Turbo Pascal source. 
  64.  
  65.  
  66.     Overview
  67.  
  68.     The following C preprocessor directives are understood:
  69.  
  70.        #define NAME STRING    ;replace all instances of NAME with STRING
  71.                               ;instances of NAME(p1,pn) are also processed
  72.  
  73.        #undef NAME            ;delete definition of NAME
  74.     
  75.        #ifdef NAME            ;compile only if NAME is defined
  76.     
  77.        #ifndef NAME           ;compile if NAME is not defined
  78.     
  79.        #else                  ;compile otherwise
  80.     
  81.        #endif                 ;resume normal compilation
  82.     
  83.        #pragma NOEXPAND       ;do not expand #defines in following lines
  84.     
  85.        #pragma EXPAND         ;resume #define expansion
  86.     
  87.        #pragma LIST           ;list preprocessed lines to screen
  88.     
  89.        #pragma NOLIST         ;stop listing
  90.     
  91.        #include "file"        ;include specified file (nesting ok)
  92.  
  93.        #include <file>        ;search TPATH for include file
  94.  
  95.        #log REST OF LINE      ;places rest of line into the logfile
  96.  
  97.  
  98.  
  99.     The following special keywords are predefined:
  100.  
  101.        SYSTEM_DATE            ;the time/date when compile was started
  102.     
  103.        LAST_UPDATE            ;last modification time of current file
  104.     
  105.        CURRENT_FILE           ;name of current file
  106.  
  107.        CURRENT_PATH           ;full pathname of current file
  108.  
  109.  
  110.  
  111.     Note that keyword replacement takes place only when the keyword in 
  112.     the source is surrounded by delimiters.   A replacement will not 
  113.     take place if the keyword is preceeded or followed by a number or a 
  114.     letter.   This preprocessor WILL make replacements within literals 
  115.     and comments - beware! 
  116.  
  117.  
  118.  
  119.  
  120.     Preprocessor commands
  121.     
  122.     Lines beginning with '#' communicate with the preprocessor.  
  123.     Indentation is allowed, but there cannot be a space between the '#' 
  124.     and the command keyword.   These lines have a syntax independent of 
  125.     the rest of the language; they may appear anywhere and have effect 
  126.     which lasts until the end of the compilation. 
  127.     
  128.  
  129.  
  130.     Token replacement
  131.  
  132.     A preprocessor line of the form:
  133.        #define NAME REPLACEMENT
  134.     causes the preprocessor to replace future instances of NAME with the 
  135.     given REPLACEMENT string.   Subsequent instances of NAME followed by 
  136.     a "(", a sequence of characters delimited by commas, and a ")" are 
  137.     replaced by the REPLACEMENT in the definition.   Each occurance of 
  138.     "%" followed by a digit is replaced by the corresponding sequence of 
  139.     characters following NAME.   To define multi-line macros, place a 
  140.     "\" at the end of each line except the last. 
  141.  
  142.     For example, the definition:
  143.        #define STATUS writeln('status: %1=',%1,' %2=',%2,' %3='%3);
  144.     defines a macro called STATUS, which can be called with 3 actual 
  145.     parameters.   If this macro is called with this statement: 
  146.        STATUS(a,index,name);
  147.     the compiler will see this line of code:
  148.        writeln('status: a=',a,' index=',index,' name=',name);
  149.  
  150.     The definition:
  151.        #define DUMP_TABLE                   \
  152.           writeln('Contents of %1:'); \
  153.           for i := 1 to %2 do               \
  154.              writeln(' %1[',i,'] = ', %1[i])
  155.     defines a macro called DUMP_TABLE, which can be called with 2 actual 
  156.     parameters.   If this macro is called with this statement: 
  157.        DUMP_TABLE(Data_Table, Table_Size);
  158.     the compiler will see this line of code:
  159.           writeln('Contents of DataTable:'); 
  160.           for i := 1 to Table_Size do        
  161.              writeln(' Data_Table[',i,'] = ', Data_Table[i]);
  162.  
  163.  
  164.  
  165.     A control line of the form:
  166.        #undef NAME
  167.     deletes the definition of NAME.
  168.  
  169.  
  170. 
  171.     Conditional compilation
  172.  
  173.     A control line of the form:
  174.        #ifdef NAME
  175.     checks whether the NAME is currently defined in the preprocessor; 
  176.     that is whether it has been the subject of a #define control line.   
  177.     A control line of the form: 
  178.        #ifndef NAME
  179.     checks whether the NAME is currently undefined in the preprocessor. 
  180.     Both forms are followed by an arbitrary number of lines. 
  181.  
  182.     #ifdef NAME
  183.        If NAME has been defined with #define, the following code will 
  184.        compile as normal.  Otherwise, the following code will be 
  185.        excluded from the compilation.   Normal compilation resumes with 
  186.        an #endif statement.   For example: 
  187.  
  188.            #ifdef FAST_VIDEO
  189.               fast_display(x,y,'display data');
  190.            #else
  191.               gotoxy(x,y);
  192.               writeln(con,'display data');
  193.            #endif
  194.            
  195.  
  196.     #ifndef NAME
  197.        Like #ifdef but compiles code if the NAME has NOT been defined.
  198.  
  199.     #else
  200.        Used with #ifdef to provide alternative code for cases where
  201.        the keyword is not defined. 
  202.  
  203.     #endif
  204.        Terminates a #ifdef block of code and resumes normal 
  205.        compilation. 
  206.  
  207.  
  208.  
  209.     #pragma NOEXPAND
  210.        This command stops macro expansion.  It is used in cases where 
  211.        macro expansion is not desired.   This also speeds up compilation 
  212.        by eliminating the need to scan each line for keywords. 
  213.  
  214.     #pragma EXPAND
  215.        This command resumes normal expansion of macros.
  216.  
  217.  
  218.  
  219.     #pragma LIST
  220.        This command causes the source code to be listed to the screen 
  221.        after macro expansion had taken place. 
  222.  
  223.     #pragma NOLIST
  224.        This command disables the source listing.
  225.  
  226. 
  227.  
  228.     #include <file>    or
  229.     #include "file"
  230.        This command causes the specified file to be included into the 
  231.        compilation.   Include files may be nested. When the <file> form 
  232.        is used, the TPATH environment variable is used to locate the 
  233.        include file.  Use the DOS set command to define the directories 
  234.        to be searched. 
  235.  
  236.  
  237.     #log REST OF LINE
  238.        This command places REST OF LINE into the compilation logfile.  
  239.        This logfile records the compiler used, all source filenames and 
  240.        revision times, and a summary of compilation speed.  This logfile 
  241.        is used to track the "pedigree" of an object file and can be very 
  242.        useful in configuration management of large projects. 
  243.  
  244.  
  245.  
  246.     Predefined keywords
  247.  
  248.     SYSTEM_DATE
  249.        This keyword will be replaced with the time and date when the 
  250.        compile was started.  It has the form:  dd-mmm-yy hh:mm:ss. 
  251.  
  252.     LAST_UPDATE
  253.        This keyword will be replaced with the last update date of the 
  254.        current source file. 
  255.  
  256.     CURRENT_FILE
  257.        This keyword will be replaced with the file name of the current 
  258.        source file. 
  259.  
  260.     CURRENT_PATH
  261.        This keyword will be replaced with the full pathname of the 
  262.        current source file. 
  263.  
  264.  
  265. 
  266.     Program requirements and limitations
  267.  
  268.     Version 1.2 of TSHELL works only with Turbo Pascal version 3.01a. 
  269.     Future releases will work with more versions of Turbo.   Note that 
  270.     since TPP does not use TURBO.COM, it works with any version of Turbo 
  271.     Pascal. 
  272.  
  273.  
  274.     Memory used:  About 50k of RAM, in addition to that normally used by 
  275.     TURBO.COM. 
  276.  
  277.     Number of #define's:  100 different keywords can be defined.  (TPP 
  278.     allows 500 keywords). 
  279.  
  280.     Maximum keyword length:  Keywords can be up to 30 characters in 
  281.     length.  Keywords must follow the same conventions as Turbo Pascal 
  282.     identifiers. 
  283.  
  284.     Maximum replacement length:  Replacement strings can be up to 70 
  285.     characters long.   Note that the line length after macro expansion 
  286.     cannot exceed 128 characters.  This limit is imposed by Turbo 
  287.     Pascal. 
  288.  
  289.     Maximum replacement lines:  Replacement strings can be any number of 
  290.     lines long.  
  291.  
  292.     #ifdef nesting:  #ifdef and #ifndef statements can be nested up to 
  293.     10 levels. 
  294.  
  295.     #include nesting:  #include statements can be nested up to 5 levels. 
  296.  
  297.  
  298.  
  299.    Changes since version 1.0
  300.  
  301.    Speed:   Several parts of TSHELL 1.2 have been rewritten in assembly 
  302.    language for greater speed.  Version 1.2 compiles itself over 3 
  303.    times faster than Version 1.0 does. 
  304.  
  305.    Nested includes files:   Include files are now allowed to nest up to 
  306.    5 levels deeply.  
  307.  
  308.    Include file search path:   The TPATH environment variable is used 
  309.    to specify the search paths to be used to locate files included with 
  310.    the #include <name> form of the include command.   This allows 
  311.    developers to place all library files into one or more common 
  312.    include directories and not have to worry about specific paths. 
  313.  
  314.    Compilation logging:   A compilation log is created for each program 
  315.    compiled under TSHELL 1.2.  This log records the compiler and shell 
  316.    used, all source files and revision dates, special programmer 
  317.    defined log entries, and a summary of compilation speed. 
  318.  
  319.    Tools:   TSHELL 1.2 includes several additional program development 
  320.    tools. These include TMAKE, TSPLIT and PEDIGREE.   TMAKE can be used 
  321.    to automatically determine what programs need recompilation.  TSPLIT 
  322.    will split up a large turbo source file into smaller parts (needed 
  323.    when TPP outputs are >60k).   PEDIGREE scans a comfile and reports 
  324.    the tag lines that it contains. 
  325.