pyrox.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 <emphasis>not</emphasis> be printed.
31 </para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term>
36 <varname>msg</varname>
37 </term>
38 <listitem>
39 <para>
40 Message to print.
41 </para>
42 </listitem>
43 </varlistentry>
44 </variablelist>
45
46 <example xml:id="function-library-lib.asserts.assertMsg-example-false">
47 <title>Printing when the predicate is false</title>
48<programlisting><![CDATA[
49assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
50stderr> trace: foo is not bar, silly
51stderr> assert failed
52]]></programlisting>
53 </example>
54 </section>
55
56 <section xml:id="function-library-lib.asserts.assertOneOf">
57 <title><function>lib.asserts.assertOneOf</function></title>
58
59 <subtitle><literal>assertOneOf :: String -> String ->
60 StringList -> Bool</literal>
61 </subtitle>
62
63 <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
64
65 <para>
66 Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. Useful for checking enums.
67 </para>
68
69 <variablelist>
70 <varlistentry>
71 <term>
72 <varname>name</varname>
73 </term>
74 <listitem>
75 <para>
76 The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message.
77 </para>
78 </listitem>
79 </varlistentry>
80 <varlistentry>
81 <term>
82 <varname>val</varname>
83 </term>
84 <listitem>
85 <para>
86 The value of what the user provided, to be compared against the values in <varname>xs</varname>.
87 </para>
88 </listitem>
89 </varlistentry>
90 <varlistentry>
91 <term>
92 <varname>xs</varname>
93 </term>
94 <listitem>
95 <para>
96 The list of valid values.
97 </para>
98 </listitem>
99 </varlistentry>
100 </variablelist>
101
102 <example xml:id="function-library-lib.asserts.assertOneOf-example">
103 <title>Ensuring a user provided a possible value</title>
104<programlisting><![CDATA[
105let sslLibrary = "bearssl";
106in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ];
107=> false
108stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
109 ]]></programlisting>
110 </example>
111 </section>
112</section>