From 85d303b71345b72c3282ac612d205e0d3d2e07f8 Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Sun, 9 Dec 2018 11:49:23 +0100 Subject: [PATCH] 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. Be sure to ship the test files. Complete CLEANFILES to remove all generated 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. * examples/test (medir): Be robust to deeper directory nesting. --- NEWS | 12 ++++-- examples/README.md | 28 +++++++++++++ examples/c++/{README => README.md} | 26 ++++++++---- examples/{ => c++}/calc++/.gitignore | 0 examples/c++/calc++/Makefile | 41 +++++++++++++++++++ .../{calc++/README => c++/calc++/README.md} | 6 ++- examples/{ => c++}/calc++/calc++.test | 0 examples/{ => c++}/calc++/local.mk | 4 +- examples/c++/local.mk | 5 ++- examples/{README => c/README.md} | 36 ++-------------- examples/c/local.mk | 20 +++++++++ examples/{ => c}/mfcalc/.gitignore | 0 examples/c/mfcalc/Makefile | 25 +++++++++++ examples/{ => c}/mfcalc/local.mk | 3 +- examples/{ => c}/mfcalc/mfcalc.test | 0 examples/{ => c}/rpcalc/.gitignore | 0 examples/c/rpcalc/Makefile | 25 +++++++++++ examples/{ => c}/rpcalc/local.mk | 3 +- examples/{ => c}/rpcalc/rpcalc.test | 0 examples/calc++/Makefile | 27 ------------ examples/d/Makefile | 2 +- examples/d/README.md | 28 +++++++++++++ examples/d/local.mk | 5 ++- examples/java/Makefile | 2 +- examples/java/README.md | 27 ++++++++++++ examples/java/local.mk | 5 ++- examples/local.mk | 6 +-- examples/test | 7 ++-- 28 files changed, 252 insertions(+), 91 deletions(-) create mode 100644 examples/README.md rename examples/c++/{README => README.md} (65%) rename examples/{ => c++}/calc++/.gitignore (100%) create mode 100644 examples/c++/calc++/Makefile rename examples/{calc++/README => c++/calc++/README.md} (98%) rename examples/{ => c++}/calc++/calc++.test (100%) rename examples/{ => c++}/calc++/local.mk (97%) rename examples/{README => c/README.md} (68%) create mode 100644 examples/c/local.mk rename examples/{ => c}/mfcalc/.gitignore (100%) create mode 100644 examples/c/mfcalc/Makefile rename examples/{ => c}/mfcalc/local.mk (95%) rename examples/{ => c}/mfcalc/mfcalc.test (100%) rename examples/{ => c}/rpcalc/.gitignore (100%) create mode 100644 examples/c/rpcalc/Makefile rename examples/{ => c}/rpcalc/local.mk (95%) rename examples/{ => c}/rpcalc/rpcalc.test (100%) delete mode 100644 examples/calc++/Makefile create mode 100644 examples/d/README.md create mode 100644 examples/java/README.md 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 . 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. + + 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 + + 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 , control-d, to end your input). +``` $ ./calc++ - one := 1 two := 2 @@ -20,14 +21,14 @@ three := 3 (one + two * three) * two * three 42 +``` You may pass `-p` to activate the parser debug traces, and `-s` to activate the scanner's. ------ + 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 . -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. - - ------ + 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 . + +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. + + diff --git a/examples/d/local.mk b/examples/d/local.mk index 92fe116e..a9f0e2d2 100644 --- a/examples/d/local.mk +++ b/examples/d/local.mk @@ -23,6 +23,7 @@ if ENABLE_D check_SCRIPTS += %D%/calc TESTS += %D%/calc.test endif +EXTRA_DIST += %D%/calc.test %D%/calc.d: %D%/calc.y $(BISON_IN) $(dist_pkgdata_DATA) $(AM_V_GEN)$(MKDIR_P) %D% @@ -31,5 +32,5 @@ endif %D%/calc: %D%/calc.d $(AM_V_GEN) $(DC) $(DCFLAGS) -of$@ $< -dist_d_DATA = %D%/calc.y %D%/Makefile -CLEANFILES += %D%/calc %D%/Calc.d +dist_d_DATA = %D%/calc.y %D%/Makefile %D%/README.md +CLEANFILES += %D%/calc %D%/calc.[do] 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. + + diff --git a/examples/java/local.mk b/examples/java/local.mk index f464f1f7..9582bfce 100644 --- a/examples/java/local.mk +++ b/examples/java/local.mk @@ -23,6 +23,7 @@ if ENABLE_JAVA check_SCRIPTS += %D%/Calc.class TESTS += %D%/Calc.test endif +EXTRA_DIST += %D%/Calc.test %D%/Calc.java: %D%/Calc.y $(BISON_IN) $(dist_pkgdata_DATA) $(AM_V_GEN)$(MKDIR_P) %D% @@ -31,5 +32,5 @@ endif %D%/Calc.class: %D%/Calc.java $(AM_V_GEN) $(SHELL) $(top_builddir)/javacomp.sh $< -dist_java_DATA = %D%/Calc.y %D%/Makefile -CLEANFILES += %D%/Calc.class %D%/Calc.java +dist_java_DATA = %D%/Calc.y %D%/Makefile %D%/README.md +CLEANFILES += %D%/*.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 diff --git a/examples/test b/examples/test index d9177cb1..d9fad7d2 100755 --- a/examples/test +++ b/examples/test @@ -16,7 +16,7 @@ # along with this program. If not, see . me=$(basename "$1" .test) -medir=$(basename "$(dirname "$1")") +medir=$(dirname "$1" | sed -e 's,.*examples/,,') # Number of the current test. number=1 @@ -28,7 +28,7 @@ exit=true cwd=$(pwd) # The exercised program. -for p in "$cwd/examples/$medir/$me" "$cwd/examples/$me" +for p in "$cwd/examples/$medir/$me" do if test -x "$p"; then prog=$p @@ -40,7 +40,8 @@ do fi done if test x"$prog" = x; then - echo "$me: ERROR: cannot find program to exercise" + echo "$me: ERROR: cannot find program to exercise in:" + echo "$me: ERROR: $cwd/examples/$medir/$me" exit 1 fi