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. An easier alias for pretty-simple's pShow. This will probably show in colour if useColorOnStderr is true.

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

Monochrome version of pshow. This will never show in colour.

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

Pretty print a showable value. An easier alias for pretty-simple's pPrint. This will print in colour if useColorOnStderr is true.

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

Monochrome version of pprint. This will never print in colour.

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" (except on Windows, where a pager will not be used). If the text contains ANSI codes, because hledger thinks the current terminal supports those, the pager should be configured to display those, otherwise users will see junk on screen (#2015). We call "setLessR" at hledger startup to make that less likely.

setupPager :: IO ()

Make sure our $LESS and $MORE environment variables contain R, to help ensure the common pager less will show our ANSI output properly. less uses $LESS by default, and $MORE when it is invoked as more. What the original more program does, I'm not sure. If $PAGER is configured to something else, this probably will have no effect.

Terminal size

getTerminalHeightWidth :: IO (Maybe (Int, Int))

An alternative to ansi-terminal's getTerminalSize, based on the more robust-looking terminal-size package. Tries to get stdout's terminal's current height and width.

getTerminalHeight :: IO (Maybe Int)

getTerminalWidth :: IO (Maybe Int)

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. ColorIntensity is Dull or Vivid (ie normal and bold). Color is one of Black, Red, Green, Yellow, Blue, Magenta, Cyan, White. Eg: color Dull Red "text".

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.

bold' :: String -> String

Versions of some of text-ansi's string colors/styles which are more careful to not print junk onscreen. These use our useColorOnStdout.

faint' :: String -> String

black' :: String -> String

red' :: String -> String

green' :: String -> String

yellow' :: String -> String

blue' :: String -> String

magenta' :: String -> String

cyan' :: String -> String

white' :: String -> String

brightBlack' :: String -> String

brightRed' :: String -> String

brightGreen' :: String -> String

brightYellow' :: String -> String

brightBlue' :: String -> String

brightMagenta' :: String -> String

brightCyan' :: String -> String

brightWhite' :: String -> String

rgb' :: Word8 -> Word8 -> Word8 -> String -> String

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.

expandHomePath :: FilePath -> IO FilePath

Expand a tilde (representing home directory) at the start of a file path. ~username is not supported. Can raise an error.

expandPath :: FilePath -> FilePath -> IO FilePath

Given a current directory, convert a possibly relative, possibly tilde-containing file path to an absolute one. ~username is not supported. Leaves "-" unchanged. Can raise an error.

expandGlob :: FilePath -> FilePath -> IO [FilePath]

Like expandPath, but treats the expanded path as a glob, and returns zero or more matched absolute file paths, alphabetically sorted. Can raise an error.

sortByModTime :: [FilePath] -> IO [FilePath]

Given a list of existing file paths, sort them by modification time, most recent first.

readFileOrStdinPortably :: String -> IO Text

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

readFileStrictly :: FilePath -> IO Text

Like readFilePortably, but read all of the file before proceeding.

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