<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" "bearssl" ];
=> false
stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
        ]]></programlisting>
  </example>
 </section>
</section>