tjh.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 xml:id="sec-functions-library-asserts">
5 <title>Assert functions</title>
6
7 <section xml:id="function-library-lib.asserts.assertMsg">
8 <title><function>lib.asserts.assertMsg</function></title>
9
10 <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
11 </subtitle>
12
13 <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
14
15 <para>
16 Print a trace message if <literal>pred</literal> is false.
17 </para>
18
19 <para>
20 Intended to be used to augment asserts with helpful error messages.
21 </para>
22
23 <variablelist>
24 <varlistentry>
25 <term>
26 <varname>pred</varname>
27 </term>
28 <listitem>
29 <para>
30 Condition under which the <varname>msg</varname> should
31 <emphasis>not</emphasis> be printed.
32 </para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term>
37 <varname>msg</varname>
38 </term>
39 <listitem>
40 <para>
41 Message to print.
42 </para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46
47 <example xml:id="function-library-lib.asserts.assertMsg-example-false">
48 <title>Printing when the predicate is false</title>
49<programlisting><![CDATA[
50assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
51stderr> trace: foo is not bar, silly
52stderr> assert failed
53]]></programlisting>
54 </example>
55 </section>
56
57 <section xml:id="function-library-lib.asserts.assertOneOf">
58 <title><function>lib.asserts.assertOneOf</function></title>
59
60 <subtitle><literal>assertOneOf :: String -> String ->
61 StringList -> Bool</literal>
62 </subtitle>
63
64 <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
65
66 <para>
67 Specialized <function>asserts.assertMsg</function> for checking if
68 <varname>val</varname> is one of the elements of <varname>xs</varname>.
69 Useful for checking enums.
70 </para>
71
72 <variablelist>
73 <varlistentry>
74 <term>
75 <varname>name</varname>
76 </term>
77 <listitem>
78 <para>
79 The name of the variable the user entered <varname>val</varname> into,
80 for inclusion in the error message.
81 </para>
82 </listitem>
83 </varlistentry>
84 <varlistentry>
85 <term>
86 <varname>val</varname>
87 </term>
88 <listitem>
89 <para>
90 The value of what the user provided, to be compared against the values in
91 <varname>xs</varname>.
92 </para>
93 </listitem>
94 </varlistentry>
95 <varlistentry>
96 <term>
97 <varname>xs</varname>
98 </term>
99 <listitem>
100 <para>
101 The list of valid values.
102 </para>
103 </listitem>
104 </varlistentry>
105 </variablelist>
106
107 <example xml:id="function-library-lib.asserts.assertOneOf-example">
108 <title>Ensuring a user provided a possible value</title>
109<programlisting><![CDATA[
110let sslLibrary = "bearssl";
111in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ];
112=> false
113stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
114 ]]></programlisting>
115 </example>
116 </section>
117</section>