yaml-env-tag 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 320980f6b147ebb155338595cf94876182b2e60b
-  data.tar.gz: d5047c9c8494a2cb074eb7337bfc0f287877b8ec
+SHA256:
+  metadata.gz: 2ed0b32ad4e8f65504108d69a1d2374da10f8f2b430b9fac5bf0dbd6e888a074
+  data.tar.gz: 7a4ed9894da32fbc6035c98ca178be64aaa2c59a4c307b41950460422ca6857b
 SHA512:
-  metadata.gz: c06d3fa7961c410439a962065700acc68abfb404d7de3f57fb12b3def14d9d97bfa1235082ca576268da923adbe9caa19dc611a22eb67f2049aa64e63d7c3d33
-  data.tar.gz: 7ba5b9c211012b6831acb90a7699e311a5aa014709f504217f24918708280eb20f601da1d451b9dccd19383ba26f4b5d2057fcf2c887ada46b209ce395381bfa
+  metadata.gz: 60c7444f8f5b576f3224b93fc1c13a7477aa9fcf2c66a6507da4aef5da618ba1eecd751b32e1e2358f2fde584382035e8a32e6d246f55b6ca1c249fd83cca3d9
+  data.tar.gz: 4ded93c275a72f3acb41e4607e664290a002d2a162e8e719cbe74df09ce4a9f88d970b07885ffcb98c5ce73af3297e1d67239b1d1b9d4d4bb3282a7c97bfb02c

data/README.adoc

@@ -1,4 +1,4 @@
-= YAML !ENV tag
+= YAML !ENV Tag
 Jakub Jirutka <https://github.com/jirutka>
 // custom
 :gem-name: yaml-env-tag
@@ -19,8 +19,9 @@ No need to use ERB in YAML just to set some keys from environment variables.
 [source, yaml]
 .*Sample YAML file using ENV! tag*
 oauth:
-  client_id: ENV! API_CLIENT_ID
-  client_secret: ENV! API_CLIENT_SECRET
+  base_uri: ENV! API_BASE_URI
+  client_id: ENV! [API_CLIENT_ID, "demo"]
+  client_secret: ENV! [API_CLIENT_SECRET, API_CLIENT_KEY, ~]
 
 
 == Usage
@@ -40,7 +41,40 @@ However, if you use `YAML.safe_load` (which is highly recommended), you need to
 [source, rb]
 YAML.safe_load(..., [YamlEnvTag::EnvVariable])
 
-If the specified environment variable does not exist (i.e. is not set), `YAML` will raise exception `YamlEnvTag::MissingEnvVariableError` when loading the file.
+
+=== Single Required Variable
+
+Specify one environment variable as a `!ENV` tagged scalar.
+If it does not exist (is not set), `YAML.load` (and other load methods) will raise `YamlEnvTag::MissingEnvVariableError`.
+
+[source, yaml]
+!ENV SOME_VARIABLE
+
+This can be also written as a tagged sequence `!ENV [SOME_VARIABLE]` or `!ENV [SOME_VARIABLE, ~]`, all three variants are equivalent.
+
+
+=== Default Value
+
+You can define a default value that is used when the specified environment variable does not exist.
+This makes the variable optional.
+Default value is the last element of a `!ENV` tagged sequence (array) with more than one element.
+
+[source, yaml]
+!ENV [SOME_VARIABLE, "default value"]
+
+
+=== Multiple Variables (Fallbacks)
+
+You may also specify more environment variables in a `!ENV` tagged sequence (array) – the first one that does exist is used.
+Keep in mind that the last element of a multi-element sequence is always interpreted as a default value, not a name of environment variable!
+
+[source, yaml]
+!ENV [SOME_VARIABLE, LEGACY_VARIABLE, "default value"]
+
+If you want to raise an exception when none of the specified environment variables exist, use `~` (nil) as the last element:
+
+[source, yaml]
+!ENV [SOME_VARIABLE, LEGACY_VARIABLE, ~]
 
 
 == License

data/lib/yaml_env_tag/env_variable.rb

@@ -8,14 +8,35 @@ module YamlEnvTag
 
     # Deserializes from YAML. This method is called by {Psych}.
     #
-    # @param coder [Psych::Coder, #scalar] coder with name of the environment
-    #   variable to read.
+    # @param coder [Psych::Coder] coder with +:scalar+ or +:seq+.
     # @raise MissingEnvVariableError if the specified environment variable
     #   is not set (i.e. does not exist in +ENV+).
     def init_with(coder)
-      var_name = coder.scalar
-      value = ::ENV[var_name] or raise MissingEnvVariableError, var_name
-      initialize(value)
+      *variables, default =
+        case coder.type
+        when :scalar
+          [coder.scalar, nil]
+        when :seq
+          coder.seq.size < 2 ? [*coder.seq, nil] : coder.seq
+        else
+          raise InvalidUsageError, "#{coder.tag} tag cannot be used on a #{coder.type} node"
+        end
+
+      initialize(variables, default)
+    end
+
+    protected
+
+    # @param variables [Array<String>] names of the environment variables;
+    #   value of the first variable that does exist will be used.
+    # @param default_value [String, nil] the default value to use when none of
+    #   the _variables_ exist.
+    def initialize(variables, default_value)
+      value = variables.lazy.map { |n| ::ENV[n] if n }.find(&:itself)
+      value ||= default_value
+
+      raise MissingEnvVariableError, variables.last if value.nil?
+      super(value.to_s)
     end
   end
 end

data/lib/yaml_env_tag/errors.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
 module YamlEnvTag
-  # An error class raised when environment variable specified by the `!ENV` tag
+  # The base exception class for YamlEnvTag.
+  class Error < ::RuntimeError; end
+
+  # Exception raised when the +!ENV+ tag is used on a wrong node type
+  # or on empty node.
+  class InvalidUsageError < Error; end
+
+  # Exception raised when environment variable specified by the +!ENV+ tag
   # is not set.
-  class MissingEnvVariableError < ::RuntimeError
+  class MissingEnvVariableError < Error
 
     attr_reader :variable_name
 

data/lib/yaml_env_tag/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YamlEnvTag
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaml-env-tag
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jakub Jirutka
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-05 00:00:00.000000000 Z
+date: 2017-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -100,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Custom YAML tag for referring environment variables in YAML files