ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / MISC / NAPP.ZIP / PP_EXE.EXE / PRETTY_P.DOC < prev next >

Wrap

Text File | 1988-05-27 | 72.3 KB | 1,990 lines

The source code and data files for GSFC Ada Standard Pretty Printer is in the public domain, but NASA does request to be notified of how many copies are made to encourage funding for similar development for the public domain. Therefore, please fill out this page and return it to: Ada Pretty Printer Notification c/o Ms. Elisabeth Brinker -- Code 522 Data Systems Applications Branch Goddard Space Flight Center Greenbelt, Maryland 20771-0001 ----------------------------------------------------------------- Ada Pretty Printer Notification Version 1.1 Name ____________________________________________________________ Address _________________________________________________________ _________________________________________________________________ _________________________________________________________________ Copies ___________________ Modified Copies _________________ _ |_| I would like information regarding any modifications since version 1.1 Comments ________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ Data Systems Technology Laboratory Series DSTL-88-003 National Aeronautics and Space Administration Goddard Space Flight Center Standard Ada Pretty Printer May 1988 FOREWORD NASA/GSFC Standard Ada Pretty Printer is a publication of the Data Systems Technology Division of the Mission Operations and Data Systems Directorate, the National Aeronautics and Space Ad- ministration, Goddard Space Flight Center (NASA/GSFC). The principal author of this document is Allyn M. Shell of AdaCraft, Inc. (a Maryland Corporation) Work was accomplished for Data Systems Technology Division under Purchase Order Number S-89844-D Single copies of this document may be obtained by writing to: Ms. Elisabeth Brinker Code 522 NASA/Goddard Space Flight Center Greenbelt, Maryland 20771 ABSTRACT This documentation contains a User Guide describing installation and limitations of the NASA/GSFC Ada Pretty Printer tool. Con- tained in the Appendix is a description of how the source code for the Pretty Printer is structured and guidelines for source code modification and reuse. This documentation was completed together with Version 1.1 of the software tool, which provides significant enhancements to expand the tool's usefulness in a software development environment. Goddard Space Flight Center Standard Ada Pretty Printer Table of Contents: 1. Background 2. Installation for IBM AT and Compatibles From Executable 3. Installation From Source Code 4. Normal Use With Single File 5. Multiple Files and Batch Mode 6. The Output Files 7. Modifying Default File Names 8. Optional Parameters 9. Pragmas and Creating a Specialized Pretty Printer 10. Error Messages 11. Limitations and Known Problems Appendix Ada Pretty Printer Code Documentation Ada Pretty Printer Notification 1 Goddard Space Flight Center Standard Ada Pretty Printer 1. Background This project began in early 1986 as an Ada learning project in the Simulations Operations Control Center (SOC) at Goddard Space Flight Center, where the tool's author was being groomed as "The Ada Expert" for the SOC. Through the process of writing a parse table generator and Ada syntax file, he was able to learn many of the intricacies of Ada he might have otherwise missed in years of development projects. The tool's author, Mr. Allyn M. Shell, joined the Ada Users Group at GSFC and subsequently became a charter member of the Ada Stan- dards Committee, a working committee of the Ada Users Group. The standards implemented in the tool are directly taken from the Ada Style Guide (Software Engineering Laboratory Series SEL-87-002) produced by the Standards Committee. In January of 1988 NASA selected AdaCraft, Inc. to update and document the Pretty Printer code that Mr. Shell wrote. The code has been released to the public domain. Enhancements are encour- aged, and NASA would like to know what was done. If some en- hancements require changes to the syntax or directives, there is a parse table generator associated with the Pretty Printer which operates on the VAX / VMS. This program can be acquired from the Data Systems Applications Branch of GSFC. (See notification at end of document for address.) It will require modification to make it usable on an IBM AT. 2 Goddard Space Flight Center Standard Ada Pretty Printer 2. Installation for IBM AT and Compatibles from Archived Executable: AT must have extended RAM with driver=vdisk.sys in the config.sys file (vdisk.sys comes with IBM's DOS). Otherwise, use PP.exe alone (expanded memory helps). INSTALLATION: After making a backup floppy, do the DOS commands designated in the left column starting from the root directory. MD Pretty | Act_Tab1.DIO Act_Tab2.DIO DirecTab.DIO CD Pretty | Heap.COM Load_PP.BAT PP.EXE A:PP_Exe | Pretty_P.DOC Pretty_P.EXE Pretty_P.EXT Your directory should include the files on the right. Print Pretty_P.DOC. If your RAM is not D: then you will need to edit Load_PP.BAT to designate the correct drive number. The Alsys compiler routines are assumed to be present by the Load_PP.BAT file but are not necessary. If you have the Alsys compiler routines, Heap.COM can be deleted. Add C:\Pretty to the path in your AutoExec.BAT file. If you expect to use the Pretty Printer frequently, include the Load_PP call (without the Heap call) before any Alsys\StartUp call in the AutoExec.BAT file. EXECUTION: with RAM: Load_PP (This only needs to be done once per session.) Pretty_Print without RAM: PP On the prompt enter file name. The last two letters will be changed to -PP for the formatted source file and -SR for the status report. 3 Goddard Space Flight Center Standard Ada Pretty Printer 3. Installation From Source Code: Compilation command lists are provided for Vax / VMS and IBM AT. Users of other machines should determine whether the VAX_Parse_- Tables can be compiled on their systems. If the VAX_Parse_Tables will compile then they should be used. Edit the appropriate com- mand list. If necessary create the Ada library. Then compile and link the source code using the edited command list. Copy the executable module into the appropriate directory, and if you have not used the VAX_Parse_Tables, you will have to copy the action tables and directives table to the same directory. These are the files: Act_Tab1.DAT Act_Tab2.DAT DirecTab.DAT Note: These tables are necessary only for the first execution of the Pretty Printer and can be deleted after the first run. The Pretty Printer will generate Direct_IO versions of these tables with .DIO designations. All of the .DIO files or all of the .DAT files must be present for the Pretty Printer to initialize. If modifications are made to the source code that do not include changes to the parse tables, the original .DIO files can be used with the new load module of the Pretty Printer. If modifications are made to the syntax or directives using the parse table generator then the parse tables and parse keys files will both need to be recompiled along with their dependent units. The .DIO files will also need to be renamed so that the new .DAT will be installed. 4 Goddard Space Flight Center Standard Ada Pretty Printer 4. Normal Use with Single File: To execute the Pretty Printer simply invoke the executable modu- le. On the VAX this would be: Run Pretty_Print On an IBM AT this would be: Pretty_Print Note: Execution of the Pretty Printer on an IBM AT or Compatible will require copying the .EXT file to RAM and assignment of the name Ada_Heap.DTA to the free space in RAM. This can be done using the Load_PP.BAT file which is included. The Pretty Printer will prompt for the name of the file to be formatted and will return several simple messages. For Example: C> Pretty_Print Ada File? > FileName.Ada FileName.APP created FileName.ASR created The Ada file FileName.Ada was formatted according to the GSFC Standard Ada Style and written to the FileName.APP file with a statistics report written to the FileName.ASR file. See Output Files section for examples. Note: Since output file names are simply modified versions of the input file name less the last two characters, distinctions bet- ween files made by differences in the extension may be lost. (For instance a declaration and corresponding body called Package1.ADA and Package1.ADB will both produce output files with the names Package1.APP and Package1.ASR.) Also file names with single char- acter extensions will raise exceptions in some implementations because the period of the intended extension will be deleted. Some error messages may also appear at the terminal. If the message is related to a parse error then the source code does not conform to the Ada LRM. In this case the -PP file will not contain a formatted version of the source file. Instead, it will be a copy of the original file with very simple error messages. Often one parse error will produce several error messages; some of which may be much later in the code where later parts of nested constructs appear. Another kind of message that appears at the terminal is a flag that is displayed for violations of the Style Guide which are not violations of Ada. These are included for NASA's use. 5 Goddard Space Flight Center Standard Ada Pretty Printer 5. Multiple Files and Batch Mode: The Pretty Printer will take a list of files and format each file on the list. Each file will produce two output files named in the same manner as for the single file. A statistics totals report is also produced named the Stat_Tot.RPT file. To format a list of files: Prepare the list to be formatted with one file name per line. The name may be preceded by blanks (no tab characters). If anything else follows on the line there must be at least one blank space immediately after the name. To execute a list of files: Indicate the input file is a list by placing an "at" sign before the file name. C> Pretty_Print Ada File? > @NameList.Ada Pretty Print -- File_1.APP File_1.APP created File_1.ASR created Pretty Print -- File_2.APP File_2.APP created File_2.ASR created Stat_Tot.Rpt created To execute the Pretty Printer in Batch mode: The first word of the first line in the files list should be the word "batch". This word must be all lower case and must be sep- arated from anything following by at least one blank. If the output file for the terminal responses is to be named, the name must appear on the same line after the word "batch" and separated before and behind by one or more spaces (no tab characters). Everything that appears on this line after the first blank space following the output file name will be considered a comment. For batch processing this list file must be named Files_In.LST and must be in the directory starting the batch job. When the batch job is completed this file should be renamed because it will cause normal execution of the Pretty Printer to execute the same list file and overwrite the output file. This may cause a loss of the existing output file even if the execution is stop- ped. 6 Goddard Space Flight Center Standard Ada Pretty Printer If the Storage_Error exception is raised while a list of files is being formatted, execution will be stopped at that file, an error message will appear at the terminal or in the output file, and the Statistics Totals Report will be generated for all files prior to the one causing the Storage_Error. Note: Files having parse errors will not produce a unit status report nor add statistics to the total. 7 Goddard Space Flight Center Standard Ada Pretty Printer 6. The Output Files: The two primary output files are the Formatted Source File and the Statistics Report. The Formatted Source File will have the same source code as the original source file but the format will be according to the Ada Style Guide (Version 1.1). A sample of the Statistics Report follows: Statistics for file named => FileName.Ada Description Amount ----------------------------------------- Units 1 Lines 69 Lines_of_Code 17 Comment_Lines 42 Blank_Lines 10 Right_Comments 6 Open_Semicolons 10 Enclosed_Semicolons 1 Maximum_Indentation 2 ----------- Code - Statistics ----------- with_clause 1 use_clause 1 body_stub 1 procedure_body 1 parameter_spec (fn & proc) 2 call_statement 1 assignment_statement 3 if_statement 2 elsif_clause 1 ----------------------------------------- The code statistics correspond to the number of parse tree nodes for the selected constructs. (Details such as identifier and op- erator counts are not included.) The open and enclosed semicolon counts are provided to determine how the semicolons are being counted by others providing Ada code. (Enclosed semicolons are those that appear within parenthesis as between the parameter declarations in the formal part of a subprogram declaration.) The maximum indentation is provided to give a rough estimate of unit complexity. The parameter_spec count includes all parameter specifications in procedure, function, and entry declarations and accept statements. The amount for the procedure body, function body, package body, package spec, etc. will include the item that is the compilation unit as well as any enclosed units. The other reported items are self explanatory. Note: When the source code contains parse errors this report will not be generated. 8 Goddard Space Flight Center Standard Ada Pretty Printer 7. Modifying Default File Names: The default file names can be changed by making changes in the FileNams.Ada file and recompiling this file and its dependencies. The files which can be modified this way are: Action_Table_One : constant String := "Act_Tab1.Dat"; Action_Table_Two : constant String := "Act_Tab2.Dat"; Directives_Table : constant String := "Directab.Dat"; Productions_Table : constant String := "Prodtabl.Dat"; Direct_Action_Table_One : constant String := "Act_Tab1.DIO"; Direct_Action_Table_Two : constant String := "Act_Tab2.DIO"; Direct_Directives_Table : constant String := "Directab.DIO"; Direct_Productions_Table : constant String := "Prodtabl.DIO"; Input_Files_List : constant String := "Files_In.Lst"; Output_List : constant String := "PPoutput.lst"; Status_Totals_Report : constant String := "Stat_Tot.Rpt"; Note: The first eight files named here are not used when the VAX Parse Tables are used. 9 Goddard Space Flight Center Standard Ada Pretty Printer 8. Optional Parameters: The Pretty Printer contains many controls that are parameterized. Any of these parameters can be overridden by pragma Form_Set. These parameters include the following: type Format_Type is (NASA_STANDARD, SPECIAL); Pretty_Print_Format : Format_Type := NASA_STANDARD; Page_Width : Natural := 80; Right_Comment_Column : Natural := 40; Colon_Offset : Natural := 15; Value_Offset : Natural := 15; Assign_Offset : Natural := 15; The following parameters can also be overridden by pragma Form_- Set, but they only apply when the Pretty_Print_Format is set to SPECIAL. Indentation : Natural := 3; Using_Half_Indentation : Boolean := TRUE; -- not recommended for Indentation < 3 Using_Reverse_Indentation : Boolean := TRUE; -- for loop names, block names, and labels type Cases is (UPPER_CASE, CAPITALIZE_FIRST, LOWER_CASE); Types_Case : Cases := CAPITALIZE_FIRST; Enumeration_Case : Cases := UPPER_CASE; Identifier_Case : Cases := CAPITALIZE_FIRST; Using_Echeloned_Declarations : Boolean := FALSE; Using_Echeloned_Assigns : Boolean := FALSE; Using_Colon_Alinement : Boolean := FALSE; Using_Value_Alinement : Boolean := FALSE; Using_Assign_Alinement : Boolean := FALSE; Using_Pointer_Alinement : Boolean := FALSE; The offset parameters in the third group are used with the "using" flags in the last group. The Colon_Offset is aligned measuring from the beginning of the identifier that it follows. The Value_Offset is for the assignment in a declaration and is aligned measuring from the colon. The Assign_Offset is for assignment statement and is aligned measuring from the beginning of the statement. The half indentation will cause the "when" clause of case state- ments, exception handlers, and variant parts of record declara- 10 Goddard Space Flight Center Standard Ada Pretty Printer tions and the "record" of the record declarations to be indented only half of a normal indentation level so that the enclosed portion of the construct will be indented one level. The reverse indentation applies to labels (which should not be used according to the Ada Style Guide) and to loop and block names. The reverse indentation causes them to stick out from the surrounding lines of code as in the Ada LRM rather than the Ada Style Guide. The capitalization parameters can be set for upper_case, lower_- case, or capitalize_first. Capitalize_First simply means that the first letter of each word is capitalized. A words in an Ada identifier must be separated by an underline to be capitalized. The one exception to this rule is: if an identifier ends with _IO then the 'O' is also capitalized. The capitalization parameters can be overridden for individual identifiers by using pragma Form. An echeloned declaration is one with the colon indented on the line following the identifier. An echeloned assign is one with the assignment indented on the line following the colon. (The echeloned assign flag is not considered unless the echeloned declaration flag is TRUE.) 11 Goddard Space Flight Center Standard Ada Pretty Printer 9. Pragmas and Creating a Specialized Pretty Printer: The Pretty Printer recognizes four pragmas. They are pragma Form_Set, pragma Form, pragma Format_Off, and Format_On. (The pragmas are all case insensitive.) pragma Form_Set (Parameter_Name => Value); The Form_Set pragma will set any of the parameters mentioned in the last section. The pragma can appear anywhere in the file being formatted and effects the formatting of the entire file and any other files which may follow immediately during the execution of the Pretty Printer. This pragma requires both the parameter name and new value. It can have multiple pairs of names and values, but it cannot continue over to a second line. There may be as many pragma Form_Set statements in a file as desired. When the same parameter is set more than once the last setting will be in force throughout the file being formatted. One exception to the parameter name requirement is the Pretty_Print_Format parame- ter. The value SPECIAL or NASA_STANDARD may be used without the parameter name, but the value must be the first setting listed in the pragma. Note: Settings of the parameters remain in effect throughout a series of formats done using a list of files starting at the beginning of the file in which they appear. This allows lists of files to be formatted uniformly without individual editing, but it will require that parameters be reset after an individual file in a list is formatted (in the next file) if they are meant to be in effect only for that one file. A recommended procedure is to place all such files at the end of any list of files to be form- atted with the pragma reset files between them. Files which contain only pragmas will be flagged as having a parse error (since they do not contain a unit), but the parameters will be set. Because the parse error is raised, a pragma file will not affect the total statistics. pragma Form (Identifier); The Form pragma allows the capitalization for individual iden- tifiers to be overridden. The capitalization used will be the first form appearing in the file (which may not necessarily be the one in the pragma). The pragma can appear anywhere in the file being formatted and affects the formatting of the entire file. This pragma can have multiple identifiers separated by commas, but it cannot continue over to a second line. This pragma does not carry over to subsequent files. 12 Goddard Space Flight Center Standard Ada Pretty Printer pragma Format_Off; pragma Format_On; The Format_On and Format_Off pragmas allow portions of a file to be excluded from the automatic indentation and spacing controls that the Pretty Printer performs. This allows tables and lists which have been indented and spaced for clarity to be left in their original clear form. These pragmas take effect at their positions in the file. The enclosed code will all be adjusted by the same number of spaces as the first line after the pragma. Note: Both pragmas in a given pair must appear at places in the code that have the same indentation level. (This means, for example, that the pragmas cannot be used to enclose only the condition line(s) of an if construct.) Creating a Specialized Pretty Printer: By setting the parameters in the Pretty_Printer_Parameters unit to the preferred values and recompiling, the user can set the Pretty Printer to the preferred local standard. If the Pretty_- Print_Format is set to NASA_Standard, the Special settings can be obtained simply by using one pragma statement: pragma Form_Set (Special); If the Pretty_Print_Format is set to Special, the NASA_Standard can still be obtained by: pragma Form_Set (NASA_Standard); 13 Goddard Space Flight Center Standard Ada Pretty Printer 10. Error Messages: Error messages can appear in several places. They can be in the terminal's output listing or the same output when sent to a file by the batch processing mode or they can appear in the formatted source code file. The error messages sent to the output listing or output file include: Parse Error Encountered in Line 20 ** this file contains goto_statement ** ** Storage_Error raised ** ** exception raised ** When the "parse error" message appears in the output listing there will be a corresponding error message in the -PP file (which will not be formatted) at the designated line which will look like: -- PARSE ERROR => @@^$^@ Where the thing after the => indicates the unparsable token. Often this error message will appear several times after a given line that will not parse because the parser will try to start parsing again with an unrecognizable piece of code. When this happens the last error message line following a given line of code will be the one that was generated first, and the token that is designated will be the one on which the parser failed. Error messages will also appear at the end of any construct that enclosed the original error. The "file contains" message is not actually an error. It is a flag designating Ada code that does not adhere to the Ada Style Guide. Not all violations of the Ada Style Guide are identified in this utility. (Some simply cannot be checked and other checks were not attempted.) The file causing a storage error in a list of files will be the last file processed because the pointers for the data base are controlled rather than recovered. Therefor, the space is un- usable for any other purpose and would only cause continual storage errors. However, the totals report is prepared and printed to a file (after the buffers are released by closing the file being processed), but the totals report will not include statistics on the file that caused the storage error. 14 Goddard Space Flight Center Standard Ada Pretty Printer 11. Limitations and Known Problems: Three limitations and known problems are enumerated in the fol- lowing paragraphs. One limitation which will affect many people is that the input source code is limited to 80 columns. This extension is one very desirable enhancement for which there simply was not enough time. Correction can be made by editing the code and inserting a line break between any two tokens in the long line before pretty printing. One known problem occurs when the Pretty Printer appends to the end of a line of code from the following line. Sometimes the spacing is not even. This can be corrected simply by rerunning the Pretty Printer using the -PP file as the input file. Another known problem occurs when a "begin" is followed by a "--" which is followed by an end of line with nothing but space bet- ween them. A parse error is generated because the Pretty Printer is looking for a syntactic comment. This can be corrected by editing the code and either removing the singular "--" or insert- ing something after it before pretty printing. 15 Appendix Ada Pretty Printer Code Documentation 1. Introduction to Code 2. Package Tokens and a Description of the Data Structure 3. Scan 4. Parse_Ada 5. Format 6. Print 7. Status_Report 8. Restart 9. Dump 10. Pretty_Print 11. Token 12. Source_Line 13. Page 14. Symbol_Text_Record 15. Symbol_Table_Entry 16. Parse_Tree_Node 17. List_Record 18. Reusable Code Ada Pretty Printer Notification 16 Appendix 1. Introduction to Code: The Pretty Printer is built around a complex data structure which is declared in package Tokens. This data structure is composed of seven interconnected record structures. These include Source- _Line, Token, Symbol_Table_Entry, Parse_Tree_Node, and several others which will be described in detail in the following sec- tions. Use of this data structure is available through seven major routines. These routines are Scan, Parse_Ada, Format, Print, Status_Report, Restart, and Dump which are described in the following sections. Several other units are also described which include the main routine, Pretty_Print, and several routi- nes which could be reusable such as Reserved_Words_Package. ---------------------------------------------------------------- 17 Appendix 2. Package Tokens and a General Description of the Data Structure: As described in the Introduction, the data structure in package Tokens is the heart of the Pretty Printer. Package Tokens con- tains more than the data structure. It contains the objects that serve as the hooks on which the data structure network hangs and a large number of the subroutines that serve the data structure. The data structure is made up of records with access pointers that serve to make the records both self recursive and intercon- necting. These records are: record name accessed by points into ------------------ -------------------- ----------- 1. Token Token_Pointer (1) 2 5 6 7 2. Source_Line Source_Line_Pointer 1 (2) 3. Page Page_Pointer 4. Symbol_Text_Record Symbol_Text_Pointer 3 (4) 5. Symbol_Table_Entry Symbol_Table_Pointer 1 4 (5) 6. Parse_Tree_Node Parse_Tree_Pointer 1 (6) 7. List_Record List_Pointer (7) The first group of objects that provide access to this structure is the group of objects and subroutines that control the freed records. They are First_Free_X, Last_Free_X, Blank_X, function New_X, and procedure Free_X where _X is the record name. The next group of objects that provide access to this structure is the group of objects that serve as the roots of the tables, tree structures, and cross reference lists. They include Start- er (the root for the Source_Line and Token structure), Reserved_- Table (Symbol_Table for reserved words), Table (Symbol_Table for other tokens organized by token kind), First_Rule (cross refere- nce for parse rules), and Parse_Tree (root of the Parse Tree). Many of the cross reference linkages are in the records of the data structure. The next group of objects that provide access to this structure is the group of objects that serve as the current position point- ers used in the utilities. These include Current_Line, Last_- Line, Current_Token, Current_Page, Page_Pos, and Last_Rule. Also Error_In_Code provides an inter-routine flag. Several objects also appear in the Tokens package which are primarily for the parse table generator (which uses the same data structure). These include Kind_Of_Scan, Class_Is_Open, Produc- tion, Defn_Count, and Class_Count. The Tokens package also includes one other package declaration, the State_Stack_Package. This package is used only in the Parse- _Ada routine, but it is included here because of implementation considerations. 18 Appendix The Tokens package declares two categories of subroutines, the data structure utility routines and the visible routines. The utility routines can be accessed only by the visible routines and other utility routines. For descriptions of these routines see the descriptions in the documentary comments with the subroutine declarations. The visible routines, Scan, Parse_Ada, Format, Print, Status_Report, Restart, and Dump, are described in the following sections. Two visible routines are not provided with the rest of this code. They are Generate_Tables and Edit. The Generate_Tables code contains more units than the rest of the Pretty Printer code but is not used directly in the Pretty Prin- ter. The code can be obtained by contacting NASA. The Edit routine was the original objective of the development project, but has not been developed yet. Both of these routines have stubs in the delivered code. ---------------------------------------------------------------- 3. Scan: This routine performs a lexical scan of Ada source code or a properly formatted syntax file. The products of this procedure are the source line, token, and symbol table data structures used by all the other routines in this package. This routine will read the source file and scan through the file one character at a time identifying the tokens and creating the symbol text and symbol table entries. The symbol table entries will all be cross referenced during the scan routine. Some of the more important routines used in the scan are Read_- Line, Add_Line, Start_Identifier, Finish_Identifier, Check_Reser- ved, Start_Number, Start_Symbol, Start_String, Start_Comment, Start_Comment_Word, Add_New_Token, Update_Source_Line, Add_To_- Symbol_Table, Add_Symbol_Text, Add_Symbol_Table_Entry, and Assign_Cross_Reference. The Read_Line routine is fairly intui- tive but it does contain the call to Add_Line which creates the Source_Line data structure. The Start_XX routines along with the Scan routine itself do the actual character by character iden- tifying of tokens. The Add_XX routines build the named parts of the data structure. And the other routines named serve to inter- connect the data structure. ---------------------------------------------------------------- 4. Parse_Ada: This procedure parses the internal tokens data structure made by the Scan routine and produces an internal parse table data structure used by the Format, Status_Report, and Dump routines. The parse procedure used is a simple LR parse. 19 Appendix The Parse_Ada routine is the only routine using the State_Stack_- Package. The parse tables are generated by the Generate_Tables routine which can also be obtained from NASA. The action tables are compressed with the table position being determined by the modulus of the table length and the conflict jump being deter- mined by the multiple of the table length as divided into the uncompressed table position (called Unique in the code). Com- ments are handled by creating individual parse trees for each comment and attaching them to the first non comment token for the line that they are in. (Left comments are attached to the EOL token.) This routine also does some minimal error recovery and places error messages in the source line and token data struc- ture. Some of the more important routines used in Parse_Ada are Assign- _Key_Values, Push_State_Stack, Pop_Top_Node, Attach_Comment, Error_Fix, and Add_Error_Comment. The Assign_Key_Values routine identifies the individual tokens and gives them keys. These keys determine the action to be taken by the parser. Every non EOL or EOF token is given a parse node as its initial sub-parse-tree. The Push_State_Stack and Pop_Top_Node routines enter and remove the sub-parse-trees and states from the state stack. The Attach_Comment routine handles comments as described above (which would not be necessary if the parser was reused as the front end of a compiler). To reuse this code as an incremental parser the final assignment to the Parse_Tree would simply be changed to whatever parse node was the father of the code being incremental- ly parsed. The Error_Fix simply takes the sub-parse-trees in the state stack as well as any unidentifiable tokens that follow and collects them as sons under a single error node. The parse con- tinues with the first token it expects to recognize. ---------------------------------------------------------------- 5. Format: The Format routine modifies the capitalization, spacing, position of line breaks and indentation in the source line and token data structure to correspond to the designated pretty print standard. The formatting process simply takes the directives which were attached to the parse nodes during parsing and moves them to the appropriate tokens. Tt then modifies the data structure accord- ing to the directives and parameter settings. Some of the more important routines used in the Format routine are Set_Pragma_Parameters, Identify_Parameter, Standardize_Para- meters, Standardize_Case, Verify_Syntactic_Comments, Move_- Actions_To_Tokens, Select_Pretty_Print_Action, EOL_Action, Action_# (where # is the directive number), Set_Token_Spacing, Format_Right_Comment, and Format_Left_Comment. The Set_Pragma_- Parameters, Identify_Parameter, Standardize_Parameters, and other Set_XX routines (where XX is the name of a parameter) are all 20 Appendix associated with the settings of parameters in the Pretty_Print_- Parameters package. The Standardize_Case routine and its sub- routines modify the capitalization of the various identifiers. (The reserved words will always be in lower case.) The Move_- Actions_To_Tokens actually moves the action directives from the parse tree where they are attached during the parse and attach them to the individual tokens where they act. The other routines all perform the action functions to format the Source_Line and Token data structure by adjusting the location of line breaks, indentation and token spacing. ---------------------------------------------------------------- 6. Print: This procedure produces a formatted source code file from the internal the Source_Line and Token data structure. The routines are Print and Print_Token. The Print routine coordinates which lines are printed, and the Print_Token prints the spaces and display text of a token. ---------------------------------------------------------------- 7. Status_Report: This routine produces a status report on statement counts for a specified file or for the totals from a list of files. The subroutines are Calculate_Counts, Sum_Counts, Print_Counts, and Print_Totals. These routines are the primary users of the Status_Data package. The statistics are gathered primarily from the cross reference counts of parse tree node types. Some are calculated using the relationships of nodes in the parse tree. The Parse_Keys package and the Syntax.Dat file will be very valuable to anyone who wants to modify the selection of statis- tics. ---------------------------------------------------------------- 8. Restart: This routine resets the variables of this package to their ini- tial state. The hooks for the data structures are cleared and the individual records are released to their free lists for reuse. Note: Since the data structure is controlled, once a storage error occurs the data structure is corrupted and can no longer be properly recovered. The major subroutines of this routine are Free_All_Symbol_Tables, Free_All_Source_Lines_And_Tokens, Free_Parse_Tree, and the Free_X routines of the Tokens package (where X is a data record struct- ure). These routines traverse the data structures and release the records to their various free lists. 21 Appendix 9. Dump: This routine will dump the internal token and parse data struc- tures into files. This routine and its Dump_XX and Print_XX rou- tines were written as part of the debug reporting for the Gener- ate_Tables routine, but they are included here because they may be helpful to anyone wanting a better look into the data struc- ture. They will need to be rewritten slightly for your individual purposes. ---------------------------------------------------------------- 10. Pretty_Print: The main routine of the Pretty Printer guides the flow of control through the routines discussed above. The Pretty Printer opera- tes two main paths, one for single file processing, the other for a list of files. This routine starts by checking for the presence of a file called Files_In.LST to determine if batch processing is in effect. If it is present and the first word is "batch" then the default output is reset to the filename indicated. If the Files_In.LST file is not present then a prompt is sent to the user to desig- nate the file to be formatted. If the filename entered by the user is not prefaced by an "at" sign, then the processing path for the single file is executed. Otherwise the processing path for the list of file is executed. 22 Appendix 11. Token: type TOKEN_KIND is ( UNKNOWN, RESERVED_WORD, IDENTIFIER, NUMERIC_LITERAL, CHARACTER_LITERAL, STRING_LITERAL, COMMENT_WORD, SPECIAL, OPERATOR, OTHER ); type TOKEN_POINTER is access TOKEN; type TOKEN is record Number : INTEGER := 0; Line : SOURCE_LINE_POINTER := null; Spaces : INTEGER := 0; Column : INTEGER := 0; Next : TOKEN_POINTER := null; Kind : TOKEN_KIND := UNKNOWN; Symbol : SYMBOL_TABLE_POINTER := null; Rule : INTEGER := 0; Construct_Position : NATURAL := 0; Directive : NATURAL := 0; Dir_List : LIST_POINTER := null; X_Ref_Next : TOKEN_POINTER := null; Parse : PARSE_TREE_POINTER := null; end record; This data structure record is the focus of the pretty printer. It provides connections to every other data structure either directly or indirectly. (See list in Section 2.) Most Token records are created during the Scan routine. Others are added by the Format routine. As they are added to the data structure the text from the original source file that the token represents is placed in the symbol table with the appropriate references and cross references in the Token record. In the Parse_Ada routine each Token record receives a Parse_Tree_Node record as its indi- vidual connection to the parse tree. At the beginning of the Format routine the action directives are collected and added to the Dir_List in parse tree order and are acted on in source line order. The Print routine creates the formatted source code for output from the Token records. And the Restart routine frees them for reuse. The individual components are used as follows: Number : identifies the order of the tokens and is used only for debug purposes. Line : points to the Source_Line record to which the Token record currently belongs. 23 Appendix Spaces : designate the number of spaces in front of the Token. This value is modified by the Format routine to make the code pretty. Column : designates the position from the beginning of the line of code of the last character of the preceding token in the line. Next : points to the next Token record. Kind : categorizes the token. (See the Token_Kind type declara- tion.) SPECIAL includes EOF, EOL, etc. Symbol : points to the Symbol_Table record which points to the Symbol_Text record which points to the Page and Position on the page containing the token's text string. This text string has its capitalization modified by the Format routine to make the code pretty. Rule : is used only in the Generate_Tables routine. Construct_Position : is used only in the Generate_Tables routine. Directive : is used only in the Generate_Tables routine. Dir_List : points to the head of the List records which contain the action directives. X_Ref_Next : points to the next Token record having the same symbol. Parse : points to the Parse_Tree_Node that is attached to this Token. ---------------------------------------------------------------- 12. Source_Line: type SOURCE_LINE_POINTER is access SOURCE_LINE; type SOURCE_LINE is record Line_No : INTEGER := 0; First_Token : TOKEN_POINTER := null; Last_Token : TOKEN_POINTER := null; Token_Count : NATURAL := 0; Prior : SOURCE_LINE_POINTER := null; Next : SOURCE_LINE_POINTER := null; end record; Most of the Source_Line records are generated by the Scan rou- 24 Appendix tine. Others are added by the Format routine to make the code pretty. The combination of the Source_Line records and Token records corresponds very closely to the source code. The individual components are used as follows: Line_No : identifies the order of the source lines and is used primarily for debug purposes. The Print routine will accept a range of line numbers for printing. Note: because the Format routine does not completely renumber the lines, ranges can get misrepresented if the lines are not renum- bered first. Therefore, if you reuse the code to print portions of code by line number be sure to renumber first. First_Token : points to the first Token record in the line. Last_Token : points to the last Token record in the line. Token_Count : indicates the number of Token records in the line. Prior : points to the prior Source_Line record. Next : points to the next Source_Line record both in the Source_- Line structure and in the free list. ---------------------------------------------------------------- 13. Page: type PAGE_POINTER is access PAGE; subtype PAGE is STRING (1 .. Page_Size); Page_Pos : NATURAL := 0; The Page array is used to hold both a display and a match copy of the symbol text. The match copy is always all lower case. Literals will have only one copy since they are never compared for a match. And reserved words have only one copy since their display form and match form are always the same (all lower case). This array is the target of the Source_Text pointers. Since this is an array the free list is maintained by a separate array of pointers. ---------------------------------------------------------------- 25 Appendix 14. Symbol_Text_Record: type SYMBOL_TEXT_POINTER is access SYMBOL_TEXT_RECORD; type SYMBOL_TEXT_RECORD is record Page : PAGE_POINTER := null; Pos : NATURAL := 0; Len : NATURAL := 0; Next : SYMBOL_TEXT_POINTER := null; end record; The Symbol_Text record designates the Page and the position and length of the text on the page. This record structure is pointed at by the Symbol_Table record. The individual components are used as follows: Page : points to the page containing the text. Pos : references the starting position of the first character of the text. Len : indicates the number of characters in the text. Next : is used by the free list. ---------------------------------------------------------------- 15. Symbol_Table_Entry: type CAP_TYPE is ( NORMAL, ENUMERATION, TYPE_SUBTYPE, SPECIAL ); type SYMBOL_TABLE_POINTER is access SYMBOL_TABLE_ENTRY; type SYMBOL_TABLE_ENTRY is record Key : NATURAL := 0; Match : SYMBOL_TEXT_POINTER := null; Display : SYMBOL_TEXT_POINTER := null; Cap : CAP_TYPE := NORMAL; Prior : SYMBOL_TABLE_POINTER := null; Next : SYMBOL_TABLE_POINTER := null; Lesser : SYMBOL_TABLE_POINTER := null; Greater : SYMBOL_TABLE_POINTER := null; Count : NATURAL := 0; X_Ref_First : TOKEN_POINTER := null; X_Ref_Last : TOKEN_POINTER := null; end record; 26 Appendix type SYMBOL_TABLE_HEADER is record First : SYMBOL_TABLE_POINTER := null; Head : SYMBOL_TABLE_POINTER := null; Last : SYMBOL_TABLE_POINTER := null; end record; type SYMBOL_TABLE_ARRAY is array (TOKEN_KIND) of SYMBOL_TABLE_HEADER; The Symbol_Table_Entry record is created by the Scan routine for each unmatched token found in the source code. The Symbol_Text records are created at the same time, and so are the Page entri- es. When a matching token symbol entry is found it is added to the cross reference list of the matched Symbol_Table_Entry. Each Symbol_Table_Entry is part of a Symbol_Table which is organized in two ways, an alphabetical list and a binary tree. These both start with a Symbol_Table_Header which contains the first and last entry of the alphabetical list and the head (root) of the binary tree. The binary tree is created by order of appearance in the source code. (No special balancing is done to improve speed.) The individual components are used as follows: Key : is assigned and used in the Parse_Ada routine. These Keys can be found in the Parse_Keys package. Match : points to the Symbol_Text record used for comparisons in the binary search. Display : points to the Symbol_Text record which is modified by the Format routine to make the code pretty and which is used by the Print routine. Cap : designates the form of capitalization to be used. (See the Cap_Type.) When the Form pragma is used, the Special value is assigned. Otherwise, the capitalization is modified in the Format routine according to the parameters designated for the capitalization type. Prior : points to the prior Symbol_Table_Entry in the alphabetic list. Next : points to the next Symbol_Table_Entry in the alphabetic list. This component is also used by the free list. Lesser : points to the prior Symbol_Table_Entry in the binary tree. 27 Appendix Greater : points to the next Symbol_Table_Entry in the binary tree. Count : indicates the number of tokens in the cross reference list. X_Ref_First : points to the first token in the cross reference list. X_Ref_Last : points to the last token in the cross reference list. ---------------------------------------------------------------- 16. Parse_Tree_Node: type PARSE_TREE_POINTER is access PARSE_TREE_NODE; type PARSE_TREE_NODE is record Number : NATURAL := 0; Rule : NATURAL := 0; Rule_Next : PARSE_TREE_POINTER := null; Pp_Dir : NATURAL := 0; Token : TOKEN_POINTER := null; Father : PARSE_TREE_POINTER := null; Brother : PARSE_TREE_POINTER := null; Comment : PARSE_TREE_POINTER := null; Sons : NATURAL := 0; First_Son : PARSE_TREE_POINTER := null; Last_Son : PARSE_TREE_POINTER := null; end record; The Parse_Tree_Node record is the second most important member of the data structure. This record provides the direct link between the Ada Syntax and the code, and it is the avenue for taking the action directives that are associated with the Syntax and attach- ing them to the tokens. The Parse Tree is a simple tree struc- ture with each node having only one father and either a token or a sub-parse-tree as a subordinate. The first level of any sub- parse-tree can have zero to many sons. Each Parse_Tree_Node designates its own immediate next Brother node in this first level of sons. All the brothers will designate the same Father node. The Parse Tree is created by the parser in the Parse_Ada routine. (The Parse Tree could alternately be created by select- ing syntax structures in a language sensitive editor. Since this was the originally intended product the Parse_Tables package and the related data files already contain the data to build these constructs directly.) 28 Appendix The individual components are used as follows: Number : indicates the order of the Parse_Tree_Nodes. This is primarily for debug purposes. Rule : designates the Syntax rule associated with a sub-parse- tree. This corresponds to the Parse Keys in the Parse_Keys package and to the Key in the Token record. It is assigned as the parser performs its reduce step. Rule_Next : points to the next Parse_Tree_Node in the cross reference list for the rule indicated. Pp_Dir : is the action directive associated with the given posi- tion of the father node's rule. The values for this com- ponent are provided in the Directives table of the Parse_- Tree package or the associated data file. Token : points to the Token record that is associated with this node. The Token component will always be null when the node has one or more son nodes. Father : points to the father node of the parse tree. Brother : points to the next brother node of the parse tree. This component is also used by the free list. Comment : points to a special sub-parse-tree which is a right comment. This will usually only be used when there is a token record subordinate. Sons : indicates the number of son nodes in the sub_parse_tree. First_Son : points to the first son node of the sub_parse_tree. Last_Son : points to the last son node of the sub_parse_tree. ---------------------------------------------------------------- 17. List_Record: type LIST_POINTER is access LIST_RECORD; type LIST_RECORD is record Ref : NATURAL := 0; Next : LIST_POINTER := null; end record; The last record structure used in the data structure of the pretty printer is the List record. This is simply a list that is 29 Appendix recursive. The only use in the Pretty Printer is for attaching multiple directives to a given token. (It is used for several other kinds of lists in the Generate_Tables routine.) The individual components are used as follows: Ref : designates the reference value of the action directive. Next : points to the next List record. This component is also used by the free list. ---------------------------------------------------------------- 18. Reusable Code: Not only can the code be used for readily modifiable Ada pretty printer, but with reasonably little modification this code could be used for any language syntax by generating the parse tables using the associated Generate_Tables routine. Similarly the code can be used as a basis for development of a language sensi- tive editor. Or it could even be used as the front end of a compiler. Some individual components which might be reusable individually include the package Reserved_Words, the procedure Lower_Case, and the procedure Next_Prime. 30 The source code and data files for GSFC Ada Standard Pretty Printer is in the public domain, but NASA does request to be notified of how many copies are made to encourage funding for similar development for the public domain. Therefore, please fill out this page and return it to: Ada Pretty Printer Notification c/o Ms. Elisabeth Brinker -- Code 522 Data Systems Applications Branch Goddard Space Flight Center Greenbelt, Maryland 20771-0001 ----------------------------------------------------------------- Ada Pretty Printer Notification Version 1.1 Name ____________________________________________________________ Address _________________________________________________________ _________________________________________________________________ _________________________________________________________________ Copies ___________________ Modified Copies _________________ _ |_| I would like information regarding any modifications since version 1.1 Comments ________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________