Hledger.Utils.IO

Helpers for pretty-printing haskell values, reading command line arguments, working with ANSI colours, files, and time. Uses unsafePerformIO.

Limitations: When running in GHCI, this module must be reloaded to see environmental changes. The colour scheme may be somewhat hard-coded.

Pretty showing/printing

pshow :: Show a => a -> String

Pretty show. Easier alias for pretty-simple's pShow.

pshow' :: Show a => a -> String

Monochrome version of pshow.

pprint :: Show a => a -> IO ()

Pretty print. Easier alias for pretty-simple's pPrint.

pprint' :: Show a => a -> IO ()

Monochrome version of pprint.

Viewing with pager

pager :: String -> IO ()

Display the given text on the terminal, using the user's $PAGER if the text is taller than the current terminal and stdout is interactive and TERM is not "dumb".

Command line arguments

progArgs :: [String]

The command line arguments that were used at program startup. Uses unsafePerformIO.

outputFileOption :: Maybe String

Read the value of the -o/--output-file command line option provided at program startup, if any, using unsafePerformIO.

hasOutputFile :: Bool

Check whether the -o/--output-file option has been used at program startup with an argument other than "-", using unsafePerformIO.

ANSI color

colorOption :: String

Read the value of the --color or --colour command line option provided at program startup using unsafePerformIO. If this option was not provided, returns the empty string.

useColorOnStdout :: Bool

Check the IO environment to see if ANSI colour codes should be used on stdout. This is done using unsafePerformIO so it can be used anywhere, eg in low-level debug utilities, which should be ok since we are just reading. The logic is: use color if the program was started with --color=yes|always or ( the program was not started with --color=no|never and a NO_COLOR environment variable is not defined and stdout supports ANSI color and -o/--output-file was not used, or its value is "-" ).

useColorOnStderr :: Bool

Like useColorOnStdout, but checks for ANSI color support on stderr, and is not affected by -o/--output-file.

color :: ColorIntensity -> Color -> String -> String

Wrap a string in ANSI codes to set and reset foreground colour.

bgColor :: ColorIntensity -> Color -> String -> String

Wrap a string in ANSI codes to set and reset background colour.

colorB :: ColorIntensity -> Color -> WideBuilder -> WideBuilder

Wrap a WideBuilder in ANSI codes to set and reset foreground colour.

bgColorB :: ColorIntensity -> Color -> WideBuilder -> WideBuilder

Wrap a WideBuilder in ANSI codes to set and reset background colour.

terminalIsLight :: Maybe Bool

Detect whether the terminal currently has a light background colour, if possible, using unsafePerformIO. If the terminal is transparent, its apparent light/darkness may be different.

terminalLightness :: Maybe Float

Detect the terminal's current background lightness (0..1), if possible, using unsafePerformIO. If the terminal is transparent, its apparent lightness may be different.

terminalFgColor :: Maybe (RGB Float)

Detect the terminal's current foreground colour, if possible, using unsafePerformIO.

terminalBgColor :: Maybe (RGB Float)

Detect the terminal's current background colour, if possible, using unsafePerformIO.

Errors

error' :: String -> a

Simpler alias for errorWithoutStackTrace

usageError :: String -> a

A version of errorWithoutStackTrace that adds a usage hint.

Files

embedFileRelative :: FilePath -> Q Exp

Like embedFile, but takes a path relative to the package directory. Similar to embedFileRelative ?

expandHomePath :: FilePath -> IO FilePath

Expand user home path indicated by tilde prefix

expandPath :: FilePath -> FilePath -> IO FilePath

Convert a possibly relative, possibly tilde-containing file path to an absolute one, given the current directory. ~username is not supported. Leave "-" unchanged. Can raise an error.

readFileOrStdinPortably :: String -> IO Text

Like readFilePortably, but read from standard input if the path is "-".

readFilePortably :: FilePath -> IO Text

Read text from a file, converting any rn line endings to n,, using the system locale's text encoding, ignoring any utf8 BOM prefix (as seen in paypal's 2018 CSV, eg) if that encoding is utf8.

readHandlePortably :: Handle -> IO Text

Time

getCurrentLocalTime :: IO LocalTime

getCurrentZonedTime :: IO ZonedTime