fix: better defined & documented .env and ENV_VAR support

.env

@@ -1,6 +1,10 @@
-TIMEZONE="US/Central" # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-DATE_FORMAT="+%F" # YYYY-MM-DD ISO 8601 😎
-SITE_URL="http://localhost:3000"
-SITE_AUTHOR="bic"
-SITE_TITLE="bic site"
-SALT="bic"
+# All defaults should exist at runtime e.g. `${MY_VARIABLE:-default value}`
+# This file is mostly being kept around for historical significance, but
+# perhaps in the future I'll want to embed e.g. a version or something
+
+# TIMEZONE="US/Central" # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+# DATE_FORMAT="+%F" # YYYY-MM-DD ISO 8601 😎
+# SITE_URL="http://localhost:3000"
+# SITE_AUTHOR="bic"
+# SITE_TITLE="bic site"
+# SALT="bic"

bic

@@ -77,7 +77,7 @@ mk_slug() {
 }
 
 mk_date() {
-  TZ="${TIMEZONE}" date -r "${1}" "${DATE_FORMAT}"
+  TZ="${TIMEZONE:-US/Central}" date -r "${1}" "${DATE_FORMAT:-+%F}"
 }
 
 mk_id() {
@@ -283,20 +283,24 @@ build() {
   log "Using source directory: ${SRC_DIR}"
   [[ -n "${BIC_OVERWRITE:-}" ]] && set +o noclobber && log "Disabled 'noclobber' redirection overwrite protection"
 
-  # pre-req check: what's missing and do we need to bail?
+  # File system: what's missing and do we need to bail?
   [[ -d "${SRC_DIR}"/pages && -f "${SRC_DIR}"/page.html  ]] || warn "pages/ + page.html for pages"
   [[ -d "${SRC_DIR}"/posts && -f "${SRC_DIR}"/entry.html ]] || warn "posts/ + entry.html for posts"
   [[ -f "${SRC_DIR}"/index.html && -f "${SRC_DIR}"/__index.html ]]  || fatal "index.html (and __index.html) required"
-  [[ -f "${SRC_DIR}"/feed.rss   && -f "${SRC_DIR}"/__feed.rss ]]    || warn "feed.rss (and __feed.rss) isn't required, but you likely want it"
-  [[ -f "${SRC_DIR}"/sitemap.xml ]] || warn "sitemap.xml isn't required, but you likely want it"
-  [[ -f "${SRC_DIR}"/robots.txt ]]  || warn "robots.txt isn't required, but you likely want it"
+  [[ -f "${SRC_DIR}"/feed.rss   && -f "${SRC_DIR}"/__feed.rss ]]    || warn "feed.rss (and __feed.rss) for an RSS feed"
+  [[ -f "${SRC_DIR}"/sitemap.xml ]] || warn "sitemap.xml for a sitemap for search engines"
+  [[ -f "${SRC_DIR}"/robots.txt ]]  || warn "robots.txt for web crawlers"
+
+  # Environment: anything not set that probably should be?
+  [[ -n "${SITE_AUTHOR:-}" ]] || warn "\$SITE_AUTHOR not set"
+  SITE_AUTHOR="$(html_escape "${SITE_AUTHOR:-}")"
+  [[ -n "${SITE_TITLE:-}" ]] || warn "\$SITE_TITLE not set"
+  SITE_TITLE="$(html_escape "${SITE_TITLE:-}")"
+  [[ -n "${SITE_URL:-}" ]] || warn "\$SITE_URL not set"
 
   [[ -d "${DEST_DIR}" ]] && rm -rf "${DEST_DIR}"
   mkdir -p "${DEST_DIR}" && log "Created build directory: ${DEST_DIR}"
 
-  SITE_AUTHOR="$(html_escape "${SITE_AUTHOR}")"
-  SITE_TITLE="$(html_escape "${SITE_TITLE}")"
-
   build_pages   # side effect(s): $ALL_PAGES
   build_posts   # side effect(s): $ALL_POSTS
   build_drafts  # side effect(s): $ALL_DRAFTS

docs/index.md

@@ -98,21 +98,37 @@ $ tree -F --dirsfirst
 
 ## Config
 
-`bic` uses an `.env` pattern. This lets you configure required variables and add
+`bic` uses an `.env` pattern. This lets you configure ~~required~~ variables and add
 any extras that can be used within your templates. Talk about batteries included.
 
-Required config (you'll have a bad time with the defaults):
+A `.env.` file simply contains lines of `KEY=value` pairs. See the HOWTO for
+advanced usage.
 
+<details>
+  <summary>HOWTO: override config at runtime</summary>
+
+  If you, for whatever reason, want to supply an environment variable at
+  runtime _and_ have it override your `.env` then use syntax such like:
+
+  ```bash
+  ENV_VAR="${ENV_VAR:-default value}"
+  ```
+
+</details>
+
+Not-100%-required but highly-recommended config:
+
+- `SITE_AUTHOR` e.g. `Captain Anonymous` (the site's author)
 - `SITE_TITLE` e.g., `My Cool Thing` (the site's title)
 - `SITE_URL` e.g., `https://domain.tld` (the site's full base URL with _no_ trailing slash)
-- `TIMEZONE` e.g., `US/Central` (the [timezone] you're in)
-- `SALT` e.g. `super-random-abcxyz` (used to seed the [Hashids] encoding)
 
-Optional, but you may want to change:
+Optional, change if needed:
 
-- `DATE_FORMAT` e.g., `+%B %d, %Y` (passed into `date`, default: `+%F` &rarr; `YYYY-MM-DD`)
-- `BUILD_DIR` e.g., `_site` (configure output directory, default: `build`)
 - `BIC_OVERWRITE` (disable file overwrite protection, see [#caveats](#caveats), default: unset)
+- `BUILD_DIR` e.g., `_site` (configure output directory, default: `build`)
+- `DATE_FORMAT` e.g., `+%B %d, %Y` (passed into `date`, default: `+%F` &rarr; `YYYY-MM-DD`)
+- `SALT` e.g. `super-random-abcxyz` (used to seed the [Hashids] encoding, default: `bic`)
+- `TIMEZONE` e.g., `US/Central` (the [timezone] you're in, default: `US/Central`)
 
 ## Templating
 

tests/.env-defaults/.env

@@ -0,0 +1 @@
+FOO="${FOO:-bar}"

tests/.env-defaults/index.html

@@ -0,0 +1 @@
+{{FOO}}

tests/.env/.env

@@ -0,0 +1 @@
+FUNKY=monkey

tests/.env/index.html

@@ -0,0 +1 @@
+{{FUNKY}}

tests/env-var/feed.rss

@@ -0,0 +1 @@
+{{SITE_URL}}

tests/test.bats

@@ -106,3 +106,38 @@
   rm -rf tests/id/build
   [[ ! -d tests/id/build ]]
 }
+
+@test "bic uses custom .env files" {
+  run ./bic tests/.env
+  [[ "${status}" == 0 ]]
+  run cat tests/.env/build/index.html
+  [[ "${lines[0]}" == "monkey" ]]
+  rm -rf tests/.env/build
+  [[ ! -d tests/.env/build ]]
+}
+
+@test "bic uses runtime ENV_VAR=values" {
+  SITE_URL='http://domain.tld' run ./bic tests/env-var
+  [[ "${status}" == 0 ]]
+  run cat tests/env-var/build/feed.rss
+  [[ "${lines[0]}" == "http://domain.tld" ]]
+  rm -rf tests/env-var/build
+  [[ ! -d tests/env-var/build ]]
+}
+
+@test "bic allows for overridable .env" {
+  run ./bic tests/.env-defaults
+  [[ "${status}" == 0 ]]
+  run cat tests/.env-defaults/build/index.html
+  [[ "${lines[0]}" == "bar" ]]
+  rm -rf tests/.env-defaults/build
+  [[ ! -d tests/.env-defaults/build ]]
+
+  # run again, this time supplying a runtime defiition of the env var
+  FOO=baz run ./bic tests/.env-defaults
+  [[ "${status}" == 0 ]]
+  run cat tests/.env-defaults/build/index.html
+  [[ "${lines[0]}" == "baz" ]]
+  rm -rf tests/.env-defaults/build
+  [[ ! -d tests/.env-defaults/build ]]
+}