git @ Cat's Eye Technologies Falderal / 7129128
Some edits to the `py-falderal` doc. Chris Pressey 9 years ago
1 changed file(s) with 48 addition(s) and 49 deletion(s). Raw diff Collapse all Expand all
+48
-49
doc/py-falderal.markdown less more
55 Motivation
66 ----------
77
8 There are a few reasons I had for re-implementing Falderal in Python:
8 The original reference implementation of Falderal was written in Haskell.
9 There are a few reasons I had for re-implementing it in Python:
910
1011 * The original Falderal implementation grew out of a Haskell-specific hack,
11 and it shows in how it's written.
12 and it showed in how it was written.
1213
1314 * Fewer discrepancies between platforms. In particular, `ghc` for Windows
1415 likes to operate in terms of MS-DOS end-of-lines (`CR`, `LF`), but I tend
2930 can then analyze), instead of just saying something pithy like `Prelude:
3031 empty list` (which I can't.)
3132
32 * Any standard worth its salt should probably have more than one
33 implementation, anyway. (Although, to be fair, the Haskell implementation
34 will probably wither in bitrot for a while before simply being forgotten.)
35
3633 Features
3734 --------
3835
39 That last point notwithstanding, `py-falderal` implements a slightly different
40 subset of the Falderal test file format than the Haskell implementation does.
36 `py-falderal` implements a slightly different subset of the
37 [Falderal Literate Test Format](Falderal_Literate_Test_Format.markdown) than
38 the Haskell implementation did.
4139
4240 In particular,
4341
44 * It mainly implements `shell command` implementations. In practice, partly
45 due to the "strict & deep" evaluation problem mentioned above, that's how
46 I've been using Falderal anyway; also, its approach makes it somewhat more
47 useful for "end-to-end" testing of compilers and interpreters, than for
48 unit-testing individual text-processing functions inside a program.
49 (Technically, it implements `Haskell function` implementations too, but it's
50 something of a hack that uses `ghc -e`.)
42 * It mainly implements `shell command` implementations. In practice, partly
43 due to the "strict & deep" evaluation problem mentioned above, that's how
44 I've been using Falderal anyway; also, its approach makes it somewhat more
45 useful for "end-to-end" testing of compilers and interpreters, than for
46 unit-testing individual text-processing functions inside a program.
47 (Technically, it implements `Haskell function` implementations too, but it's
48 something of a hack that uses `ghc -e`.)
5149
52 * I plan for it to *only* understand indented Falderal blocks. The idea is
53 that the Falderal tests will almost certainly be embedded in a Markdown
54 document (possibly with Bird-style literate code also embedded therein,)
55 and no extra processing should be required to format something readable
56 from that Markdown. The four-space-indented Falderal blocks come out as
57 preformatted blocks, which is quite good enough. Relatedly,
50 * I plan for it to *only* understand indented Falderal blocks. The idea is
51 that the Falderal tests will almost certainly be embedded in a Markdown
52 document (possibly with Bird-style literate code also embedded therein,)
53 and no extra processing should be required to format something readable
54 from that Markdown. The four-space-indented Falderal blocks come out as
55 preformatted blocks, which is quite good enough. Relatedly,
5856
59 * It does no formatting. There are a set of classes for parsing Falderal
60 files (`Document`s) into blocks (`Block`s), and methods for formatting
61 blocks into text. But aside from reporting the results of a test run,
62 they're not used by the utility to format Falderal files. If you want to
63 do extra processing on your Falderal/Markdown file so that Falderal
64 blocks are prettier, you certainly can do that, but you'll need to write
65 your own script which uses these classes, for it is outside the scope of
66 `py-falderal`.
57 * It does no formatting. There are a set of classes for parsing Falderal
58 files (`Document`s) into blocks (`Block`s), and methods for formatting
59 blocks into text. But aside from reporting the results of a test run,
60 they're not used by the utility to format Falderal files. If you want to
61 do extra processing on your Falderal/Markdown file so that Falderal
62 blocks are prettier, you certainly can do that, but you'll need to write
63 your own script which uses these classes, for it is outside the scope of
64 `py-falderal`.
6765
68 * I'm not so sure about `-> Functionality "blah" is implemented by shell
69 command "flargh"` anymore. I mean, it should certainly be the case that
70 functionalities can have multiple implementations, but
71 * Perhaps implementations should not be specified in Falderal documents
72 at all — that approach is more abstract. But it requires them to be
73 specified on the tool's command line, which in practice requires there
74 to be a driver script to run the tests, for a particular implementation;
75 but this is not necessarily a bad thing. (The effective practice has
76 been, actually, to write out a bit of "configuration Markdown" with
77 that "Functionality is implemented by" snippet in it, and to load that
78 before loading the main tests. Rather than to configure the functionality
79 implementation(s) on the command line itself.)
80 * When `falderal` is run on more than one input file, what is the scope
81 of a functionality, and what is the scope of the implementations of a
82 functionality? Currently, in the Falderal semantics, that scope is
83 global, and maybe that is appropriate; but maybe finer-grained control
84 would be nice.
66 * I'm not so sure about `-> Functionality "blah" is implemented by shell
67 command "flargh"` anymore. I mean, it should certainly be the case that
68 functionalities can have multiple implementations, but
69
70 * Perhaps implementations should not be specified in Falderal documents
71 at all — that approach is more abstract. But it requires them to be
72 specified on the tool's command line, which in practice requires there
73 to be a driver script to run the tests, for a particular implementation;
74 but this is not necessarily a bad thing. (The effective practice has
75 been, actually, to write out a bit of "configuration Markdown" with
76 that "Functionality is implemented by" snippet in it, and to load that
77 before loading the main tests. Rather than to configure the functionality
78 implementation(s) on the command line itself.)
79 * When `falderal` is run on more than one input file, what is the scope
80 of a functionality, and what is the scope of the implementations of a
81 functionality? Currently, in the Falderal semantics, that scope is
82 global, and maybe that is appropriate; but maybe finer-grained control
83 would be nice.
8584
86 * `py-falderal` also does not try to optimize the test runs into a block of
87 test runs (which didn't work out so well in the Haskell implementation,
88 for `shell command`s, anyway.)
85 * `py-falderal` also does not try to optimize the test runs into a block of
86 test runs (which didn't work out so well in the Haskell implementation,
87 for `shell command`s, anyway.)