Allow to provide the initial `Iter` substitution map

[noirbizarre]

Hi 👋🏼

Would it be possible to allow providing the initial Iter.substitution_data ?

As of today, fields are private and it's not possible to provide some initial substitution.

Use case: Sometimes you need to parse a dotenv file, but you need some substitution to be considered without modifying the environment. I had this case multiple times, sometimes it was to set the environment variables before load the dotenv file, but I have cases where I can't.

If this feature is acceptable to you, I might give a try to implementing it.

(Unless there is already this capability or another alternative I am not aware of)

[allan2]

I'd like to understand this better. Can you provide an example?

[noirbizarre]

Let say I want to parse a dotenv file, but I want ${APP_VAR} to be substituted without it existing in the environment because I only load the file in the context of my app, but I don't actually modify the environment.
I read a bit the main code today, so with the new API I would like to be able to write something like this:

let mut app_env = HashMap::new();
app_env.insert("APP_VAR", "value");
app_env.insert("APP_OTHER_VAR", "other-value");
let env = EnvLoader::with_vars(app_env).load()

To parse a dotenv file like this

# This var should resolve into value-something
MY_VAR=${APP_VAR}-something
OTHER=${VAR_FROM_THE_ACTUAL_ENV}

So it's just the ability to set some variables before parsing so they can properly be substituted like if they were in the environment (or they would overwrite it if some with the same name already exist in the environment)

[allan2]

I don't wish to make substitution_data public, but what you want can still be achieved like so:

use std::io::Cursor;

use dotenvy::{EnvLoader, EnvSequence};

fn main() -> Result<(), dotenvy::Error> {
    // Read from a string (or a file reader).
    let s = "FOO=def\nFOO_SUBBED=${FOO}123";
    let cursor = Cursor::new(s.as_bytes());
    let map1 = EnvLoader::with_reader(cursor)
        .sequence(EnvSequence::InputOnly)
        .load()?;

    // Read from the actual environment.
    let mut map2 = EnvLoader::new().sequence(EnvSequence::EnvOnly).load()?;

    // Add keys from map1 to map2, replacing values for existing keys.
    map2.extend(map1);

    println!("{}", map2.get("FOO").unwrap());  // def
    println!("{}", map2.get("FOO_SUBBED").unwrap());  // should be def123
    Ok(())
}

This example doesn't actually work because of a bug in substitution with the new API (#150). But besides that, the new API should cover your use case. Let me know your thoughts.

[noirbizarre]

No, it doesn't work: if any variable in the dotenv file (the 2nd load) is referencing FOO or FOO_SUBBED, they will be replaced by an empty string, unless you modify the environment when loading map1, which I can't.
For your example to reflect my cases, you should have the .env containing something like BAR=${FOO}-from-file, then you'll see that BAR=-from-file while reading map2.

It prevent 2 use cases I have:

• providing variables not in the environment for interpolation
• referencing variables from a dotenv file into another without modifying the environment

As of today, the only workaround I have found is concatenating all the variables and the dotenv files into a single dotenv file then load it with dotenvy, which hit the performances and seems overly complicated while I could provide the hashmap I already have as initial substitution.

My need is not to make substitution_data public, but to have a way to provide initial data for interpolation (the with_vars() in my example).

[noirbizarre]

Actually, the workaround isn't fully working on mise (works fine on my other project which is simpler).
So if this is OK for you, I'd like to submit a pull-request to add this.

[allan2]

This should be resolved when #150 is fixed. I would prefer not to add an additional method such as with_vars unless it is to do something that cannot be done with the current API.

[noirbizarre]

But that's precisely my point in the previous comment: it doesn't work with the current API and #150 won't fix it as the case you describe and are trying to fix is not my case, it only works if you can modify the environment.
The current doesn't allow injecting variables without modifying the environment.

My cases, in their simplest forms are:

1. loading 2 consecutive files with the second referencing some vars from the first, without env modification:

# secrets.env
SOME_SECRET=abcd

# app.env
APP_SECRET=${SOME_SECRET}

The current API doesn't support loading secrets.env then app.env and have substitution working without modifying the actual environment.

2. app expose a APP_VAR and try to load an environment file referencing it, without env modification:

# .env
SOME_VAR=${APP_VAR}-something

The current API doesn't support loading this .env with substitution without injecting APP_VAR in the actual env.

[noirbizarre]

Note: one of the cases is actually an issue I am trying to fix on mise and you can see more context here:

• Environment variables cascading/overriding broken jdx/mise#4688
• fix(env): fix dotenv files cascading (fix #4688) jdx/mise#4996
• Mise 2025.5.1 regression: Failed to parse dotenv file jdx/mise#5008
• fix(dotenv): properly escape values in generated dotenv jdx/mise#5010

[jdx]

+1 to this. If dotenvy doesn't add support for this we will likely need to fork dotenvy for mise.

[allan2]

PRs are welcome for #150, which will resolve this issue.

[jdx]

I don't see how. To be clear what we need is the ability to parse .env files with custom variables passed in that are not related to the process's environment. Simply ignoring the environment doesn't help.