home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pccts1.zip / ANTLR / ANTLR1.TXT < prev    next >
Text File  |  1993-09-01  |  11KB  |  311 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.  Selective back-
  15. tracking  is  also  available to handle non-LL(k) and even non-LALR(k)
  16. constructs.  Antlr also produces a definition of a lexer which can  be
  17. automatically  converted  into  C  code  for a DFA-based lexer by dlg.
  18. Hence, antlr serves a function much like that of yacc, however, it  is
  19. notably  more  flexible  and is more integrated with a lexer generator
  20. (antlr directly generates dlg code, whereas yacc  and  lex  are  given
  21. independent  descriptions).   Unlike  yacc which accepts LALR(1) gram-
  22. mars, antlr accepts LL(k) grammars in an extended BNF notation - which
  23. eliminates the need for precedence rules.
  24.  
  25.      Like  yacc  grammars,  antlr  grammars  can  use   automatically-
  26. maintained  symbol  attribute  values  referenced as dollar variables.
  27. Further, because antlr generates top-down  parsers,  arbitrary  values
  28. may  be inherited from parent rules (passed like function parameters).
  29. Antlr also has a mechanism for  creating  and  manipulating  abstract-
  30. syntax-trees.
  31.  
  32.      There are various other niceties in antlr, including the  ability
  33. to spread one grammar over multiple files or even multiple grammars in
  34. a single file, the ability to generate a version of the  grammar  with
  35. actions stripped out (for documentation purposes), and lots more.
  36.  
  37.  
  38. -ck nUse up to n symbols of lookahead when  using  compressed  (linear
  39.      approximation)  lookahead.   This type of lookahead is very cheap
  40.      to compute and is attempted before full LL(k) lookahead, which is
  41.      of  exponential  complexity  in  the worst case.  In general, the
  42.      compressed lookahead can be much deeper (e.g, -ck  10)  than  the
  43.      full lookahead (which usually must be less than 4).
  44.  
  45. -cr  Generate a cross-reference for all rules.  For each rule, print a
  46.      list of all other rules that reference it.
  47.  
  48. -e1  Ambiguities/errors shown in low detail (default).
  49.  
  50. -e2  Ambiguities/errors shown in more detail.
  51.  
  52. -e3  Ambiguities/errors shown in excruciating detail.
  53.  
  54. -fe file
  55.      Rename err.c to file.
  56.  
  57. -fh file
  58.  
  59.  
  60.  
  61.                                                                 Page 1
  62.  
  63.                                                                  PCCTS
  64.  
  65.  
  66.      Rename stdpccts.h header (turns on -gh) to file.
  67.  
  68. -fl file
  69.      Rename lexical output, parser.dlg, to file.
  70.  
  71. -fm file
  72.      Rename file with lexical mode definitions, mode.h, to file.
  73.  
  74. -fr file
  75.      Rename file which remaps globally visible  symbols,  remap.h,  to
  76.      file.
  77.  
  78. -ft file
  79.      Rename tokens.h to file.
  80.  
  81. -ga  Generate ANSI-compatible code (default case).  This has not  been
  82.      rigorously  tested  to be ANSI XJ11 C compliant, but it is close.
  83.      The normal output of antlr is  currently  compilable  under  both
  84.      K&R,  ANSI C, and C++-this option does nothing because antlr gen-
  85.      erates a bunch of #ifdef's to do the right thing depending on the
  86.      language.
  87.  
  88. -gc  Indicates that antlr should generate no C code, i.e.,  only  per-
  89.      form analysis on the grammar.
  90.  
  91. -gd  C code is inserted in each of the antlr generated  parsing  func-
  92.      tions  to  provide  for user-defined handling of a detailed parse
  93.      trace.  The inserted code consists of calls to the  user-supplied
  94.      macros  or  functions  called zzTRACEIN and zzTRACEOUT.  The only
  95.      argument is a char * pointing to a C-style string  which  is  the
  96.      grammar  rule  recognized by the current parsing function.  If no
  97.      definition is given for the trace functions, upon rule entry  and
  98.      exit, a message will be printed indicating that a particular rule
  99.      as been entered or exited.
  100.  
  101. -ge  Generate an error class for each non-terminal.
  102.  
  103. -gh  Generate stdpccts.h for  non-ANTLR-generated  files  to  include.
  104.      This  file  contains  all  defines needed to describe the type of
  105.      parser generated by antlr (e.g. how much lookahead  is  used  and
  106.      whether  or  not  trees  are constructed) and contains the header
  107.      action specified by the user.
  108.  
  109. -gk  Generate parsers  that  delay  lookahead  fetches  until  needed.
  110.      Without  this option, antlr generates parsers which always have k
  111.      tokens of lookahead available.  This option is incompatible  with
  112.      -pr  and  renders  references to LA(i) invalid as one never knows
  113.      when the ith token of lookahead will be fetched.
  114.  
  115. -gl  Generate line info about grammar actions in C parser of the  form
  116.      # line "file"  which makes error messages from the C/C++ compiler
  117.      make more sense as they will "point" into the  grammar  file  not
  118.      the  resulting  C file.  Debugging is easier as well, because you
  119.      will step through the grammar not C file.
  120.  
  121.  
  122.  
  123.                                                                 Page 2
  124.  
  125.                                                                  PCCTS
  126.  
  127.  
  128. -gp prefix
  129.      Prefix all functions generated from rules with prefix.   This  is
  130.      now obsolete.  Use the "#parser "name"" antlr directive.
  131.  
  132. -gs  Do not generate sets for token expression lists; instead generate
  133.      a  ||-separated  sequence of LA(1)==token_number.  The default is
  134.      to generate sets.
  135.  
  136. -gt  Generate code for Abstract-Syntax Trees.
  137.  
  138. -gx  Do not create the lexical  analyzer  files  (dlg-related).   This
  139.      option  should be given when the user wishes to provide a custom-
  140.      ized lexical analyzer.  It may also be used in  make  scripts  to
  141.      cause  only  the parser to be rebuilt when a change not affecting
  142.      the lexical structure is made to the input grammars.
  143.  
  144. -k n Set k of LL(k) to n; i.e. set tokens of look-ahead (default==1).
  145.  
  146. -p   The complete grammar, collected from all input grammar files  and
  147.      stripped  of  all  comments  and  embedded  actions, is listed to
  148.      stdout.  This is intended to aid in viewing the entire grammar as
  149.      a  whole  and  to  eliminate  the  need to keep actions concisely
  150.      stated so that the grammar is  easier  to  read.   Hence,  it  is
  151.      preferable to embed even complex actions directly in the grammar,
  152.      rather than to call them as  subroutines,  since  the  subroutine
  153.      call overhead will be saved.
  154.  
  155. -pa  This option is the same as -p except that the output is annotated
  156.      with the first sets determined from grammar analysis.
  157.  
  158. -pr  Obsolete - used to turn on use of predicates in parsing decisions
  159.      in  release 1.06.  Now, in 1.10, the specification of a predicate
  160.      implies that it should be used.  When a  syntactic  ambiguity  is
  161.      discovered,  antlr  searches  for  predicates that can be used to
  162.      disambiguate the decision.  Predicates have dual roles as  seman-
  163.      tic validation and disambiguation predicates.
  164.  
  165. -prc on
  166.      Turn on the computation and hoisting of predicate context.
  167.  
  168. -prc off
  169.      Turn off the computation and hoisting of predicate context.  This
  170.      option  makes  1.10  behave like the 1.06 release with option -pr
  171.      on.  Context computation is off by default.
  172.  
  173. -rl  Limit the maximum number of tree nodes used by  grammar  analysis
  174.      to n.  Occasionally, antlr is unable to analyze a grammar submit-
  175.      ted by the user.  This rare situation can  only  occur  when  the
  176.      grammar is large and the amount of lookahead is greater than one.
  177.      A nonlinear analysis algorithm is used by  PCCTS  to  handle  the
  178.      general  case  of  LL(k)  parsing.   The  average  complexity  of
  179.      analysis, however, is near linear due to some fancy  footwork  in
  180.      the  implementation which reduces the number of calls to the full
  181.      LL(k) algorithm.  An error message will  be  displayed,  if  this
  182.  
  183.  
  184.  
  185.                                                                 Page 3
  186.  
  187.                                                                  PCCTS
  188.  
  189.  
  190.      limit  is  reached,  which  indicates the grammar construct being
  191.      analyzed when antlr hit a  non-linearity.   Use  this  option  if
  192.      antlr seems to go out to lunch and your disk start thrashing; try
  193.      n=10000 to start.  Once the offending construct has been  identi-
  194.      fied,  try to remove the ambiguity that antlr was trying to over-
  195.      come with large lookahead analysis.  The introduction  of  (...)?
  196.      backtracking  blocks  eliminates  some  of these problems - antlr
  197.      does not analyze alternatives that begin with (...)?  (it  simply
  198.      backtracks, if necessary, at run time).
  199.  
  200. -w1  Set low warning level.  Do not warn if semantic predicates and/or
  201.      (...)? blocks are assumed to cover ambiguous alternatives.
  202.  
  203. -w2  Ambiguous parsing  decisions  yield  warnings  even  if  semantic
  204.      predicates  or (...)? blocks are used.  Warn if predicate context
  205.      computed and semantic predicates incompletely disambiguate alter-
  206.      native productions.
  207.  
  208. -    Read grammar from standard input  and  generate  stdin.c  as  the
  209.      parser file.
  210.  
  211.  
  212.      Antlr works...  we think.  There is no implicit guarantee of any-
  213. thing.  We reserve no legal rights to the software known as the Purdue
  214. Compiler Construction Tool Set  (PCCTS)  -  PCCTS  is  in  the  public
  215. domain.   An  individual  or  company  may  do whatever they wish with
  216. source code distributed with PCCTS or the  code  generated  by  PCCTS,
  217. including  the  incorporation of PCCTS, or its output, into commercial
  218. software.  We encourage users to develop software  with  PCCTS.   How-
  219. ever,  we  do ask that credit is given to us for developing PCCTS.  By
  220. "credit", we mean that if you incorporate our source code into one  of
  221. your  programs  (commercial  product,  research project, or otherwise)
  222. that  you  acknowledge  this  fact  somewhere  in  the  documentation,
  223. research  report,  etc...  If you like PCCTS and have developed a nice
  224. tool with the output, please  mention  that  you  developed  it  using
  225. PCCTS.   As  long  as these guidelines are followed, we expect to con-
  226. tinue enhancing this system and expect to make other  tools  available
  227. as they are completed.
  228.  
  229.  
  230. *.c  output C parser
  231.  
  232. parser.dlg
  233.      output dlg lexical analyzer
  234.  
  235. err.ctoken string array, error sets and error support routines
  236.  
  237. remap.h
  238.      file that redefines all globally visible parser symbols.  The use
  239.      of the #parser directive creates this file
  240.  
  241. stdpccts.h
  242.      list of definitions needed by C files, not  generated  by  PCCTS,
  243.      that reference PCCTS objects.  This is not generated by default.
  244.  
  245.  
  246.  
  247.                                                                 Page 4
  248.  
  249.                                                                  PCCTS
  250.  
  251.  
  252. tokens.h
  253.      output #defines for tokens used and function prototypes for func-
  254.      tions generated for rules
  255.  
  256.  
  257. dlg(1), pccts(1)
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.                                                                 Page 5
  310.  
  311.