[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: I need simpler examples (was: RE: Enhancement request: enabling Vari
|
From: |
Akim Demaille |
|
Subject: |
Re: I need simpler examples (was: RE: Enhancement request: enabling Variant in C parsers) |
|
Date: |
Sun, 9 Dec 2018 12:49:12 +0100 |
> Le 9 déc. 2018 à 06:53, Akim Demaille <address@hidden> a écrit :
>
>> * I give exact command lines to run my example, you don't
>
> It's an ongoing effort. If you look the history of the examples you'll see
> that they are getting Makefiles and READMEs. In particular calc++ has its
> Makefile, so your comment is quite inaccurate.
This should help to bridge the gap.
commit 7a39accad1e469fda16a40ab9467cbc55a61bee0
Author: Akim Demaille <address@hidden>
Date: Sun Dec 9 11:49:23 2018 +0100
examples: sort them per language and complete them
Convert some of the READMEs to Markdown, which is now more common, and
nicely displayed in some git hosting services.
Add missing READMEs and Makefiles. Generate XML, HTML and Dot files.
* examples/calc++: Move into...
* examples/c++: here.
* examples/mfcalc, examples/rpcalc: Move into...
* examples/c: here.
* examples/README.md, examples/c++/calc++/Makefile, examples/c/local.mk,
* examples/c/mfcalc/Makefile, examples/c/rpcalc/Makefile,
* examples/d/README.md, examples/java/README.md:
New files.
diff --git a/NEWS b/NEWS
index c902e9ee..9c49fe84 100644
--- a/NEWS
+++ b/NEWS
@@ -137,8 +137,12 @@ GNU Bison NEWS
** Documentation
- The examples (installed in .../share/doc/bison/examples), now include a
- Java calculator.
+ The examples/ directory (installed in .../share/doc/bison/examples) has
+ been restructured per language for clarity. The examples come with a
+ README and a Makefile. Not only can they be used to toy with Bison, they
+ can also be starting points for your own grammars.
+
+ There is now a Java example.
** Changes
@@ -647,7 +651,7 @@ GNU Bison NEWS
Traditional Yacc generates 'y.tab.c' whatever the name of the input file.
Therefore Makefiles written for Yacc expect 'y.tab.c' (and possibly
- 'y.tab.h' and 'y.outout') to be generated from 'foo.y'.
+ 'y.tab.h' and 'y.output') to be generated from 'foo.y'.
To this end, for ages, AC_PROG_YACC, Autoconf's macro to look for an
implementation of Yacc, was using Bison as 'bison -y'. While it does
@@ -3284,7 +3288,7 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
LocalWords: pragmas noreturn untyped Rozenman unexpanded Wojciech Polak
LocalWords: Alexandre MERCHANTABILITY yytype emplace ptr automove lvalues
LocalWords: nonterminal yy args Pragma dereference yyformat rhs docdir
- LocalWords: Redeclarations rpcalc Autoconf YFLAGS Makefiles outout PROG
+ LocalWords: Redeclarations rpcalc Autoconf YFLAGS Makefiles PROG
LocalWords: Heimbigner AST src ast Makefile srcdir MinGW
Local Variables:
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..811672df
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,28 @@
+This directory contains examples of Bison grammar files, sorted per
+language.
+
+Several of them come from the documentation, which should be installed
+together with Bison. The URLs are provided for convenience.
+
+These examples come with a README and a Makefile. Not only can they be used
+to toy with Bison, they can also be starting points for your own grammars.
+
+Please, be sure to read the C examples before looking at the other
+languages, as these examples are simpler.
+
+<!---
+
+Local Variables:
+fill-column: 76
+ispell-dictionary: "american"
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the "GNU Free
+Documentation License" file as part of this distribution.
+--->
diff --git a/examples/c++/README b/examples/c++/README.md
similarity index 65%
rename from examples/c++/README
rename to examples/c++/README.md
index 3d6c2034..7459450a 100644
--- a/examples/c++/README
+++ b/examples/c++/README.md
@@ -1,11 +1,11 @@
-This directory contains examples of Bison grammar files in C++.
+# Examples in C++
-* Examples in C++
+This directory contains examples of Bison grammar files in C++.
You can run `make` to compile these examples. And `make clean` to tidy
afterwards.
-** simple.yy - Simple example in C++14
+## simple.yy - Simple example in C++14
A very simple example in C++, based on variants and symbol constructors.
Variants allow to use any C++ type as semantic value type, and symbol
constructors ensure consistency between declared token type and effective
@@ -16,21 +16,32 @@ Run as `./simple`.
Extracted from the documentation: "A Simple C++ Example".
https://www.gnu.org/software/bison/manual/html_node/A-Simple-C_002b_002b-Example.html
-** variant.yy - Self-contained example in C++98
+## variant.yy - Self-contained example in C++98
A variation of simple.yy, in C++98.
Run as `./variant`.
-** variant-11.yy - Self-contained example in modern C++
+## variant-11.yy - Self-contained example in modern C++
Another variation of simple.yy, closely related to the previous one, but
exhibiting support for C++11's move semantics.
Run as `./variant` or `./variant NUMBER`.
------
+## calc++ - A Complete C++ Example
+A fully featured C++ version of the canonical example for parsers: a
+calculator. Also uses Flex for the scanner.
+
+Don't look at this example first: it is fully featured and can serve as a
+starting point for a clean parser in C++. The previous examples are better
+introductory examples, and the C examples are also useful introductory
+examples.
+
+Extracted from the documentation: "A Complete C++ Example".
+https://www.gnu.org/software/bison/manual/html_node/A-Complete-C_002b_002b-Example.html
+
+<!---
Local Variables:
-mode: outline
fill-column: 76
ispell-dictionary: "american"
End:
@@ -45,3 +56,4 @@ Texts. A copy of the license is included in the "GNU Free
Documentation License" file as part of this distribution.
# LocalWords: mfcalc calc parsers yy ispell american
+--->
diff --git a/examples/calc++/.gitignore b/examples/c++/calc++/.gitignore
similarity index 100%
rename from examples/calc++/.gitignore
rename to examples/c++/calc++/.gitignore
diff --git a/examples/c++/calc++/Makefile b/examples/c++/calc++/Makefile
new file mode 100644
index 00000000..a2d83d7c
--- /dev/null
+++ b/examples/c++/calc++/Makefile
@@ -0,0 +1,41 @@
+# This Makefile is designed to be simple and readable. It does not
+# aim at portability. It requires GNU Make.
+
+BASE = calc++
+BISON = bison
+CXX = g++
+FLEX = flex
+XSLTPROC = xsltproc
+
+all: $(BASE)
+
+%.cc %.hh %.xml %.gv: %.yy
+ $(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.cc $<
+
+%.cc: %.ll
+ $(FLEX) $(FLEXFLAGS) -o$@ $<
+
+%.o: %.cc
+ $(CXX) $(CXXFLAGS) -c -o$@ $<
+
+$(BASE): $(BASE).o driver.o parser.o scanner.o
+ $(CXX) -o $@ $^
+
+$(BASE).o: parser.hh
+parser.o: parser.hh
+scanner.o: parser.hh
+
+run: $(BASE)
+ @echo "Type arithmetic expressions. Quit with ctrl-d."
+ ./$< -
+
+html: parser.html
+%.html: %.xml
+ $(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON)
--print-datadir)/xslt/xml2xhtml.xsl $<
+
+CLEANFILES =
\
+ $(BASE) *.o
\
+ parser.hh parser.cc parser.output parser.xml parser.html parser.gv
location.hh \
+ scanner.cc
+clean:
+ rm -f $(CLEANFILES)
diff --git a/examples/calc++/README b/examples/c++/calc++/README.md
similarity index 98%
rename from examples/calc++/README
rename to examples/c++/calc++/README.md
index 8fbd2d74..d4d5154f 100644
--- a/examples/calc++/README
+++ b/examples/c++/calc++/README.md
@@ -13,6 +13,7 @@ evaluate.
The program calc++ expects the file to parse as argument; pass `-` to read
the standard input (and then hit <Ctrl-d>, control-d, to end your input).
+```
$ ./calc++ -
one := 1
two := 2
@@ -20,14 +21,14 @@ three := 3
(one + two * three) * two * three
<Ctrl-d>
42
+```
You may pass `-p` to activate the parser debug traces, and `-s` to activate
the scanner's.
------
+<!---
Local Variables:
-mode: outline
fill-column: 76
ispell-dictionary: "american"
End:
@@ -50,3 +51,4 @@ You should have received a copy of the GNU General Public
License
along with this program. If not, see <http://www.gnu.org/licenses/>.
# LocalWords: mfcalc calc parsers yy MERCHANTABILITY Ctrl ispell american
+--->
diff --git a/examples/calc++/calc++.test b/examples/c++/calc++/calc++.test
similarity index 100%
rename from examples/calc++/calc++.test
rename to examples/c++/calc++/calc++.test
diff --git a/examples/calc++/local.mk b/examples/c++/calc++/local.mk
similarity index 97%
rename from examples/calc++/local.mk
rename to examples/c++/calc++/local.mk
index 8de5bf4d..a051ad46 100644
--- a/examples/calc++/local.mk
+++ b/examples/c++/calc++/local.mk
@@ -79,6 +79,6 @@ EXTRA_DIST += %D%/calc++.test
## Installing. ##
## ------------ ##
-calcxxdir = $(docdir)/examples/calc++
+calcxxdir = $(docdir)/%D%
calcxx_DATA = $(calcxx_extracted)
-dist_calcxx_DATA = %D%/README %D%/Makefile
+dist_calcxx_DATA = %D%/README.md %D%/Makefile
diff --git a/examples/c++/local.mk b/examples/c++/local.mk
index 66556a70..e251276f 100644
--- a/examples/c++/local.mk
+++ b/examples/c++/local.mk
@@ -13,7 +13,8 @@
## You should have received a copy of the GNU General Public License
## along with this program. If not, see <http://www.gnu.org/licenses/>.
-cxxdir = $(examplesdir)/c++
+cxxdir = $(docdir)/%D%
+include %D%/calc++/local.mk
## -------- ##
## Simple. ##
@@ -66,5 +67,5 @@ if ENABLE_CXX11
endif
EXTRA_DIST += %D%/variant-11.test
-dist_cxx_DATA = %D%/README %D%/Makefile %D%/variant.yy %D%/variant-11.yy
+dist_cxx_DATA = %D%/README.md %D%/Makefile %D%/variant.yy %D%/variant-11.yy
CLEANFILES += %D%/simple.output %D%/variant.output %D%/variant-11.output
diff --git a/examples/README b/examples/c/README.md
similarity index 68%
rename from examples/README
rename to examples/c/README.md
index e9b505ca..5093d7a4 100644
--- a/examples/README
+++ b/examples/c/README.md
@@ -3,10 +3,7 @@ This directory contains examples of Bison grammar files.
Most of them come from the documentation, which should be installed together
with Bison. The URLs are provided for convenience.
-
-* Examples in C
-
-** rpcalc - Reverse Polish Notation Calculator
+# rpcalc - Reverse Polish Notation Calculator
The first example is that of a simple double-precision Reverse Polish
Notation calculator (a calculator using postfix operators). This example
provides a good starting point, since operator precedence is not an issue.
@@ -14,42 +11,16 @@ provides a good starting point, since operator precedence
is not an issue.
Extracted from the documentation: "Reverse Polish Notation Calculator"
https://www.gnu.org/software/bison/manual/html_node/RPN-Calc.html
-** mfcalc - Multi-Function Calculator
+# mfcalc - Multi-Function Calculator
A more complete C example: a multi-function calculator.
Extracted from the documentation: "Multi-Function Calculator: mfcalc".
https://www.gnu.org/software/bison/manual/html_node/Multi_002dfunction-Calc.html
-
-* Examples in C++
-
-** c++ - A directory of simple C++ examples
-
-** calc++ - A Complete C++ Example
-A fully featured C++ version of the canonical example for parsers: a
-calculator. Also uses Flex for the scanner.
-
-Extracted from the documentation: "A Complete C++ Example".
-https://www.gnu.org/software/bison/manual/html_node/A-Complete-C_002b_002b-Example.html
-
-
-* Examples in D
-
-** d/calc.y
-The usual calculator.
-
-
-* Examples in Java
-
-** java/Calc.y
-The usual calculator.
-
-
------
+<!---
Local Variables:
-mode: outline
fill-column: 76
ispell-dictionary: "american"
End:
@@ -64,3 +35,4 @@ Texts. A copy of the license is included in the "GNU Free
Documentation License" file as part of this distribution.
# LocalWords: mfcalc calc parsers yy
+--->
diff --git a/examples/c/local.mk b/examples/c/local.mk
new file mode 100644
index 00000000..dcd90424
--- /dev/null
+++ b/examples/c/local.mk
@@ -0,0 +1,20 @@
+## Copyright (C) 2018 Free Software Foundation, Inc.
+##
+## This program is free software: you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+cdir = $(docdir)/%D%
+dist_c_DATA = %D%/README.md
+
+include %D%/mfcalc/local.mk
+include %D%/rpcalc/local.mk
diff --git a/examples/mfcalc/.gitignore b/examples/c/mfcalc/.gitignore
similarity index 100%
rename from examples/mfcalc/.gitignore
rename to examples/c/mfcalc/.gitignore
diff --git a/examples/c/mfcalc/Makefile b/examples/c/mfcalc/Makefile
new file mode 100644
index 00000000..b9518089
--- /dev/null
+++ b/examples/c/mfcalc/Makefile
@@ -0,0 +1,25 @@
+# This Makefile is designed to be simple and readable. It does not
+# aim at portability. It requires GNU Make.
+
+BASE = mfcalc
+BISON = bison
+XSLTPROC = xsltproc
+
+all: $(BASE)
+
+%.c %.xml %.gv: %.y
+ $(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.c $<
+
+%: %.c
+ $(CC) $(CFLAGS) -o $@ $<
+
+run: $(BASE)
+ @echo "Type arithmetic expressions. Quit with ctrl-d."
+ ./$<
+
+html: $(BASE).html
+%.html: %.xml
+ $(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON)
--print-datadir)/xslt/xml2xhtml.xsl $<
+
+clean:
+ rm -f $(BASE) $(BASE).c $(BASE).html $(BASE).xml $(BASE).gv
$(BASE).output
diff --git a/examples/mfcalc/local.mk b/examples/c/mfcalc/local.mk
similarity index 95%
rename from examples/mfcalc/local.mk
rename to examples/c/mfcalc/local.mk
index 62923b37..c76bfa5a 100644
--- a/examples/mfcalc/local.mk
+++ b/examples/c/mfcalc/local.mk
@@ -38,5 +38,6 @@ dist_TESTS += %D%/mfcalc.test
## Installing. ##
## ------------ ##
-mfcalcdir = $(docdir)/examples/mfcalc
+mfcalcdir = $(docdir)/%D%
mfcalc_DATA = $(mfcalc_extracted)
+dist_mfcalc_DATA = %D%/Makefile
diff --git a/examples/mfcalc/mfcalc.test b/examples/c/mfcalc/mfcalc.test
similarity index 100%
rename from examples/mfcalc/mfcalc.test
rename to examples/c/mfcalc/mfcalc.test
diff --git a/examples/rpcalc/.gitignore b/examples/c/rpcalc/.gitignore
similarity index 100%
rename from examples/rpcalc/.gitignore
rename to examples/c/rpcalc/.gitignore
diff --git a/examples/c/rpcalc/Makefile b/examples/c/rpcalc/Makefile
new file mode 100644
index 00000000..87e18f34
--- /dev/null
+++ b/examples/c/rpcalc/Makefile
@@ -0,0 +1,25 @@
+# This Makefile is designed to be simple and readable. It does not
+# aim at portability. It requires GNU Make.
+
+BASE = rpcalc
+BISON = bison
+XSLTPROC = xsltproc
+
+all: $(BASE)
+
+%.c %.xml %.gv: %.y
+ $(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.c $<
+
+%: %.c
+ $(CC) $(CFLAGS) -o $@ $<
+
+run: $(BASE)
+ @echo "Type arithmetic expressions in reverse polish notation. Quit
with ctrl-d."
+ ./$<
+
+html: $(BASE).html
+%.html: %.xml
+ $(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON)
--print-datadir)/xslt/xml2xhtml.xsl $<
+
+clean:
+ rm -f $(BASE) $(BASE).c $(BASE).html $(BASE).xml $(BASE).gv
diff --git a/examples/rpcalc/local.mk b/examples/c/rpcalc/local.mk
similarity index 95%
rename from examples/rpcalc/local.mk
rename to examples/c/rpcalc/local.mk
index 48f6ac67..6889e7de 100644
--- a/examples/rpcalc/local.mk
+++ b/examples/c/rpcalc/local.mk
@@ -38,5 +38,6 @@ dist_TESTS += %D%/rpcalc.test
## Installing. ##
## ------------ ##
-rpcalcdir = $(docdir)/examples/rpcalc
+rpcalcdir = $(docdir)/%D%
rpcalc_DATA = $(rpcalc_extracted)
+dist_rpcalc_DATA = %D%/Makefile
diff --git a/examples/rpcalc/rpcalc.test b/examples/c/rpcalc/rpcalc.test
similarity index 100%
rename from examples/rpcalc/rpcalc.test
rename to examples/c/rpcalc/rpcalc.test
diff --git a/examples/calc++/Makefile b/examples/calc++/Makefile
deleted file mode 100644
index 6b6c4998..00000000
--- a/examples/calc++/Makefile
+++ /dev/null
@@ -1,27 +0,0 @@
-# This Makefile is designed to be simple and readable. It does not
-# aim at portability. It requires GNU Make.
-
-BISON = bison
-CXX = g++
-FLEX = flex
-
-all: calc++
-
-%.cc %.hh: %.yy
- $(BISON) $(BISONFLAGS) -o $*.cc $<
-
-%.cc: %.ll
- $(FLEX) $(FLEXFLAGS) -o$@ $<
-
-%.o: %.cc
- $(CXX) $(CXXFLAGS) -c -o$@ $<
-
-calc++: calc++.o driver.o parser.o scanner.o
- $(CXX) -o $@ $^
-
-calc++.o: parser.hh
-parser.o: parser.hh
-scanner.o: parser.hh
-
-clean:
- rm -f calc++ *.o parser.hh parser.cc scanner.cc
diff --git a/examples/d/Makefile b/examples/d/Makefile
index 1c41b6ce..45ae6289 100644
--- a/examples/d/Makefile
+++ b/examples/d/Makefile
@@ -14,7 +14,7 @@ all: calc
$(DC) $(DCFLAGS) $<
run: calc
- echo "Type arithmetic expressions. Quit with ctrl-d."
+ @echo "Type arithmetic expressions. Quit with ctrl-d."
./$<
html: calc.html
diff --git a/examples/d/README.md b/examples/d/README.md
new file mode 100644
index 00000000..32d8a9c8
--- /dev/null
+++ b/examples/d/README.md
@@ -0,0 +1,28 @@
+# Examples in D
+
+This directory contains examples of Bison grammar files in D.
+
+You can run `make` to compile these examples. And `make clean` to tidy
+afterwards.
+
+## d/calc.y
+The usual calculator.
+
+<!---
+
+Local Variables:
+fill-column: 76
+ispell-dictionary: "american"
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the "GNU Free
+Documentation License" file as part of this distribution.
+
+# LocalWords: mfcalc calc parsers yy
+--->
diff --git a/examples/d/local.mk b/examples/d/local.mk
index 92fe116e..bab6e25f 100644
--- a/examples/d/local.mk
+++ b/examples/d/local.mk
@@ -31,5 +31,5 @@ endif
%D%/calc: %D%/calc.d
$(AM_V_GEN) $(DC) $(DCFLAGS) -of$@ $<
-dist_d_DATA = %D%/calc.y %D%/Makefile
+dist_d_DATA = %D%/calc.y %D%/Makefile %D%/README.md
CLEANFILES += %D%/calc %D%/Calc.d
diff --git a/examples/java/Makefile b/examples/java/Makefile
index de9a54a6..5a165205 100644
--- a/examples/java/Makefile
+++ b/examples/java/Makefile
@@ -15,7 +15,7 @@ all: Calc.class
$(JAVAC) $(JAVACFLAGS) $<
run: Calc.class
- echo "Type arithmetic expressions. Quit with ctrl-d."
+ @echo "Type arithmetic expressions. Quit with ctrl-d."
$(JAVA) $(JAVAFLAGS) Calc
html: Calc.html
diff --git a/examples/java/README.md b/examples/java/README.md
new file mode 100644
index 00000000..99df7f3a
--- /dev/null
+++ b/examples/java/README.md
@@ -0,0 +1,27 @@
+# Examples in Java
+
+This directory contains examples of Bison grammar files in Java.
+
+You can run `make` to compile these examples. And `make clean` to tidy
+afterwards.
+
+## java/Calc.y
+The usual calculator.
+
+<!---
+
+Local Variables:
+mode: markdown
+fill-column: 76
+ispell-dictionary: "american"
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the "GNU Free
+Documentation License" file as part of this distribution.
+--->
diff --git a/examples/java/local.mk b/examples/java/local.mk
index f464f1f7..d1476251 100644
--- a/examples/java/local.mk
+++ b/examples/java/local.mk
@@ -31,5 +31,5 @@ endif
%D%/Calc.class: %D%/Calc.java
$(AM_V_GEN) $(SHELL) $(top_builddir)/javacomp.sh $<
-dist_java_DATA = %D%/Calc.y %D%/Makefile
+dist_java_DATA = %D%/Calc.y %D%/Makefile %D%/README.md
CLEANFILES += %D%/Calc.class %D%/Calc.java
diff --git a/examples/local.mk b/examples/local.mk
index 0fd81b5c..83969468 100644
--- a/examples/local.mk
+++ b/examples/local.mk
@@ -71,13 +71,11 @@ examples-unline:
## ---------- ##
examplesdir = $(docdir)/examples
-dist_examples_DATA = %D%/README
+dist_examples_DATA = %D%/README.md
CLEANDIRS += %D%/*.dSYM
-include %D%/calc++/local.mk
+include %D%/c/local.mk
include %D%/c++/local.mk
include %D%/d/local.mk
include %D%/java/local.mk
-include %D%/mfcalc/local.mk
-include %D%/rpcalc/local.mk