Hledger.Utils.IO

hledger-lib-1.41: A library providing the core functionality of hledger

Safe Haskell | None
Language | Haskell2010

Hledger.Utils.IO

Contents

- Pretty showing/printing
- Errors
- Time
- Files
- Command line parsing
- Terminal size
- Pager output
- ANSI colour/styles
  - hledger-specific
  - Generic

Description

General and hledger-specific input/output-related helpers for pretty-printing haskell values, error reporting, time, files, command line parsing, terminals, pager output, ANSI colour/styles, etc.

Synopsis

- pshow :: Show a => a -> String
- pshow' :: Show a => a -> String
- pprint :: Show a => a -> IO ()
- pprint' :: Show a => a -> IO ()
- error' :: String -> a
- usageError :: String -> a
- warn :: String -> a -> a
- getCurrentLocalTime :: IO LocalTime
- getCurrentZonedTime :: IO ZonedTime
- embedFileRelative :: FilePath -> Q Exp
- expandHomePath :: FilePath -> IO FilePath
- expandPath :: FilePath -> FilePath -> IO FilePath
- expandGlob :: FilePath -> FilePath -> IO [FilePath]
- sortByModTime :: [FilePath] -> IO [FilePath]
- readFileOrStdinPortably :: String -> IO Text
- readFileStrictly :: FilePath -> IO Text
- readFilePortably :: FilePath -> IO Text
- readHandlePortably :: Handle -> IO Text
- progArgs :: [String]
- getOpt :: [String] -> IO (Maybe String)
- parseYN :: String -> Bool
- parseYNA :: String -> YNA
- data YNA
  - = Yes
  - | No
  - | Auto
- getTerminalHeightWidth :: IO (Maybe (Int, Int))
- getTerminalHeight :: IO (Maybe Int)
- getTerminalWidth :: IO (Maybe Int)
- setupPager :: IO ()
- runPager :: String -> IO ()
- colorOption :: IO YNA
- useColorOnStdout :: IO Bool
- useColorOnStderr :: IO Bool
- useColorOnStdoutUnsafe :: Bool
- useColorOnStderrUnsafe :: Bool
- bold' :: String -> String
- 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' :: Float -> Float -> Float -> String -> String
- color :: ColorIntensity -> Color -> String -> String
- bgColor :: ColorIntensity -> Color -> String -> String
- colorB :: ColorIntensity -> Color -> WideBuilder -> WideBuilder
- bgColorB :: ColorIntensity -> Color -> WideBuilder -> WideBuilder
- terminalIsLight :: Maybe Bool
- terminalLightness :: Maybe Float
- terminalFgColor :: Maybe (RGB Float)
- terminalBgColor :: Maybe (RGB Float)

# 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 useColorOnStderrUnsafe 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 useColorOnStderrUnsafe is true.

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

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

# Errors

error' :: String -> a #

Simpler alias for errorWithoutStackTrace

usageError :: String -> a #

A version of errorWithoutStackTrace that adds a usage hint.

warn :: String -> a -> a #

Show a warning message on stderr before returning the given value. Use this when you want to show the user a message on stderr, without stopping the program. Currently we do this very sparingly in hledger; we prefer to either quietly work, or loudly raise an error. Variable output can make scripting harder.

# Time

getCurrentLocalTime :: IO LocalTime #

getCurrentZonedTime :: IO ZonedTime #

# 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 #

# Command line parsing

progArgs :: [String] #

The program's command line arguments. Uses unsafePerformIO; tends to stick in GHCI until reloaded, and may or may not detect args provided by a hledger config file.

getOpt :: [String] -> IO (Maybe String) #

Given one or more long or short option names, read the rightmost value of this option from the command line arguments. If the value is missing raise an error. Concatenated short flags (-a -b written as -ab) are not supported.

parseYN :: String -> Bool #

Parse yyesalways or nnonever to true or false, or with any other value raise an error.

parseYNA :: String -> YNA #

Parse yyesalways or nnonever or a/auto to a YNA choice, or with any other value raise an error.

data YNA #

Constructors

Yes |
No |
Auto |

#### Instances

Instances details

Show YNA # |
Instance details Defined in Hledger.Utils.IO Methods showsPrec :: Int -> YNA -> ShowS # show :: YNA -> String # showList :: [YNA] -> ShowS #
Eq YNA # |
Instance details Defined in Hledger.Utils.IO Methods (==) :: YNA -> YNA -> Bool # (/=) :: YNA -> YNA -> Bool #

# 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) #

# Pager output

setupPager :: IO () #

runPager :: String -> IO () #

Display the given text on the terminal, trying to use a pager ($PAGER, less, or more) when appropriate, otherwise printing to standard output. Uses maybePagerFor.

hledger's output may contain ANSI style/color codes (if the terminal supports them and they are not disabled by --color=no or NO_COLOR), so the pager should be configured to handle these. setupPager tries to configure that automatically when using the `less` pager.

# ANSI colour/styles

## hledger-specific

colorOption :: IO YNA #

Get the value of the rightmost --color or --colour option from the program's command line arguments.

useColorOnStdout :: IO Bool #

Should ANSI color and styles be used for standard output ? Considers useColorOnHandle stdout and hasOutputFile.

useColorOnStderr :: IO Bool #

Should ANSI color and styles be used for standard error output ? Considers useColorOnHandle stderr; is not affected by an --output-file option.

useColorOnStdoutUnsafe :: Bool #

Like useColorOnStdout, but using unsafePerformIO. Useful eg for low-level debug code. Sticky in GHCI until reloaded, may not always be affected by --color in a hledger config file, etc.

useColorOnStderrUnsafe :: Bool #

Like useColorOnStdoutUnsafe, but for stderr.

bold' :: String -> String #

Set various ANSI styles/colours in a string, only if useColorOnStdoutUnsafe says we should.

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' :: Float -> Float -> Float -> String -> String #

## Generic

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.

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.