env

By Goblin Docs ~ 8 min read

:env reads an environment variable by name and returns its value as a string.

Overview

:env takes a single string argument — the name of the environment variable — and returns its value.

Note

The intrinsic (colon) prefix : is optional to denote that you are using a built-in action (rather than a user-created one). It is optional, but you may find it helpful. All Goblin docs use this prefix in our code snippets.

See more on this here: Intrinsic Prefix

Try this in the REPL:

gbln(1): :env("HOME")
/Users/yourname
gbln(2): :env("DOES_NOT_EXIST")

gbln(3): :env("DOES_NOT_EXIST") == ""
true

gbln(1): :env("HOME")
/Users/yourname
gbln(2): :env("DOES_NOT_EXIST")

gbln(3): :env("DOES_NOT_EXIST") == ""
true

Basic Usage

Read a variable

port | :env("PORT")

port | :env("PORT")

With a fallback

Important

:env returns an empty string "" when the variable is not set — not nil. Use an explicit empty string check if you need a fallback.

port | :env("PORT")
if port == ""
    port |= "4242"
xx

port | :env("PORT")
if port == ""
    port |= "4242"
xx

Or use :trim to normalize and check in one step:

port | :trim(:env("PORT"))
if port == ""
    port |= "4242"
xx

port | :trim(:env("PORT"))
if port == ""
    port |= "4242"
xx

Reading Goblin Host Variables

When a Goblin script is invoked by the host, several variables are set automatically:

query  | :trim(:env("GOBLIN_QUERY_STRING"))
method | :env("GOBLIN_METHOD")
body   | :env("GOBLIN_BODY")

query  | :trim(:env("GOBLIN_QUERY_STRING"))
method | :env("GOBLIN_METHOD")
body   | :env("GOBLIN_BODY")

Variable	Description
`GOBLIN_QUERY_STRING`	Query string passed by the host
`GOBLIN_METHOD`	HTTP method (`GET`, `POST`, etc.)
`GOBLIN_BODY`	Raw request body
`GOBLIN_NONINTERACTIVE`	Set to `1` when running non-interactively

Errors

:env raises a runtime error if you pass a non-string argument:

:env(42)
/// error: T0205 type-mismatch: env expects a string (variable name)

:env(42)
/// error: T0205 type-mismatch: env expects a string (variable name)

It raises a wrong-arity error if called with anything other than exactly one argument:

:env("A", "B")
/// error: R0301 wrong-arity: expected 1, got 2

:env("A", "B")
/// error: R0301 wrong-arity: expected 1, got 2