Commit 54308e242d301379855d8e12b0d419ed6c0f86b9 - Falderal

Update README. Chris Pressey 7 years ago

1 changed file(s) with 35 addition(s) and 22 deletion(s). Raw diff Collapse all Expand all

+35

-22

README.markdown less more

25	25	expected to be a certain, predicted thing, and if it's not that thing, the
26	26	implementation is probably considered incorrect.
27	27
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?
29	29
30	30	You could write a bunch of standalone test sources, and store the output you
31	31	expect from them in a bunch of other files, and write a shell script that runs

36	36	comment syntax of your programming language (if your programming language
37	37	supports comments) and is also detached from all the other test descriptions.
38	38
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
43	39	You could write unit tests in the unit test framework of your choice, but
44	40	if your programming language has more than one implementation one day (and
45	41	you should really consider that possibility) then you might not be able to
46	42	re-use it so easily for other implementations in other languages.
47	43
	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
48	49	Or... you could write a Markdown document with beautiful yet precise prose
49	50	describing your wonderful language, alternating with example code (in the
50	51	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.
54	55
55	56	And you could even write this document before you even start implementing
56	57	your language; then when it is all clear "on paper", you have a target at
57	58	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).
60	62
61	63	Features of the Format
62	64	----------------------

68	70	* Run tests from one or more documents.
69	71	* Report the results, with some given level of detail.
70	72
	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
71	76	Each Falderal test is for some abstract _functionality_, and each
72	77	functionality may have multiple concrete _implementations_. Thus the same
73	78	tests can be run multiple times, once for each implementation of the

75	80
76	81	Directives in the Falderal document may assign functionalities to tests,
77	82	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.
81	86
82	87	Inherent Limitations
83	88	--------------------

98	103	This distribution contains:
99	104
100	105	* `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).
102	108	(Note that this specification should not be expected to remain stable
103	109	through the 0.x version series.) There are other documents in there too.
104	110	* `bin/falderal` — the reference implementation of Falderal, written in

106	112	sources in `src/falderal`. You don't need to install it; just add
107	113	the `bin` directory of this distribution to your `$PATH`. This
108	114	implementation is (somewhat) documented in `doc/py-falderal.markdown`.
	115	* `script` — miscellaneous small tools intended to be used in tests.
109	116	* `src` — source code for py-falderal.
110	117	* `tests` — a set of tests for Falderal itself. (Note that these are not
111	118	written in Falderal, as that would just be too confusing.)

127	134	Projects using Falderal
128	135	-----------------------
129	136
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)
135	150
136	151	Xoomonk, Madison, Velo, and Exanoke are good examples of how a literate
137	152	test suite can be useful in both describing a programming language through
138	153	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
142	155	Language Design (TDLD), where the tests were written as part of designing the
143	156	language, before any attempt at implementation; the others are more like
144	157	traditional test suites, written after-the-fact.