|
1 |
| - |
| 1 | + |
2 | 2 |
|
3 | 3 | README: library "Sexplib"
|
4 | 4 | *************************
|
5 | 5 | Copyright (C) 2012 Jane Street Holding, LLC (1)
|
6 | 6 | =====================================================
|
7 | 7 | Author: Markus Mottl
|
8 | 8 | ======================
|
9 |
| - New York, 2012-03-20 |
| 9 | + New York, 2012-04-20 |
10 | 10 | ====================
|
11 | 11 |
|
12 | 12 |
|
@@ -138,15 +138,25 @@ using OCamlMakefile just add it to the 'PACKS'-variable.
|
138 | 138 | 4.1 Lexical conventions of S-expression
|
139 | 139 | ========================================
|
140 | 140 |
|
141 |
| - Whitespace, which consists of space, newline, carriage return, horizontal |
142 |
| -tab and form feed, is ignored unless within an OCaml-string, where it is |
143 |
| -treated according to OCaml-conventions. The semicolon introduces comments. |
144 |
| -Comments are ignored, and range up to the next newline character. The left |
145 |
| -parenthesis opens a new list, the right parenthesis closes it again. Lists can |
146 |
| -be empty. The double quote denotes the beginning and end of a string following |
147 |
| -the lexical conventions of OCaml (see OCaml-manual for details). All |
148 |
| -characters other than double quotes, left- and right parentheses, and |
149 |
| -whitespace are considered part of a contiguous string. |
| 141 | + Whitespace, which consists of space, newline, horizontal tab, and form feed, |
| 142 | +is ignored unless within an OCaml-string, where it is treated according to |
| 143 | +OCaml-conventions. The left parenthesis opens a new list, the right one closes |
| 144 | +it again. Lists can be empty. The double quote denotes the beginning and end |
| 145 | +of a string following the lexical conventions of OCaml (see the OCaml-manual |
| 146 | +for details). All characters other than double quotes, left- and right |
| 147 | +parentheses, whitespace, carriage return, and comment-introducing characters |
| 148 | +or sequences (see next paragraph) are considered part of a contiguous string. |
| 149 | + |
| 150 | + A line comment is introduced using a semicolon, which comments out all text |
| 151 | +up to the end of the next newline character. The sequence '%;' introduces an |
| 152 | +S-expression comment. This means that the next S-expression, which must be |
| 153 | +syntactically correct and may be an atom (quoted or unquoted) or list, |
| 154 | +following this two-character sequence will be ignored. Whitespace or other |
| 155 | +comments between this sequence and the subsequent S-expression are ignored. |
| 156 | +Block comments are opened with '#|' and closed with '|#'. They can be nested |
| 157 | +and require that double-quotes within the block balance and contain |
| 158 | +syntactically correct OCaml-strings, similar to quoted atoms. These |
| 159 | +OCaml-strings may contain comment characters without causing parsing problems. |
150 | 160 |
|
151 | 161 |
|
152 | 162 | 4.2 Grammar of S-expressions
|
@@ -222,7 +232,7 @@ which indicates that a record field should be optional. E.g.:
|
222 | 232 | {
|
223 | 233 | x : int option;
|
224 | 234 | y : int sexp_option;
|
225 |
| - } |
| 235 | + } with sexp |
226 | 236 | >>
|
227 | 237 |
|
228 | 238 | The type 'sexp_option' is equivalent to ordinary options, but is treated
|
@@ -263,6 +273,36 @@ field should be defined.
|
263 | 273 | similar to the type 'sexp_option'. They assume the empty list, empty array,
|
264 | 274 | and false value respectively as default values.
|
265 | 275 |
|
| 276 | + More complex default values can be specified explicitly using several |
| 277 | +constructs, e.g.: |
| 278 | +<< let z_test v = v > 42 |
| 279 | + |
| 280 | + type t = |
| 281 | + { |
| 282 | + x : int with default(42); |
| 283 | + y : int with default(3), sexp_drop_default; |
| 284 | + z : int with default(3), sexp_drop_if(z_test); |
| 285 | + } with sexp |
| 286 | +>> |
| 287 | + |
| 288 | + The 'default' record field extension above is supported by the underlying |
| 289 | +preprocessor library 'type_conv' and specifies the intended default value for |
| 290 | +a record field in its argument. Sexplib will use this information to generate |
| 291 | +code which will set this record field to the default value if an S-expression |
| 292 | +omits this field. If a record is converted to an S-expression, record fields |
| 293 | +with default values will be emitted as usual. Specifying 'sexp_drop_default' |
| 294 | +will add a test for polymorphic equality to the generated code such that a |
| 295 | +record field containing its default value will be suppressed in the resulting |
| 296 | +S-expression. This option requires the presence of a default value. |
| 297 | +'sexp_drop_if' on the other hand does not require a default. Its argument must |
| 298 | +be a function, which will receive the current record value. If the result of |
| 299 | +this function is 'true', then the record field will be suppressed in the |
| 300 | +resulting S-expression. |
| 301 | + |
| 302 | + The above extensions can be quite creatively used together with manifest |
| 303 | +types, functors, and first-class modules to make the emission of record fields |
| 304 | +or the definition of their default values configurable at runtime. |
| 305 | + |
266 | 306 |
|
267 | 307 | 4.7 Conversion of sum types
|
268 | 308 | ============================
|
|
0 commit comments