| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Hledger.Utils.IO
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]
- openFileOrStdin :: String -> IO Handle
- readFileOrStdinPortably :: String -> IO Text
- readFileOrStdinPortably' :: Maybe DynEncoding -> String -> IO Text
- readFileStrictly :: FilePath -> IO Text
- readFilePortably :: FilePath -> IO Text
- readHandlePortably :: Handle -> IO Text
- readHandlePortably' :: Maybe DynEncoding -> Handle -> IO Text
- inputToHandle :: Text -> IO Handle
- progArgs :: [String]
- getOpt :: [String] -> IO (Maybe String)
- parseYN :: String -> Bool
- parseYNA :: String -> YNA
- data YNA
- 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
- sgrresetall :: 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 Source #
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 Source #
Monochrome version of pshow. This will never show in colour.
pprint :: Show a => a -> IO () Source #
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 () Source #
Monochrome version of pprint. This will never print in colour.
Errors
error' :: String -> a Source #
Call errorWithoutStackTrace, prepending a "Error:" label. Also do some ANSI styling of the first line when allowed (using unsafe IO).
usageError :: String -> a Source #
Like error', but add a hint about using -h.
warn :: String -> a -> a Source #
Show a message, with "Warning:" label, on stderr before returning the given value. Also do some ANSI styling of the first line when we detect that's supported (using unsafe IO). Currently we use this very sparingly in hledger; we prefer to either quietly work, or loudly raise an error. (Varying output can make scripting harder.)
Time
Files
embedFileRelative :: FilePath -> Q Exp Source #
Like embedFile, but takes a path relative to the package directory.
expandHomePath :: FilePath -> IO FilePath Source #
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 Source #
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] Source #
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] Source #
Given a list of existing file paths, sort them by modification time, most recent first.
readFileOrStdinPortably :: String -> IO Text Source #
Like readFilePortably, but read from standard input if the path is "-".
readFileOrStdinPortably' :: Maybe DynEncoding -> String -> IO Text Source #
Like readFileOrStdinPortably, but take an optional converter.
readFileStrictly :: FilePath -> IO Text Source #
Like readFilePortably, but read all of the file before proceeding.
readFilePortably :: FilePath -> IO Text Source #
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' :: Maybe DynEncoding -> Handle -> IO Text Source #
Command line parsing
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) Source #
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 Source #
Parse yyesalways or nnonever to true or false, or with any other value raise an error.
parseYNA :: String -> YNA Source #
Parse yyesalways or nnonever or a/auto to a YNA choice, or with any other value raise an error.
Terminal size
getTerminalHeightWidth :: IO (Maybe (Int, Int)) Source #
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.
Pager output
setupPager :: IO () Source #
runPager :: String -> IO () Source #
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 Source #
Get the value of the rightmost --color or --colour option from the program's command line arguments.
useColorOnStdout :: IO Bool Source #
Should ANSI color and styles be used for standard output ? Considers useColorOnHandle stdout and hasOutputFile.
useColorOnStderr :: IO Bool Source #
Should ANSI color and styles be used for standard error output ? Considers useColorOnHandle stderr; is not affected by an --output-file option.
useColorOnStdoutUnsafe :: Bool Source #
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 Source #
Like useColorOnStdoutUnsafe, but for stderr.
bold' :: String -> String Source #
Set various ANSI styles/colours in a string, only if useColorOnStdoutUnsafe says we should.
brightBlack' :: String -> String Source #
brightRed' :: String -> String Source #
brightGreen' :: String -> String Source #
brightYellow' :: String -> String Source #
brightBlue' :: String -> String Source #
brightMagenta' :: String -> String Source #
brightCyan' :: String -> String Source #
brightWhite' :: String -> String Source #
sgrresetall :: String Source #
Generic
color :: ColorIntensity -> Color -> String -> String Source #
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 Source #
Wrap a string in ANSI codes to set and reset background colour.
colorB :: ColorIntensity -> Color -> WideBuilder -> WideBuilder Source #
Wrap a WideBuilder in ANSI codes to set and reset foreground colour.
bgColorB :: ColorIntensity -> Color -> WideBuilder -> WideBuilder Source #
Wrap a WideBuilder in ANSI codes to set and reset background colour.
terminalIsLight :: Maybe Bool Source #
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 Source #
Detect the terminal's current background lightness (0..1), if possible, using unsafePerformIO. If the terminal is transparent, its apparent lightness may be different.