Markus Mottl avatar Markus Mottl committed 3b63170

Added documentation for the new record field syntax extensions

Comments (0)

Files changed (2)

base/sexplib/README

       {
         x : int option;
         y : int sexp_option;
-      }
+      } with sexp
 >>
   
   The type 'sexp_option' is equivalent to ordinary options, but is treated
 similar to the type 'sexp_option'. They assume the empty list, empty array,
 and false value respectively as default values.
   
+  More complex default values can be specified explicitly using several
+constructs, e.g.:
+<<  let z_test v = v > 42
+  
+    type t =
+      {
+        x : int with default(42);
+        y : int with default(3), sexp_drop_default;
+        z : int with default(3), sexp_drop_if(z_test);
+      } with sexp
+>>
+  
+  The 'default' record field extension above is supported by the underlying
+preprocessor library 'type_conv' and specifies the intended default value for
+a record field in its argument. Sexplib will use this information to generate
+code which will set this record field to the default value if an S-expression
+omits this field. If a record is converted to an S-expression, record fields
+with default values will be emitted as usual. Specifying 'sexp_drop_default'
+will add a test for polymorphic equality to the generated code such that a
+record field containing its default value will be suppressed in the resulting
+S-expression. This option requires the presence of a default value.
+'sexp_drop_if' on the other hand does not require a default. Its argument must
+be a function, which will receive the current record value. If the result of
+this function is 'true', then the record field will be suppressed in the
+resulting S-expression.
+  
+  The above extensions can be quite creatively used together with manifest
+types, functors, and first-class modules to make the emission of record fields
+or the definition of their default values configurable at runtime.
+  
 
 4.7  Conversion of sum types
 ============================

base/sexplib/doc/README.tex

     {
       x : int option;
       y : int sexp_option;
-    }
+    } with sexp
 \end{verbatim}
 
 The type \verb=sexp_option= is equivalent to ordinary options, but is
 \\
 The types \verb=sexp_list=, \verb=sexp_array=, and \verb=sexp_bool= can be
 used in ways similar to the type \verb=sexp_option=.  They assume the empty
-list, empty array, and false value respectively as default values.
+list, empty array, and false value respectively as default values.\\
+\\
+More complex default values can be specified explicitly using several
+constructs, e.g.:
+
+\begin{verbatim}
+  let z_test v = v > 42
+
+  type t =
+    {
+      x : int with default(42);
+      y : int with default(3), sexp_drop_default;
+      z : int with default(3), sexp_drop_if(z_test);
+    } with sexp
+\end{verbatim}
+
+\noindent The \verb=default= record field extension above is supported by the
+underlying preprocessor library \verb=type_conv= and specifies the intended
+default value for a record field in its argument.  Sexplib will use this
+information to generate code which will set this record field to the default
+value if an S-expression omits this field.  If a record is converted to an
+S-expression, record fields with default values will be emitted as usual.
+Specifying \verb=sexp_drop_default= will add a test for polymorphic equality
+to the generated code such that a record field containing its default value
+will be suppressed in the resulting S-expression.  This option requires the
+presence of a default value.  \verb=sexp_drop_if= on the other hand does
+not require a default.  Its argument must be a function, which will receive
+the current record value.  If the result of this function is \verb=true=,
+then the record field will be suppressed in the resulting S-expression.\\
+\\
+The above extensions can be quite creatively used together with manifest
+types, functors, and first-class modules to make the emission of record
+fields or the definition of their default values configurable at runtime.
 
 \subsection{Conversion of sum types}
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.