dotenv

This package provides a simple Guile interface to .env (or dotenv) files. It implements parsing of files and setting environment variables from them.

Using dotenv

If you just need to load your .env in the current directory:

cat .env
name=value
test=12**@
foo=123#%####1###
last="my-${name}"

you can try this in a REPL:

scheme@(guile-user)> (use-modules (dotenv parser))
scheme@(guile-user)> (load-dotenv)
scheme@(guile-user)> (getenv "name")
$1 = "value"
scheme@(guile-user)> (getenv "test")
$2 = "12**@"
scheme@(guile-user)> (getenv "foo")
$3 = "123#%####1###"
scheme@(guile-user)> (getenv "last")
$4 = "my-${name}"
scheme@(guile-user)>

Notice how last's value has not been substituted with name's. dotenv is able to compute variables values based on previous variables values. To do so just define an empty environment, and pass it to dotenv's public API.

scheme@(guile-user)> (use-modules (ice-9 vlist))
scheme@(guile-user)> (define environment vlist-null)
scheme@(guile-user)> (load-dotenv #:environment environment)
scheme@(guile-user)> (getenv "last")
$5 = "my-value"

Using dotenv CLI

dotenv's command line interface is pretty simple, it mostly exposes the public API through the command line:

$ dotenv
Usage: dotenv [-h]
              [--cmdtree]
              [--usage]
              [--version]

Keywords:
  --cmdtree      
  --help     -h  
  --usage        
  --version      

Subcommands:
  build        Build a dotenv file from a Scheme file evaluating to a list of pairs.
  generate     Generate the automaton needed to parse dotenv files.
  read         Read dotenv files into Scheme code.

You can parse .env files into Scheme code:

$ cat .env                
a=b                                                                                             
c=d
$ dotenv read .env
(("a" . "b") ("c" . "d"))

Or even the reverse: you can convert Scheme list of pairs to .env files:

$ cat ./pairs.scm
'(("1" . 2) ("3" . 4))
$ dotenv build pairs.scm
1=2
3=4

Installing the CLI

You can install the CLI from Guix with:

$ guix install guile-dotenv-cli

(dotenv parser)

This module implements a parser for dotenv files, it exports the following functions:

• dotenv->scm: Parse a dotenv file's content into a list of pairs. Takes a string argument, str, that contains the dotenv file's content. Each of the returned pair represents a mapping defined into the dotenv file: the first element of the pair would be the variable name and the second would be the variable number.
• dotenv-file->scm: Parse a dotenv file into a list of pairs. Takes a string argument, str, that contains the dotenv file name. Each of the returned pair represents a mapping defined into the dotenv file: the first element of the pair would be the variable name and the second would be the variable number.
• load-dotenv: Parse a dotenv file into a list of pairs and load them into the environment as variables. Takes an optional string directory argument that indicates the directory where the dotenv file will be found (defaults to the current directory), and a file-name keyword argument, this argument denotes the name of the dotenv file (defaults to ".env").

scheme@(guile-user)> (dotenv-file->scm ".env")
$4 = (("name" . "value") ("test" . "12**@") ("foo" . "123#%####1###"))

(dotenv builder)

This module implements a serializer for Scheme values to dotenv files, it exports the following functions:

• scm->dotenv: Creates a dotenv file from scm, a list of pairs. Takes one optional argument, port, which defaults to the current output port where the dotenv file will be written. It also takes some keyword arguments: validate? if true, the native value will be validated before starting to print the dotenv file (defaults to #t), true represents the serialization of the #t value (defaults to "true"), false represents the serialization of the #f value(defaults to "false").
• scm->dotenv-string: Creates a dotenv file from scm, a list of pairs, into a string. It also takes some keyword arguments: validate? if true, the native value will be validated before starting to print the dotenv file (defaults to #t), true represents the serialization of the #t value (defaults to "true"), false represents the serialization of the #f value (defaults to "false").

scheme@(guile-user)> ,use(dotenv builder)
scheme@(guile-user)> (define scm
                      '(("name" . "value") ("test" . "12**@") ("foo" . "123#%####1###")))
scheme@(guile-user)> (scm->dotenv-string scm)
$5 = "name=value\ntest=12**@\nfoo=123#%####1###\n"
scheme@(guile-user)> (display (scm->dotenv-string scm))
name=value
test=12**@
foo=123#%####1###

Installing dotenv

Building from source

Guix

To build with Guix you just need the guix command available on your system, then you can run:

guix build -f guix.scm

Autotools

To use autotools you need at least the following dependencies:

• autoconf
• automake
• guile
• make
• pkg-config

then you can run:

autoreconf -vif
./configure
make

In case you want to build the command line interface you also need guile-config.

Guix channel

To configure Guix for using this repository as a channel, you need to create a .config/guix/channels.scm file with the following content:

(cons* (channel
        (name 'dotenv)
        (url "https://codeberg.org/fishinthecalculator/dotenv.git")
        (branch "main")
        ;; Enable signature verification:
        (introduction
         (make-channel-introduction
          "507f28bbda8b1599f48f7039ec51aa9ad51afc17"
          (openpgp-fingerprint
           "8D10 60B9 6BB8 292E 829B  7249 AED4 1CC1 93B7 01E2"))))
       %default-channels)

Otherwise, if you already have a .config/guix/channels.scm you can simply prepend this channel to the preexisting ones:

(cons* (channel
        (name 'dotenv)
        (url "https://codeberg.org/fishinthecalculator/dotenv.git")
        (branch "main")
        ;; Enable signature verification:
        (introduction
         (make-channel-introduction
          "507f28bbda8b1599f48f7039ec51aa9ad51afc17"
          (openpgp-fingerprint
           "8D10 60B9 6BB8 292E 829B  7249 AED4 1CC1 93B7 01E2"))))
       (channel
        (name 'nonguix)
        (url "https://gitlab.com/nonguix/nonguix")
        ;; Enable signature verification:
        (introduction
         (make-channel-introduction
          "897c1a470da759236cc11798f4e0a5f7d4d59fbc"
          (openpgp-fingerprint
           "2A39 3FFF 68F4 EF7A 3D29  12AF 6F51 20A0 22FB B2D5"))))
       %default-channels)

What is a Guix channel?

A channel is roughly the Guix equivalent of the AUR or container registries. It's a software repository providing Guix package and service definitions.

Contributing

All contributions are welcome. If you have commit access please remember to setup the authentication hook with

guix git authenticate --cache-key=channels/dotenv --stats 507f28bbda8b1599f48f7039ec51aa9ad51afc17 "8D10 60B9 6BB8 292E 829B  7249 AED4 1CC1 93B7 01E2"

Licence

Unless otherwise stated all the files in this repository are to be considered under the GPL 3.0 terms. You are more than welcome to open issues or send patches.