home *** CD-ROM | disk | FTP | other *** search
/ Programmer's ROM - The Computer Language Library / programmersrom.iso / ada / style / check.doc < prev    next >
Encoding:
Text File  |  1988-05-03  |  17.1 KB  |  885 lines
  1.  
  2.                                  STYLE CHECKER
  3.  
  4.  
  5.  
  6.                This document  describes  a  general  overview  of  the
  7.  
  8.           structure of the Ada Style Checker's package structure.  The
  9.  
  10.           description includes information that will be  of  value  in
  11.  
  12.           understanding  the  interaction  of  the  software  and  the
  13.  
  14.           interfaces necessary for the software to function  properly.
  15.  
  16.           This  document  should  also serve as a guide for any future
  17.  
  18.           maintenance that may become necessary or desired.
  19.  
  20.  
  21.  
  22.                The following list  is  a  list  of  the  source  files
  23.  
  24.           required  to  build  the  Style Checker.  They are listed in
  25.  
  26.           compilation order
  27.  
  28.  
  29.  
  30.           1.  DYN.ADA - DYN (dynamic  string)  package  (specification
  31.  
  32.               and body)
  33.  
  34.  
  35.  
  36.           2.  FILE_SPEC.ADA - FILE_HANDLING package specification
  37.  
  38.  
  39.  
  40.           3.  TOKENIZER_SPEC.ADA - TOKENIZER package specification
  41.  
  42.  
  43.  
  44.           4.  STYLE_PARAM_SPEC.ADA    -    STYLE_PARAMETERS    package
  45.  
  46.               specification
  47.  
  48.  
  49.  
  50.           5.  REPORT_GEN_SPEC.ADA    -    REPORT_GENERATOR     package
  51.  
  52.               specification
  53.  
  54.  
  55.  
  56.           6.  STACK_PACKAGE.ADA - STACK_PACKAGE package (specification
  57.  
  58.               and body)
  59.  
  60.  
  61.  
  62.           7.  TOKEN_DEFINITION.ADA    -    TOKEN_DEFINITION    package
  63.  
  64.               (specification and body)
  65.  
  66.  
  67.  
  68.           8.  MANAGER.ADA - MANAGER package (specification and body)
  69.  
  70.  
  71.  
  72.           9.  HELP_FILE_SPEC.ADA - HELP package specification
  73.  
  74.  
  75.  
  76.          10.  COMMAND_LINE.ADA    -    COMMAND_LINE_HANDLER    package
  77.  
  78.               (specification and body)
  79.  
  80.  
  81.  
  82.          11.  HELP_FILE_SPEC.ADA - HELP package specification
  83.  
  84.  
  85.  
  86.          12.  HELP_FILE_BODY.ADA - HELP package body
  87.  
  88.  
  89.  
  90.          13.  HELP_INFO_SPEC.ADA - HELP_INFO package specification
  91.  
  92.  
  93.  
  94.          14.  HELP_INFO_BODY.ADA - HELP_INFO package body
  95.  
  96.  
  97.  
  98.          15.  HELP_DIS_ALL.ADA - a separate procedure in HELP_UTILITY
  99.  
  100.  
  101.  
  102.          16.  HELP_EXIT.ADA - a separate procedure in HELP_UTILITY
  103.  
  104.  
  105.  
  106.          17.  HELP_FIND.ADA - a separate procedure in HELP_UTILITY
  107.  
  108.                                                                 Page 2
  109.  
  110.  
  111.  
  112.  
  113.  
  114.          18.  HELP_GET.ADA - a separate procedure in HELP_UTILITY
  115.  
  116.  
  117.  
  118.          19.  HELP_INIT.ADA - a separate procedure in HELP_UTILITY
  119.  
  120.  
  121.  
  122.          20.  HELP_ME.ADA - a separate procedure in HELP_UTILITY
  123.  
  124.  
  125.  
  126.          21.  HELP_MENU.ADA - a separate procedure in HELP_UTILITY
  127.  
  128.  
  129.  
  130.          22.  HELP_PROMPT.ADA - a separate procedure in HELP_UTILITY
  131.  
  132.  
  133.  
  134.          23.  HELP_RESET.ADA - a separate procedure in HELP_UTILITY
  135.  
  136.  
  137.  
  138.          24.  HELP_TEXT.ADA - a separate procedure in HELP_UTILITY
  139.  
  140.  
  141.  
  142.          25.  FILE_BODY.ADA - FILE_HANDLING package body
  143.  
  144.  
  145.  
  146.          26.  TOKENIZER_BODY.ADA - TOKENIZER package body
  147.  
  148.  
  149.  
  150.          27.  INSERT.ADA - A separate procedure in the TOKENIZER
  151.  
  152.  
  153.  
  154.          28.  IS_A_RESERVED_WORD.ADA - A  separate  procedure  in  the
  155.  
  156.               TOKENIZER
  157.  
  158.  
  159.  
  160.          29.  RESERVED_WORD.ADA  -  A  separate   procedure   in   the
  161.  
  162.               TOKENIZER
  163.  
  164.  
  165.  
  166.          30.  NEXT_CHARACTER.ADA  -  A  separate  procedure   in   the
  167.  
  168.               TOKENIZER
  169.  
  170.  
  171.  
  172.          31.  NEXT_IDENTIFIER.ADA  -  A  separate  procedure  in   the
  173.  
  174.               TOKENIZER
  175.  
  176.  
  177.  
  178.          32.  BUILD_TOKENS.ADA - A separate procedure in the TOKENIZER
  179.  
  180.  
  181.  
  182.          33.  LINE_CONTAINING.ADA  -  A  separate  procedure  in   the
  183.  
  184.               TOKENIZER
  185.  
  186.  
  187.  
  188.          34.  TREE_ROOT.ADA - A separate procedure in the TOKENIZER
  189.  
  190.  
  191.  
  192.          35.  STYLE_PARAM_BODY.ADA - STYLE_PARAMETERS package body
  193.  
  194.  
  195.  
  196.          36.  REPORT_GEN_BODY.ADA - REPORT_GENERATOR package body
  197.  
  198.  
  199.  
  200.          37.  STYLE_CHECKER.ADA - main procedure (STYLE_CHECKER)
  201.  
  202.  
  203.  
  204.          38.  BEGIN_OF_LINE_INDENT.ADA - A separate procedure  in  the
  205.  
  206.               STYLE_CHECKER
  207.  
  208.  
  209.  
  210.          39.  CHECK_STATEMENTS.ADA  -  A  separate  procedure  in  the
  211.  
  212.               STYLE_CHECKER
  213.  
  214.  
  215.  
  216.          40.  CHECK_END_OF_BLOCKS.ADA - A separate  procedure  in  the
  217.  
  218.               STYLE_CHECKER
  219.  
  220.                                                                 Page 3
  221.  
  222.  
  223.  
  224.  
  225.  
  226.          41.  CHECK_THE_STYLE.ADA  -  A  separate  procedure  in   the
  227.  
  228.               STYLE_CHECKER
  229.  
  230.  
  231.  
  232.          42.  CHECK_FOR_ATTRIBUTE.ADA - A separate  procedure  in  the
  233.  
  234.               STYLE_CHECKER
  235.  
  236.  
  237.  
  238.          43.  CHECK_OBJECT_NAMES.ADA - A  separate  procedure  in  the
  239.  
  240.               STYLE_CHECKER
  241.  
  242.  
  243.  
  244.          44.  CHECK_UNIVERSAL.ADA  -  A  separate  procedure  in   the
  245.  
  246.               STYLE_CHECKER
  247.  
  248.  
  249.  
  250.          45.  COMMENT_TOKEN.ADA  -  A  separate   procedure   in   the
  251.  
  252.               STYLE_CHECKER
  253.  
  254.  
  255.  
  256.          46.  CURRENT_TOKEN.ADA  -  A  separate   procedure   in   the
  257.  
  258.               STYLE_CHECKER
  259.  
  260.  
  261.  
  262.          47.  ENTERING_BLOCK.ADA  -  A  separate  procedure   in   the
  263.  
  264.               STYLE_CHECKER
  265.  
  266.  
  267.  
  268.          48.  ENTERING_SUB_BLOCK.ADA - A  separate  procedure  in  the
  269.  
  270.               STYLE_CHECKER
  271.  
  272.  
  273.  
  274.          49.  EXITING_BLOCK.ADA  -  A  separate   procedure   in   the
  275.  
  276.               STYLE_CHECKER
  277.  
  278.  
  279.  
  280.          50.  GET_NEXT_TOKEN.ADA  -  A  separate  procedure   in   the
  281.  
  282.               STYLE_CHECKER
  283.  
  284.  
  285.  
  286.          51.  IS_STATEMENT.ADA  -  A   separate   procedure   in   the
  287.  
  288.               STYLE_CHECKER
  289.  
  290.  
  291.  
  292.          52.  LITERAL.ADA - A separate procedure in the STYLE_CHECKER
  293.  
  294.  
  295.  
  296.          53.  NEW_LINE_TOKEN.ADA  -  A  separate  procedure   in   the
  297.  
  298.               STYLE_CHECKER
  299.  
  300.  
  301.  
  302.          54.  NON_TRIVIAL_TOKEN.ADA -  A  separate  procedure  in  the
  303.  
  304.               STYLE_CHECKER
  305.  
  306.  
  307.  
  308.          55.  OBJECT_NAME.ADA  -   A   separate   procedure   in   the
  309.  
  310.               STYLE_CHECKER
  311.  
  312.  
  313.  
  314.          56.  RESERVE_WORD.ADA  -  A   separate   procedure   in   the
  315.  
  316.               STYLE_CHECKER
  317.  
  318.  
  319.  
  320.          57.  SEARCH_BACKWARD.ADA  -  A  separate  procedure  in   the
  321.  
  322.               STYLE_CHECKER
  323.  
  324.  
  325.  
  326.          58.  SEARCH_BACK_ONE_OF.ADA - A  separate  procedure  in  the
  327.  
  328.               STYLE_CHECKER
  329.  
  330.                                                                 Page 4
  331.  
  332.  
  333.  
  334.  
  335.  
  336.          59.  SEARCH_FORWARD.ADA  -  A  separate  procedure   in   the
  337.  
  338.               STYLE_CHECKER
  339.  
  340.  
  341.  
  342.          60.  SEARCH_FORE_ONE_OF.ADA - A  separate  procedure  in  the
  343.  
  344.               STYLE_CHECKER
  345.  
  346.  
  347.  
  348.          61.  TYPE_DECLARATION.ADA  -  A  separate  procedure  in  the
  349.  
  350.               STYLE_CHECKER
  351.  
  352.  
  353.  
  354.                                                                 Page 5
  355.  
  356.  
  357.  
  358.  
  359.  
  360.                                   THE PACKAGES
  361.  
  362.  
  363.  
  364.                In  the  next  section   each   package   is   outlined
  365.  
  366.           separately.  The packages are listed in compilation order.
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.                                   Package DYN
  375.  
  376.  
  377.  
  378.                This package is contained in the file DYN.ADA.  It is a
  379.  
  380.           dynamic  string  package,  modeled  after the dynamic string
  381.  
  382.           package described by Sylvan  Rubin  of  Ford  Aerospace  and
  383.  
  384.           Communications  Corporation in the Nov/Dec 1984 issue of the
  385.  
  386.           Journal of Pascal, Ada and Modula-2.  It is  primarily  used
  387.  
  388.           by  the  TOKENIZER package, but is used a little by most all
  389.  
  390.           of the packages in the STYLE_CHECKER.   A  possible  problem
  391.  
  392.           with   this   package   is   that   on   a  system  with  no
  393.  
  394.           UNCHECKED_DEALLOCATION and no automatic "garbage collection"
  395.  
  396.           of  access  objects  problems  with  heap size may arise.  A
  397.  
  398.           proposed  solution  is  to   change   the   dynamic   string
  399.  
  400.           representation.   Since  it  is  a  private type this should
  401.  
  402.           cause few problems with the rest of the system.
  403.  
  404.                                                                 Page 6
  405.  
  406.  
  407.  
  408.  
  409.  
  410.                              Package FILE_HANDLING
  411.  
  412.  
  413.  
  414.                This package is contained in the files
  415.  
  416.  
  417.  
  418.           1.  FILE_SPEC.ADA
  419.  
  420.  
  421.  
  422.           2.  FILE_BODY.ADA
  423.  
  424.  
  425.  
  426.           The   FILE_HANDLING    package    controls    the    initial
  427.  
  428.           identification and opening of the input and output files.
  429.  
  430.                                                                 Page 7
  431.  
  432.  
  433.  
  434.  
  435.  
  436.                                Package TOKENIZER
  437.  
  438.  
  439.  
  440.                The TOKENIZER package is  contained  in  the  following
  441.  
  442.           files:
  443.  
  444.  
  445.  
  446.           1.  TOKENIZER_SPEC.ADA
  447.  
  448.  
  449.  
  450.           2.  TOKENIZER_BODY.ADA
  451.  
  452.  
  453.  
  454.           3.  INSERT.ADA
  455.  
  456.  
  457.  
  458.           4.  IS_A_RESERVED_WORD.ADA
  459.  
  460.  
  461.  
  462.           5.  RESERVED_WORD.ADA
  463.  
  464.  
  465.  
  466.           6.  NEXT_CHARACTER.ADA
  467.  
  468.  
  469.  
  470.           7.  NEXT_IDENTIFIER.ADA
  471.  
  472.  
  473.  
  474.           8.  BUILD_TOKENS.ADA
  475.  
  476.  
  477.  
  478.           9.  LINE_CONTAINING.ADA
  479.  
  480.  
  481.  
  482.          10.  TREE_ROOT.ADA
  483.  
  484.  
  485.  
  486.  
  487.  
  488.           The TOKENIZER package  processes  the  Ada  input  file  and
  489.  
  490.           produces  tokens  to be processed by the subsequent packages
  491.  
  492.           of the Style Checker.  It also serves as  the  interface  to
  493.  
  494.           the  stream  of tokens.  All the calls to TEXT_IO GET's from
  495.  
  496.           the  input  files  are  localized  to   the   NEXT_CHARACTER
  497.  
  498.           function.
  499.  
  500.  
  501.  
  502.                This package  has  a  procedure  BUILD_TOKENS  that  is
  503.  
  504.           called first, and then the functions FIRST_TOKEN, NEXT_TOKEN
  505.  
  506.           and PREVIOUS_TOKEN  are  used  to  move  through  the  token
  507.  
  508.           stream.   Since  the TOKEN type is a private type changes in
  509.  
  510.           the internal  representation  of  TOKENs  should  cause  few
  511.  
  512.           problems with the other packages.
  513.  
  514.                                                                 Page 8
  515.  
  516.  
  517.  
  518.  
  519.  
  520.                            Package  STYLE_PARAMETERS
  521.  
  522.  
  523.  
  524.                The STYLE_PARAMETERS package is contained in the  files
  525.  
  526.           :
  527.  
  528.  
  529.  
  530.           1.  STYLE_PARAM_SPEC.ADA
  531.  
  532.  
  533.  
  534.           2.  STYLE_PARAM_BODY.ADA
  535.  
  536.  
  537.  
  538.  
  539.  
  540.                This package  contains  the  functions  and  procedures
  541.  
  542.           called  to get the parameters that drive the style checking.
  543.  
  544.           In   order   to    alter    the    parameters    the    file
  545.  
  546.           STYLE_PARAM_BODY.ADA  must  be  edited,  and  the  procedure
  547.  
  548.           SET_STYLE_PARAMETERS  must  be  altered   to   reflect   the
  549.  
  550.           appropriate  parameter(s).   For more information concerning
  551.  
  552.           the individual parameters and their meaning see  the  source
  553.  
  554.           code documentation and the on-line help facility.
  555.  
  556.                                                                 Page 9
  557.  
  558.  
  559.  
  560.  
  561.  
  562.                            Package   REPORT_GENERATOR
  563.  
  564.  
  565.  
  566.                This package is contained in the files:
  567.  
  568.  
  569.  
  570.           1.  REPORT_GEN_SPEC.ADA
  571.  
  572.  
  573.  
  574.           2.  REPORT_GEN_BODY.ADA
  575.  
  576.  
  577.  
  578.  
  579.  
  580.                This package contains the procedures that generate both
  581.  
  582.           the flaws report file and the style report file.  If any new
  583.  
  584.           style checks are to be added to the STYLE_CHECKER needed  to
  585.  
  586.           be  added to several places in the REPORT_GENERATOR package.
  587.  
  588.           They must be added to the record  that  contains  the  count
  589.  
  590.           information for all the flaws.  They need to be added to the
  591.  
  592.           enumeration type that lists  the  flaws.   This  enumeration
  593.  
  594.           type  is  a  parameter  to the PUT_FLAW procedure.  Then the
  595.  
  596.           code to add them to the style report must be  added  to  the
  597.  
  598.           GENERATE_REPORT procedure.
  599.  
  600.                                                                Page 10
  601.  
  602.  
  603.  
  604.  
  605.  
  606.                              Package STACK_PACKAGE
  607.  
  608.  
  609.  
  610.                This package is contained in the file:
  611.  
  612.  
  613.  
  614.           1.  STACK_PACKAGE.ADA
  615.  
  616.  
  617.  
  618.  
  619.  
  620.           This package is a generic stack package.
  621.  
  622.                                                                Page 11
  623.  
  624.  
  625.  
  626.  
  627.  
  628.                      Packages TOKEN_DEFINITION and MANAGER
  629.  
  630.  
  631.  
  632.                These packages are contained in the files:
  633.  
  634.  
  635.  
  636.           1.  TOKEN_DEFINITION.ADA
  637.  
  638.  
  639.  
  640.           2.  MANAGER.ADA
  641.  
  642.  
  643.  
  644.  
  645.  
  646.                These   two   pacakges   are   inhereted    from    the
  647.  
  648.           SPELLING_CHECKER  tool.  They currently are stubbed out.  If
  649.  
  650.           it was desired to have the  STYLE_CHECKER  check  that  each
  651.  
  652.           variable  name  was a word these two packages could be moved
  653.  
  654.           from the SPELLING_CHECKER (and  any  further  packages  they
  655.  
  656.           needed)  and  code  could  be  added  in  the  STYLE_CHECKER
  657.  
  658.           procedure CHECK_OBJECT_NAMES.  Currently the code  to  check
  659.  
  660.           if  a variable is a word is included, but nothing is done if
  661.  
  662.           the result is false.
  663.  
  664.                                                                Page 12
  665.  
  666.  
  667.  
  668.  
  669.  
  670.                Packages HELP, HELP_INFO_SUPPORT and HELP_UTILITY
  671.  
  672.  
  673.  
  674.                  These packages are contained in the files:
  675.  
  676.  
  677.  
  678.           1.  HELP_FILE_SPEC.ADA
  679.  
  680.  
  681.  
  682.           2.  HELP_FILE_BODY.ADA
  683.  
  684.  
  685.  
  686.           3.  HELP_INFO_SPEC.ADA
  687.  
  688.  
  689.  
  690.           4.  HELP_INFO_BODY.ADA
  691.  
  692.  
  693.  
  694.           5.  HELP_SPEC.ADA
  695.  
  696.  
  697.  
  698.           6.  HELP_BODY.ADA
  699.  
  700.  
  701.  
  702.           7.  HELP_DIS_ALL.ADA
  703.  
  704.  
  705.  
  706.           8.  HELP_EXIT.ADA
  707.  
  708.  
  709.  
  710.           9.  HELP_FIND.ADA
  711.  
  712.  
  713.  
  714.          10.  HELP_GET.ADA
  715.  
  716.  
  717.  
  718.          11.  HELP_INIT.ADA
  719.  
  720.  
  721.  
  722.          12.  HELP_ME.ADA
  723.  
  724.  
  725.  
  726.          13.  HELP_MENU.ADA
  727.  
  728.  
  729.  
  730.          14.  HELP_PROMPT.ADA
  731.  
  732.  
  733.  
  734.          15.  HELP_RESET.ADA
  735.  
  736.  
  737.  
  738.          16.  HELP_TEXT.ADA
  739.  
  740.  
  741.  
  742.          17.  STYLE_HELP.INI (Not a compiled unit, a text file)
  743.  
  744.  
  745.  
  746.  
  747.  
  748.                These  packages  are  the  help  utility.    The   file
  749.  
  750.           STYLE_HELP.INI   contains   the  source  used  by  the  help
  751.  
  752.           facility.  Any change of  the  name  of  the  STYLE_HELP.INI
  753.  
  754.           filename   will  require  a  change  of  the  initialization
  755.  
  756.           filename constant in the FILE_HANDLING package.
  757.  
  758.  
  759.  
  760.                The text file  used  by  the  HELP_UTILITY  Package  is
  761.  
  762.           required to have a particular format.  If the file is not in
  763.  
  764.           this format, an exception will  be  raised.   The  following
  765.  
  766.           explains the required format.
  767.  
  768.  
  769.  
  770.                COMMENTS:  Comments may be embeded in  the  text  file.
  771.  
  772.           All  comments are ignored when the file is read into memory.
  773.  
  774.           A text line is considered a comment if the first and  second
  775.  
  776.           characters of the line are minus signs ( -- ).
  777.  
  778.                                                                Page 13
  779.  
  780.  
  781.  
  782.  
  783.  
  784.                TOPICS:  The first non-comment  text  line  MUST  begin
  785.  
  786.           with  the  digit  1 in column one.  This number is the topic
  787.  
  788.           level.  In other words, text (as defined  below)  cannot  be
  789.  
  790.           found  in the text file before a topic is found to which the
  791.  
  792.           text can be associated.  Topics are those subjects for which
  793.  
  794.           information is being provided.  A topic name may contain any
  795.  
  796.           printable character except blanks.  Embedded blanks are  NOT
  797.  
  798.           allowed  in  a  topic  name.  This will not be flagged as an
  799.  
  800.           error but the name will be truncated  at  the  first  blank.
  801.  
  802.           All  letters  in  the  name  must  be  capitals.   It is not
  803.  
  804.           required to have a space separating the topic level from the
  805.  
  806.           topic  name.   Any  line  beginning  with  a  digit  will be
  807.  
  808.           considered a topic line.
  809.  
  810.  
  811.  
  812.                SUBTOPICS:  A topic may have subtopics.  Subtopics  are
  813.  
  814.           denoted  by  having  a  level  exactly  one greater than the
  815.  
  816.           associated topic level.  Subtopics follow the same rules  as
  817.  
  818.           topics  in all other aspects.  There is no constraint (other
  819.  
  820.           than a lack of memory) on the number of subtopic levels.
  821.  
  822.  
  823.  
  824.                TEXT:   All  text  lines   not   beginning   with   two
  825.  
  826.           consecutive minus signs or a digit will be considered text.
  827.  
  828.  
  829.  
  830.                The text file is saved exactly  as  the  user  sees  it
  831.  
  832.           (including blank lines) with the follow exceptions:
  833.  
  834.  
  835.  
  836.            -  topic and subtopic names have  leading  blanks  stripped
  837.  
  838.               off
  839.  
  840.  
  841.  
  842.            -  if the topic or subtopic name is longer  than  one  half
  843.  
  844.               the  screen  size,  it  may  be truncated when a menu of
  845.  
  846.               information is output
  847.  
  848.  
  849.  
  850.            -  if the text line is longer than  the  screen  size,  the
  851.  
  852.               text line is truncated before output
  853.  
  854.  
  855.  
  856.            -  the text file lines are assumed to be eighty  characters
  857.  
  858.               maximum.
  859.  
  860.  
  861.  
  862.                                                                Page 14
  863.  
  864.  
  865.  
  866.  
  867.  
  868.                           Package COMMAND_LINE_HANDLER
  869.  
  870.  
  871.  
  872.                This package is contained in the file COMMAND_LINE.ADA.
  873.  
  874.           This  package  contains routines which return words from the
  875.  
  876.           command line.  It expects an external file to  created  that
  877.  
  878.           contains  each  word  that follows the inkoking command, one
  879.  
  880.           word per line.  These lines are interpreted  as  file  names
  881.  
  882.           and opened by a procedure in this package.
  883.  
  884.  
  885.