Add shell-style variable interpolation with $VAR and ${VAR} syntax

Author: chgeuer

lib/envious.ex

@@ -47,6 +47,9 @@ defmodule Envious do
   - `{:ok, map}` on success, where map contains the parsed key-value pairs
   - `{:error, message}` on failure, with a descriptive error message including line/column info
 
+  Variable interpolation is supported using `$VAR` or `${VAR}` syntax in values.
+  Variables are resolved using previously defined variables in the file (top-down).
+
   ## Examples
 
       iex> Envious.parse("PORT=3000")
@@ -55,14 +58,19 @@ defmodule Envious do
       iex> Envious.parse("export API_KEY=secret\\nDATABASE_URL=postgres://localhost")
       {:ok, %{"API_KEY" => "secret", "DATABASE_URL" => "postgres://localhost"}}
 
+      iex> Envious.parse("A=foo\\nB=$A-bar")
+      {:ok, %{"A" => "foo", "B" => "foo-bar"}}
+
       iex> Envious.parse("KEY=\\"unclosed")
       {:error, "Parse error at line 1, column 5: could not parse remaining input"}
   """
   def parse(str) do
     case Parser.parse(str) do
       # Success with all input consumed
       {:ok, parsed, "", _context, _line, _offset} ->
-        {:ok, Map.new(parsed)}
+        # Build the map while resolving variable interpolations
+        result = build_env_map(parsed)
+        {:ok, result}
 
       # Success but with remaining unparsed input - this is an error
       {:ok, _parsed, remaining, _context, {line, col}, _offset} when remaining != "" ->
@@ -80,6 +88,27 @@ defmodule Envious do
     end
   end
 
+  # Build environment map from parsed tuples, resolving variable interpolations
+  # Variables are resolved in order, so later variables can reference earlier ones
+  defp build_env_map(parsed) do
+    Enum.reduce(parsed, %{}, fn {key, value}, acc ->
+      resolved_value = resolve_interpolations(value, acc)
+      Map.put(acc, key, resolved_value)
+    end)
+  end
+
+  # Resolve variable interpolations in a value using the accumulated environment
+  # Only resolves specially-marked interpolations from the parser, not literal $VAR in the input
+  defp resolve_interpolations(value, env) when is_binary(value) do
+    # Replace our special markers with actual variable values
+    # Format: __ENVIOUS_VAR__[varname]__
+    Regex.replace(~r/__ENVIOUS_VAR__\[([^\]]+)\]__/, value, fn _, var_name ->
+      Map.get(env, var_name, "")
+    end)
+  end
+
+  defp resolve_interpolations(value, _env), do: value
+
   @doc """
   Parse a .env file string into a map, raising on error.
 

lib/envious/parser.ex

@@ -137,33 +137,51 @@ defmodule Envious.Parser do
       ?]..?~
     ])
 
-  # Content inside double quotes: either escape sequences or regular characters
+  # Variable interpolation: $VAR or ${VAR}
+  # Returns the variable name tagged for later interpolation
+  var_interpolation =
+    choice([
+      # ${VAR} format - capture just the variable name
+      ignore(string("${"))
+      |> concat(var_name)
+      |> ignore(string("}"))
+      |> tag(:var_interp),
+      # $VAR format - capture just the variable name
+      ignore(string("$"))
+      |> concat(var_name)
+      |> tag(:var_interp)
+    ])
+
+  # Content inside double quotes: escape sequences, variable interpolation, or regular characters
+  # Double quotes allow variable interpolation (like shell behavior)
   double_quoted_content =
     choice([
+      var_interpolation,
       escape_sequence,
       double_quoted_regular_char
     ])
 
   # Content inside single quotes: either escape sequences or regular characters
+  # Single quotes do NOT allow variable interpolation (like shell behavior)
   single_quoted_content =
     choice([
       escape_sequence,
       single_quoted_regular_char
     ])
 
-  # Double-quoted value: "value with spaces"
-  # - Handles escape sequences and regular characters
-  # - Post-processes to convert escape sequences to actual characters
+  # Double-quoted value: "value with spaces and $VAR interpolation"
+  # - Handles escape sequences, variable interpolation, and regular characters
+  # - Post-processes to build string with interpolations resolved
   double_quoted_value =
     ignore(double_quote)
     |> times(double_quoted_content, min: 0)
     |> ignore(double_quote)
-    |> reduce({List, :to_string, []})
-    |> post_traverse(:process_escape_sequences)
+    |> post_traverse(:build_quoted_value)
 
-  # Single-quoted value: 'value with spaces'
+  # Single-quoted value: 'value with spaces, no interpolation'
   # - Handles escape sequences and regular characters
   # - Post-processes to convert escape sequences to actual characters
+  # - Does NOT support variable interpolation (like shell behavior)
   single_quoted_value =
     ignore(single_quote)
     |> times(single_quoted_content, min: 0)
@@ -175,29 +193,39 @@ defmodule Envious.Parser do
   # - Newline (\n) and carriage return (\r) - these end the value
   # - Hash (#) - this starts an inline comment
   # - Quotes (" and ') - these start quoted values
+  # - Dollar ($) - this starts variable interpolation
+  # - Brace ({, }) - reserved for ${VAR} syntax
   #
   # Character ranges:
   # - ?\s..?! is space (0x20) through exclamation (0x21), excluding double-quote (0x22)
-  # - ?$..?& is dollar through ampersand, excluding hash (0x23) and single-quote (0x27)
-  # - ?(..?~ is open-paren through tilde - includes alphanumeric and symbols
+  # - ?%..?& is percent through ampersand, excluding hash (0x23) and single-quote (0x27)
+  # - ?(..?z is open-paren through lowercase z, excluding braces ({ and })
+  # - ?|..?~ is pipe through tilde
   unquoted_value_char =
     utf8_char([
       # Space (32) through exclamation (33), which excludes double-quote (34)
       ?\s..?!,
-      # Dollar (36) through ampersand (38), which excludes hash (35) and single-quote (39)
-      ?$..?&,
-      # Open-paren (40) through tilde (126) - includes all alphanumeric and symbols
-      ?(..?~
+      # Percent (37) through ampersand (38), which excludes hash (35), dollar (36), and single-quote (39)
+      ?%..?&,
+      # Open-paren (40) through lowercase z (122), which excludes left-brace (123)
+      ?(..?z,
+      # Pipe (124) through tilde (126), which excludes right-brace (125)
+      ?|..?~
     ])
 
-  # Unquoted value: traditional unquoted values
-  # - Collect 0 or more value characters (allows empty values like KEY=)
-  # - Convert the character list to a string
-  # - Trim whitespace from both ends (handles inline comments: "value # comment")
+  # Unquoted value content: either variable interpolation or regular characters
+  unquoted_value_content =
+    choice([
+      var_interpolation,
+      unquoted_value_char
+    ])
+
+  # Unquoted value: supports variable interpolation
+  # - Collect 0 or more value parts (allows empty values like KEY=)
+  # - Post-process to trim whitespace (handles inline comments: "value # comment")
   unquoted_value =
-    times(unquoted_value_char, min: 0)
-    |> reduce({List, :to_string, []})
-    |> post_traverse(:trim_value)
+    times(unquoted_value_content, min: 0)
+    |> post_traverse(:build_unquoted_value)
 
   # Parse the value portion after the = sign
   # Values can be:
@@ -274,28 +302,73 @@ defmodule Envious.Parser do
   defp not_line_terminator(<<?\r, _::binary>>, context, _, _), do: {:halt, context}
   defp not_line_terminator(_, context, _, _), do: {:cont, context}
 
-  # Post-traversal callback to trim whitespace from parsed values
+  # Post-traversal callback to build a quoted value with variable interpolation support
   #
-  # This is used to remove trailing whitespace before inline comments.
-  # Example: "value  # comment" becomes "value"
+  # Takes the accumulated tokens (which may include :var_interp tags and character codes)
+  # and builds a single string value. Variable interpolations are left as markers
+  # to be resolved later by the main Envious module.
   #
   # Parameters:
   # - rest: Remaining input after parsing
-  # - [value]: The parsed value (as a single-element list from the accumulator)
+  # - acc: Accumulated tokens from the quoted value
   # - context: Parser context
   # - _line, _offset: Position information (unused)
   #
-  # Returns: {rest, [trimmed_value], context}
+  # Returns: {rest, [string_value], context}
+  defp build_quoted_value(rest, acc, context, _line, _offset) do
+    # Reverse the accumulator and build the string
+    value = acc |> Enum.reverse() |> build_value_string([])
+    {rest, [value], context}
+  end
+
+  # Post-traversal callback to build an unquoted value with variable interpolation support
+  #
+  # Similar to build_quoted_value but also trims whitespace.
   #
-  # Note: We must return `rest` (not an empty list) to allow the parser to
-  # continue processing remaining input. Returning [] would consume all input.
-  defp trim_value(rest, [value], context, _line, _offset) when is_binary(value) do
-    {rest, [String.trim(value)], context}
+  # Parameters:
+  # - rest: Remaining input after parsing
+  # - acc: Accumulated tokens from the unquoted value
+  # - context: Parser context
+  # - _line, _offset: Position information (unused)
+  #
+  # Returns: {rest, [string_value], context}
+  defp build_unquoted_value(rest, acc, context, _line, _offset) do
+    # Reverse the accumulator and build the string, then trim
+    value = acc |> Enum.reverse() |> build_value_string([]) |> String.trim()
+    {rest, [value], context}
   end
 
-  # Fallback clause for trim_value when accumulator doesn't match expected pattern
-  defp trim_value(rest, acc, context, _line, _offset) do
-    {rest, acc, context}
+  # Build a string from a list of tokens, handling variable interpolations
+  # Tokens can be:
+  # - Integers (character codes)
+  # - {:var_interp, [var_name]} tuples representing variable interpolations
+  # Returns a string with interpolation markers using a special syntax that won't conflict with user input
+  defp build_value_string([], acc) do
+    acc
+    |> Enum.reverse()
+    |> IO.iodata_to_binary()
+    |> process_escapes_in_string([])
+    |> IO.iodata_to_binary()
+  end
+
+  defp build_value_string([{:var_interp, [var_name]} | rest], acc) when is_binary(var_name) do
+    # Use a special marker that won't conflict with normal .env content
+    # Format: __ENVIOUS_VAR__[varname]__
+    build_value_string(rest, ["__ENVIOUS_VAR__[#{var_name}]__" | acc])
+  end
+
+  defp build_value_string([char | rest], acc) when is_integer(char) do
+    build_value_string(rest, [<<char::utf8>> | acc])
+  end
+
+  defp build_value_string([other | rest], acc) do
+    # Handle any other tokens (shouldn't normally happen)
+    build_value_string(rest, [to_string(other) | acc])
+  end
+
+  # Process escape sequences in a string (for values that support them)
+  defp process_escapes_in_string(binary, acc) when is_binary(binary) do
+    process_escapes(binary, acc)
   end
 
   # Post-traversal callback to convert [value, key] list to {key, value} tuple

test/envious/parser_test.exs

@@ -42,4 +42,89 @@ defmodule Envious.ParserTest do
     assert Parser.parse(file) ==
              {:ok, [{"FOO", "bar"}, {"BAZ", "qux"}], "", %{}, {4, 61}, 61}
   end
+
+  test "variable interpolation with ${VAR} in double quotes" do
+    file = """
+    export A="foo"
+    export B="bar and ${A}"
+    """
+
+    # Parser just parses - interpolation happens in Envious module
+    result = Envious.parse(file)
+    assert result == {:ok, %{"A" => "foo", "B" => "bar and foo"}}
+  end
+
+  test "variable interpolation with $VAR in double quotes" do
+    file = """
+    A=hello
+    B="world and $A"
+    """
+
+    result = Envious.parse(file)
+    assert result == {:ok, %{"A" => "hello", "B" => "world and hello"}}
+  end
+
+  test "variable interpolation in unquoted values" do
+    file = """
+    export A=foo
+    export B=bar-$A-baz
+    """
+
+    result = Envious.parse(file)
+    assert result == {:ok, %{"A" => "foo", "B" => "bar-foo-baz"}}
+  end
+
+  test "mixed variable interpolation formats" do
+    file = """
+    export A="A"
+    export B="B and ${A} or $A"
+    """
+
+    result = Envious.parse(file)
+    assert result == {:ok, %{"A" => "A", "B" => "B and A or A"}}
+  end
+
+  test "variable interpolation with undefined variable" do
+    file = """
+    B="value is $UNDEFINED"
+    """
+
+    result = Envious.parse(file)
+    # Undefined variables resolve to empty string
+    assert result == {:ok, %{"B" => "value is "}}
+  end
+
+  test "single quotes do not interpolate variables" do
+    file = """
+    A=foo
+    B='$A is not interpolated'
+    """
+
+    result = Envious.parse(file)
+    assert result == {:ok, %{"A" => "foo", "B" => "$A is not interpolated"}}
+  end
+
+  test "multiple interpolations in one value" do
+    file = """
+    A=hello
+    B=world
+    C="$A $B from ${A} and ${B}"
+    """
+
+    result = Envious.parse(file)
+
+    assert result ==
+             {:ok, %{"A" => "hello", "B" => "world", "C" => "hello world from hello and world"}}
+  end
+
+  test "chained variable interpolation" do
+    file = """
+    A=foo
+    B=$A-bar
+    C=$B-baz
+    """
+
+    result = Envious.parse(file)
+    assert result == {:ok, %{"A" => "foo", "B" => "foo-bar", "C" => "foo-bar-baz"}}
+  end
 end