{"id":22288707,"url":"https://github.com/heziode/ada-dotenv","last_synced_at":"2025-07-30T03:35:13.528Z","repository":{"id":95101075,"uuid":"331789757","full_name":"Heziode/ada-dotenv","owner":"Heziode","description":"Loads environment variables from .env for Ada projects.","archived":false,"fork":false,"pushed_at":"2021-01-22T21:03:39.000Z","size":27,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-30T18:38:40.706Z","etag":null,"topics":["ada","alire","dotenv","env","environment-variables"],"latest_commit_sha":null,"homepage":"","language":"Ada","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Heziode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-22T00:12:17.000Z","updated_at":"2025-01-13T22:47:42.000Z","dependencies_parsed_at":"2023-03-09T11:00:17.605Z","dependency_job_id":null,"html_url":"https://github.com/Heziode/ada-dotenv","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heziode%2Fada-dotenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heziode%2Fada-dotenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heziode%2Fada-dotenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heziode%2Fada-dotenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Heziode","download_url":"https://codeload.github.com/Heziode/ada-dotenv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245543426,"owners_count":20632648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ada","alire","dotenv","env","environment-variables"],"created_at":"2024-12-03T17:06:34.401Z","updated_at":"2025-03-25T21:20:06.922Z","avatar_url":"https://github.com/Heziode.png","language":"Ada","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ada-dotenv\n\n\u003e This library is a port of [dotenv](https://github.com/motdotla/dotenv) + [dotenv-expand](https://github.com/motdotla/dotenv-expand) in Ada.\n\nDotenv is a zero-dependency library that loads environment variables from a `.env` file. Storing configuration in the environment separate from code is based on [The Twelve-Factor App](http://12factor.net/config) methodology.\n\n[![Alire](https://img.shields.io/endpoint?style=for-the-badge\u0026url=https://alire.ada.dev/badges/dotenv.json)](https://alire.ada.dev/crates/dotenv)\n[![LICENSE](https://img.shields.io/github/license/heziode/ada-dotenv.svg?style=for-the-badge)](LICENSE)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-white.svg?style=for-the-badge)](https://conventionalcommits.org)\n\n## Install\n\n### Using alire\n\n```bash\nalr with dotenv\n```\n\n### From scratch\n\nFrom the root of your project\n\n```bash\nmkdir lib\ncd lib\ngit clone https://github.com/Heziode/ada-dotenv\n```\n\nAnd add the following to your `.gpr`: `with \"./lib/ada-dotenv/dotenv.gpr\";`\n\n## Usage\n\nAs early as possible in your application, require and configure dotenv.\n\n```ada\nwith Dotenv;\n\n-- … Somewhere in a body\n\nDotenv.Config;\n```\n\n*Note: a way to achieve this is to load environment variable during elaboration. See [example/src/example_3.adb](example/src/example_3.adb)*\n\nCreate a `.env` file in the root directory of your project. Add environment-specific variables on new lines in the form of `NAME=VALUE`.\nFor example:\n\n```dosini\nDB_HOST=localhost\nDB_USER=root\nDB_PASS=s1mpl3\n```\n\nEnvironment variables now has the keys and values you defined in your `.env` file.\n\n```ada\nwith Ada.Environment_Variables;\n\n-- … Somewhere in a body\nAda.Text_IO.Put_Line (\"DB_HOST: \" \u0026 Ada.Environment_Variables.Value (\"DB_HOST\")); -- result: localhost\n```\n\n## Config\n\n`Config` will read your `.env` file, parse the contents, assign it to environment variables.\nAll `Config`, `Config_Overwrite`, `Config_Debug` and `Config_Interpolate` can raise **Ada.Directories.Name_Error** if no valid path found for environment variable file.\n\nThese procedures can take several parameters, like **Overwrite**, **Debug**, **Interpolation**, **Path**, **File_Form**. See [dotenv.ads](./src/dotenv.ads) for more details.\n\n### Options\n\n#### Path\n\nEnvironment Variable: `DOTENV_CONFIG_PATH`\n\nDefault: `\"\"`\n\nYou may specify a custom path if your file containing environment variables is located elsewhere.\n\n```ada\nDotenv.Config(Path =\u003e \"/custom/path/to/.env\");\n```\n\nIf no **Path** provided, the configuration try to solve the name in the following order:\n\n- If **DOTENV_CONFIG_PATH** environment variable is set, it use it\n- Find a `.env` file in the current working directory\n- Find a `.env` file in the execution directory\n\n#### File_Form\n\nEnvironment Variable: `DOTENV_CONFIG_FILE_FORM`\n\nDefault: `wcem=8`\n\nYou may specify the encoding or any other option for file with this parameter.\n\n```ada\nDotenv.Config(File_Form =\u003e \"wcem=8\");\n```\n\n#### Debug\n\nEnvironment Variable: `DOTENV_CONFIG_DEBUG`\n\nDefault: `False`\n\nYou may turn on logging to help debug why certain keys or values are not being set as you expect.\n\n```ada\nDotenv.Config_Debug (Debug =\u003e True);\n\n-- Or\n\nDotenv.Config (Overwrite     =\u003e False\n               Interpolation =\u003e False,\n               Debug         =\u003e True,\n               Path          =\u003e \"\",\n               File_Form     =\u003e \"\");\n```\n\n#### Overwrite\n\nEnvironment Variable: `DOTENV_CONFIG_OVERWRITE`\n\nDefault: `False`\n\nYou may turn on overwrite to overwrite existing environment variable.\n\n```ada\nDotenv.Config_Overwrite (Overwrite =\u003e True);\n\n-- Or\n\nDotenv.Config (Overwrite     =\u003e True,\n               Debug         =\u003e False,\n               Interpolation =\u003e False,\n               Path          =\u003e \"\",\n               File_Form     =\u003e \"\");\n```\n\n#### Interpolation\n\nEnvironment Variable: `DOTENV_CONFIG_INTERPOLATION`\n\nDefault: `False`\n\nYou may turn on interpolation to interpolate variable.\nFor example, if we have the following environment variables:\n- `FIRSTNAME=John`\n- `LASTNAME=Doe`\n- `HELLO=Hello ${FIRSTNAME} $LASTNAME`\n\nThen the final value of `HELLO` will be \"Hello John Doe\" if Interpolation is True.\n  \n```ada\nDotenv.Config_Interpolation (Interpolation =\u003e True);\n\n-- Or\n\nDotenv.Config (Overwrite     =\u003e False,\n               Debug         =\u003e False,\n               Interpolation =\u003e True,\n               Path          =\u003e \"\",\n               File_Form     =\u003e \"\");\n```\n\n## Parse\n\nThe engine which parses the contents of your file containing environment variables is available to use. It accepts a `String` (path to your environment file) or a `File_Type` and will return a `Map` with the parsed keys and values.\n\n```ada\nwith Ada.Environment_Variables;\nwith Ada.Text_IO;\nwith Dotenv;\n\nprocedure Parse_Example is\n   Env : constant Dotenv.Environment_Variable_Map.Map := Dotenv.Parse (Path =\u003e \"/custom/path/to/.env\");\nbegin\n   Ada.Text_IO.Put_Line (Env.Element (\"DB_HOST\"));\nend Parse_Example;\n```\n\n### Options\n\n#### Debug\n\nEnvironment Variable: `DOTENV_CONFIG_DEBUG`\n\nDefault: `False`\n\nYou may turn on logging to help debug why certain keys or values are not being set as you expect.\n\n```ada\nwith Ada.Environment_Variables;\nwith Ada.Text_IO;\nwith Dotenv;\n\nprocedure Parse_Example is\n   Env : constant Dotenv.Environment_Variable_Map.Map := Dotenv.Parse (Path =\u003e \"/custom/path/to/.env\",\n                                                                       Debug =\u003e True);\nbegin\n   Ada.Text_IO.Put_Line (Env.Element (\"DB_HOST\"));\nend Parse_Example;\n```\n\n### Rules\n\nThe parsing engine currently supports the following rules:\n\n- `BASIC=basic` becomes `Key: \"BASIC\", Value: \"basic\"`\n- empty lines are skipped\n- lines beginning with `#` are treated as comments\n- empty values become empty strings (`EMPTY=` becomes `Key: \"EMPTY\", Value: \"\"`)\n- inner quotes are maintained (think JSON) (`JSON={\"foo\": \"bar\"}` becomes `Key: \"JSON\", Value: \"{\\\"foo\\\": \\\"bar\\\"}\"`)\n- whitespace is removed from both ends of unquoted values (see more on [`Trim`](http://www.ada-auth.org/standards/aarm12_w_tc1/html/AA-A-4-5.html#I6512)) (`FOO=  some value  ` becomes `Key: \"FOO\", Value: \"some value\"`)\n- single and double quoted values are escaped (`SINGLE_QUOTE='quoted'` becomes `Key: \"SINGLE_QUOTE\", Value: \"quoted\"`)\n- single and double quoted values maintain whitespace from both ends (`FOO=\"  some value  \"` becomes `Key: \"FOO\", Value: \"  some value  \"`)\n- double quoted values expand new lines (`MULTILINE=\"new\\nline\"` becomes\n\n```\nKey: \"MULTILINE\", Value: \"new\nline\"\n```\n\n## FAQ\n\n### Should I commit my `.env` file?\n\nNo. We **strongly** recommend against committing your `.env` file to version\ncontrol. It should only include environment-specific values such as database\npasswords or API keys. Your production database should have a different\npassword than your development database.\n\n### Should I have multiple `.env` files?\n\nNo. We **strongly** recommend against having a \"main\" `.env` file and an \"environment\" `.env` file like `.env.test`. Your config should vary between deploys, and you should not be sharing values between environments.\n\n\u003e In a twelve-factor app, env vars are granular controls, each fully orthogonal to other env vars. They are never grouped together as “environments”, but instead are independently managed for each deploy. This is a model that scales up smoothly as the app naturally expands into more deploys over its lifetime.\n\u003e\n\u003e – [The Twelve-Factor App](http://12factor.net/config)\n\n### What happens to environment variables that were already set?\n\nBy default, we will not modify any environment variables that have already been set. In particular, if there is a variable in your `.env` file which collides with one that already exists in your environment, then that variable will be skipped. This behavior allows you to override all `.env` configurations with a machine-specific environment, although it is not recommended.\n\nIf you want to override an environment variable, you can set the parameter [**Overwrite**](#Overwrite) of `Config`, `Config_Overwrite` to `True`, or by setting the environment variable `DOTENV_CONFIG_OVERWRITE=True`.\n\n### What about variable expansion/interpolation?\n\nDotenv support variable interpolation.\n\nFor example, if we have the following environment variables:\n- `FIRSTNAME=John`\n- `LASTNAME=Doe`\n- `HELLO=Hello ${FIRSTNAME} $LASTNAME`\n\nThen the final value of `HELLO` will be \"Hello John Doe\" if Interpolation is True.\n\nIf you want to interpolate an environment variable, you can set the parameter [**Interpolation**](#Interpolation) of `Config`, `Config_Interpolation` to `True`, or by setting the environment variable `DOTENV_CONFIG_INTERPOLATION=True`.\n\n## Contributing Guide\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Change Log\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n## Licence\n\nSee [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheziode%2Fada-dotenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheziode%2Fada-dotenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheziode%2Fada-dotenv/lists"}