GHC.Internal.System.Environment.Blank

ghc-internal-9.1400.0: Basic libraries

Copyright | (c) Habib Alamin 2017
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.Internal.System.Environment.Blank

Description

A setEnv implementation that allows blank environment variables. Mimics the `Env` module from the `unix` package, but with support for Windows too.

The matrix of platforms that:

- support `putenv(FOO)` to unset environment variables,
- support `putenv("FOO=")` to unset environment variables or set them to blank values,
- support `unsetenv` to unset environment variables,
- support `setenv` to set environment variables,
- etc.

is very complicated. Some platforms don't support unsetting of environment variables at all.

Synopsis

- getArgs :: IO [String]
- getEnvironment :: IO [(String, String)]
- getProgName :: IO String
- withArgs :: [String] -> IO a -> IO a
- withProgName :: String -> IO a -> IO a
- getExecutablePath :: IO FilePath
- getEnv :: String -> IO (Maybe String)
- getEnvDefault :: String -> String -> IO String
- setEnv :: String -> String -> Bool -> IO ()
- unsetEnv :: String -> IO ()

# Documentation

getArgs :: IO [String] Source #

Computation `getArgs` returns a list of the program's command line arguments (not including the program name).

getEnvironment :: IO [(String, String)] Source #

`getEnvironment` retrieves the entire environment as a list of `(key,value)` pairs.

If an environment entry does not contain an `'='` character, the `key` is the whole entry and the `value` is the empty string.

getProgName :: IO String Source #

Computation `getProgName` returns the name of the program as it was invoked.

However, this is hard-to-impossible to implement on some non-Unix OSes, so instead, for maximum portability, we just return the leafname of the program as invoked. Even then there are some differences between platforms: on Windows, for example, a program invoked as foo is probably really `FOO.EXE`, and that is what `getProgName` will return.

withArgs :: [String] -> IO a -> IO a Source #

`withArgs` `args act` - while executing action `act`, have `getArgs` return `args`.

withProgName :: String -> IO a -> IO a Source #

`withProgName` `name act` - while executing action `act`, have `getProgName` return `name`.

getExecutablePath :: IO FilePath Source #

Returns the absolute pathname of the current executable, or `argv[0]` if the operating system does not provide a reliable way query the current executable.

Note that for scripts and interactive sessions, this is the path to the interpreter (e.g. ghci.)

Since base 4.11.0.0, `getExecutablePath` resolves symlinks on Windows. If an executable is launched through a symlink, `getExecutablePath` returns the absolute path of the original executable.

If the executable has been deleted, behaviour is ill-defined and varies by operating system. See `executablePath` for a more reliable way to query the current executable.

Since: base-4.6.0.0

getEnv :: String -> IO (Maybe String) Source #

Similar to `lookupEnv`.

getEnvDefault Source #

Arguments

:: String | variable name
-> String | fallback value
-> IO String | variable value or fallback value

Get an environment value or a default value.

setEnv Source #

Arguments

:: String | variable name
-> String | variable value
-> Bool | overwrite
-> IO () |

Like `setEnv`, but allows blank environment values and mimics the function signature of `setEnv` from the `unix` package.

Beware that this function must not be executed concurrently with `getEnv`, `lookupEnv`, `getEnvironment` and such. One thread reading environment variables at the same time with another one modifying them can result in a segfault, see Setenv is not Thread Safe for discussion.

unsetEnv :: String -> IO () Source #

Like `unsetEnv`, but allows for the removal of blank environment variables. May throw an exception if the underlying platform doesn't support unsetting of environment variables.

Beware that this function must not be executed concurrently with `getEnv`, `lookupEnv`, `getEnvironment` and such. One thread reading environment variables at the same time with another one modifying them can result in a segfault, see Setenv is not Thread Safe for discussion.