git @ Cat's Eye Technologies Robin / c86d728
Refactor docs, write about macro as fundamental abstraction. Chris Pressey 5 years ago
5 changed file(s) with 230 addition(s) and 199 deletion(s). Raw diff Collapse all Expand all
+2
-2
HISTORY.md less more
3737
3838 * bigrats. Instead, in Robin 0.2 you get 32-bit signed integers (yes,
3939 precisely those.) Anything else, you have to build.
40 * its module system. Robin has its own, much less hermetic/holistic
41 system. See the file [doc/Modules.md](doc/Modules.md).
40 * its module system. Robin 0.2 has its own, much less hermetic/holistic
41 system.
4242 * concurrency.
4343 * I/O and side-effects. It has reactors instead.
4444 * its grand ambitions. Robin would rather exist than be perfect.
+7
-7
README.md less more
105105 discards from Scheme is its jargony terminology: no `cdr`, no `cons`,
106106 no `lambda`.
107107
108 Further Documentation
109 ---------------------
108 Repository Layout
109 -----------------
110110
111 * [doc/Tutorial.md](doc/Tutorial.md) — Robin tutorial.
112 * [doc/Robin.md](doc/Robin.md) — core language specification.
113 * [doc/Modules.md](doc/Modules.md) — ideas about modules.
114 * [stdlib/](stdlib/) — normative definitions of standard symbols.
115 * [HISTORY.md](HISTORY.md) — history of the language.
111 * bin/ — driver script, destination for executable when built.
112 * src/ — Haskell source for reference interpreter.
113 * [doc/](doc/README.md) — Tutorial, specification, rationale, etc.
114 * stdlib/ — normative definitions of standard library symbols.
115 * [HISTORY.md](HISTORY.md) — history of this distribution.
116116 * [TODO.md](TODO.md) — plans.
117117
118118 [Scheme]: http://schemers.org/
+0
-190
doc/Modules.md less more
0 Robin: Modules
1 ==============
2
3 In this document, "Robin" refers to the Robin programming language
4 version 0.3.
5
6 Robin's module system is this: Robin does not have a module system.
7
8 We're still working this out, so bear with us. Let's start with
9 some fundamental principles of Robin. You may love them or think
10 they are stupid (I can't tell, myself,) but they are what they are.
11
12 * The core Robin language includes only a handful of symbols,
13 called _intrinsics_. These represent functionality that would
14 be impossible or highly impractical to write in Robin itself.
15
16 * A Robin program may, of course, define new symbols internal
17 to that program, by assigning them meanings in its environment.
18
19 * The Robin language expresses Robin programs; it does not
20 express metadata about Robin programs.
21
22 * Corollary: the contents of a Robin program is kept separate
23 from the metadata about that Robin program.
24
25 * Corollary: a Robin program that uses a symbol which is defined
26 outside of that program does not, and in fact _cannot_, care
27 where it is defined.
28
29 * Corollary: dependencies between Robin (sub)programs and/or
30 modules is an implementation-level concern, not a
31 language-level concern.
32
33 * Corollary: how the reference implementation solves the problem
34 of dependencies between Robin programs is not necessarily how
35 any other implementation should solve the problem.
36
37 * ... all the Robin language really "knows" is that a Robin
38 program may be split up into seperate "files" (where "file" means
39 "input of program text into the implementation", I guess.)
40
41 * Robin recognizes a set of symbols, currently called `stdlib`,
42 that (should) have a (relatively) fixed meaning in all Robin
43 programs, whether they are used in any given program or not.
44
45 * Note (that should be elsewhere?): most of the macros defined
46 in `stdlib` are supposed to, intentionally, take a fixed number
47 of arguments for some reason (nominally, to make some kind of
48 future static analysis easier.)
49
50 * It is something like Maslow's hierarchy of needs. Robin's
51 intrinsics make programming possible (*barely* possible —
52 survival-level.) Robin's `stdlib` makes programming liveable.
53 If there was another level, it might make programming pleasant,
54 even.
55
56 Some implications of this setup in practice are:
57
58 * If you distribute a Robin program to someone else, you need to
59 tell them (somehow) what other Robin (sub)programs/modules it
60 depends on.
61
62 * Actually this is hardly different from C, where dependency
63 information is encoded both in `#include`'s and in a `Makefile`
64 or similar, which links in the correct modules. The difference
65 in Robin is simply that there are no `#include`s.
66
67 * Other languages, such as Haskell and Python, try to include
68 all dependency information in the program source code itself.
69 This does away with `Makefile`-type dependency information,
70 but at the cost of entangling programs and metadata about
71 programs into the same files, into the same language grammar.
72
73 * It would be entirely possible to define a "Robin dependency
74 language" which:
75
76 * describes the dependencies between different Robin programs
77 * informs a tool like `make`
78 * uses Robin's syntax
79 * and perhaps even embeds Robin as an embedded language
80 (and thus perhaps appears as a Robin "top-level form")
81
82 ...*but*, the important thing to note is that such a language
83 would *not be Robin itself*.
84
85 * Any symbol in `stdlib` could be implemented in any language
86 whatsoever, as long as the implementation knows what the
87 semantics of the symbol is.
88
89 * To signal that a program requires some symbol to be defined
90 before the program can be considered meaningful, it may
91 assert that the symbol is defined, using the `assert`
92 top-level form.
93
94 The more pragmatic aspect of how the reference implementation
95 currently handles the issue of dependencies between Robin programs,
96 keeping in mind that this is an implementation issue and _not_ a
97 language issue, and thus that the reference implementation is _not_
98 normative in this regard:
99
100 * Each symbol defined in the Robin `stdlib` is written in its own
101 Robin source file in the `stdlib` subdirectory, bundled along
102 with tests for it.
103
104 * All of the symbols in the `stdlib` directory are implemented in
105 Robin. This is because, being a reference implementation, they
106 are "executable specifications" rather than production code.
107 They are supposed to be correct and simple and understandable,
108 rather than performant.
109
110 * Groups of symbols in the `stdlib` are collected into files
111 called "packages", in the `pkg` subdirectory, which are simply
112 concatenations, topologically sorted by dependency, of those
113 individual files in the `stdlib` subdirectory. (These packages
114 are built both by `./build.sh` and `./test.sh`.)
115
116 * The groupings of symbols within a package follow certain themes,
117 but are largely arbitrary, due to the ease with which a
118 particular symbol could be grouped into two different packages
119 by theme, and partly done for the convenience of the test suite,
120 and to make dependencies work out "nicely", so that symbols can
121 be implemented in terms of other symbols.
122
123 * However, this package has the following justification:
124 The package `small` is identified as a fairly minimal set
125 of symbols to make programming tolerable
126 (somewhere between possible and liveable in that "Maslow's
127 hierarchy" analogy.) No symbol in it depends on any symbol
128 defined in any other package; only intrinsics and other symbols
129 in `small`. The functions in the `small` package have also
130 been implemented directly in Haskell, in the reference interpreter.
131
132 Here is a graphical depiction of the "hierarchy" of defined symbols
133 (it's in HTML because it'd be trickier to depict in plain text or
134 Markdown.)
135
136 <table style="border: 1px solid; padding: 1em; margin: 1em">
137 <tr><th>Standard Library</th></tr>
138 <tr><td>
139
140 <p><i>(boolean)</i> and or xor not boolean?</p>
141
142 <p><i>(list)</i> empty? map fold reverse filter find append elem? length index
143 take-while drop-while first rest last prefix? flatten</p>
144
145 <p><i>(alist)</i> lookup extend delete</p>
146
147 <p><i>(env)</i> env? export sandbox unbind unshadow</p>
148
149 <p><i>(arith)</i> abs add &gt; &gt;= &lt; &lt;= multiply divide remainder</p>
150
151 <p><i>(misc)</i> itoa</p>
152
153 <table style="border: 1px solid; padding: 1em; margin: 1em">
154 <tr><th>"Small" Library</th></tr>
155 <tr><td>
156 literal
157 list
158 bind
159 env
160 let
161 choose
162 bind-args
163
164 <table style="border: 1px solid; padding: 1em; margin: 1em">
165 <tr><th>Intrinsics</th></tr>
166 <tr><td>
167 head
168 tail
169 prepend
170 list?
171 symbol?
172 macro?
173 number?
174 equal?
175 subtract
176 sign
177 macro
178 eval
179 if
180 raise
181 catch
182 </td></tr>
183 </table>
184
185 </td></tr>
186 </table>
187
188 </td></tr>
189 </table>
+9
-0
doc/README.md less more
0 Robin Documentation
1 ===================
2
3 * [Robin Tutorial](Tutorial.md)
4 * [Robin Specification](Robin.md)
5 * [Design Goals and Rationale](Rationale.md)
6
7 For normative definitions of the symbols in the standard library,
8 see the definition files in the [stdlib directory](../stdlib/).
+212
-0
doc/Rationale.md less more
0 Robin: Design Goals and Rationale
1 =================================
2
3 In this document, "Robin" refers to the Robin programming language
4 version 0.3.
5
6 Macro as fundamental abstraction
7 --------------------------------
8
9 This is certainly the most unorthodox feature, the one that departs
10 the most from Scheme et al.
11
12 It allows the language to have no "special forms" whatsoever.
13 (Scheme would need at least `define-syntax` if it wanted to define
14 `if`, `set!`, and the other parts of its syntax, as macros.)
15
16 Whether having no special forms whatsoever is advantageous in any
17 way, or not, remains to be seen.
18
19 One thinks it might make analysis of the code simpler — an analyzer
20 doesn't need to know about special forms.
21
22 But, in practice, since everything is a macro, `eval` is called a
23 lot, and `eval` poses a significant problem for analysis.
24
25 Module System
26 -------------
27
28 Robin's module system is this: Robin does not have a module system.
29
30 We're still working this out, so bear with us. Let's start with
31 some fundamental principles of Robin. You may love them or think
32 they are stupid (I can't tell, myself,) but they are what they are.
33
34 * The core Robin language includes only a handful of symbols,
35 called _intrinsics_. These represent functionality that would
36 be impossible or highly impractical to write in Robin itself.
37
38 * A Robin program may, of course, define new symbols internal
39 to that program, by assigning them meanings in its environment.
40
41 * The Robin language expresses Robin programs; it does not
42 express metadata about Robin programs.
43
44 * Corollary: the contents of a Robin program is kept separate
45 from the metadata about that Robin program.
46
47 * Corollary: a Robin program that uses a symbol which is defined
48 outside of that program does not, and in fact _cannot_, care
49 where it is defined.
50
51 * Corollary: dependencies between Robin (sub)programs and/or
52 modules is an implementation-level concern, not a
53 language-level concern.
54
55 * Corollary: how the reference implementation solves the problem
56 of dependencies between Robin programs is not necessarily how
57 any other implementation should solve the problem.
58
59 * ... all the Robin language really "knows" is that a Robin
60 program may be split up into seperate "files" (where "file" means
61 "input of program text into the implementation", I guess.)
62
63 * Robin recognizes a set of symbols, currently called `stdlib`,
64 that (should) have a (relatively) fixed meaning in all Robin
65 programs, whether they are used in any given program or not.
66
67 * Note (that should be elsewhere?): most of the macros defined
68 in `stdlib` are supposed to, intentionally, take a fixed number
69 of arguments for some reason (nominally, to make some kind of
70 future static analysis easier.)
71
72 * It is something like Maslow's hierarchy of needs. Robin's
73 intrinsics make programming possible (*barely* possible —
74 survival-level.) Robin's `stdlib` makes programming liveable.
75 If there was another level, it might make programming pleasant,
76 even.
77
78 Some implications of this setup in practice are:
79
80 * If you distribute a Robin program to someone else, you need to
81 tell them (somehow) what other Robin (sub)programs/modules it
82 depends on.
83
84 * Actually this is hardly different from C, where dependency
85 information is encoded both in `#include`'s and in a `Makefile`
86 or similar, which links in the correct modules. The difference
87 in Robin is simply that there are no `#include`s.
88
89 * Other languages, such as Haskell and Python, try to include
90 all dependency information in the program source code itself.
91 This does away with `Makefile`-type dependency information,
92 but at the cost of entangling programs and metadata about
93 programs into the same files, into the same language grammar.
94
95 * It would be entirely possible to define a "Robin dependency
96 language" which:
97
98 * describes the dependencies between different Robin programs
99 * informs a tool like `make`
100 * uses Robin's syntax
101 * and perhaps even embeds Robin as an embedded language
102 (and thus perhaps appears as a Robin "top-level form")
103
104 ...*but*, the important thing to note is that such a language
105 would *not be Robin itself*.
106
107 * Any symbol in `stdlib` could be implemented in any language
108 whatsoever, as long as the implementation knows what the
109 semantics of the symbol is.
110
111 * To signal that a program requires some symbol to be defined
112 before the program can be considered meaningful, it may
113 assert that the symbol is defined, using the `assert`
114 top-level form.
115
116 The more pragmatic aspect of how the reference implementation
117 currently handles the issue of dependencies between Robin programs,
118 keeping in mind that this is an implementation issue and _not_ a
119 language issue, and thus that the reference implementation is _not_
120 normative in this regard:
121
122 * Each symbol defined in the Robin `stdlib` is written in its own
123 Robin source file in the `stdlib` subdirectory, bundled along
124 with tests for it.
125
126 * All of the symbols in the `stdlib` directory are implemented in
127 Robin. This is because, being a reference implementation, they
128 are "executable specifications" rather than production code.
129 They are supposed to be correct and simple and understandable,
130 rather than performant.
131
132 * Groups of symbols in the `stdlib` are collected into files
133 called "packages", in the `pkg` subdirectory, which are simply
134 concatenations, topologically sorted by dependency, of those
135 individual files in the `stdlib` subdirectory. (These packages
136 are built both by `./build.sh` and `./test.sh`.)
137
138 * The groupings of symbols within a package follow certain themes,
139 but are largely arbitrary, due to the ease with which a
140 particular symbol could be grouped into two different packages
141 by theme, and partly done for the convenience of the test suite,
142 and to make dependencies work out "nicely", so that symbols can
143 be implemented in terms of other symbols.
144
145 * However, this package has the following justification:
146 The package `small` is identified as a fairly minimal set
147 of symbols to make programming tolerable
148 (somewhere between possible and liveable in that "Maslow's
149 hierarchy" analogy.) No symbol in it depends on any symbol
150 defined in any other package; only intrinsics and other symbols
151 in `small`. The functions in the `small` package have also
152 been implemented directly in Haskell, in the reference interpreter.
153
154 Here is a graphical depiction of the "hierarchy" of defined symbols
155 (it's in HTML because it'd be trickier to depict in plain text or
156 Markdown.)
157
158 <table style="border: 1px solid; padding: 1em; margin: 1em">
159 <tr><th>Standard Library</th></tr>
160 <tr><td>
161
162 <p><i>(boolean)</i> and or xor not boolean?</p>
163
164 <p><i>(list)</i> empty? map fold reverse filter find append elem? length index
165 take-while drop-while first rest last prefix? flatten</p>
166
167 <p><i>(alist)</i> lookup extend delete</p>
168
169 <p><i>(env)</i> env? export sandbox unbind unshadow</p>
170
171 <p><i>(arith)</i> abs add &gt; &gt;= &lt; &lt;= multiply divide remainder</p>
172
173 <p><i>(misc)</i> itoa</p>
174
175 <table style="border: 1px solid; padding: 1em; margin: 1em">
176 <tr><th>"Small" Library</th></tr>
177 <tr><td>
178 literal
179 list
180 bind
181 env
182 let
183 choose
184 bind-args
185
186 <table style="border: 1px solid; padding: 1em; margin: 1em">
187 <tr><th>Intrinsics</th></tr>
188 <tr><td>
189 head
190 tail
191 prepend
192 list?
193 symbol?
194 macro?
195 number?
196 equal?
197 subtract
198 sign
199 macro
200 eval
201 if
202 raise
203 catch
204 </td></tr>
205 </table>
206
207 </td></tr>
208 </table>
209
210 </td></tr>
211 </table>