EnvVar

Temporarily set environment variable values by treating the environment as a stack, and using blocks to control scope

Example

ENV["SomeEnvVar"] = "some original value"

EnvVar.push("SomeEnvVar", "some new value") do
  # The SomeEnvVar environment value is
  # "some new value" inside this block
  p ENV["SomeEnvVar"]
  # => "some new value"
end

# The SomeEnvVar environment value is restored
# to the original value at the end of the block
p ENV["SomeEnvVar"]
# => "some original value"

Pushing a Change to an Environment Variable

push(variable_name, value, &action)

EnvVar.push("SomeEnvVar", "some new value") do
  # The SomeEnvVar environment value is
  # "some new value" inside this block
end

The value of the environment variable will be changed to the new value before the block executes, and will be restored to the original value after the block executes.

If the environment variable does not already exist, it will be declared in the environment and then unset at the conclusion of the action block.

Returns

A dictionary of the environment variable name and the environment variable's original value. The dictionary's type is Hash.

Parameters

Name	Description	Type
variable_name	The name of the environment variable whose value will be affected	String
value	The value to assign to the environment variable	String
action	The block to be executed in the context of the new environment variable value	Proc

Pushing a Change to a Set of Environment Variables

self.push(hash, value, &action)

new_values = {
  "SomeEnvVar" => "some new value",
  "SomeOtherEnvVar" => "some other new value",
}

EnvVar.push(new_values) do
  # The SomeEnvVar environment value is
  # "some new value" inside this block
  # The SomeOtherEnvVar environment value is
  # "some other new value" inside this block
end

The value of an environment variable will be changed to the new value before the block executes, and will be restored to the original value after the block executes.

If an environment variable does not already exist, it will be declared in the environment and then unset at the conclusion of the action block.

Returns

A dictionary of the environment variable names and the environment variables' original values. The dictionary's type is Hash.

Parameters

Name	Description	Type
hash	The dictionary of environment variable names whose values will be affected, and the new values	Hash
action	The block to be executed in the context of the new environment variable values	Proc

Getting an Environment Variable's Value

self.get(variable_name)

ENV["SomeEnvVar"] = "some value"
EnvVar.get("SomeEnvVar")
# => "some value"

Returns

The environment variable's value. The environment variable's value is String. If the environment variable is not set, the returned value is nil.

Parameters

Name	Description	Type
variable_name	The name of the environment variable whose value will be retrieved	String

Fetching an Environment Variable's Value

self.fetch(variable_name)

ENV["SomeEnvVar"] = "some value"
EnvVar.fetch("SomeEnvVar")
# => "some value"

If the environment variable is not set, KeyError is raised.

EnvVar.fetch("SomeUnsetVar")
# => key not found: "SomeUnsetVar" (KeyError)

Returns

The environment variable's value. The environment variable's value is String.

Parameters

Name	Description	Type
variable_name	The name of the environment variable whose value will be retrieved	String

Raises

KeyError if the environment variable is not set.

Setting an Environment Variable's Value

self.set(variable_name, value)

EnvVar.set("SomeEnvVar", "some value")

Sets the value of the environment variable.

Returns

The value that was set. The type of the returned value is String.

Parameters

Name	Description	Type
variable_name	The name of the environment variable whose value will be set	String
value	The value to assign to the environment variable	String

Unsetting an Environment Variable

self.unset(variable_name, &action)

ENV["SomeEnvVar"] = "some value"
EnvVar.unset("SomeEnvVar")
# => "some value"

ENV["SomeEnvVar"]
# => nil

Unsets the environment variable. The environment variable is removed from the environment, rather than set to an empty value.

Returns

The value of the environment variable before it was unset. The environment variable's type is String. If the environment variable was not set, the returned value is nil.

Parameters

Name	Description	Type
variable_name	The name of the environment variable to remove	String
action	The block to be executed while the environment variable is unset	Proc

Unsetting an Environment Variable for the Duration of a Block

ENV["SomeEnvVar"] = "some original value"

EnvVar.unset("SomeEnvVar") do
  # The SomeEnvVar environment variable does not
  # exist in the environment inside this block
  p ENV.key?("SomeEnvVar")
  # => false
end

# The SomeEnvVar environment variable is restored
# to the original value at the end of the block
p ENV["SomeEnvVar"]
# => "some original value"

The environment variable will be removed from the environment before the block executes, and will be restored to the original value after the block executes. The original value is restored even when the block raises an error.

If the environment variable does not already exist, it will not exist at the conclusion of the action block, even if the block sets it.

Returns

The value of the environment variable before it was unset. The environment variable's type is String. If the environment variable was not set, the returned value is nil.

Parameters

Name	Description	Type
variable_name	The name of the environment variable to remove	String
action	The block to be executed in the context of the unset environment variable	Proc

Log Messages

Each operation writes a pair of messages: a trace message before the work, and a debug message after it. Every interpolated value is inspected, so a value appears quoted and an absent value appears as nil.

Operation	Level	Message
get	trace	Getting environment variable (Name: …)
	debug	Got environment variable (Name: …, Value: …)
fetch	trace	Fetching environment variable (Name: …)
	debug	Fetched environment variable (Name: …, Value: …)
set	trace	Setting environment variable (Name: …, Value: …)
	debug	Set environment variable (Name: …, Value: …)
unset	trace	Unsetting environment variable (Name: …)
	debug	Unset environment variable (Name: …, Value: …)
push_values	trace	Pushing environment variables (Hash)
	debug	Pushed environment variables (Hash)

Log Tags

The following tags are applied to log messages recorded by the EnvVar operations:

Tag	Description
env_var	Applied to all log messages written by this library

To print this library's log messages, and only this library's, set LOG_TAGS to the library's tag and LOG_LEVEL to trace:

LOG_TAGS=env_var LOG_LEVEL=trace ruby some_script.rb

LOG_LEVEL=trace is the most verbose level, and prints every level beneath it as well, which is what shows both messages of each operation's pair. Log messages are written to stderr unless CONSOLE_DEVICE is set to stdout.

The environment variables above are the logger's, not this library's. For the full set and their syntax, see Eventide's logger library, evt-log.

License

The EnvVar library is released under the MIT License.