home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / p / pccts.zip / antlr / antlr1.txt < prev    next >
Text File  |  1992-12-08  |  9KB  |  249 lines
  1.  
  2.  
  3.  
  4. antlr - ANother Tool for Language Recognition
  5.  
  6.  
  7. antlr [options] grammar_files
  8.  
  9.  
  10.      Antlr converts an extended form of context-free  grammar  into  a
  11. set  of  C  functions  which  directly  implement an efficient form of
  12. deterministic recursive-descent LL(k) parser.   Context-free  grammars
  13. may be augmented with predicates to allow semantics to influence pars-
  14. ing; this allows a form of context-sensitive parsing.  Antlr also pro-
  15. duces  a  definition  of  a lexer which can be automatically converted
  16. into C code for a DFA-based lexer by dlg.  Hence, antlr serves a func-
  17. tion  much like that of yacc, however, it is notably more flexible and
  18. is more integrated with a lexer generator  (antlr  directly  generates
  19. dlg  code,  whereas  yacc and lex are given independent descriptions).
  20. Unlike yacc which accepts LALR(1) grammars, antlr accepts LL(k)  gram-
  21. mars  in an extended BNF notation - which eliminates the need for pre-
  22. cedence rules.
  23.  
  24.      Like  yacc  grammars,  antlr  grammars  can  use   automatically-
  25. maintained  symbol  attribute  values  referenced as dollar variables.
  26. Further, because antlr generates top-down  parsers,  arbitrary  values
  27. may  be inherited from parent rules (passed like function parameters).
  28. Antlr also has a mechanism for  creating  and  manipulating  abstract-
  29. syntax-trees.
  30.  
  31.      There are various other niceties in antlr, including the  ability
  32. to spread one grammar over multiple files or even multiple grammars in
  33. a single file, the ability to generate a version of the  grammar  with
  34. actions stripped out (for documentation purposes), and lots more.
  35.  
  36.  
  37. -cr  Generate a cross-reference for all rules.  For each rule, print a
  38.      list of all other rules that reference it.
  39.  
  40. -e1  Ambiguities/errors shown in low detail (default).
  41.  
  42. -e2  Ambiguities/errors shown in more detail.
  43.  
  44. -e3  Ambiguities/errors shown in excrutiating detail.
  45.  
  46. -fe file
  47.      Rename err.c to file.
  48.  
  49. -fh file
  50.      Rename stdpccts.h header (turns on -gh) to file.
  51.  
  52. -fl file
  53.      Rename lexical output, parser.dlg, to file.
  54.  
  55. -ft file
  56.      Rename tokens.h to file.
  57.  
  58.  
  59.  
  60.  
  61.                                                                 Page 1
  62.  
  63.                                                                  PCCTS
  64.  
  65.  
  66. -ga  Generate ANSI-compatible code (default case).  This has not  been
  67.      rigorously  tested  to be ANSI XJ11 C compliant, but it is close.
  68.      The normal output of antlr is currently compilable under both K&R
  69.      and  ANSI  C-this  option  does  nothing, but is reserved for the
  70.      future.
  71.  
  72. -gc  Indicates that antlr should generate no C code, i.e.,  only  per-
  73.      form analysis on the grammar.
  74.  
  75. -gd  C code is inserted in each of the antlr generated  parsing  func-
  76.      tions  to  provide  for user-defined handling of a detailed parse
  77.      trace.  The inserted code consists of calls to the  user-supplied
  78.      macros  or  functions  called zzTRACEIN and zzTRACEOUT.  The only
  79.      argument is a char * pointing to a C-style string  which  is  the
  80.      grammar  rule  recognized by the current parsing function.  If no
  81.      definition is given for the trace functions, upon rule entry  and
  82.      exit, a message will be printed indicating that a particular rule
  83.      as been entered or exited.
  84.  
  85. -ge  Generate an error class for each non-terminal.
  86.  
  87. -gh  Generate stdpccts.h for  non-ANTLR-generated  files  to  include.
  88.      This  file  contains  all  defines needed to describe the type of
  89.      parser generated by antlr (e.g. how much lookahead  is  used  and
  90.      whether  or  not  trees  are constructed) and contains the header
  91.      action specified by the user.
  92.  
  93. -gk  Generate parsers  that  delay  lookahead  fetches  until  needed.
  94.      Without  this option, antlr generates parsers which always have k
  95.      tokens of lookahead available.  This option is incompatible  with
  96.      -pr  and  renders  references to LA(i) invalid as one never knows
  97.      when the ith token of lookahead will be fetched.
  98.  
  99. -gl  Generate line info about grammar actions in C parser of the  form
  100.      # line "file"  which makes error messages from the C/C++ compiler
  101.      make more sense as they will "point" into the  grammar  file  not
  102.      the  resulting  C file.  Debugging is easier as well, because you
  103.      will step through the grammar not C file.
  104.  
  105. -gp prefix
  106.      Prefix all functions generated from rules with prefix.
  107.  
  108. -gs  Do not generate sets for token expression lists; instead generate
  109.      a  ||-separated  sequence of LA(1)==token_number.  The default is
  110.      to generate sets.
  111.  
  112. -gt  Generate code for Abstract-Syntax Trees.
  113.  
  114. -gx  Do not create the lexical  analyzer  files  (dlg-related).   This
  115.      option  should be given when the user wishes to provide a custom-
  116.      ized lexical analyzer.  It may also be used in  make  scripts  to
  117.      cause  only  the parser to be rebuilt when a change not affecting
  118.      the lexical structure is made to the input grammars.
  119.  
  120.  
  121.  
  122.  
  123.                                                                 Page 2
  124.  
  125.                                                                  PCCTS
  126.  
  127.  
  128. -k n Set k of LL(k) to n; i.e. set tokens of look-ahead (default==1).
  129.  
  130. -p   The complete grammar, collected from all input grammar files  and
  131.      stripped  of  all  comments  and  embedded  actions, is listed to
  132.      stdout.  This is intended to aid in viewing the entire grammar as
  133.      a  whole  and  to  eliminate  the  need to keep actions concisely
  134.      stated so that the grammar is  easier  to  read.   Hence,  it  is
  135.      preferable to embed even complex actions directly in the grammar,
  136.      rather than to call them as  subroutines,  since  the  subroutine
  137.      call overhead will be saved.
  138.  
  139. -pa  This option is the same as -p except that the output is annotated
  140.      with the first sets determined from grammar analysis.
  141.  
  142. -pr  Turn on use of predicates in parsing decisions  (alpha  version).
  143.      When  a  syntactic  ambiguity  is  discovered, antlr searches for
  144.      predicates that can be used to disambiguate the decision.  Predi-
  145.      cates  have  dual roles as semantic validation and disambiguation
  146.      predicates.
  147.  
  148. -rl  Limit the maximum number of tree nodes used by  grammar  analysis
  149.      to n.  Occasionally, antlr is unable to analyze a grammar submit-
  150.      ted by the user.  This rare situation can  only  occur  when  the
  151.      grammar is large and the amount of lookahead is greater than one.
  152.      A nonlinear analysis algorithm is used by  PCCTS  to  handle  the
  153.      general  case  of  LL(k)  parsing.   The  average  complexity  of
  154.      analysis, however, is near linear due to some fancy  footwork  in
  155.      the  implementation which reduces the number of calls to the full
  156.      LL(k) algorithm.  An error message will  be  displayed,  if  this
  157.      limit  is  reached,  which  indicates the grammar construct being
  158.      analyzed when antlr hit a  non-linearity.   Use  this  option  if
  159.      antlr seems to go out to lunch and your disk start thrashing; try
  160.      n=10000 to start.  Once the offending construct has been  identi-
  161.      fied,  try to remove the ambiguity that antlr was trying to over-
  162.      come with large lookahead analysis.
  163.  
  164.  
  165.      Antlr works...  we think.  There is no implicit guarantee of any-
  166. thing.  We reserve no legal rights to the software known as the Purdue
  167. Compiler Construction Tool Set  (PCCTS)  -  PCCTS  is  in  the  public
  168. domain.   An  individual  or  company  may  do whatever they wish with
  169. source code distributed with PCCTS or the  code  generated  by  PCCTS,
  170. including  the  incorporation of PCCTS, or its output, into commerical
  171. software.  We encourage users to develop software  with  PCCTS.   How-
  172. ever,  we  do ask that credit is given to us for developing PCCTS.  By
  173. "credit", we mean that if you incorporate our source code into one  of
  174. your  programs  (commercial  product,  research project, or otherwise)
  175. that  you  acknowledge  this  fact  somewhere  in  the  documentation,
  176. research  report,  etc...  If you like PCCTS and have developed a nice
  177. tool with the output, please  mention  that  you  developed  it  using
  178. PCCTS.   As  long  as these guidelines are followed, we expect to con-
  179. tinue enhancing this system and expect to make other  tools  available
  180. as they are completed.
  181.  
  182.  
  183.  
  184.  
  185.                                                                 Page 3
  186.  
  187.                                                                  PCCTS
  188.  
  189.  
  190. *.c  output C parser
  191.  
  192. parser.dlg
  193.      output dlg lexical analyzer
  194.  
  195. err.ctoken string array, error sets and error support routines
  196.  
  197. tokens.h
  198.      output #defines for tokens used and function prototypes for func-
  199.      tions generated for rules
  200.  
  201. stdpccts.h
  202.      list of definitions needed by C files, not  generated  by  PCCTS,
  203.      that reference PCCTS objects.  This is not generated by default.
  204.  
  205.  
  206. dlg(1), pccts(1)
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.                                                                 Page 4
  248.  
  249.