{"id":15587777,"url":"https://github.com/icyleaf/poncho","last_synced_at":"2025-06-23T19:04:02.577Z","repository":{"id":38376568,"uuid":"141518527","full_name":"icyleaf/poncho","owner":"icyleaf","description":"A .env parser/loader improved for performance.","archived":false,"fork":false,"pushed_at":"2024-11-12T12:40:26.000Z","size":71,"stargazers_count":29,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T07:05:36.863Z","etag":null,"topics":["crystal","dotenv","dotenv-loader","dotenv-parser"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icyleaf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-19T03:14:30.000Z","updated_at":"2024-11-12T12:40:14.000Z","dependencies_parsed_at":"2022-08-25T02:12:00.080Z","dependency_job_id":null,"html_url":"https://github.com/icyleaf/poncho","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fponcho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fponcho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fponcho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fponcho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icyleaf","download_url":"https://codeload.github.com/icyleaf/poncho/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250566445,"owners_count":21451230,"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":["crystal","dotenv","dotenv-loader","dotenv-parser"],"created_at":"2024-10-02T22:03:17.598Z","updated_at":"2025-04-24T04:50:29.424Z","avatar_url":"https://github.com/icyleaf.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"![poncho-logo](https://github.com/icyleaf/poncho/raw/master/logo-small.png)\n\n# Poncho\n\n[![Language](https://img.shields.io/badge/language-crystal-776791.svg)](https://github.com/crystal-lang/crystal)\n[![Tag](https://img.shields.io/github/tag/icyleaf/poncho.svg)](https://github.com/icyleaf/poncho/blob/master/CHANGELOG.md)\n[![Linux CI](https://github.com/icyleaf/poncho/actions/workflows/linux-ci.yml/badge.svg?branch=master)](https://github.com/icyleaf/poncho/actions/workflows/linux-ci.yml)\n\nA .env parser/loader improved for performance. Poncho Icon by lastspark from [Noun Project](https://thenounproject.com).\n\n\u003c!-- TOC --\u003e\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Parse](#parse)\n    - [Rules](#rules)\n    - [Overrides](#overrides)\n    - [Examples](#examples)\n  - [Load](#load)\n    - [Orders](#orders)\n    - [Overrides](#overrides-1)\n    - [Examples](#examples-1)\n- [Best solution](#best-solution)\n- [Donate](#donate)\n- [How to Contribute](#how-to-contribute)\n- [You may also like](#you-may-also-like)\n- [License](#license)\n\n\u003c!-- /TOC --\u003e\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n  poncho:\n    github: icyleaf/poncho\n```\n\n## Usage\n\nAdd your application configuration to your `.env` file in the root of your project:\n\n```bash\nMYSQL_HOST=localhost\nMYSQL_PORT=3306\nMYSQL_DATABASE=poncho\nMYSQL_USER=poncho\nMYSQL_PASSWORD=74e10b72-33b1-434b-a476-cfee0faa7d75\n```\n\nNow you can parse or load it.\n\n### Parse\n\nPoncho parses the contents of your file containing environment variables is available to use.\nIt accepts a String or IO and will return an `Hash` with the parsed keys and values.\n\n#### Rules\n\nPoncho parser currently supports the following rules:\n\n- Skipped the empty line and comment(`#`).\n- Ignore the comment which after (`#`).\n- `ENV=development` becomes `{\"ENV\" =\u003e \"development\"}`.\n- Snakecase and upcase the key: `dbName` becomes `DB_NAME`, `DB_NAME` becomes `DB_NAME`\n- Support variables in value. `$NAME` or `${NAME}`.\n- Whitespace is removed from both ends of the value. `NAME = foo ` becomes`{\"NAME\" =\u003e \"foo\"}`\n- New lines are expanded if in double quotes. `MULTILINE=\"new\\nline\"` becomes `{\"MULTILINE\" =\u003e \"new\\nline\"}`\n- Inner quotes are maintained (such like `Hash`/`JSON`). `JSON={\"foo\":\"bar\"}` becomes `{\"JSON\" =\u003e \"{\\\"foo\\\":\\\"bar\\\"}\"}`\n- Empty values become empty strings.\n- Single and double quoted values are escaped.\n- Overwrite optional (default is non-overwrite).\n- Support variables in value. `WELCOME=\"hello $NAME\"` becomes `{\"WELCOME\" =\u003e \"hello foo\"}`\n\n#### Overrides\n\nBy default, Poncho won't overwrite existing environment variables as dotenv assumes the deployment environment\nhas more knowledge about configuration than the application does.\nTo overwrite existing environment variables you can use `Poncho.parse!(string_or_io)` /\n`Poncho.from_file(file, overwrite: true)` and `Poncho.parse(string_or_io, overwrite: true)`.\n\n#### Examples\n\n```crystal\nrequire \"poncho\"\n# Or only import parser\nrequire \"poncho/parser\"\n\nponcho = Poncho.from_file \".env\"\n# or\nponcho = Poncho.parse(\"ENV=development\\nENV=production\")\nponcho[\"ENV\"] # =\u003e \"development\"\n\n# Overwrite value with exists key\nponcho = Poncho.parse!(\"ENV=development\\nENV=production\")\nponcho[\"ENV\"] # =\u003e \"production\"\n```\n\n### Load\n\nPoncho loads the environment file is easy to use, based on parser above.\n\nIt accepts both single file (or path) and multiple files.\n\n#### Orders\n\nPoncho loads **single file** supports the following order with environment name (default is `development`):\n\n- `.env` - The Original®\n- `.env.development` - Environment-specific settings.\n- `.env.local` - Local overrides. This file is loaded for all environments except `test`.\n- `.env.development.local` - Local overrides of environment-specific settings.\n\n\u003e **NO** effect with multiple files, it only loads the given files.\n\n#### Overrides\n\nBy default, Poncho won't overwrite existing environment variables as dotenv assumes the deployment environment\nhas more knowledge about configuration than the application does.\nTo overwrite existing environment variables you can use `Poncho.load!(*files)` or `Poncho.load(*files, overwrite: true)`.\n\n#### Examples\n\n```crystal\nrequire \"poncho\"\n# Or only import loader\nrequire \"poncho/loader\"\n\n# Load singe file\n# Searching order: .env.development, .env.local, .env.development.local\nPoncho.load \".env\"\n\n# Load from path\nPoncho.load \"config/\"\n\n# Load production file\n# Searching order: .env, .env.production, .env.local, .env.production.local\nPoncho.load \".env\", env: \"production\"\n\n# Load multiple files and overwrite value with exists key\n# note: ignore enviroment name.\n# Searching order: .env, .env.local\nPoncho.load! \".env\", \".env.local\", env: \"test\"\n```\n\n## Best solution\n\n[Totem](https://github.com/icyleaf/totem) is here to help with that. Poncho was built-in to Totem to better with configuration.\nConfiguration file formats is always the problem, you want to focus on building awesome things.\n\n## How to Contribute\n\nYour contributions are always welcome! Please submit a pull request or create an issue to add a new question, bug or feature to the list.\n\nAll [Contributors](https://github.com/icyleaf/poncho/graphs/contributors) are on the wall.\n\n## You may also like\n\n- [halite](https://github.com/icyleaf/halite) - Crystal HTTP Requests Client with a chainable REST API, built-in sessions and middlewares.\n- [totem](https://github.com/icyleaf/totem) - Load and parse a configuration file or string in JSON, YAML, dotenv formats.\n- [markd](https://github.com/icyleaf/markd) - Yet another markdown parser built for speed, Compliant to CommonMark specification.\n- [popcorn](https://github.com/icyleaf/popcorn) - Easy and Safe casting from one type to another.\n- [fast-crystal](https://github.com/icyleaf/fast-crystal) - 💨 Writing Fast Crystal 😍 -- Collect Common Crystal idioms.\n\n## License\n\n[MIT License](https://github.com/icyleaf/poncho/blob/master/LICENSE) © icyleaf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficyleaf%2Fponcho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficyleaf%2Fponcho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficyleaf%2Fponcho/lists"}