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