git @ Cat's Eye Technologies Falderal / c3dfb87
Update README for release of version 0.1. catseye 9 years ago
3 changed file(s) with 32 addition(s) and 127 deletion(s). Raw diff Collapse all Expand all
+32
-55
README.text less more
00 Falderal
11 ========
2
3 Falderal is a framework for writing, running, and formatting "doctest"-like
4 literate test suites for Haskell functions. It is particularly suited for
5 testing and documenting functions which interpret or compile programming
6 languages -- especially esoteric ones.
27
38 Here's the situation:
49
510 * You have a Haskell program, formatted in literate Haskell.
611 * You have some Haskell functions which take Strings to Strings.
7 * You have some unit tests for those functions that you want to
8 include them in the literate Haskell source in a nicely readable
9 fashion.
10 * You want to be able to optionally treat the literate Haskell
11 source as being in Markdown format, to convert it to HTML, etc.
12 * You have some unit tests for those functions that you want to present in
13 a nicely readable fashion, possibly included right in the literate Haskell
14 source.
1215
13 If this describes you, then Falderal might help. The particular need
14 I had that encouraged me to write it is having implemented several
16 If this describes you, then Falderal might help. The particular need I had
17 that encouraged me to write it is having implemented several esoteric
1518 programming languages in Haskell, and wanting to write nicely formatted
1619 tests suites for them.
1720
18 How to Use it
19 -------------
21 Current Version
22 ---------------
2023
21 * Write a literate Haskell program as usual.
22 * Define a section for each function you want to test. Delimit
23 the section just as you would with Markdown.
24 * In that section, write whatever text you like describing the
25 tests. Generally, you would preface each test with text revelant
26 to it; this text will be output if the test fails.
27 * Write a test by prefixing each line of input with a | character in
28 the first column, and prefixing each line of output with a = character.
29 For example,
24 The current version of Falderal is 0.1. The API should not be expected to
25 be stable through the 0.x series, however Test.Falderal.Runner.run is not
26 expected to change its type signature (it takes a "property list" of options,
27 although no options are currently honoured.)
3028
31 | 2+2
32 = 4
29 Development
30 -----------
3331
34 * If you expect your test to fail, you can include the name of an
35 exception to expect, prefixed with a ? character, instead of
36 expected output. For example,
32 Falderal development is hosted on BitBucket:
3733
38 | 1/0
39 ? DivideByZeroError
34 https://bitbucket.org/catseye/falderal/
4035
41 * Write a driver for the tests. The driver can be included in the
42 selfsame literate Haskell file, or it can be located elsewhere.
43 It will typically set up some configuration, then call one of the
44 Falderal test runners. The main piece of configuration to set up
45 is a mapping between section names and the functions that are to be
46 tested in those sections. How and when your driver is called is
47 up to you.
48 * Optionally, preprocess your literate Haskell source with the included
49 script before sending it through Markdown to help it come out the
50 other end nicely.
36 Bugs may be reported (and features requested) on the Issue Tracker:
5137
52 TODO
53 ----
38 https://bitbucket.org/catseye/falderal/issues
5439
55 * Equivalency tests: for testing functions of type
40 Official release distfiles may at some point be available through Falderal's
41 project page on Cat's Eye Technologies' website:
5642
57 (Eq a) => String -> a
58
59 The idea is that you give multiple input strings in a set; if the
60 function does not map them all to the same value, that's a test
61 failure.
62 * Test monadic functions somehow.
63 * Expand on the previous point to test external programs via
64 Unix subprocesses; after all, Unix programs are more or less
65 functions from Strings to Strings. In other words, (ab)use
66 Falderal as a kind of shunit variant.
67 * There is no hard-and-fast requirement to use Markdown. I originally
68 considered it because its syntax for blockquotes coincides with
69 literate Haskell's syntax for code; however, when I tried it with
70 Burro, preprocessing was still desirable anyway, and with preprocessing,
71 just about any markup format could be used for the literal text.
72 The markup format could be specified in the Haskell source, and the
73 formatting process could be driven by a function call.
43 http://catseye.tc/project/falderal/
44
45 For Further Information
46 -----------------------
47
48 Please see the Falderal wiki on BitBucket:
49
50 https://bitbucket.org/catseye/falderal/wiki/
+0
-55
script/make.pl less more
0 #!/usr/bin/perl -w
1
2 $title = "The Burro Programming Language, v2.0";
3 $lhs_input = "../src/Burro.lhs";
4 $lhs_temp = "lhs.tmp";
5 $html_temp = "html.tmp";
6 $html_output = "burro.html";
7
8 open INFILE, "<$lhs_input";
9 open OUTFILE, ">$lhs_temp";
10
11 while (defined ($line = <INFILE>)) {
12 chomp $line;
13 if ($line =~ /^\>(.*?)coding\:(.*?)$/) {
14 # pass
15 } elsif ($line =~ /^\>(.*?)$/) {
16 print OUTFILE " $1\n";
17 } else {
18 $line =~ s/\s\-\-\s/ \&mdash\; /g;
19 print OUTFILE "$line\n";
20 }
21 }
22
23 close INFILE;
24 close OUTFILE;
25
26 system "Markdown.pl <$lhs_temp >$html_temp";
27
28 open INFILE, "<$html_temp";
29 open OUTFILE, ">$html_output";
30
31 print OUTFILE <<"EOH";
32 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
33 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
34 <head>
35 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
36 <title>$title</title>
37 <link rel="stylesheet" type="text/css" href="markdown-lhs.css" />
38 </head>
39 <body>
40 EOH
41
42 while (defined ($line = <INFILE>)) {
43 print OUTFILE $line;
44 }
45
46 print OUTFILE <<"EOF";
47 </body>
48 </html>
49 EOF
50
51 close INFILE;
52 close OUTFILE;
53
54 system "rm *.tmp";
+0
-17
script/markdown-lhs.css less more
0 blockquote {
1 font-family: monospace;
2 white-space: pre;
3 border-style: solid;
4 border-width: 1px;
5 border-color: black;
6 padding-left: 3em;
7 }
8
9 pre {
10 border-style: solid;
11 border-width: 1px;
12 border-color: black;
13 padding-left: 3em;
14 padding-top: 1em;
15 padding-bottom: 1em;
16 }