git @ Cat's Eye Technologies Beatnik / e76b23f
Describe the tools available in the script/ directory. Chris Pressey 7 years ago
1 changed file(s) with 104 addition(s) and 3 deletion(s). Raw diff Collapse all Expand all
22
33 This is Cat's Eye Technologies' distribution of tools for Cliff L. Biffle's
44 **[Beatnik][]** programming language. This includes an interpreter for Beatnik,
5 some example Beatnik programs, a compiler from a wimpmode dialect called
5 some example Beatnik programs, a compiler from a [wimpmode][] dialect called
66 **Wottasquare**, and various small utilities which can (for example) search a
77 dictionary file for all words with a given Scrabble score.
88
9 Usage information for these tools TBW.
9 All tools are written in Python and located in the `scripts` directory.
10 You may wish to `cd` to this directory to run them, or put this directory
11 on your executable search path.
1012
11 The contents of this repository are in the public domain.
13 beatnik.py
14 ----------
15
16 Basic usage:
17
18 beatnik.py (filename.beatnik|--eval 'Beatnik program source')
19
20 Interprets the Beatnik program in the given source file, or, if the `--eval`
21 flag is given, the Beatnik program in the command line.
22
23 It considers the program to be written in Beatnik at face value. That is to
24 say, it interprets the Beatnik specification as containing no errors, even
25 though the author claims there is an error in it and won't divulge where.
26 Don't expect this interpreter to work on the example programs supplied with
27 the specification.
28
29 There are two bugs/shortcomings that should really be fixed someday:
30
31 * Integers on the stack can be any value supported by Python, rather
32 than limited to the range 0-255.
33 * The instructions that skip back, probably skip back the wrong amount.
34
35 Other than those two things, this interpreter seems to have the same behaviour
36 as Catatonic Porpoise's interpreter. Could use some test cases, though.
37
38 `beatnik.py` also takes a `--debug` flag, which dumps some internal state
39 to standard error as the program is run.
40
41 `beatnik.py` also takes a `--tokenize` flag, which prevents the program
42 from being run, and instead dumps a readable representation of the program
43 to standard output.
44
45 Thus, the following idiom can be used to find out what Scrabble score, and
46 thus what Beatnik instruction, a particular word has.
47
48 $ beatnik.py --tokenize --eval 'Twenty'
49 'Twenty' = 12 (DUP)
50
51 TODO: the dump should really be in Wottasquare format, making this a
52 Beatnik-to-Wottasquare compiler.
53
54 wottasquare.py
55 --------------
56
57 Basic usage:
58
59 wottasquare.py filename.wottasquare
60
61 Reads the Wottasquare program from the given file and compiles it to an
62 equivalent Beatnik program on standard output.
63
64 The Wottasquare language has the same semantics as the Beatnik language,
65 but each token has the form `[n:comment]` where `n` is the Scrabble score,
66 given in decimal, and `comment` is optional, purely descriptive, and ignored
67 by translation tools such as this one.
68
69 Thus, the Wottasquare token `[5]` could be translated to any word which has
70 a Scrabble score of 5, such as `slug`, for use in Beatnik.
71
72 By default, `wottasquare.py` looks in `/usr/share/dict/words` for
73 words to use when translating Wottasquare to Beatnik. TODO: make this
74 dictionary file configurable.
75
76 There are two flags which trigger special behaviour:
77
78 wottasquare.py --find 'number-or-word'
79
80 Shows the Scrabble score of the given word (or treats the given argument as
81 a Scrabble score, if it is numeric,) then dumps, to standard output, 20 words
82 chosen from the dictionary file which have the same Scrabble score as the given
83 word. Examples:
84
85 $ wottasquare.py --find chase
86 10
87 cubits badger gourmet pointers militant acumen engorges rehab fulled bibles bonny wantons motored blasters colossus warder howl colonial mainline frailer
88
89 $ wottasquare.py --find 5
90 5
91 nip rode sitar lisle stilt uteri slug stain stool earls terns cot liter stout lob lab trots lotus altos boo
92
93 The flag `--find-all` works similarly, but dumps _all_ words from the dictionary
94 with the given Scrabble score to standard output.
95
96 make-wottasquare-print.py
97 -------------------------
98
99 Takes a string on the command line and writes, to standard output, a
100 Wottasquare program which, when run, prints that string. It does not produce
101 the most efficient such program.
102
103 This tool was used to generate `eg/hello-world.wottasquare`, which was then
104 translated to Beatnik by `wottasquare.py`, which was then manually formatted
105 and punctuated, with some (maybe 3%) words "adjusted" to make it flow better.
106
107 License
108 -------
109
110 The contents of this repository are in the public domain. See the file
111 UNLICENSE in this directory for more information.
12112
13113 [Beatnik]: http://esolangs.org/wiki/Beatnik
114 [wimpmode]: http://esolangs.org/wiki/Wimpmode