home *** CD-ROM | disk | FTP | other *** search
/ Fatal Distractions! / fataldistractions.bin / appndxa / masters / agtlint.doc < prev    next >
Text File  |  1993-10-27  |  15KB  |  392 lines
  1. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           1
  2.  
  3.  
  4.          Program and documentation by:
  5.  
  6.               David S. Raley
  7.               13523 Demetrias Way
  8.               Germantown, MD 20874
  9.               Compuserve: [72247,1153]
  10.               Internet:   72247,1153@compuserve.com
  11.  
  12.  
  13. INTRODUCTION
  14.  
  15.     AGTLINT is an error analysis utility for use with David R. Malmberg's
  16. Adventure Game Toolkit. While it is primarily intended for use with the
  17. Master's Edition, AGTLINT is also useful in debugging Classic Edition and
  18. AGTNUM source files.
  19.  
  20.     AGTLINT reads through a source file (.AGT, .CMD, .DAT, or .MSG file)
  21. and verifies that all the tokens in use are valid. With .AGT files, AGTLINT
  22. also verifies that any labels that are defined are consistant with the uses
  23. defined in the AGT manual. It then generates a file listing any errors or 
  24. warnings found, as well as a complete symbol table for the source file.
  25.  
  26.     AGTLINT does not replace the compiler, but supplements it. First of all,
  27. it does not generate an executable adventure file. Second, it concentrates on
  28. those errors that the compiler doesn't recognize. Together, the two programs
  29. should recognize almost any syntactic or symantic error. 
  30.  
  31.     AGTLINT cannot detect logical errors, of course, but with this utility,
  32. you no longer have to worry about spending three days trying to debug an
  33. error only to learn that the problem was that you used a noun label with a
  34. flag token. You can now save your debugging skills for the true logical
  35. errors that only the programmer can handle.
  36.  
  37.  
  38.  
  39. SHAREWARE
  40.  
  41.     AGTLINT is distributed as shareware. If you find this utility useful in
  42. debugging your adventure games, please send $10 to the author. This
  43. includes an automatic upgrade to the next release of the program when it
  44. is available. Once you are registered, you are considered registered for
  45. all later releases. Registered users wishing to obtain a later release
  46. directly from the author may upgrade at $5 (the upgrade is free if the
  47. new version repairs a significant bug reported by the user). Please specify 
  48. size and density of disk, as well as the release number you presently have 
  49. when you register or upgrade.
  50.  
  51.  
  52. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           2
  53.  
  54.  
  55. USING AGTLINT
  56.  
  57.     The syntax for AGTLINT is as follows:
  58.  
  59.          AGTLINT     Sourcefile    [Switches]
  60.  
  61.     The Sourcefile is the AGT source file AGTLINT is to analyze. This file
  62. will generally be a .AGT file, though it may also be a .CMD, .MSG, or .DAT
  63. file is you are using the Classic Edition. If no extension is provided,
  64. AGTLINT will assume a .AGT file.
  65.  
  66.     The following switches are recognized by AGTLINT. Note that the letters
  67. in brackets are optional.
  68.  
  69.          /?             Display the help screen and exit.
  70.  
  71.          /A[PPEND]      This switch appends the report to an existing .LIN
  72.                         file instead of overwriting the present one. This
  73.                         switch has no effect if no such file exists.
  74.  
  75.          /C[LASSIC]     This switch tells AGTLINT that you are analyzing
  76.                         a Classic Edition source file. This allows AGTNUM
  77.                         to accept numbers (and macros evaluating to numbers)
  78.                         as parameters for most tokens. 
  79.  
  80.          /I[GNORE]=str  Tells AGTLINT to ignore any lines starting with the
  81.                         specified string and assume that they are comments.
  82.                         AGTLINT already accepts the following strings as
  83.                         comment headers (b represents a space):
  84.  
  85.                              ;                        !
  86.                              (                        /
  87.                              {                        *
  88.                              =                        <
  89.                              REMb                     REM:
  90.  
  91.  
  92.          /N[UM]         This switch tells AGTLINT that you are analyzing
  93.                         an AGTNUM source file. This allows AGTNUM to
  94.                         recognize multi-line macros and multiple labels
  95.                         for VARIABLES, COUNTERS, and FLAGS.
  96.  
  97.          /S[MALL]       Tells AGTNUM that a Classic input is from the small
  98.          /S[TANDARD]    (or standard) version (200 rooms, 100 nouns,
  99.                         100 creatures). Big and Master's Edition source
  100.                         files should not use this switch.
  101.  
  102.     AGTLINT will then read through the file and generate its report file. It
  103. will display its status, as well as any errors it finds, on the screen as
  104. it finds them.
  105.  
  106.     If you wish to exit AGTLINT during analysis, simply hit the ESC key.
  107.  
  108.  
  109. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           3
  110.  
  111.  
  112. THE REPORT FILE
  113.  
  114.     After the banners and copyright message, the report file lists all
  115. informational, warning, and error messages. Each message include the
  116. message type, the line number of the file it is in, and finally the
  117. message itself. 
  118.  
  119.     Informational messages indicate the status of the program. These
  120. include the opening and closing of include files, and the start of each
  121. pass. These are useful for tracing the file where any erros and warnings
  122. are located.
  123.  
  124.     Warning messages are issued when an unknown element is encountered.
  125. This could be a comment, a token to a later version of AGT than the
  126. current version of AGTLINT handles, a non-standard default token in an
  127. object definition (such as using OPENABLE as an opposite case for CLOSABLE),
  128. or a misspelled token. Note that the compiler has a limited number of 
  129. significant characters in a token name, while AGTLINT does not.
  130.  
  131.     Error messages are issued when something is found that definitely must
  132. be corrected before running the program. An example of an error is using a
  133. noun label where a flag label is expected.
  134.  
  135.     After the resource list is a list of the total number of errors and
  136. warnings. If all is well, both should be 0.
  137.  
  138.     After the number of errors, AGTLINT lists the resources used in the 
  139. program. Note that any flags or room flags that are defined as macros 
  140. are not listed here. The number of available items for each resource 
  141. is for the version of MCOMPILE corresponding to this version of AGTLINT. 
  142.  
  143.     After the resource list is a list of all macro definitions in the
  144. source file, followed by a list of all symbols definitions in the file.
  145.  
  146.  
  147. COMMENTS
  148.  
  149.     AGTLINT assumes that anything it does not recognize is an error. To
  150. do otherwise would defeat the purpose of the program. Unfortunately,
  151. there is no standardized method for placing comments in the AGT file.
  152. To avoid getting your comments flagged as errors, use one of the more
  153. common comment separators. The ones AGTLINT recognizes are:
  154.  
  155.               ;                        !
  156.               (                        /
  157.               {                        *
  158.               =                        <
  159.               REMb                     REM:
  160.  
  161.     You may also define your own comment separator by using the /IGNORE
  162. switch when you start AGTLINT. So, if you wanted to use COM: as a comment
  163. separator, you should start AGTLINT with:
  164.  
  165.               AGTLINT ADV_FILE /I=COM:
  166.  
  167.  
  168. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           4
  169.  
  170.  
  171.                              APPENDIX  A
  172.  
  173.  
  174. Informational Messages
  175.  
  176.     Starting First Pass                          All
  177.     Starting Second Pass                         All
  178.  
  179.          Displayed at the start of a pass.
  180.  
  181.     End of main file                             All
  182.  
  183.          Displayed at the end of Pass 2.
  184.  
  185.     Opening include file                         All
  186.     End of include file                          All
  187.  
  188.          Displayed when an include file is opened and closed. All messages
  189.          displayed between the opening and closing of an include file
  190.          refer to the line numbers within the include file.
  191.  
  192.     Operation aborted by user                    All
  193.  
  194.          User hit the ESC key during analysis.
  195.     
  196. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           5
  197.  
  198.  
  199. Warnings
  200.  
  201.     Unknown compiler directive                   All
  202.  
  203.          An unrecognized compiler directive was found.
  204.  
  205.     Unreachable token                            All
  206.  
  207.          A token is placed after a closing token (DoneWithTurn,
  208.          ReDirectTo, QuitThisCMD, or QuitAllCMDs). Usually this
  209.          is a superfluous DoneWithTurn (which is innocuous); if
  210.          it's anything else, the token should probably be moved.
  211.  
  212.     Token expected after NOT                     All
  213.  
  214.          NOT should be followed by another token, but AGTLINT
  215.          didn't find one.
  216.  
  217.     Unrecognized token                           All
  218.  
  219.          AGTLINT found a token it did not recognize a token that was
  220.          found inside a command or item definition.
  221.  
  222.     Description redefinition                     Master, AGTNUM
  223.  
  224.          A description of this type has already been defined for this
  225.          item. This is usually the result of mislabelling either the 
  226.          flagged description or the other one with the same label.
  227.          Descriptions include:
  228.  
  229.               HELP                SPECIAL
  230.               TALK_DESCR          ASK_DESCR
  231.               PUSH_DESCR          PULL_DESCR
  232.               TURN_DESCR          PLAY_DESCR
  233.               TEXT                CREATURE_DESCR
  234.               ROOM_DESCR          NOUN_DESCR
  235.  
  236.     Unknown entity                               All
  237.  
  238.          An unknown token was found outside the scope of a message, command,
  239.          definition, or descriptor. This can either be a comment without a
  240.          recognized comment marker or a mispelled item.
  241.  
  242.  
  243. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           6
  244.  
  245.  
  246.     Numerical token expected                     All
  247.  
  248.          A paramter that should be a numerical value has a non-numeric
  249.          value instead.
  250.  
  251.     Time parameter out of range                  Master, AGTNUM
  252.  
  253.          A time parameter was not between 0000 and 2400.
  254.  
  255.     Unknown direction                            Master, AGTNUM
  256.  
  257.          A direction parameter was not between 1 and 12.
  258.  
  259.     Symbol expected                              Master, AGTNUM
  260.  
  261.          A symbolic parameter was expected, but a number was found instead.
  262.  
  263.     Unknown parameter type                       All
  264.  
  265.          A parameter is neither a symbol nor a number. Most likely, this
  266.          means that a parameter is missing and that a trailing comment
  267.          was taken for the parameter instead.
  268.  
  269.     Incorrect Param type                         Master, AGTNUM
  270.  
  271.          A symbol was found for a parameter, but of the wrong type for
  272.          the present token (such as using a flag for GetIt).
  273.  
  274.  
  275. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           7
  276.  
  277.  
  278. Errors
  279.  
  280.     Symbol definition expected                   Master, AGTNUM
  281.  
  282.          A symbol was expected for a NOUN, CREATURE, or ROOM definition,
  283.          but was not found.
  284.  
  285.     Symbol redefinition                          Master, AGTNUM
  286.  
  287.          A NOUN, CREATURE, or ROOM definition is using symbol that has
  288.          already been defined.
  289.  
  290.     Macro name expected                          All
  291.  
  292.          There was no symbol following #define.
  293.  
  294.     Macro has no value                           Master
  295.  
  296.          The macro being defined has no value. The macro is assigned a
  297.          null value. Note that if the input is an AGTNUM source (/NUM),
  298.          AGTLINT will assume that you are defining a multi-line macro
  299.          (the macro is still assigned a null value, and so is not
  300.          evaluated, but no error message is given).
  301.  
  302.     Macro redefinition                           All
  303.  
  304.          A macro has already been defined with this label.
  305.  
  306.     Param1 must be <= Param2                     All
  307.  
  308.          This token requires the parameters to define a range. Tokens
  309.          with this requirement are: BetweenRooms, GoToRandomRoom,
  310.          RandomMessage, GetNumberInput, and PlayRandom.
  311.  
  312.     Label expected to follow                     Master, AGTNUM
  313.  
  314.          A description is not followed by a label.
  315.  
  316.     Undefined label                              Master, AGTNUM
  317.  
  318.          The label following a description header is not defined.
  319.  
  320.     Incorrect label type                         Master, AGTNUM
  321.  
  322.          The label following a description header is defined for an
  323.          inappropriate item (such as defining TEXT for a ROOM).
  324.          
  325. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           8
  326.  
  327.  
  328.     Missing Parameter                            Any
  329.  
  330.          The present token has a missing parameter. This message may
  331.          be given on either a definition or a command in Master and
  332.          AGTNUM sources, but only on command in Classic sources.
  333.  
  334.     Undefined parameter                          Master, Classic
  335.  
  336.          The specified parameter label is not defined.
  337.  
  338.     Too many items defined for resource          Any
  339.  
  340.          AGTLINT has found more definitions for the given resource than
  341.          are allowed. Note that limits are only defined for Masters 1.52+
  342.          and Small Classic source files. If you are using either the Big
  343.          Edition or an ealier version of the Master's Edition, use the
  344.          Master's numbers, since they are sufficient to cover those cases.
  345.  
  346.     Unable to open include file                  Any
  347.  
  348.          The given include file could not be opened.
  349.     
  350.     Number too large                             Classic
  351.     Number too small                             Classic
  352.  
  353.          A description's item number is either too large or too small.
  354.  
  355.     Numeric parameter too large                  Classic
  356.     Numeric parameter too small                  Classic
  357.  
  358.          A parameter's numeric value is either too large or too small.
  359.  
  360.  
  361. AGTLINT 1.56-1              Copyright 1993 by David S. Raley           9
  362.  
  363.  
  364.                              APPENDIX  B
  365.  
  366.  
  367. NOTE ON THE VERSION NUMBER
  368.  
  369.     Release 1 supports versions of the Master's Edition up to 1.56--the
  370. version number is this given as 1.56-1. This release works properly with
  371. all version of the Master's Edition, as well as with inputs for the
  372. Classic Edition. This release has been tested on AGTNUM source files,
  373. though there are no guarantees that all of its features are supported.
  374.  
  375.  
  376. VERSION HISTORY
  377.  
  378. Release 1 (supports up to Version 1.56)     Released 27 October 1993
  379.  
  380.  
  381.  
  382.  
  383.  
  384.     If you have any questions about this utility, please contact the author. 
  385.  
  386.                               David S. Raley
  387.                               13523 Demetrias Way
  388.                               Germantown, MD 20874
  389.                               Compuserve: [72247,1153]
  390.                               Internet:   72247,1153@compuserve.com
  391.  
  392.