examples/c/README.md

   1 # Examples in C
   2
   3 This directory contains simple examples of Bison grammar files in C.
   4
   5 Some of them come from the documentation, which should be installed together
   6 with Bison.  The URLs are provided for convenience.
   7
   8 ## rpcalc - Reverse Polish Notation Calculator
   9 The first example is that of a simple double-precision Reverse Polish
  10 Notation calculator (a calculator using postfix operators). This example
  11 provides a good starting point, since operator precedence is not an issue.
  12
  13 Extracted from the documentation: [Reverse Polish Notation
  14 Calculator](https://www.gnu.org/software/bison/manual/html_node/RPN-Calc.html).
  15
  16 ## calc - Simple Calculator
  17 This example is slightly more complex than rpcalc: it features infix
  18 operators (`1 + 2`, instead of `1 2 +` in rpcalc), but it does so using a
  19 unambiguous grammar of the arithmetic instead of using precedence
  20 directives (%left, etc.).
  21
  22 ## mfcalc - Multi-Function Calculator
  23 A more complete C example: a multi-function calculator.  More complex than
  24 the previous example.  Using precedence directives to support infix
  25 operators.
  26
  27 Extracted from the documentation: [Multi-Function Calculator:
  28 mfcalc](https://www.gnu.org/software/bison/manual/html_node/Multi_002dfunction-Calc.html).
  29
  30 ## lexcalc - calculator with Flex and Bison
  31 The calculator with precedence directives and location tracking.  It uses
  32 Flex to generate the scanner.
  33
  34 ## reccalc - recursive calculator with Flex and Bison
  35 This example builds on top of the previous one to provide a reentrant
  36 parser.  Such parsers can be called concurrently in different threads, or
  37 even recursively.  To demonstrate this feature, expressions in parentheses
  38 are tokenized as strings, and then recursively parsed from the parser.  So
  39 `(((1)+(2))*((3)+(4)))` uses eight parsers, with a depth of four.
  40
  41 ## pushcalc - calculator implemented with a push parser
  42 All the previous examples are so called "pull parsers": the user invokes the
  43 parser once, which repeatedly calls the scanner until the input is drained.
  44
  45 This example demonstrates the "push parsers": the user calls the scanner to
  46 fetch the next token, passes it to the parser, and repeats the operation
  47 until the input is drained.
  48
  49 This example is a straightforward conversion of the 'calc' example to the
  50 push-parser model.
  51
  52 ## bistromathic - all the bells and whistles
  53 This example demonstrates best practices when using Bison.
  54 - Its hand-written scanner tracks locations.
  55 - Its interface is pure.
  56 - It uses %params to pass user information to the parser and scanner.
  57 - Its scanner uses the `error` token to signal lexical errors and enter
  58   error recovery.
  59 - Its interface is "incremental", well suited for interaction: it uses the
  60   push-parser API to feed the parser with the incoming tokens.
  61 - It features an interactive command line with completion based on the
  62   parser state, based on `yyexpected_tokens`.
  63 - It uses Bison's standard catalogue for internationalization of generated
  64   messages.
  65 - It uses a custom syntax error with location, lookahead correction and
  66   token internationalization.
  67 - Error messages quote the source with squiggles that underline the error:
  68 ```
  69 > 123 456
  70 1.5-7: syntax error: expected end of file or + or - or * or / or ^ before number
  71     1 | 123 456
  72       |     ^~~
  73 ```
  74 - It supports debug traces with semantic values.
  75 - It uses named references instead of the traditional $1, $2, etc.
  76
  77 <!---
  78
  79 Local Variables:
  80 fill-column: 76
  81 ispell-dictionary: "american"
  82 End:
  83
  84 Copyright (C) 2018-2020 Free Software Foundation, Inc.
  85
  86 This file is part of GNU bison, the GNU Compiler Compiler.
  87
  88 Permission is granted to copy, distribute and/or modify this document
  89 under the terms of the GNU Free Documentation License, Version 1.3 or
  90 any later version published by the Free Software Foundation; with no
  91 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  92 Texts.  A copy of the license is included in the "GNU Free
  93 Documentation License" file as part of this distribution.
  94
  95 LocalWords:  mfcalc calc parsers yy rpcalc lexcalc redux reccalc ispell
  96 LocalWords:  reentrant tokenized american postfix pushcalc bistromathic
  97 LocalWords:  lookahead
  98
  99 -->