dotenv 2.2.1 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 95698b07caac9203e94c95ae1075999dedcbd920
-  data.tar.gz: b072b014503b4c1c528de3b757f04285edf4099d
+SHA256:
+  metadata.gz: ac1a9e8e04f95f111da23bf2541070f2617864fc3c55ac4e11e6b91c78d11a9b
+  data.tar.gz: 24bf24be5be7020e72877e32d8cd2d9cf022a74b182569c77b2c81c0d482696b
 SHA512:
-  metadata.gz: 580b4fa8f27c2739b43e84eac9cb12b0febb59300db9f717630b249fdecfa4015098faf840106012e9fac8b68e522c383ac01098c18dd6771bfe75a46912cd2d
-  data.tar.gz: 8e8d92bc27cd525d6019bcea29235b330c37d8b123bc801bdb3509344a41c0e758718c1e530c8d7bf2c98b0d4686f59749a18dc2729fe1d3cd27748733668539
+  metadata.gz: 1f8d6ae3bfd67c1b57bc4d72346d670c02570d07cee953930d6b7f9018cc053ac42624d1bc4d59dd112abe5ba711d551199ff92a2672d5434577356b0a24d0c0
+  data.tar.gz: 38488d0f24d6f6014f87415775f94969cd56236bcb848c77b5dd4d066285ec47993006f87f1ab1afb50a033db101fe206741ec8e561de602a88717ad6fff3bdf

data/README.md

@@ -1,6 +1,4 @@
-# dotenv [![Build Status](https://secure.travis-ci.org/bkeepers/dotenv.png?branch=master)](https://travis-ci.org/bkeepers/dotenv)
-
-[![Join the chat at https://gitter.im/bkeepers/dotenv](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/bkeepers/dotenv?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+# dotenv [![Gem Version](https://badge.fury.io/rb/dotenv.svg)](https://badge.fury.io/rb/dotenv) [![Join the chat at https://gitter.im/bkeepers/dotenv](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/bkeepers/dotenv?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 Shim to load environment variables from `.env` into `ENV` in *development*.
 
@@ -32,7 +30,10 @@ dotenv is initialized in your Rails app during the `before_configuration` callba
 # config/application.rb
 Bundler.require(*Rails.groups)
 
-Dotenv::Railtie.load
+# Load dotenv only in development or test environment
+if ['development', 'test'].include? ENV['RAILS_ENV']
+  Dotenv::Railtie.load
+end
 
 HOSTNAME = ENV['HOSTNAME']
 ```
@@ -64,7 +65,7 @@ Dotenv.load
 
 By default, `load` will look for a file called `.env` in the current working directory. Pass in multiple files and they will be loaded in order. The first value set for a variable will win.
 
-```
+```ruby
 require 'dotenv'
 Dotenv.load('file1.env', 'file2.env')
 ```
@@ -72,7 +73,13 @@ Dotenv.load('file1.env', 'file2.env')
 Alternatively, you can use the `dotenv` executable to launch your application:
 
 ```shell
-$ dotenv ./script.py
+$ dotenv ./script.rb
+```
+
+The `dotenv` executable also accepts a single flag, `-f`. Its value should be a comma-separated list of configuration files, in the order of most important to least. All of the files must exist. There _must_ be a space between the flag and its value.
+
+```
+$ dotenv -f ".env.local,.env" ./script.rb
 ```
 
 To ensure `.env` is loaded in rake, load the tasks:
@@ -112,9 +119,21 @@ export SECRET_KEY=YOURSECRETKEYGOESHERE
 If you need multiline variables, for example private keys, you can double quote strings and use the `\n` character for newlines:
 
 ```shell
-PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9…\n-----END DSA PRIVATE KEY-----\n"
+PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
+```
+
+Alternatively, multi-line values with line breaks are now supported for quoted values.
+
+```shell
+PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
+...
+HkVN9...
+...
+-----END DSA PRIVATE KEY-----"
 ```
 
+This is particularly helpful when using the Heroku command line plugin [`heroku-config`](https://github.com/xavdid/heroku-config) to pull configuration variables down that may have line breaks.
+
 ### Command Substitution
 
 You need to add the output of a command in one of your variables? Simply add it with `$(your_command)`:
@@ -147,6 +166,31 @@ SECRET_KEY=YOURSECRETKEYGOESHERE # comment
 SECRET_HASH="something-with-a-#-hash"
 ```
 
+### Required Keys
+
+If a particular configuration value is required but not set, it's appropriate to raise an error.
+
+To require configuration keys:
+
+```ruby
+# config/initializers/dotenv.rb
+
+Dotenv.require_keys("SERVICE_APP_ID", "SERVICE_KEY", "SERVICE_SECRET")
+```
+
+If any of the configuration keys above are not set, your application will raise an error during initialization. This method is preferred because it prevents runtime errors in a production application due to improper configuration.
+
+### Parsing
+
+To parse a list of env files for programmatic inspection without modifying the ENV:
+
+```ruby
+Dotenv.parse(".env.local", ".env")
+# => {'S3_BUCKET' => 'YOURS3BUCKET', 'SECRET_KEY' => 'YOURSECRETKEYGOESHERE', ...}
+```
+
+This method returns a hash of the ENV var name/value pairs.
+
 ## Frequently Answered Questions
 
 ### Can I use dotenv in production?
@@ -159,23 +203,58 @@ If you use this gem to handle env vars for multiple Rails environments (developm
 
 ### What other .env* files can I use?
 
-`dotenv-rails` will load the following files, starting from the bottom. The first value set (or those already defined in the environment) take precedence:
+`dotenv-rails` will override in the following order (highest defined variable overrides lower):
+
+| Hierarchy Priority | Filename                 | Environment          | Should I `.gitignore`it?                            | Notes                                                        |
+| ------------------ | ------------------------ | -------------------- | --------------------------------------------------- | ------------------------------------------------------------ |
+| 1st (highest)      | `.env.development.local` | Development          | Yes!                                                | Local overrides of environment-specific settings.            |
+| 1st                | `.env.test.local`        | Test                 | Yes!                                                | Local overrides of environment-specific settings.            |
+| 1st                | `.env.production.local`  | Production           | Yes!                                                | Local overrides of environment-specific settings.            |
+| 2nd                | `.env.local`             | Wherever the file is | Definitely.                                         | Local overrides. This file is loaded for all environments _except_ `test`. |
+| 3rd                | `.env.development`       | Development          | No.                                                 | Shared environment-specific settings                         |
+| 3rd                | `.env.test`              | Test                 | No.                                                 | Shared environment-specific settings                         |
+| 3rd                | `.env.production`        | Production           | No.                                                 | Shared environment-specific settings                         |
+| Last               | `.env`                   | All Environments     | Depends (See [below](#should-i-commit-my-env-file)) | The Original®                                                |
 
-- `.env` - The Original®
-- `.env.development`, `.env.test`, `.env.production` - Environment-specific settings.
-- `.env.local` - Local overrides. This file is loaded for all environments _except_ `test`.
-- `.env.development.local`, `.env.test.local`, `.env.production.local` - Local overrides of environment-specific settings.
 
 ### Should I commit my .env file?
 
 Credentials should only be accessible on the machines that need access to them. Never commit sensitive information to a repository that is not needed by every development machine and server.
 
+
+You can use the `-t` or `--template` flag on the dotenv cli to create a template of your `.env` file.
+```shell
+$ dotenv -t .env
+```
+A template will be created in your working directory named `{FINAME}.template`. So in the above example, it would create a `.env.template` file.
+
+The template will contain all the environment variables in your `.env` file but with their values set to the variable names.
+
+```shell
+# .env
+S3_BUCKET=YOURS3BUCKET
+SECRET_KEY=YOURSECRETKEYGOESHERE
+```
+
+Would become
+
+```shell
+# .env.template
+S3_BUCKET=S3_BUCKET
+SECRET_KEY=SECRET_KEY
+```
+
 Personally, I prefer to commit the `.env` file with development-only settings. This makes it easy for other developers to get started on the project without compromising credentials for other environments. If you follow this advice, make sure that all the credentials for your development environment are different from your other deployments and that the development credentials do not have access to any confidential data.
 
 ### Why is it not overriding existing `ENV` variables?
 
 By default, it **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 `Dotenv.overload`.
 
+You can also use the `-o` or `--overload` flag on the dotenv cli to override existing `ENV` variables.
+```shell
+$ dotenv -o -f ".env.local,.env"
+```
+
 ## Contributing
 
 If you want a better idea of how dotenv works, check out the [Ruby Rogues Code Reading of dotenv](https://www.youtube.com/watch?v=lKmY_0uY86s).

data/lib/dotenv/cli.rb

@@ -1,36 +1,57 @@
 require "dotenv"
+require "dotenv/version"
+require "dotenv/template"
+require "optparse"
 
 module Dotenv
-  # The CLI is a class responsible of handling all the command line interface
-  # logic.
-  class CLI
-    attr_reader :argv
+  # The command line interface
+  class CLI < OptionParser
+    attr_reader :argv, :filenames, :overload
 
     def initialize(argv = [])
       @argv = argv.dup
+      @filenames = []
+      @overload = false
+
+      super "Usage: dotenv [options]"
+      separator ""
+
+      on("-f FILES", Array, "List of env files to parse") do |list|
+        @filenames = list
+      end
+
+      on("-o", "--overload", "override existing ENV variables") do
+        @overload = true
+      end
+
+      on("-h", "--help", "Display help") do
+        puts self
+        exit
+      end
+
+      on("-v", "--version", "Show version") do
+        puts "dotenv #{Dotenv::VERSION}"
+        exit
+      end
+
+      on("-t", "--template=FILE", "Create a template env file") do |file|
+        template = Dotenv::EnvTemplate.new(file)
+        template.create_template
+      end
+
+      order!(@argv)
     end
 
     def run
-      filenames = parse_filenames || []
-      begin
-        Dotenv.load!(*filenames)
-      rescue Errno::ENOENT => e
-        abort e.message
+      if @overload
+        Dotenv.overload!(*@filenames)
       else
-        exec(*argv) unless argv.empty?
+        Dotenv.load!(*@filenames)
       end
-    end
-
-    private
-
-    def parse_filenames
-      pos = argv.index("-f")
-      return nil unless pos
-      # drop the -f
-      argv.delete_at pos
-      # parse one or more comma-separated .env files
-      require "csv"
-      CSV.parse_line argv.delete_at(pos)
+    rescue Errno::ENOENT => e
+      abort e.message
+    else
+      exec(*@argv) unless @argv.empty?
     end
   end
 end

data/lib/dotenv/environment.rb

@@ -4,13 +4,13 @@ module Dotenv
   class Environment < Hash
     attr_reader :filename
 
-    def initialize(filename)
+    def initialize(filename, is_load = false)
       @filename = filename
-      load
+      load(is_load)
     end
 
-    def load
-      update Parser.call(read)
+    def load(is_load = false)
+      update Parser.call(read, is_load)
     end
 
     def read

data/lib/dotenv/missing_keys.rb

@@ -0,0 +1,10 @@
+module Dotenv
+  class Error < StandardError; end
+
+  class MissingKeys < Error # :nodoc:
+    def initialize(keys)
+      key_word = "key#{keys.size > 1 ? "s" : ""}"
+      super("Missing required configuration #{key_word}: #{keys.inspect}")
+    end
+  end
+end

data/lib/dotenv/parser.rb

@@ -12,38 +12,46 @@ module Dotenv
       [Dotenv::Substitutions::Variable, Dotenv::Substitutions::Command]
 
     LINE = /
-      \A
-      \s*
-      (?:export\s+)?    # optional export
-      ([\w\.]+)         # key
-      (?:\s*=\s*|:\s+?) # separator
-      (                 # optional value begin
-        '(?:\'|[^'])*'  #   single quoted value
-        |               #   or
-        "(?:\"|[^"])*"  #   double quoted value
-        |               #   or
-        [^#\n]+         #   unquoted value
-      )?                # value end
-      \s*
-      (?:\#.*)?         # optional comment
-      \z
+      (?:^|\A)              # beginning of line
+      \s*                   # leading whitespace
+      (?:export\s+)?        # optional export
+      ([\w.]+)              # key
+      (?:\s*=\s*?|:\s+?)    # separator
+      (                     # optional value begin
+        \s*'(?:\\'|[^'])*'  #   single quoted value
+        |                   #   or
+        \s*"(?:\\"|[^"])*"  #   double quoted value
+        |                   #   or
+        [^\#\r\n]+          #   unquoted value
+      )?                    # value end
+      \s*                   # trailing whitespace
+      (?:\#.*)?             # optional comment
+      (?:$|\z)              # end of line
     /x
 
     class << self
       attr_reader :substitutions
 
-      def call(string)
-        new(string).call
+      def call(string, is_load = false)
+        new(string, is_load).call
       end
     end
 
-    def initialize(string)
+    def initialize(string, is_load = false)
       @string = string
       @hash = {}
+      @is_load = is_load
     end
 
     def call
-      @string.split(/[\n\r]+/).each do |line|
+      # Convert line breaks to same format
+      lines = @string.gsub(/\r\n?/, "\n")
+      # Process matches
+      lines.scan(LINE).each do |key, value|
+        @hash[key] = parse_value(value || "")
+      end
+      # Process non-matches
+      lines.gsub(LINE, "").split(/[\n\r]+/).each do |line|
         parse_line(line)
       end
       @hash
@@ -52,32 +60,19 @@ module Dotenv
     private
 
     def parse_line(line)
-      if (match = line.match(LINE))
-        key, value = match.captures
-        @hash[key] = parse_value(value || "")
-      elsif line.split.first == "export"
+      if line.split.first == "export"
         if variable_not_set?(line)
           raise FormatError, "Line #{line.inspect} has an unset variable"
         end
-      elsif line !~ /\A\s*(?:#.*)?\z/ # not comment or blank line
-        raise FormatError, "Line #{line.inspect} doesn't match format"
       end
     end
 
     def parse_value(value)
       # Remove surrounding quotes
-      value = value.strip.sub(/\A(['"])(.*)\1\z/, '\2')
-
-      if Regexp.last_match(1) == '"'
-        value = unescape_characters(expand_newlines(value))
-      end
-
-      if Regexp.last_match(1) != "'"
-        self.class.substitutions.each do |proc|
-          value = proc.call(value, @hash)
-        end
-      end
-      value
+      value = value.strip.sub(/\A(['"])(.*)\1\z/m, '\2')
+      maybe_quote = Regexp.last_match(1)
+      value = unescape_value(value, maybe_quote)
+      perform_substitutions(value, maybe_quote)
     end
 
     def unescape_characters(value)
@@ -91,5 +86,24 @@ module Dotenv
     def variable_not_set?(line)
       !line.split[1..-1].all? { |var| @hash.member?(var) }
     end
+
+    def unescape_value(value, maybe_quote)
+      if maybe_quote == '"'
+        unescape_characters(expand_newlines(value))
+      elsif maybe_quote.nil?
+        unescape_characters(value)
+      else
+        value
+      end
+    end
+
+    def perform_substitutions(value, maybe_quote)
+      if maybe_quote != "'"
+        self.class.substitutions.each do |proc|
+          value = proc.call(value, @hash, @is_load)
+        end
+      end
+      value
+    end
   end
 end

data/lib/dotenv/substitutions/command.rb

@@ -13,14 +13,14 @@ module Dotenv
           \$                  # literal $
           (?<cmd>             # collect command content for eval
             \(                # require opening paren
-            ([^()]|\g<cmd>)+  # allow any number of non-parens, or balanced
+            (?:[^()]|\g<cmd>)+  # allow any number of non-parens, or balanced
                               # parens (by nesting the <cmd> expression
                               # recursively)
             \)                # require closing paren
           )
         /x
 
-        def call(value, _env)
+        def call(value, _env, _is_load)
           # Process interpolated shell commands
           value.gsub(INTERPOLATED_SHELL_COMMAND) do |*|
             # Eliminate opening and closing parentheses

data/lib/dotenv/substitutions/variable.rb

@@ -18,17 +18,23 @@ module Dotenv
           \}?           # closing brace
         /xi
 
-        def call(value, env)
+        def call(value, env, is_load)
+          combined_env = is_load ? env.merge(ENV) : ENV.to_h.merge(env)
           value.gsub(VARIABLE) do |variable|
             match = $LAST_MATCH_INFO
+            substitute(match, variable, combined_env)
+          end
+        end
+
+        private
 
-            if match[1] == '\\'
-              variable[1..-1]
-            elsif match[3]
-              env.fetch(match[3]) { ENV[match[3]] }
-            else
-              variable
-            end
+        def substitute(match, variable, env)
+          if match[1] == "\\"
+            variable[1..-1]
+          elsif match[3]
+            env.fetch(match[3], "")
+          else
+            variable
           end
         end
       end

data/lib/dotenv/template.rb

@@ -0,0 +1,26 @@
+module Dotenv
+  EXPORT_COMMAND = "export ".freeze
+  # Class for creating a template from a env file
+  class EnvTemplate
+    def initialize(env_file)
+      @env_file = env_file
+    end
+
+    def create_template
+      File.open(@env_file, "r") do |env_file|
+        File.open("#{@env_file}.template", "w") do |env_template|
+          env_file.each do |line|
+            env_template.puts template_line(line)
+          end
+        end
+      end
+    end
+
+    def template_line(line)
+      var, value = line.split("=")
+      template = var.gsub(EXPORT_COMMAND, "")
+      is_a_comment = var.strip[0].eql?("#")
+      value.nil? || is_a_comment ? line : "#{var}=#{template}"
+    end
+  end
+end

data/lib/dotenv/version.rb

@@ -1,3 +1,3 @@
 module Dotenv
-  VERSION = "2.2.1".freeze
+  VERSION = "2.8.1".freeze
 end

data/lib/dotenv.rb

@@ -1,5 +1,6 @@
 require "dotenv/parser"
 require "dotenv/environment"
+require "dotenv/missing_keys"
 
 # The top level Dotenv module. The entrypoint for the application logic.
 module Dotenv
@@ -12,7 +13,7 @@ module Dotenv
   def load(*filenames)
     with(*filenames) do |f|
       ignoring_nonexistent_files do
-        env = Environment.new(f)
+        env = Environment.new(f, true)
         instrument("dotenv.load", env: env) { env.apply }
       end
     end
@@ -21,7 +22,7 @@ module Dotenv
   # same as `load`, but raises Errno::ENOENT if any files don't exist
   def load!(*filenames)
     with(*filenames) do |f|
-      env = Environment.new(f)
+      env = Environment.new(f, true)
       instrument("dotenv.load", env: env) { env.apply }
     end
   end
@@ -30,12 +31,29 @@ module Dotenv
   def overload(*filenames)
     with(*filenames) do |f|
       ignoring_nonexistent_files do
-        env = Environment.new(f)
+        env = Environment.new(f, false)
         instrument("dotenv.overload", env: env) { env.apply! }
       end
     end
   end
 
+  # same as `overload`, but raises Errno::ENOENT if any files don't exist
+  def overload!(*filenames)
+    with(*filenames) do |f|
+      env = Environment.new(f, false)
+      instrument("dotenv.overload", env: env) { env.apply! }
+    end
+  end
+
+  # returns a hash of parsed key/value pairs but does not modify ENV
+  def parse(*filenames)
+    with(*filenames) do |f|
+      ignoring_nonexistent_files do
+        Environment.new(f, false)
+      end
+    end
+  end
+
   # Internal: Helper to expand list of filenames.
   #
   # Returns a hash of all the loaded environment variables.
@@ -55,6 +73,12 @@ module Dotenv
     end
   end
 
+  def require_keys(*keys)
+    missing_keys = keys.flatten - ::ENV.keys
+    return if missing_keys.empty?
+    raise MissingKeys, missing_keys
+  end
+
   def ignoring_nonexistent_files
     yield
   rescue Errno::ENOENT

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dotenv
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.8.1
 platform: ruby
 authors:
 - Brandon Keepers
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-04-28 00:00:00.000000000 Z
+date: 2022-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -39,19 +39,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: '0'
 description: Loads environment variables from `.env`.
 email:
 - brandon@opensoul.org
@@ -67,16 +67,18 @@ files:
 - lib/dotenv/cli.rb
 - lib/dotenv/environment.rb
 - lib/dotenv/load.rb
+- lib/dotenv/missing_keys.rb
 - lib/dotenv/parser.rb
 - lib/dotenv/substitutions/command.rb
 - lib/dotenv/substitutions/variable.rb
 - lib/dotenv/tasks.rb
+- lib/dotenv/template.rb
 - lib/dotenv/version.rb
 homepage: https://github.com/bkeepers/dotenv
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -91,9 +93,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.8
-signing_key: 
+rubygems_version: 3.2.32
+signing_key:
 specification_version: 4
 summary: Loads environment variables from `.env`.
 test_files: []