Let’s say you’re writing a web server. You want the server to take a port to listen on, and an application to run. So you create the following function:
run
::
Int
->
Application
->
IO
()
But suddenly you realize that some people will want to customize their timeout durations. So you modify your API:
run
::
Int
->
Int
->
Application
->
IO
()
So, which Int
is the timeout, and which is the port? Well, you could create some type aliases, or comment your code. But there’s another problem creeping into the code: this run
function is getting unmanageable. Soon you’ll need to take an extra parameter to indicate how exceptions should be handled, and then another one to control which host to bind to, and so on.
A more extensible solution is to introduce a settings data type:
data
Settings
=
Settings
{
settingsPort
::
Int
,
settingsHost
::
String
,
settingsTimeout
::
Int
}
And this makes the calling code almost self-documenting:
run
Settings
{
settingsPort
=
8080
,
settingsHost
=
"127.0.0.1"
,
settingsTimeout
=
30
}
myApp
Great—couldn’t be clearer, right? True, but what happens when you have 50 settings to your web server? Do you really want to have to specify all of those each time? Of course not. So instead, the web server should provide a set of defaults:
defaultSettings
=
Settings
3000
"127.0.0.1"
30
And now, instead of needing to write that long bit of code, you can get away with:
run
defaultSettings
{
settingsPort
=
8080
}
myApp
-- (1)
This is great, except for one minor hitch. Let’s say you now decide to add an extra record to Settings
. Any code out in the wild looking like this:
run
(
Settings
8080
"127.0.0.1"
30
)
myApp
-- (2)
will be broken, because the Settings
constructor now takes four arguments. The
proper thing to do would be to bump the major version number so that dependent
packages don’t get broken. But having to change major versions for every minor
setting you add is a nuisance. The solution? Don’t export the Settings
constructor:
module
MyServer
(
Settings
,
settingsPort
,
settingsHost
,
settingsTimeout
,
run
,
defaultSettings
)
where
With this approach, no one can write code like (2), so you can freely add new records without any fear of code breaking.
The one downside of this approach is that it’s not immediately obvious from the Haddocks that you can actually change the settings via record syntax. That’s the point of this chapter: to clarify what’s going on in the libraries that use this technique.
I personally use this technique in a few places—feel free to have a look at the Haddocks to see what I mean:
Warp: Settings
http-conduit
: Request
and ManagerSettings
xml-conduit
Parsing: ParseSettings
Rendering: RenderSettings
As a tangential issue, http-conduit
and xml-conduit
actually create
instances of the Default
typeclass instead of declaring brand new
identifiers. This means you can just type def
instead of
defaultParserSettings
.