diff options
Diffstat (limited to 'doc/functions/library/asserts.xml')
-rw-r--r-- | doc/functions/library/asserts.xml | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml new file mode 100644 index 00000000000..7c94222ef13 --- /dev/null +++ b/doc/functions/library/asserts.xml @@ -0,0 +1,112 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-functions-library-asserts"> + <title>Assert functions</title> + + <section xml:id="function-library-lib.asserts.assertMsg"> + <title><function>lib.asserts.assertMsg</function></title> + + <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" /> + + <para> + Print a trace message if <literal>pred</literal> is false. + </para> + + <para> + Intended to be used to augment asserts with helpful error messages. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + Condition under which the <varname>msg</varname> should <emphasis>not</emphasis> be printed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>msg</varname> + </term> + <listitem> + <para> + Message to print. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.asserts.assertMsg-example-false"> + <title>Printing when the predicate is false</title> +<programlisting><![CDATA[ +assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly" +stderr> trace: foo is not bar, silly +stderr> assert failed +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.asserts.assertOneOf"> + <title><function>lib.asserts.assertOneOf</function></title> + + <subtitle><literal>assertOneOf :: String -> String -> + StringList -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" /> + + <para> + Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. Useful for checking enums. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>val</varname> + </term> + <listitem> + <para> + The value of what the user provided, to be compared against the values in <varname>xs</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>xs</varname> + </term> + <listitem> + <para> + The list of valid values. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.asserts.assertOneOf-example"> + <title>Ensuring a user provided a possible value</title> +<programlisting><![CDATA[ +let sslLibrary = "bearssl"; +in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ]; +=> false +stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl" + ]]></programlisting> + </example> + </section> +</section> |