System.Environment.Blank

base-4.11.1.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 | Safe
Language | Haskell2010

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. I think AIX is screwed, but we don't support it. The whole situation with setenv(3), unsetenv(3), and putenv(3) is not good. Even mingw32 adds its own crap to the pile, but luckily, we can just use Windows' native environment functions to sidestep the issue.

#12494

Synopsis

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

# Documentation

getExecutablePath :: IO FilePath #

Returns the absolute pathname of 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.

Since: base-4.6.0.0

getArgs :: IO [String] #

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

getProgName :: IO String #

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 #

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

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

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

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

`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.

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

`lookupEnv`.

getEnvDefault #

Arguments

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

Get an environment value or a default value.

setEnv #

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.

unsetEnv :: String -> IO () #

Like `unsetEnv`, but allows for the removal of blank environment variables.