README.md

   1 # πyacc LALR1 syntax compiler
   2
   3 The πyacc program is in general a replacement for the YACC utility from AT&T
   4 or Berkeley Unix, or the GNU Bison equivalent. πyacc takes an input file with
   5 the extension .y and produces a parser in the form of C or Python source code.
   6
   7 πyacc takes the same input syntax as Bison. Many of the more obscure Bison
   8 features are not implemented, and are ignored and/or will cause a warning or
   9 error message. Enough of the standard functionality is implemented to be able
  10 to build a correctly working Bison and Flex, and we can likely add more Bison
  11 features if your project happens to depend on them.
  12
  13 The parsers generated by πyacc are LALR1. When generating C source code, we use
  14 a Bison skeleton, and therefore, provided you use the supported feature set
  15 such that we can correctly populate the skeleton, the result should be a simple
  16 drop-in replacement for the Bison-generated parser with few compatibility
  17 issues (however, we modified the skeleton slightly to use the C preprocessor
  18 for some constructs that Bison would deal with at compile time using m4).
  19
  20 When generating Python source code, we use our own skeleton which has many more
  21 features than Bison's. The most important feature is that we can process
  22 annotations in the .y input file which instruct the parser on how to generate
  23 an abstract syntax tree automatically during parsing. This is a huge time-saver
  24 since in the common case you do not need to write any action code to run when
  25 a rule is matched (we write the action code for you). You may write action code
  26 as well, since some parsers need to maintain state or change things during the
  27 execution of the parser in order to correctly parse the input.
  28
  29 The Python skeleton is designed to be highly compatible with the Bison
  30 skeleton, with fairly direct translations of each Bison construct that you
  31 could have invoked from your Bison .y source. In particular we don't force you
  32 to generate a re-entrant parser, even though Python does this very well. This
  33 is to make it easy to convert legacy .y specifications over to Python and
  34 πyacc. We also provide a tool called c_to_python (created using πyacc), which
  35 is capable of identifying the C code in your .y specification and translating
  36 it. The translation is pretty rough at present, but gives you a starting point.
  37
  38 Further detailed documentation and tutorials will be added to the project in
  39 due course. For the present, the software is in active development, so it would
  40 be premature to document everything exactly as it is now. Please do contact the
  41 author Nick Downing <nick@ndcode.org>, should you have questions or feedback.