New Package: A minimal configuration variable (CFV) file format
Posted: 11-11-2026I just published a new package called CFV to Hackage. This is a parser for configuration files that contain variable declarations. Typically, developing web apps requires connecting to various services that require configuration settings that may change based on the stage of development. Furthermore, these settings might require access tokens and other fields that can change. Good software engineering says we shouldn’t just hardcode these.
I know, I know, you are thinking that I just described DotEnv files. Well,
basically yes, but DotEnv files and their libraries that parse them also assume
you want to load them into your environment variables, but I don’t always want
that. In addition, there are not many features supported by DotEnv files that
help us prevent common problems with using files of this style. Lastly, I want
to have more than just one .env file.
So I decided to write my own file format for dealing with declaring
configuration variables for my developments. Before discussing the features,
here is a simple example of a project_awesome.cfv file:
-- Configuration Settings for Project Awesome
stage = "development"; -- Toggle for development stage
today = `date -I`; -- Today's date in YYYY-MM-DD
-- Access token for our super secret backend
secret access_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkphbmUgRG9lIiwiaWF0IjoxNzYyODY5NTAwLCJleHAiOjE3NjI4NzMxMDB9.Zm9yLWRlbW8tcHVycG9zZXMtb25seS1ub3QtYS1yZWFsLXNpZ25hdHVyZQ';
Comments can occur anywhere and use Haskell’s single-line comment syntax. Then there are two types of variable declarations:
- Public variable declarations are declared with no attribute.
- Secret variable declarations are declared with the
secretattribute. This attribute is kept after parsing, so that these can be treated specially, because the user considers them to be sensitive.
Then a variable can be declared using the syntax:
name = "...";andname = '..';declare strings. You can also escape nested quotes if needed.name =`cmd`;declares a variablenamewhose value is the output of the shell commandcmdwhen it is run in the users login shell. By default it is ran in$SHELL, but a custom shell configuration can be supplied to the parser. Running the command in the login shell gives them access to the users$PATH.
The main parts of the API are:
Parsing can be carried out using:
parseCfvFile :: FilePath -> IO (Either CfvError [Binding]) parseCfvFileWith :: ShellConfig -> FilePath -> IO (Either CfvError [Binding])The former uses the default shell configuration, and the latter allows the programmer to specify a custom shell configuration. The result of both of these is either
[Binding]or aCfvError. The latter can be converted into a human readableTextusing:renderCfvError :: CfvError -> TextA
Bindingis:type VarName = Text type VarValue = Text newtype Var = Var VarAttr VarValue type Binding = (VarName,Var)where
VarNameis the variables name,Varis a pair of the variables attribute,SecretorPublic, and aVarValuethe fully evaluated value of the variable asText.To prevent accidentally leaking secrets in logs and such the default
Showinstance forBindingreplaces the values of secret variables with(). So running show on the list of bindings fromproject_awesome.cfvfrom above produces:[("stage", Public "development"), ("today", Public "2026-11-11"), ("access_token", Secret ())]
That’s it! I plan to add various features to this as I go. Here are a few I have in mind:
Some basic types, numbers, and dates
Sum types for type safe toggles rather than booleans. This will give us some validation before just injecting them into our developments.
Name spaces for settings. I’m not sure how this will look yet, but basically a record for settings. This allows having multiple groups of settings in the same file, and provides some organization.
PRs welcome!