Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/icyleaf/poncho
A .env parser/loader improved for performance.
https://github.com/icyleaf/poncho
crystal dotenv dotenv-loader dotenv-parser
Last synced: about 2 months ago
JSON representation
A .env parser/loader improved for performance.
- Host: GitHub
- URL: https://github.com/icyleaf/poncho
- Owner: icyleaf
- License: mit
- Created: 2018-07-19T03:14:30.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-11-12T12:40:26.000Z (3 months ago)
- Last Synced: 2024-11-29T13:12:17.889Z (2 months ago)
- Topics: crystal, dotenv, dotenv-loader, dotenv-parser
- Language: Crystal
- Homepage:
- Size: 69.3 KB
- Stars: 29
- Watchers: 4
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Poncho
[](https://github.com/crystal-lang/crystal)
[](https://github.com/icyleaf/poncho/blob/master/CHANGELOG.md)
[](https://github.com/icyleaf/poncho/actions/workflows/linux-ci.yml)
A .env parser/loader improved for performance. Poncho Icon by lastspark from [Noun Project](https://thenounproject.com).
- [Installation](#installation)
- [Usage](#usage)
- [Parse](#parse)
- [Rules](#rules)
- [Overrides](#overrides)
- [Examples](#examples)
- [Load](#load)
- [Orders](#orders)
- [Overrides](#overrides-1)
- [Examples](#examples-1)
- [Best solution](#best-solution)
- [Donate](#donate)
- [How to Contribute](#how-to-contribute)
- [You may also like](#you-may-also-like)
- [License](#license)
## Installation
Add this to your application's `shard.yml`:
```yaml
dependencies:
poncho:
github: icyleaf/poncho
```
## Usage
Add your application configuration to your `.env` file in the root of your project:
```bash
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=poncho
MYSQL_USER=poncho
MYSQL_PASSWORD=74e10b72-33b1-434b-a476-cfee0faa7d75
```
Now you can parse or load it.
### Parse
Poncho parses the contents of your file containing environment variables is available to use.
It accepts a String or IO and will return an `Hash` with the parsed keys and values.
#### Rules
Poncho parser currently supports the following rules:
- Skipped the empty line and comment(`#`).
- Ignore the comment which after (`#`).
- `ENV=development` becomes `{"ENV" => "development"}`.
- Snakecase and upcase the key: `dbName` becomes `DB_NAME`, `DB_NAME` becomes `DB_NAME`
- Support variables in value. `$NAME` or `${NAME}`.
- Whitespace is removed from both ends of the value. `NAME = foo ` becomes`{"NAME" => "foo"}`
- New lines are expanded if in double quotes. `MULTILINE="new\nline"` becomes `{"MULTILINE" => "new\nline"}`
- Inner quotes are maintained (such like `Hash`/`JSON`). `JSON={"foo":"bar"}` becomes `{"JSON" => "{\"foo\":\"bar\"}"}`
- Empty values become empty strings.
- Single and double quoted values are escaped.
- Overwrite optional (default is non-overwrite).
- Support variables in value. `WELCOME="hello $NAME"` becomes `{"WELCOME" => "hello foo"}`
#### Overrides
By default, Poncho won't overwrite existing environment variables as dotenv assumes the deployment environment
has more knowledge about configuration than the application does.
To overwrite existing environment variables you can use `Poncho.parse!(string_or_io)` /
`Poncho.from_file(file, overwrite: true)` and `Poncho.parse(string_or_io, overwrite: true)`.
#### Examples
```crystal
require "poncho"
# Or only import parser
require "poncho/parser"
poncho = Poncho.from_file ".env"
# or
poncho = Poncho.parse("ENV=development\nENV=production")
poncho["ENV"] # => "development"
# Overwrite value with exists key
poncho = Poncho.parse!("ENV=development\nENV=production")
poncho["ENV"] # => "production"
```
### Load
Poncho loads the environment file is easy to use, based on parser above.
It accepts both single file (or path) and multiple files.
#### Orders
Poncho loads **single file** supports the following order with environment name (default is `development`):
- `.env` - The Original®
- `.env.development` - Environment-specific settings.
- `.env.local` - Local overrides. This file is loaded for all environments except `test`.
- `.env.development.local` - Local overrides of environment-specific settings.
> **NO** effect with multiple files, it only loads the given files.
#### Overrides
By default, Poncho won't overwrite existing environment variables as dotenv assumes the deployment environment
has more knowledge about configuration than the application does.
To overwrite existing environment variables you can use `Poncho.load!(*files)` or `Poncho.load(*files, overwrite: true)`.
#### Examples
```crystal
require "poncho"
# Or only import loader
require "poncho/loader"
# Load singe file
# Searching order: .env.development, .env.local, .env.development.local
Poncho.load ".env"
# Load from path
Poncho.load "config/"
# Load production file
# Searching order: .env, .env.production, .env.local, .env.production.local
Poncho.load ".env", env: "production"
# Load multiple files and overwrite value with exists key
# note: ignore enviroment name.
# Searching order: .env, .env.local
Poncho.load! ".env", ".env.local", env: "test"
```
## Best solution
[Totem](https://github.com/icyleaf/totem) is here to help with that. Poncho was built-in to Totem to better with configuration.
Configuration file formats is always the problem, you want to focus on building awesome things.
## How to Contribute
Your contributions are always welcome! Please submit a pull request or create an issue to add a new question, bug or feature to the list.
All [Contributors](https://github.com/icyleaf/poncho/graphs/contributors) are on the wall.
## You may also like
- [halite](https://github.com/icyleaf/halite) - Crystal HTTP Requests Client with a chainable REST API, built-in sessions and middlewares.
- [totem](https://github.com/icyleaf/totem) - Load and parse a configuration file or string in JSON, YAML, dotenv formats.
- [markd](https://github.com/icyleaf/markd) - Yet another markdown parser built for speed, Compliant to CommonMark specification.
- [popcorn](https://github.com/icyleaf/popcorn) - Easy and Safe casting from one type to another.
- [fast-crystal](https://github.com/icyleaf/fast-crystal) - 💨 Writing Fast Crystal 😍 -- Collect Common Crystal idioms.
## License
[MIT License](https://github.com/icyleaf/poncho/blob/master/LICENSE) © icyleaf