-- -- Author: Robert C. Shock, Dept of CS & CEG Wright State University -- In cooperation with: WRDC/ELED WPAFB Dayton, OH -- USER HELP GUIDE TO THE VHDL STYLE TOOL SET Sections: 1 INTRODUCTION 2 EXAMPLES 3 SUMMARY 4 CONSTRAINTS 1 INTRODUCTION 1.1 Intent of this tool set This document describes a set of software tools that operate on vhdl source code. This tool set provides the mechanism to customize many textual code characteristics of vhdl code to an individual's style of programming. These tools allow a programmer to impose his/her own style on the appearance of vhdl source code. The effect of a programmer working in his/her personal style is to increase productivity while not imposing a particular style on other programmers that will later use his code. Why another textual tool set? Most commercial tools operate on a textual document, not vhdl source code. Why not use a prettyprinter? Sommerville pinpoints a major deficiency of using a prettyprinter in a work environment. The problem with most prettyprinting systems is that they incorporate a set of conventions which have been invented by the tool designer and which are rarely explicitly specified. This means that, if an organization has existing standards, it is not possible to tailor prettyprinters to these standards. [I. Sommerville, Software Engineering 3rd Ed. p374] Prettyprinters impose absolute, detailed structural form on code. They eliminate entirely all style variations of the programmer even though the style may manifest some worthy goal such as enhancing understandability. The following standardization of the two distinct styles of procedure calls below illustrates an egregious flaw of prettyprinters. vhdl_lexicon.iterate ( the_specification, text_io.standard_output ); vhdl_lexicon.iterate ( using_this_shape_style => the_specification, on_the_text_file => text_io.standard_output ); A prettyprinter formalizes both calls to a linear structure that collapses the form of the second call to one line: vhdl_lexicon.iterate ( using_ .. ). Although the format of the second call reflects the programmer's emphasis on clarity and understandability, the prettyprinter totally ignores the format, and simultaneously destroys and loses the intended style of the programmer. The problem is that a prettyprinter dictates uniformly every minute phase of the code format. One practical solution is to have a set of fine-grained tools such that each tool operates only on one style of the source code while preserving each remaining style of the format. 1.2 Style Classes and vhdl code A vhdl source code is defined to be a text file that conforms to the specifications of the Vhdl-LRM ( IEEE Standard VHDL Language Reference Manual IEEE Std 1076-1987 ). Its logical data structure is a linearly ordered set ( sequence ) of lexical elements. Each lexical element further divides into sub_elements. Henceforth, the term lexical unit denotes the set of or a subset of the lexical sub_elements. LEXICAL ELEMENT ==> LEXICAL UNIT identifiers ==> identifier_reserved, identifier_not_reserved abstract literal ==> literal_abstract_decimal, literal_abstract_based literal_character ==> literal_character literal_string ==> literal_string literal_bit_string ==> literal_bit_string comment ==> comment separators ==> separator_end_of_file, separator_end_of_page, separator_end_of_line, separator_format_effector 1.3 Objective: The different classes of style are the letter style, the type style, the shape style, and the scroll style. The objective of each tool ( program ) is to impose only one style on the source code. Each object of each lexical unit will be transliterated to the value of the imposing style. For instance, when the specification calls for assigning the lexical unit comment to the value of upper case of the letter style, each object ( comment line ) of the lexical unit comment will be of upper case. Precisely, each letter character of each comment line will be of upper case. -------------------------------------------------------------------------------- 2 EXAMPLES This section displays an application of the tools on code. 2.1 LETTER TOOLS: -- Summary: letter tools and specifications -- LEXICAL UNIT (tool name => ) vletter vlower vupper reserved_word lower_case lower_case lower_case non_reserved_word mix_case lower_case upper_case literal_abstract_decimal upper_case lower_case upper_case literal_abstract_based upper_case lower_case upper_case literal_bit_string upper_case lower_case upper_case comment unchanged unchanged unchanged literal_character unchanged unchanged unchanged literal_string unchanged unchanged unchanged effectors unchanged unchanged unchanged SAMPLE CODE: source name = letter.example -- SYSTEM.VHD File FROM HERE TO NEXT FILE MARKER # PACKAGE SySTEM is TYPE Bus_CYclL is (Intack, Illegal, io_READ, Io_Write, Mem_Code_Read, Halt_Or_Shutdown, Mem_Data_Read, Mem_Data_Write); type Position is (Byte3, Byte2, Byte1, Byte0, -- do NOT change Word2, WORD1W, Word0, -- position dependent tword1, Tword0, Dword0); x"FFF" -- equivalent TO : b"1111_1111_1111" "strings" """" 'a' 16#0f_F# 16#E#e1_1 ///// call tool vletter ///// > vletter letter.example The format of letter.example after the call vletter letter.example is: -- SYSTEM.VHD File FROM HERE TO NEXT FILE MARKER # package System is type Bus_Cycll is (Intack, Illegal, Io_Read, Io_Write, Mem_Code_Read, Halt_Or_Shutdown, Mem_Data_Read, Mem_Data_Write); type Position is (Byte3, Byte2, Byte1, Byte0, -- do NOT change Word2, Word1w, Word0, -- position dependent Tword1, Tword0, Dword0); X"FFF" -- equivalent TO : B"1111_1111_1111" "strings" """" 'a' 16#0F_F# 16#E#E1_1 2.2 SHAPE TOOLS: -- Summary: shape tools and specifications -- Specification (tool name =>) vshape vshape94 the_column_width 80 94 the_indent_margin 48 48 the_tab_set 3 3 the_wrap_indent_length 1 1 the_comment_ragged_indent 14 14 the_comment_wrap_string "-- " "-- " ** Goal: create your own shape specification by defining it on this text file: shape.spec -- note the order of the values are important -- for instant the integer in line 3 will always be the tab set -- there must be exactly 6 lines 55 -- column width 12 -- indent margin maximum 4 -- tab set 1 -- wrap indent length 14 -- comment right adjust length --&& -- comment wrap string: constraint exactly the first 4 characters SAMPLE CODE: source code name = file_1.vhdl whose content is: -- SYSTEM.VHD FILE FROM HERE TO NEXT FILE MARKER # note this portion of the comment will illustrate the wraparound features of a comment line package system is type bus_cycle is (intack, illegal, io_read, io_write, mem_code_read, halt_or_shutdown, mem_data_read, mem_data_write); type position is (byte3, byte2, byte1, byte0, -- do NOT change word2, word1, word0, -- position dependent tword1, tword0, dword0); if this_identifier_is_too_long_to_fit_on_one_line_then_it_will_wraparound_with_this_format then a := "line exceeds an indention of 12 " entity clock_ckt is generic (per: time); port (run: in bit := '0'; clk, clk2: out bit := '0'); end clock_ckt; -- /// call vshape_set_style shape.spec file_1.vhdl > vshape_set_style shape.spec file_1.vhdl -- the format of file_1.vhdl is: -- SYSTEM.VHD FILE FROM HERE TO NEXT FILE --&&MARKER # note this portion of the comment --&&will illustrate the wraparound features of --&&a comment line package system is type bus_cycle is (intack, illegal, io_read, io_write, mem_code_read, halt_or_shutdown, mem_data_read, mem_data_write); type position is (byte3, byte2, byte1, byte0, -- do NOT change word2, word1, word0, -- position dependent tword1, tword0, dword0); if this_identifier_is_too_long_to_fit_on_one_line_then_it_w ill_wraparound_with_this_format then a := "line exceeds an indention of 12 " entity clock_ckt is generic (per: time); port (run: in bit := '0'; clk, clk2: out bit := '0'); end clock_ckt; -------------------------------------------------------------------------------- 3 SUMMARY -- Summary: letter tools and specifications -- LEXICAL UNIT (tool name => ) vletter vlower vupper reserved_word lower_case lower_case lower_case non_reserved_word mix_case lower_case upper_case literal_abstract_decimal upper_case lower_case upper_case literal_abstract_based upper_case lower_case upper_case literal_bit_string upper_case lower_case upper_case comment unchanged unchanged unchanged literal_character unchanged unchanged unchanged literal_string unchanged unchanged unchanged effectors unchanged unchanged unchanged -- Summary: shape tools and specifications -- Specification (tool name =>) vshape vshape94 the_column_width 80 94 the_indent_margin 48 48 the_tab_set 3 3 the_wrap_indent_length 1 1 the_comment_ragged_indent 14 14 the_comment_wrap_string "-- " "-- " -- Summary: scroll tools and specifications -- Specification (tool name =>) vscroll vsun vscroll22 the_column_width 80 94 80 the_indent_margin 48 48 48 the_tab_set 3 3 3 the_wrap_indent_length 1 1 1 the_comment_ragged_indent 14 14 14 the_comment_wrap_string "-- " "-- " "-- " rows per screen 23 33 22 the prompt string "" ">>" " < return >" -- Summary: type tools and specifications -- LEXICAL UNIT vtype vtype_italics vlw * reserved_word bold italics bold non_reserved_word roman roman roman literal_abstract_decimal italics italics italics literal_abstract_based italics italics italics literal_bit_string italics italics italics literal_character italics italics italics literal_string roman bold roman comment italics italics italics delimiter.single roman roman roman delimiter.double roman roman roman * vlw: shape specification is: 94 the_column_width 48 the_indent_margin 3 the_tab_set 1 the_wrap_indent_length 14 the_comment_ragged_indent "-- " the_comment_wrap_string -- SUMMARY OF "SET" TOOLS -- The set tools are: vletter_set_style, vshape_set_style, vscroll_set_style, vtype_set_style These set tools allows the programmer to design his own format style by defining the desired style specification on a text file. The example below illustrates how to define one's desired specification. USER FORMAT FOR LETTER SPECIFICATION ON A TEXT FILE: ( 6 lines ) lower_case -- identifier_reserved -to- lower_case, mix_case -- identifier_not_reserved -to- mix_case, upper_case -- literal_abstract_decimal -to- upper_case, upper_case -- literal_abstract_based -to- upper_case, upper_case -- literal_bit_string -to- upper_case, upper_case -- literal_comment -to- upper_case, Example: for vhdl source file f1.vhdl, f2.vhdl, f3 require reserved words to be upper case, non-reserved words to be mix case, comments to be upper case, bit strings to lower case and all other lexical units to be unchanged. Edit a text file, say letter.spec, to have exactly 6 lines and to have the value of the first string on each line to have one of these values: lower_case upper_case mix_case unchanged_case upper_case -- reserved words: only the first string 'upper_case' will be read mix_case -- non-reserved words unchanged_case -- abstract_decimal unchanged_case -- abstract_based numeric lower_case -- bit string upper_case -- comment --/// call /// -- > vletter_set_style letter.spec f1.vhdl f2.vhdl f3 USER FORMAT FOR SHAPE SPECIFICATION ON A TEXT FILE: ( 6 lines ) ** To design a shape specification use the tool 'set_shape_style' and edit a text file having the order of values defined below. This procedure follows that of the previous example and can be used in other style designs. 80 -- column width 48 -- indent margin maximum 3 -- tab set 1 -- wrap indent length 14 -- comment right adjust length --&& -- comment wrap string: constraint exactly the first 4 characters USER FORMAT FOR SCROLL SPECIFICATION ON A TEXT FILE: ( 8 lines ) 80 -- column width 48 -- indent margin maximum 3 -- tab set 1 -- wrap indent length 14 -- comment right adjust length -- -- comment wrap string: constraint exactly the first 4 characters 22 -- rows per screen and the prompt string to continue is on the next line < strike ret > ** Note the entire line 8 is read by the program. USER FORMAT FOR TYPE SPECIFICATION ON A TEXT FILE: ( 10 lines ) bold -- identifier_reserved roman -- identifier_not_reserved italics -- abstract_decimal italics -- abstract_based italics -- bit_string italics -- literal_character roman -- literal_string italics -- literal_comment roman -- delimiter_single roman -- delimiter_double -------------------------------------------------------------------------------- 4 CONSTRAINTS 4.1 Line length: there is no restriction on the length of a line. 4.2 Compilation: if a file vhdl compiles then its output from each tool compiles. 4.3 Robustness: occurs when the first character is incorrect in syntax or when a matching quotation character is missing example file1: bc %7 end string " no matching parenthesis > vlower file1 file1: bc --* %7 end string " no matching parenthesis -- E R R O R" 4.4 Read only tool: ( scroll tools ) vscroll vscroll22 vsun vscroll_set_style ( type tools ) vlw vtype vtype_italics vtype_set_style ( help tools ) vhdl_tools help_vhdl_tools vhdl_user_guide * The above tools do not alter the input source code Read-Write tools: ( letter tools ) vletter vlower vupper vletter_set_style ( shape tools ) vshape vshape94 vshape_set_style * The above tools alter the input source code example vletter file1 file2 The original letter style of file1 and file2 are replaced by the letter specification defined in vletter. Consequently, to save the original letter style of a file, the file must be copied to another file.