git @ Cat's Eye Technologies Falderal / 54308e2
Update README. Chris Pressey 6 years ago
1 changed file(s) with 35 addition(s) and 22 deletion(s). Raw diff Collapse all Expand all
2525 expected to be a certain, predicted thing, and if it's not that thing, the
2626 implementation is probably considered incorrect.
2727
28 So why not write those examples in a format that can be tested?
28 So why not write those examples in a format that can be run and tested?
2929
3030 You could write a bunch of standalone test sources, and store the output you
3131 expect from them in a bunch of other files, and write a shell script that runs
3636 comment syntax of your programming language (if your programming language
3737 supports comments) and is also detached from all the other test descriptions.
3838
39 You could write doctests, but if your language isn't implemented in Python
40 it's awkward, and there can be awkward quoting issues with how you embed your
41 test sources inside that big Python string.
42
4339 You could write unit tests in the unit test framework of your choice, but
4440 if your programming language has more than one implementation one day (and
4541 you should really consider that possibility) then you might not be able to
4642 re-use it so easily for other implementations in other languages.
4743
44 In a language like Python, you could write doctests, but that also ties your
45 tests to one implementation of your language. There can be awkward
46 quoting issues with how you embed your test sources inside those embedded
47 strings that comprise your doctests, as well.
48
4849 Or... you could write a Markdown document with beautiful yet precise prose
4950 describing your wonderful language, alternating with example code (in the
5051 form of embedded Falderal tests) clarifying each of the points you are
51 making; then you could use a Falderal-speaking tool to run each of these tests
52 against any implementation of your language which exists or will exist in
53 the future.
52 making; then you could use a Falderal-comprehending tool to run each of these
53 tests against any implementation of your language which exists or will exist
54 in the future.
5455
5556 *And* you could even write this document *before* you even start implementing
5657 your language; then when it is all clear "on paper", you have a target at
5758 which you can aim while writing your language. As you implement more and more
58 of it, more and more tests in your test suite will pass. This is the essence
59 of Test-Driven Language Design (TDLD).
59 of it, more and more tests in your test suite will pass. This is simply the
60 idea behind Test-Driven Development (TDD) applied to language design, which we
61 will call Test-Driven Language Design (TDLD).
6062
6163 Features of the Format
6264 ----------------------
6870 * Run tests from one or more documents.
6971 * Report the results, with some given level of detail.
7072
73 There is, of course, a reference implementation which does both of these
74 things. It is called py-falderal and it is written in Python 2.7.
75
7176 Each Falderal test is for some abstract _functionality_, and each
7277 functionality may have multiple concrete _implementations_. Thus the same
7378 tests can be run multiple times, once for each implementation of the
7580
7681 Directives in the Falderal document may assign functionalities to tests,
7782 and may define implementations for given functionalities. Implementations
78 may be defined outside of any document, as well. Falderal defines one kind
79 of implementation, implementation by Bourne shell command, but is not
80 inherently restricted from supporting other kinds of implementations.
83 may be defined outside of any document, as well. Falderal defines one
84 general kind of implementation, implementation by Bourne shell command, but
85 is not inherently restricted from supporting other kinds of implementations.
8186
8287 Inherent Limitations
8388 --------------------
98103 This distribution contains:
99104
100105 * `doc` — contains documents about Falderal. For the specification of
101 the file format, see `doc/Falderal_Literate_Test_Format.markdown`.
106 the file format, see
107 [`doc/Falderal_Literate_Test_Format.markdown`](doc/Falderal_Literate_Test_Format.markdown).
102108 (Note that this specification should not be expected to remain stable
103109 through the 0.x version series.) There are other documents in there too.
104110 * `bin/falderal` — the reference implementation of Falderal, written in
106112 sources in `src/falderal`. You don't need to install it; just add
107113 the `bin` directory of this distribution to your `$PATH`. This
108114 implementation is (somewhat) documented in `doc/py-falderal.markdown`.
115 * `script` — miscellaneous small tools intended to be used in tests.
109116 * `src` — source code for py-falderal.
110117 * `tests` — a set of tests for Falderal itself. (Note that these are not
111118 written in Falderal, as that would just be too confusing.)
127134 Projects using Falderal
128135 -----------------------
129136
130 (NOTE Actually, I'm sure this information can be extracted from Chrysoberyl
131 somehow, so in the future, just link to that here.)
132
133 Exanoke, Flobnar, Hev, Iphigeneia, Madison, Pail, Pixley, PL-{GOTO}.NET, Robin,
134 Quylthulg, Velo, and Xoomonk.
137 * [Exanoke](http://catseye.tc/node/Exanoke)
138 * [Flobnar](http://catseye.tc/node/Flobnar)
139 * [Hev](http://catseye.tc/node/Hev)
140 * [Iphigeneia](http://catseye.tc/node/Iphigeneia)
141 * [Madison](http://catseye.tc/node/Madison)
142 * [Pail](http://catseye.tc/node/Pail)
143 * [Pixley](http://catseye.tc/node/Pixley)
144 * [PL-{GOTO}.NET](http://catseye.tc/node/PL-{GOTO}.NET)
145 * [Robin](http://catseye.tc/node/Robin)
146 * [Quylthulg](http://catseye.tc/node/Quylthulg)
147 * [Velo](http://catseye.tc/node/Velo)
148 * [Yolk](http://catseye.tc/node/Yolk)
149 * [Xoomonk](http://catseye.tc/node/Xoomonk)
135150
136151 Xoomonk, Madison, Velo, and Exanoke are good examples of how a literate
137152 test suite can be useful in both describing a programming language through
138153 examples and testing that an implementation of the language does not violate
139 the language specification.
140
141 Xoomonk, Madison, Velo, and Exanoke are, in fact, exercises in Test-Driven
154 the language specification. They are, in fact, exercises in Test-Driven
142155 Language Design (TDLD), where the tests were written as part of designing the
143156 language, before any attempt at implementation; the others are more like
144157 traditional test suites, written after-the-fact.