README.md

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