Skip to content
This repository was archived by the owner on Apr 12, 2021. It is now read-only.
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: NixOS/nixpkgs-channels
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: 4e73b76ede45
Choose a base ref
...
head repository: NixOS/nixpkgs-channels
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 131cb302abb4
Choose a head ref
  • 1 commit
  • 5 files changed
  • 1 contributor

Commits on Oct 5, 2018

  1. nixpkgs: Start documenting library functions in XML 

    Covers assert functions and about half of the attrsets functions.

Some internal consistency around IDs could be improved.

(cherry picked from commit f835f77)
    @grahamc
    grahamc committed Oct 5, 2018
    Copy the full SHA
    131cb30 View commit details
Showing with 1,069 additions and 1 deletion.
  1. +1 −1 doc/Makefile
  2. +2 −0 doc/functions.xml
  3. +15 −0 doc/functions/library.xml
  4. +113 −0 doc/functions/library/asserts.xml
  5. +938 −0 doc/functions/library/attrsets.xml
2 changes: 1 addition & 1 deletion doc/Makefile
View file
Original file line number Diff line number Diff line change
@@ -69,7 +69,7 @@ highlightjs:
cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/


manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml
manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml

.version:
2 changes: 2 additions & 0 deletions doc/functions.xml
View file
Original file line number Diff line number Diff line change
@@ -7,6 +7,8 @@
The nixpkgs repository has several utility functions to manipulate Nix
expressions.
</para>

<xi:include href="functions/library.xml" />
<xi:include href="functions/overrides.xml" />
<xi:include href="functions/generators.xml" />
<xi:include href="functions/debug.xml" />
15 changes: 15 additions & 0 deletions doc/functions/library.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<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">
<title>Nixpkgs Library Functions</title>

<para>
Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or
through <code>import &lt;nixpkgs/lib&gt;</code>.
</para>

<xi:include href="./library/asserts.xml" />

<xi:include href="./library/attrsets.xml" />
</section>
113 changes: 113 additions & 0 deletions doc/functions/library/asserts.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
<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>

<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>

<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>
Loading