-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.bf
292 lines (241 loc) · 11.3 KB
/
README.bf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
[BF.DOC---EFFECTIVE BRAINFUCK DOCUMENTATION FORMAT
bf.doc is an outcome of a long history of Brainfuck coding, with
incomplete documentation formats and comment conventions. The goals
that bf.doc sets for itself is:
- Being embeddable into any Brainfuck code with little to no effort.
- Being readable yet concise.
- Being intuitive enough to be easily adopted and reproduced.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119 (https://datatracker.ietf.org/doc/html/rfc2119).
[1 HISTORY OF BRAINFUCK DOCUMENTATION FORMATS
[1.1 DOCUMENTATION FILES
Brainfuck programmers often neglect creating separate documentation
files, using inline commentaries and comment loops instead. Daniel
B. Christofani has gone as far as to write complex Brainfuck files
in a literate programming style, with code and documentation for it
interleaved together. This style puts too much restrictions on the
prose, in particular by removing all the dots, hyphens, and commas
critical to one's understanding of written text.]
[1.2 COMMENTS
Brainfuck code comments are the first (and, possibly the main) type
of documentation that Brainfuck codebases had. Many comment
syntaxes were conjured in the absence of a standardized one:
[ comment loop ]
======Urban Muller's syntax======
********** Clive Gifford's syntax **********
// C-like syntax
/* C89-like syntax */
; Lisp/asm-like syntax
Absence of syntax altogether
* Brian Raiter's syntax
# sh-like syntax
Most of those, with the notable exception of comment loop, were
qute restrictive in what type of characters can be used, with
Brainfuck command characters (+-<>,.[]) and debug characters (!#)
being impossible to use.
Because of comment loops being almost unrestricted in their syntax,
they gained a certain use, especially as a header/footer comments
documenting the general program structure, behavior, and
copyright.]
[1.3 MEMORY LAYOUTS
Because there appeared a way to describe program structure and
memory use in program comments, there appeared ways to represent
memory layouts in those, with varying levels of verboseness and
expressiveness (see https://github.com/rdebath/Brainfuck for most
of these examples):
= = = = = = = = = = = =
u r b a n m u l l e r
= = = = = = = = = = = =
|i|n|t|u|i|t|i|v|e|
... D a n 'i' e l ... B ... 'C' h r '1' s t 0 f 'a' n i ...
___________________________________________________
|m |a |k |s |i |m | |K |o |r |z |h |/ |d |b|f |i |
[r,e,s,0,0,0,1]
=== J a m e s result=Stanley ===
{u n/k*n o%w n w/i t*h o/p/e r a*t i%o*n s}
cell #1=Justice, cell #2=Suh
Out of those, most are only usable inside comment loops, with the
notable exception of res0001 syntax being a comment loop
itself. Syntax of Daniel B Christofani is inspiring in how it
separates cell integer values (0), char values ('a'), and sequences
of cells (...).]
[1.4 CHARACTER ENCODINGS
Only two significant character encodings emerged:
Spelled out characters: 3 plus 5 minus 8
Parenthesised spelled out characters: 3 (plus) 5 (minus) 8 (dot)]
[1.5 MEMORY POINTERS
Two concise pointer representations appeared:
'cell
^cell
Both are good enough, but using apostrophes interferes with
character representation seen in Daniel B Christofani's code.]]
[2 BF.DOC
bf.doc, inspired by the long history of Brainfuck documentation
syntaxes, synthesizes the most reasonable of the syntaxes for code
comments and memory layouts.
[2.1 DOCUMENTATION FILES
bf.doc-conformant documentation files MUST be written a one big
nested comment loop, with the (all caps) title of the file
following the opening bracket, and (all caps) (sub)section headings
following their respective opening brackets with section numbers
prepended to them. Section numbers are 1-indexed and there is no
whitespace between the section opening bracket and section
number. Closing brackets SHOULD follow the last word of the
(sub)section, and, if the (sub)section is the last in the
document/section/subsection, then closing brackets of those SHOULD
compound together. A small example:
[bf.doc:
[TITLE
..
[1 SECTION ONE
...
[1.1 SUBSECTION ONE POINT ONE
...]
[1.2 SUBSECTION ONE POINT TWO
...]]
[2 SECTION TWO
...]]]
Note that this document is bf.doc conformant too, so you can use it
as an example.
[2.1.1 ENUMERATIONS AND NESTED LISTS IN DOCUMENTATION FILES
It's often the case that one needs to enumerate certain values or
list certain points when documenting the software. In such cases,
the most intuitive hyphen-space unordered list (or number-indexed
ordered list) syntax is to be used:
- This is the first-level item. Hyphen+space starting marker.
- This is another first-level item, but spilling into next line:
Notice next line indented the same level as the non-list text.
-- Second-level item: two hyphens.
-- Second-level item long enough to spill over to the next line:
Notice the zero indentation again.
--- Third-level.
---- Fourth-level.
- Et cetera.
[2.1.1.1 ORDERED/NUMBERED LISTS
Unordered lists are only useful for small drafts and chaotic
notes (which is not to say these are useless, but...) Ordered
lists are more linkable and structured. These lists allow one to
refer to a certain point with a clear numeric label, which,
augmented by the section number, provides a robust way of linking
to list elements. So the syntax of the ordered lists in bf.doc is:
.1 Ordered lists start from 1.
.2 They should normally have the dot before the number.
3 Hovever, this dot can be dropped for readability.
2.1.1.1.4 This dot is an abbreviation for the section-qualified
item number.
.5 Notice the zero indentation above---same as for unordered lists.
.6 Having the number, one can expand it to the full
section-qualified reference, like 2.1.1.1.6, and use it to refer
to the list item from outside the document.
.7 Ordered lists can be nested, much like unordered lists---the
child item number is just get an index based on the parent item
index:
.7.1 This nested item has a parent item index suffixed by a
nested item index (1-indexed).
7.2 Parent elements' leading dot can be omitted, but other
elements beyond it MUST NOT be omitted.
Having the ordered lists spelled out, one can enjoy much more
coherent documentation with more normative reference links to
point others to.
For the documentation writer/reader/referencer convenience,
unordered list can be implicitly ordered for greater linkability:
- This unordered list is numbered as .8 (due to previous list
ending in .7).
- This one is .9.
-- This is .9.1 (nested ordered 1-indexed list)]
See the example of the real nested lists in the next section.]]
[2.2 COMMENT SYNTAX & ENCODING
Comments conforming to bf.doc are to follow these rules:
- All comments (and all the Brainfuck file text at that) MUST be
lowercase 7-bit ASCII text.
-- In case one needs non-ASCII text in the file, a proper ASCII
encoding should be used, like ArmSCII for Armenian or Romaji for
Japanese.
- File-level comment MUST belong to a comment loop, conventional
for other BF codebases.
- Block-level comments SHOULD precede the block.
-- OPTIONALLY, end those with a colon to indicate that what follows
is a block (akin to Python block syntax.)
-- Loop header comments SHOULD follow the opening bracket.
--- Closing bracket SHOULD have the exact same comment, but with
"ends" appended to it, as in
[bf:
[ main loop
->
] main loop ends]
- Line-level comments MUST directly follow the code.
- Line-level comments (be it loop headers, block comments, or line comments)
SHOULD start with a space, separating them from the commands.
- Comments SHOULD always end with a newline. Comment and code
SHOULD NOT be mixed unless direly needed.
Comments documenting lines/blocks with cell initialization or
modification SHOULD list the value in that cell as either of:
- A numeric value in parentheses.
-- As decimal number.
-- Or as hexadecimal number (that MUST be prefixed with an
unambiguous prefix like "0x", "x", "h", or or hash sign).
-- Or any other base given (MUST have an unambiguous base
indication).
- A display char corresponding to it, in single quotes.
-- For control characters, the display char is OPTIONAL.
-- For non-graphic characters, an existing C-like escape sequence
like '\n' MAY be used.
- An unambiguous spelled out name.
- For characters that might be interpreted as commands, an encoding
below SHOULD be used.
Comments MUST use spelled out encoding without parentheses and with
spaces between the encoded character and surrounding text. The list
of characters to encode is:
- '+' -> plus
- '-' -> minus
- ',' -> comma
- '.' -> dot, period
- '<' -> less than, lt
- '>' -> greater than, gt
- '['/']' -> opening bracket/closing bracket
- '#' -> hash
- '!' -> bang, exclamation mark
For example:
[bf:
[-] empty the cell (taken from https://whatever minus website dot com)]]
[2.3 CODE/VERBATIM BLOCKS
All code/verbatim blocks MUST be wrapped into a comment loop of
their own, with the language/type of code as the loop header, with
no space between the comment loop opening bracket and the
language/type marker. For example:
[bf:
+[>+]]
Such a convention ensures that all the elements of the code block
are self-contained and clear about which language/format they are
written in.]
[2.4 MEMORY LAYOUTS
Given the complexity of memory layouts that should be represented,
bf.doc adopts an exhaustive memory representation syntax that MUST
be followed in program/library documentation:
- [0] : a cell with a numeric value equal to the number.
- ['a'] : a cell with a value equal to the char.
- [a] : a cell with a variable in it.
- [...] : an arbitrary sequence of cells with whatever (unimportant) values.
- [x...] : a variable holding a sequence of null-terminated cells (a string).
- [^d] : a cell with the pointer on it.
- [^x...] : a sequence of cells (string) with the pointer in the beginning.
- [x^...] : a sequence of cells (string) with the pointer in the end.
- [x...^] : ditto.
In the cases where it's obvious that cell values are characters,
it's possible to omit the single quotes, as in
[h][e][l][l][o] == ['h']['e']['l']['l']['o']
In the cases where it's obvious that a bracketed sequence is a
sequence of characters, one can list all the characters in a single
set of brackets without single quotes or only using single/double
quotes around the sequence contents:
[hello]
== ["hello"]
== ['hello']
== [h][e][l][l][o]
== ['h']['e']['l']['l']['o']
This syntax is quite similar to Daniel B Cristofani one, but wraps
all cells into square brackets. Because of this, memory layout
schemes can appear inline in the code as part of or instead of
comment loops.]]]