nixos/doc/manual/from_md/configuration/abstractions.section.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-module-abstractions">
  <title>Abstractions</title>
  <para>
    If you find yourself repeating yourself over and over, it’s time to
    abstract. Take, for instance, this Apache HTTP Server configuration:
  </para>
  <programlisting language="bash">
{
  services.httpd.virtualHosts =
    { &quot;blog.example.org&quot; = {
        documentRoot = &quot;/webroot/blog.example.org&quot;;
        adminAddr = &quot;alice@example.org&quot;;
        forceSSL = true;
        enableACME = true;
        enablePHP = true;
      };
      &quot;wiki.example.org&quot; = {
        documentRoot = &quot;/webroot/wiki.example.org&quot;;
        adminAddr = &quot;alice@example.org&quot;;
        forceSSL = true;
        enableACME = true;
        enablePHP = true;
      };
    };
}
</programlisting>
  <para>
    It defines two virtual hosts with nearly identical configuration;
    the only difference is the document root directories. To prevent
    this duplication, we can use a <literal>let</literal>:
  </para>
  <programlisting language="bash">
let
  commonConfig =
    { adminAddr = &quot;alice@example.org&quot;;
      forceSSL = true;
      enableACME = true;
    };
in
{
  services.httpd.virtualHosts =
    { &quot;blog.example.org&quot; = (commonConfig // { documentRoot = &quot;/webroot/blog.example.org&quot;; });
      &quot;wiki.example.org&quot; = (commonConfig // { documentRoot = &quot;/webroot/wiki.example.com&quot;; });
    };
}
</programlisting>
  <para>
    The <literal>let commonConfig = ...</literal> defines a variable
    named <literal>commonConfig</literal>. The <literal>//</literal>
    operator merges two attribute sets, so the configuration of the
    second virtual host is the set <literal>commonConfig</literal>
    extended with the document root option.
  </para>
  <para>
    You can write a <literal>let</literal> wherever an expression is
    allowed. Thus, you also could have written:
  </para>
  <programlisting language="bash">
{
  services.httpd.virtualHosts =
    let commonConfig = ...; in
    { &quot;blog.example.org&quot; = (commonConfig // { ... })
      &quot;wiki.example.org&quot; = (commonConfig // { ... })
    };
}
</programlisting>
  <para>
    but not <literal>{ let commonConfig = ...; in ...; }</literal> since
    attributes (as opposed to attribute values) are not expressions.
  </para>
  <para>
    <emphasis role="strong">Functions</emphasis> provide another method
    of abstraction. For instance, suppose that we want to generate lots
    of different virtual hosts, all with identical configuration except
    for the document root. This can be done as follows:
  </para>
  <programlisting language="bash">
{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = webroot:
        { documentRoot = webroot;
          adminAddr = &quot;alice@example.org&quot;;
          forceSSL = true;
          enableACME = true;
        };
    in
      { &quot;example.org&quot; = (makeVirtualHost &quot;/webroot/example.org&quot;);
        &quot;example.com&quot; = (makeVirtualHost &quot;/webroot/example.com&quot;);
        &quot;example.gov&quot; = (makeVirtualHost &quot;/webroot/example.gov&quot;);
        &quot;example.nl&quot; = (makeVirtualHost &quot;/webroot/example.nl&quot;);
      };
}
</programlisting>
  <para>
    Here, <literal>makeVirtualHost</literal> is a function that takes a
    single argument <literal>webroot</literal> and returns the
    configuration for a virtual host. That function is then called for
    several names to produce the list of virtual host configurations.
  </para>
</section>