Documentation

Overview

    Package environ is an environment variable manipulation library.

    It couples the system's environment, represented as a []string of KEY[=VALUE] strings, into a key/value map and back.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Join

    func Join(k, v string) string

      Join creates an environment variable definition for the supplied key/value.

      func Split

      func Split(v string) (key, value string)

        Split splits the supplied environment variable value into a key/value pair.

        If v is of the form:

        - KEY, returns (KEY, "")
        - KEY=, returns (KEY, "")
        - KEY=VALUE, returns (KEY, VALUE)
        

        Types

        type Env

        type Env map[string]string

          Env contains system environment variables. It preserves each environment variable verbatim (even if invalid).

          Internally env is represented by a map of environment key to its "KEY=VALUE" value. Note that the value here is the full "KEY=VALUE", not just the VALUE part. This allows us to reconstitute the original environment string slice without reallocating all of its composite strings.

          func FromCtx

          func FromCtx(ctx context.Context) Env

            FromCtx returns a copy of the current Env in `ctx`.

            This is guaranteed to return a non-nil Env (i.e. it's always safe for assignment/manipulation)

            If no Env has been set with With, this returns `System()`.

            func New

            func New(s []string) Env

              New instantiates a new Env instance from the supplied set of environment KEY=VALUE strings using LoadSlice.

              The environment is automatically configured with the local system's case insensitivity.

              func System

              func System() Env

                System returns an Env instance instantiated with the current os.Environ values.

                The environment is automatically configured with the local system's case insensitivity.

                func (Env) Clone

                func (e Env) Clone() Env

                  Clone creates a new Env instance that is identical to, but independent from, e.

                  If e is nil, returns nil. Otherwise returns a new (perhaps empty) Env.

                  func (Env) Get

                  func (e Env) Get(k string) (v string, ok bool)

                    Get returns the environment value for the supplied key.

                    If the value is defined, ok will be true and v will be set to its value (note that this can be empty if the environment has an empty value). If the value is not defined, ok will be false.

                    func (Env) GetEmpty

                    func (e Env) GetEmpty(k string) string

                      GetEmpty is the same as Get, except that instead of returning a separate boolean indicating the presence of a key, it will return an empty string if the key is missing.

                      func (Env) Iter

                      func (e Env) Iter(cb func(k, v string) error) error

                        Iter iterates through all of the key/value pairs in Env and invokes the supplied callback, cb, for each element.

                        If the callback returns error, iteration will stop immediately.

                        func (Env) Len

                        func (e Env) Len() int

                          Len returns the number of environment variables defined in e.

                          func (Env) Load

                          func (e Env) Load(m map[string]string)

                            Load adds environment variables defined in a key/value map to an existing environment.

                            func (Env) Map

                            func (e Env) Map() map[string]string

                              Map returns a map of the key/value values in the environment.

                              This is a clone of the contents of e; manipulating this map will not change the values in e.

                              If env is either nil or empty, returns nil.

                              func (Env) Remove

                              func (e Env) Remove(k string) bool

                                Remove removes a value from the environment, returning true if the value was present. If the value was missing, Remove returns false.

                                Remove is different from Set(k, "") in that Set persists the key with an empty value, while Remove removes it entirely.

                                func (Env) RemoveMatch

                                func (e Env) RemoveMatch(fn func(k, v string) bool)

                                  RemoveMatch iterates over all keys and values in the environment, invoking the callback function, fn, for each key/value pair. If fn returns true, the key is removed from the environment.

                                  func (Env) Set

                                  func (e Env) Set(k, v string)

                                    Set sets the supplied environment key and value.

                                    func (Env) SetEntry

                                    func (e Env) SetEntry(entry string)

                                      SetEntry sets the supplied environment to a "KEY[=VALUE]" entry.

                                      func (Env) SetInCtx

                                      func (e Env) SetInCtx(ctx context.Context) context.Context

                                        SetInCtx installs a copy of the Env into the context, which can be retrieved with `FromCtx`.

                                        func (Env) Sorted

                                        func (e Env) Sorted() []string

                                          Sorted returns the contents of the environment, sorted by key.

                                          func (Env) String

                                          func (e Env) String() string

                                            String returns debug representation of Env.

                                            func (Env) Update

                                            func (e Env) Update(other Env)

                                              Update adds all key/value from other to the current environment. If there is a duplicate key, the value from other will overwrite the value from e.

                                              Values from other will be sorted and added in alphabetic order. This means that if e is case insensitive and there are multiple keys in other that converge on the same case insensitive key, the one that is alphabetically highest will be added.

                                              Source Files