GEMini Atari

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

/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / fcc / manual.asc < prev next >

Wrap

Text File | 1991-12-14 | 37.3 KB | 913 lines

FLOW CHART COMIPLER MANUAL version 1.0 PLEASE SEND ANY PROBLEM REPORTS TO: Mark Falleroni 1029E. 4750S. Ogden, Utah 84403 PLEASE INCLUDE A DESCRIPTION OF THE PROBLEM, ALONG WITH THE FLOW CHART SOURCE FILE THAT CAUSED THE PROBLEM System Requirements: 512K, Color Monitor, Gemini 10X or compatible PURPOSE AND OBJECTIVES The purpose of this program was to determine a method to solve the problem of the manual generation of flowcharts. The objective is to develop software that will automate the flowchart design and development process. PROPOSED SOLUTION The solution to the problem was to develop a unique flowchart design language that could be compiled. The requirement to compile the flowchart design language resulted in a flowchart compiler that can compile a flowchart design language source file, display the compiled file to a windowed environment, and print the compiled file in a high resolution graphics mode. There are example source files at the end of this document to help familiarize you with the language and compiler. DEFINITION OF TERMS FDL - Flowchart Design Language; a design language used to describe a software design. The FDL is the source language for the Flowchart Compiler. FCC - acronym for the FlowChart Compiler. Ellipses - Any menu item followed by an ellipses (...) indicates that further input is required. The ellipses usually follows menu items that prompt for filenames, module names or page numbers. Output File - a file created by the flowchart compiler. This type of file is the result of a successful compile of an ASCII text, flowchart design language file. It contains commands for the drawing module. These commands contain information that determines the type of flowchart symbols that are drawn, their positions, and connectivity relationships with other flowchart blocks. DESIGN The flowchart compiler was written in the C programming language. It takes full advantage of the desktop metaphor features provided by the GEM interface. The compiler was designed to perform the following functions: 1. Compile flowchart design language source code 2. Display a module complexity estimate 3. Display a compiled file to a scrollable window 4. Print a compiled file in a high resolution 5. Edit a flowchart design language source file 6. Display the amount of free system memory 7. Display the amount of free disk memory 8. Display help screens to the user FLOWCHART DESIGN LANGUAGE (FDL) A structured language was developed to facilitate the development of flowcharts. It is simply called the Flowchart Design Language and will be referred to hereafter as the FDL. The language is similar to modern day high level structured programming languages and contains most of the other programming language constructs. The language consists of control statements, looping statements, a call subroutine statement, assignment statement and page layout commands. It does not support the use of a 'goto' or the premature exit from a loop. The FDL was designed to represent existing software or new designs of a modular nature and it is best used in that manner. The FDL is very flexible from a user perspective in that it can be as detailed or as general as desired. If a high level use is desired, statements similar to those found in a program design language can be used. If a low level use is desired, statements very close to a programming language can be used. KEYWORDS The following is a list of FDL keywords: ^, if, while, for, call, then, else, endif, endwhile, do, endfor, until, repeat, program, endprg, module, endmod, ife, endelse, header, footer, date To be recognized as a keyword by the flowchart compiler, the following FDL keywords must appear as the first word in an FDL statement: ^, if, while, for, call, until, repeat, endif, else, endwhile, endfor, ife, endelse The keywords listed above can be used anywhere in the string of a statement. If they are not used as the first word, they are not recognized as keywords. An example would be the use of the keyword 'for' in the middle of the following high level assignment statement: "Set a = b for the next pass through the loop;" All FDL statements must be terminated with a semicolon. PAGE LAYOUT STATEMENTS All page layout statements must begin with a carrot '^'. Only the following keywords can appear after a carrot: program, endprg, module, endmod, header, footer, date Program Statement The program statement must be the first statement of any FDL source file. It has the following form: ^program program_name; The program_name string is required and must be less than 15 characters in length. On printed or displayed output, the program_name string is positioned in the upper left corner of the flowchart page. Endprg Statement The endprg statement must be the last statement in an FDL source file. It must immediately appear after the last endmod statement since it signals the end of the file. The endprg statement has the following form: ^endprg; Module Statement The module statement indicates the beginning of a module and must immediately follow the program statement or an endmod statement. The module statement has the form: ^module module_name; The module_name string is required and must be less than 14 characters in length. The module_name string is placed in the module ENTRY block. Each module begins with a '^module module_name;' statement and ends with an endmod statement. Endmod Statement The endmod statement indicates the end of a module. It must match a prior module statement. It has the form: ^endmod endmod_string; An example of the use of the endmod statement follows: ^module One; statement 1; statement 2; statement 3; ... ... ... statement n; ^endmod Return To Caller; The endmod string is required and must be less than 17 characters in length. The endmod string appears in the exit block of the flowchart. Header Statement The header statement can appear anywhere in a module. It has the form: ^header header_string; The header string must be less than 35 characters in length. On printed or displayed output, it appears just to the right of the program name at the top of the flowchart page. A header is a useful item that can be used to display a module name at the top of each page. If multiple header statements appear in a module, the last header statement is considered legitimate and the previous header statements are ignored. The header statement is optional and need not appear in the source file. Footer Statement The footer statement can appear anywhere within a module. It has the form: ^footer footer_string; The footer string must be less than 45 characters in length. On printed or displayed output, it appears at the bottom of the page, approximately 25 characters from the left margin. A footer is a useful item that can be used to display a module name at the bottom of each page. If multiple footer statements appear in a module, the last footer statement is considered legitimate and the previous footer statements are ignored. The footer statement is optional and need not appear in the FDL source file. Date Statement The date statement is used to indicate the month, day and year that the source file was developed. It is an optional statement.The date statement has the form: ^date mon day year; where mon = three character month (Dec, Nov, etc.) in upper or lower case day = two character day year = four character year The date appears in the upper right part of the displayed or printed flowchart output. CONDITIONAL STATEMENTS The FDL supports two conditional statements; they are if..then..endif, and ife..then..else..endelse. The if..then..endif statement has the form: if conditional_statement then statement 1; statement 2; ... ... statement n; endif; The conditional statement must be less than 40 characters in length and any single word within the conditional statement must be less than 17 characters. Words that are greater than or equal to 17 characters in length will cause a code generator error. The 'then' keyword must follow the conditional statement and the 'endif' keyword terminates the 'if' conditional statement. This statement is used to bypass processing if the condition is false. The second conditional statement is the ife..then..else..endelse statement. This statement is similar to the previous one with regards to the length of the conditional statement and individual word length. This statement is used to execute one processing path if the condition is false and another processing path if the condition is true. It has the form: ife conditional_statement then statement 1; statement 2; .. statement n; else statement n + 1; statement n + 2; .. statement n + m; endelse; These conditional statements can be nested within each other to a level that does not exceed the FCC complexity limit of 15. LOOPING STATEMENTS The FDL supports three looping structures; they are while, for, and repeat. There are restrictions on their use due to the type of flowchart block each statement generates. While Statement The while statement is used to execute processing while a condition is true. Once the condition becomes false, the loop is exited. The while statement has the form: while condition_statement do statement 1; ... statement n; endwhile; The 'do' keyword must follow the condition statement. The 'endwhile' keyword terminates the while statement. Due to the type of flowchart blocks that are generated by a while statement, a while statement cannot immediately follow another while statement. This is demonstrated below: while x > y do while z > a do { THIS IS NOT ALLOWED } { THIS IS ALLOWED } while x > y do initialize z; while z > a do .. .. endwhile; endwhile; A while statement cannot immediately follow an ife..then..else..endelse statement. This is demonstrated below: ife the condition is true then while x < 100 do { THIS IS NOT ALLOWED } { THIS IS ALLOWED } ife the condition is true then initialize x; while x < 100 do .. .. endwhile; else .. endelse; A while statement cannot immediately follow a for..do..endfor statement. This is demonstrated below: for x = 100 0 - 1 do while a > 34 do { THIS IS NOT ALLOWED } { THIS IS ALLOWED } for x = 100 0 - 1 do initialize a; while a > 34 do .. .. endwhile; endfor; For Statement The for statement is another looping statement supported by the FDL. It has the following form: for loop_var = init_val limit_val sign increment do statement 1; statement 2; ... statement n; endfor; The loop_var can be any character or word. The init_val can be a number or a character or word. The init_val is the value given to the loop_var at the beginning of the for loop. The limit_val can be a character or a word or a number. The loop_var is compared to the limit_val at the beginning of the for loop. The sign must be either a '+' or '-'. The increment must be a number. Based upon the sign, the increment is added or subtracted to the loop_var at the end of the for loop. If the sign is positive, the loop_var is tested to see if it is less than the limit_val. If the sign is negative, the loop_var is tested to see if it is greater than the limit_val. FOR statements can be nested to a level that does not exceed the FCC complexity limit of 15. Repeat Statement The repeat statement allows the subsequent processing that occurs within the loop to execute at least once. The repeat statement has the form: repeat statement 1; ... statement n; until condition_statement; The repeat statement cannot immediately follow a while statement, a ife..then..else..endelse statement or a for statement. This is demonstrated below: while loopvar < limit do repeat { THESE ARE NOT ALLOWED } ife condition is true then repeat for a = 0 100 + 1 do repeat { THESE ARE ALLOWED } while loopvar < limit do any legal statement; repeat .. until condition is false; .. endwhile; ife condition is true then any legal statement; repeat; .. until condition is false; else .. endelse; for a = 0 100 + 1 do any legal statement; repeat .. until condition is false; .. endfor; The 'until' keyword, if used as the first word in a statement, indicates the end of the repeat statement. The conditional statement must be less than 40 characters in length. Any word within the conditional statement cannot be longer than 16 characters. ASSIGNMENT STATEMENT The assignment statement is simply any string that does not begin with a keyword. The minimum string size is 2 words and the maximum is 60 characters. The maximum word length in an assignment statement string must be less than 19 characters. An assignment statement can follow any other statement. SUBROUTINE CALL STATEMENT The call statement must begin with the keyword 'call'. It can be 49 characters in length. The maximum word length within a call statement string is 17 characters or less. The call statement has the form: Call module get_char() to input the next letter; When displayed or printed, the keyword 'call' is spelled in all capital letters. SYNTAX FDL syntax was designed to be straightforward and easy to remember. Most of the FDL syntax rules were discussed above. Here are the remaining syntax rules for the FDL: 1. Any statement that does not begin with a keyword is considered to be an assignment statement. 2. All statements must terminate with a semicolon. 3. Each FDL source file must begin with the FDL statement - '^program progname;' where progname is the name of the program. 4. The program name must be less than 16 characters in length. 5. Each FDL source file must terminate with the FDL statement - '^endprg;'. 6. A '^module module_name;' statement must immediately follow a program statement. 7. FDL source statements can be upper or lower case characters or a combination thereof. 8. Comment statements must begin with a '{' and end with a '}'. Once a left curly brace is encountered by the FCC scanner, all subsequent text is ignored by the scanner until an End Of File or a right curly brace is found. FLOWCHART COMPILER PROGRAM DESIGN Flowchart Compiler Menu Titles and Items Title Choices Desktop About the Flowchart Compiler... File Compile Display Print Edit Delete Quit Options Display Next Page Output Set Edit Info Browse Manual Memory System Disk Help Compile Display Print Edit Set Edit Pathname Browse Manual Each menu title and menu item within a title will now be discussed: Desk By convention, the desk menu contains one application item choice, and up to six accessories. File Menu Under this title, there are items that manipulate files. There is also a menu item that if selected, will exit the program. Compile The 'Compile...' item displays a dialog box that prompts the user for the full pathname of the input file, output file, temporary file, and error file. If a valid input filename is entered and the file successfully opened for reading, a window is opened. Status messages and/or error messages are scrolled in the window to inform the user of compilation progress. The FCC scans, then parses the input file. If errors are detected, a message is output to the screen and it is also written to the error file. Modules that have errors do not have code generated. If one module has an error, the output file is assumed to be corrupted. Display This menu item will display a successfully compiled file in a window. 23% of the first flow chart page will be displayed. The window can be scrolled vertically or closed at any time. To view subsequent pages, choose 'Display Next Page' from the 'Options' menu. Print The Print item allows the user to print a compiled file in 120 horizontal by 72 vertical resolution. The user is prompted for a filename. If the file can be successfully opened, the display window is opened. The first page of the file is copied into the offscreen buffer and approximately 23% is displayed in the display window. The contents of the offscreen buffer are then printed. The user can prematurely terminate the print function by typing Control D. Edit This menu item allows an editor to be Pexec'd. You must specify the full pathname of the editor you want to use in the 'Set Edit Info' item from the 'Options' menu. Delete This menu item displays a standard file selector box and will delete any selected file. Options Menu This menu contains items that allow the user to display pages of a compiled flowchart file, specify a range for flowchart output, specify editor information, or browse this manual. Display Next Page This menu item is enabled only when a flowchart file is being displayed. It displays the next page of the flowchart file to the screen. Output This selection displays a dialog box that allows the user to select display or print options. All pages, only a module, or only a page range within a module will be displayed or printed. If all pages are selected the user should then exit the dialog. If a module is selected, then the user needs to enter the name of the module (case sensitive) to be displayed. If the user wants to print a page range within a module, he/she should enter the module name, and the start and stop page numbers. Set Edit Info This selection allows the user to name the work file for a session. It also allows the user to specify which editor should be invoked when the 'Edit' item is selected from the 'File' menu. When the editor is invoked, it will automatically load the named file. Memory Menu The memory menu item contains two choices; system and disk. System This selection displays the amount of free system memory in an alert box. Disk The user is prompted for a drive letter. The amount of free space, used space and total space is displayed in an alert box. Help Menu The items under this menu title display information about the selection. The Browse Manual selection invokes the editor and this documentation file is automatically loaded. The user should write protect this file to prevent any inadvertant modification. ************ Language (BNF) Accepted by the Flow Chart Compiler ********* There may be an error or two here... Legend: <...> non-terminals, | or, + after non-terminal is considered superscript <program> ::= ^program <string>; <modules> ^endprog; <modules> ::= ^module <string>;<statements> ^endmod<string>; <modules> | /\ <statements> ::= <statement> <statements> | /\ <statement>::= if <condition> then <statements> endif ; | ife <condition> then <statements> else <statements> endelse;| <assignment statement>; | while <condition> do <statements> endwhile ; | repeat <statements> until <condition> ; | /\ (NULL string); | for <loop var> = <initial val> <limit val> <sign> <increment val> do <statements> endfor ; | <layout command> ;| call <string>; | {<comment>} <condition> ::= <string> <string> ::= <char><string> | /\ <char> ::= a|b|c|d..z|A|B|C|D..Z|0..9|!|"|#|$|%|&|'|(|)|space| *|+|,|-|.|/|:|?|@|[|\|]|^|_|`|{|} <assignment statement> ::= <string> <loop var> ::= <string> <digit> ::= 0..9 <initial val> ::= +<digit>+ | -<digit>+ | <digit>+ <limit val> ::= <initial val> <sign> ::= + | - <increment val> ::= <digit>+ <layout command> ::= ^<command> <string> | ^date <month> <day> <year> <command> ::= header | footer <month> ::= jan | feb | mar | apr | may | jun | jul | aug | sep | oct | nov | dec <day> ::= <digit>2 <year> ::= <digit>4 <comment> ::= <string> The Flow Chart Design Language (FDL) Keywords are: ^, if, ife, endelse, while, for, call, then, else, endif, endwhile, do, endfor, until, repeat, program, endprg, module, endmod Flow chart string length capacity is less than 60 characters for any block. All statements are terminated with a semicolon. Comments can be placed anywhere within the source file. ************** Compiler Error Messages ************************ "Expected '^' for Module statement." - the compiler expected to find a '^' before a module statement "Missing '^ENDPRG;' statement." - an end of file was read before the '^ENDPRG' statement was found "Expected '^' for PROGRAM statement." - the compiler expected to find a '^' before a PROGRAM statement "PROGRAM statement expected." - compiler expected to find a PROGRAM statement "Missing program NAME." - the compiler parsed a semicolon instead of a program name "Program NAME expected; keyword found." - the compiler parsed a keyword instead of a program name "Program NAME exceeds 15 character limit." - the program name exceeded the maximum length "MODULE keyword expected." - the compiler expected to find a MODULE keyword "Module NAME exceeds 13 character limit." - the module name exceeded the maximum length "Missing module NAME." - the compiler expected to find a module name but found a semicolon instead "HEADER string length exceeds 35 characters." - the HEADER string exceeded the allowable limit "FOOTER string length exceeds 45 characters." - the FOOTER string exceeded the allowable limit "Page number string string length exceeds 4 characters." - page number string length exceeded the allowable limit "Invalid character in page number." - page number contained a non numeric character "PROGRAM statement should be the first statement in the file." - the program keyword was used incorrectly, it can only be used to declare a program at the beginning of the FDL source file "ENDMOD string length exceeds 17 character limit." - the string length exceeded the allowable limit "MODULE statement must follow ENDMOD statement." - MODULE keyword can only be used to declare a module in a FDL source file "ENDPRG statement must follow ENDMOD statement." - the ENDPRG keyword can only be used after an ENDMOD statement to terminate the FDL source file "Invalid MONTH in DATE statement." - the month string in a DATE statement did not match the first 3 characters of any month "Invalid DAY in DATE statement." - day field in date statement is not a number or the length is > 2 characters "Invalid YEAR in DATE statement." - the year field in a date statement is is not a number or the length is > 4 characters "Missing semicolon." - compiler expected to parse a semicolon "String length exceeds 60 character limit." - string length for an operand exceeds the maximum string length limit. "No Text String Found." - compiler expected to parse a string but instead parsed a semicolon "REPEAT statement cannot immediately follow WHILE." - a repeat statement immediately followed a while statement in the source file "REPEAT statement cannot immediately follow IFE." - a repeat statement immediately followed the start of an IF..THEN..ELSE..ENDELSE structure "REPEAT statement cannot immediately follow FOR." - repeat statement immediately followed a FOR statement "Expected COMMAND statement." - the compiler expected to parse a command statement after a '^' keyword "IF condition string length exceeds 40 characters." - the string length for the conditional part of an IF statement exceeded the maximum length allowed "WHILE statement cannot immediately follow WHILE." - a while statement immediately followed another while statement "WHILE statement cannot immediately follow FOR." - a while statement immediately followed a for statement "WHILE statement cannot immediately follow IFE." - a while statement immediately followed an ife statement "WHILE condition string length exceeds 40 characters." - the conditional string length of a while statement exceeded the maximum limit "THEN keyword improperly used." - the then keyword was not used as the terminator of an IF or IFE statement "No matching IFE statement." - an ELSE keyword was used incorrectly, the compiler couldn't find a matching IFE statement "No matching IF statement." - an ENDIF statement was used incorrectly, the compiler parsed an ENDIF and couldn't find the corresponding IF statement. "No matching WHILE statement." - an ENDWHILE statement was used incorrectly, the compiler parsed an ENDWHILE and couldn't find a matching WHILE statement "UNTIL condition string length exceeds 40 characters." - the conditional string for an UNTIL block exceeded the maximum string length limit "No matching REPEAT statement." - an UNTIL keyword was used incorrectly, the compiler parsed an UNTIL keyword and could not find a matching REPEAT statement "No matching ELSE statement." - the ENDELSE keyword was used incorrectly, the compiler parsed the ENDELSE keyword and could not find a matching ELSE statement "IFE condition string length exceeds 40 characters." - the conditional string part of an IFE statement exceeded the maximum length limit "No condition string found." - the compiler expected to parse a conditional string and the string consisted of only 1 word or a semicolon was parsed instead "Missing DO keyword in a WHILE statement." - the compiler parsed a WHILE statement without parsing the DO keyword after the conditional string "Missing THEN keyword in IF statement." - the compiler parsed an IF statement without parsing the THEN keyword after the conditional string "Conditional string length exceeds 40 character limit." - during the parse of a conditional string, the length exceeded the maximum length limit "Expected to find a string." - during the parse for an assignment string, a semicolon was found before a string "ASSIGNMENT string length exceeds 60 characters." - the length of an assignment string exceeded the maximum length limit "CALL string length exceeds 56 characters." - the length of a CALL string exceeded the maximum length limit "Missing LOOP VARIABLE in FOR statement." - the compiler expected to parse a loop variable for a FOR statement and found a keyword instead "Missing '=' in FOR statement." - compiler expected to find an '=' for a FOR statement "Missing INITIAL VALUE in FOR statement." - compiler expected to find an initial value for a FOR statement and instead found a keyword "Missing LIMIT VALUE in FOR statement." - compiler expected to find a limit value for a FOR statement and instead found a keyword "Missing + or - operator in a FOR statement." - compiler expected to find an increment/decrement sign for a FOR statement "Missing INCREMENT VALUE in FOR statement." - compiler expected to find an increment value for a FOR statement and instead found a keyword "Missing DO keyword in a FOR statement." - compiler expected to find a DO keyword in a FOR statement "No matching FOR statement." - incorrect use of the ENDFOR keyword, the compiler parsed an ENDFOR statement and could not find a matching FOR statement "Missing ENDIF statement." - there is an IF statement in the module that is not terminated by an ENDIF statement. This error is discovered when the ENDMOD statement is processed. "Missing ENDFOR statement." - there is a FOR statement in the module that is not terminated by an ENDFOR statement. This error is discovered when the ENDMOD statement is processed "Missing ENDWHILE statement." - there is a WHILE statement in the module that is not terminated by an ENDWHILE statement. This error is discovered when the ENDMOD statement is processed "Missing UNTIL statement." - there is a REPEAT statement in the module that is not terminated by an UNTIL statement. This error is discovered when the ENDMOD statement is processed "Code Generator: String -> <STRING> ... doesn't fit in block." - code generator error; even though a string does not exceed the string length limit, the string will not fit inside the specified block. Reword (reduce the size) the string in the editor and recompile the source file "Unmatched '{' caused early read of EOF." - a comment was started and not finished with a closing '}'. The compiler searched to the end of file for the missing '}'