formatting-7.2.0: Combinator-based type-safe formatting (like printf() or FORMAT)

Copyright | (c) 2013 Chris Done 2013 Shachaf Ben-Kiki
License | BSD3
Maintainer | alex@farfromthere.net
Stability | experimental
Portability | GHC
Safe Haskell | None
Language | Haskell2010

Formatting.Formatters

Contents

- Text/string types
- Numbers
- Padding
- Bases
- Buildables

Description

Formatting functions.

Synopsis

- text :: Format r (Text -> r)
- stext :: Format r (Text -> r)
- string :: Format r (String -> r)
- shown :: Show a => Format r (a -> r)
- char :: Format r (Char -> r)
- builder :: Format r (Builder -> r)
- fconst :: Builder -> Format r (a -> r)
- int :: Integral a => Format r (a -> r)
- float :: Real a => Format r (a -> r)
- fixed :: Real a => Int -> Format r (a -> r)
- sci :: Format r (Scientific -> r)
- scifmt :: FPFormat -> Maybe Int -> Format r (Scientific -> r)
- shortest :: Real a => Format r (a -> r)
- groupInt :: (Buildable n, Integral n) => Int -> Char -> Format r (n -> r)
- commas :: (Buildable n, Integral n) => Format r (n -> r)
- ords :: Integral n => Format r (n -> r)
- plural :: (Num a, Eq a) => Text -> Text -> Format r (a -> r)
- asInt :: Enum a => Format r (a -> r)
- left :: Buildable a => Int -> Char -> Format r (a -> r)
- right :: Buildable a => Int -> Char -> Format r (a -> r)
- center :: Buildable a => Int -> Char -> Format r (a -> r)
- fitLeft :: Buildable a => Int -> Format r (a -> r)
- fitRight :: Buildable a => Int -> Format r (a -> r)
- base :: Integral a => Int -> Format r (a -> r)
- bin :: Integral a => Format r (a -> r)
- oct :: Integral a => Format r (a -> r)
- hex :: Integral a => Format r (a -> r)
- prefixBin :: Integral a => Format r (a -> r)
- prefixOct :: Integral a => Format r (a -> r)
- prefixHex :: Integral a => Format r (a -> r)
- bytes :: (Ord f, Integral a, Fractional f) => Format Builder (f -> Builder) -> Format r (a -> r)
- build :: Buildable a => Format r (a -> r)
- class Buildable p

# Text/string types

text :: Format r (Text -> r) Source #

Output a lazy text.

stext :: Format r (Text -> r) Source #

Output a strict text.

string :: Format r (String -> r) Source #

Output a string.

shown :: Show a => Format r (a -> r) Source #

Output a showable value (instance of `Show`) by turning it into `Text`:

    >>> format ("Value number " % shown % " is " % shown % ".") 42 False
    "Value number 42 is False."

char :: Format r (Char -> r) Source #

Output a character.

builder :: Format r (Builder -> r) Source #

Build a builder.

fconst :: Builder -> Format r (a -> r) Source #

Like `const` but for formatters.

# Numbers

int :: Integral a => Format r (a -> r) Source #

Render an integral e.g. 123 -> "123", 0 -> "0".

float :: Real a => Format r (a -> r) Source #

Render some floating point with the usual notation, e.g. 123.32 => "123.32"

fixed :: Real a => Int -> Format r (a -> r) Source #

Render a floating point number using normal notation, with the given number of decimal places.

sci :: Format r (Scientific -> r) Source #

Render a scientific number.

scifmt :: FPFormat -> Maybe Int -> Format r (Scientific -> r) Source #

Render a scientific number with options.

shortest :: Real a => Format r (a -> r) Source #

Render a floating point number using the smallest number of digits that correctly represent it. Note that in the case of whole numbers it will still add one decimal place, e.g. "1.0".

groupInt :: (Buildable n, Integral n) => Int -> Char -> Format r (n -> r) Source #

Group integral numbers, e.g. groupInt 2 `.` on 123456 -> "12.34.56".

commas :: (Buildable n, Integral n) => Format r (n -> r) Source #

Add commas to an integral, e.g 12000 -> "12,000".

ords :: Integral n => Format r (n -> r) Source #

Add a suffix to an integral, e.g. 1st, 2nd, 3rd, 21st.

plural :: (Num a, Eq a) => Text -> Text -> Format r (a -> r) Source #

English plural suffix for an integral.

For example:

    >>> :set -XOverloadedStrings
    >>> formatPeople = format (int % " " <> plural "person" "people" % ".") :: Int -> Data.Text.Lazy.Text
    >>> formatPeople 1
    "1 person."
    >>> formatPeople 3
    "3 people."

asInt :: Enum a => Format r (a -> r) Source #

Shows the Int value of Enum instances using `fromEnum`.

    >>> format ("Got: " % char % " (" % asInt % ")") 'a' 'a'
    "Got: a (97)"

# Padding

left :: Buildable a => Int -> Char -> Format r (a -> r) Source #

Pad the left hand side of a string until it reaches k characters wide, if necessary filling with character c.

right :: Buildable a => Int -> Char -> Format r (a -> r) Source #

Pad the right hand side of a string until it reaches k characters wide, if necessary filling with character c.

center :: Buildable a => Int -> Char -> Format r (a -> r) Source #

Pad the left & right hand side of a string until it reaches k characters wide, if necessary filling with character c.

fitLeft :: Buildable a => Int -> Format r (a -> r) Source #

Fit in the given length, truncating on the left.

fitRight :: Buildable a => Int -> Format r (a -> r) Source #

Fit in the given length, truncating on the right.

# Bases

base :: Integral a => Int -> Format r (a -> r) Source #

Render an integral at base n.

bin :: Integral a => Format r (a -> r) Source #

Render an integer using binary notation. (No leading 0b is added.) Defined as `bin = `base` 2`.

oct :: Integral a => Format r (a -> r) Source #

Render an integer using octal notation. (No leading 0o is added.) Defined as `oct = `base` 8`.

hex :: Integral a => Format r (a -> r) Source #

Render an integer using hexadecimal notation. (No leading 0x is added.) Has a specialized implementation.

prefixBin :: Integral a => Format r (a -> r) Source #

Render an integer using binary notation with a leading 0b.

See also `binPrefix` for fixed-width formatting.

prefixOct :: Integral a => Format r (a -> r) Source #

Render an integer using octal notation with a leading 0o.

See also `octPrefix` for fixed-width formatting.

prefixHex :: Integral a => Format r (a -> r) Source #

Render an integer using hexadecimal notation with a leading 0x.

See also `hexPrefix` for fixed-width formatting.

bytes Source #

Arguments

:: (Ord f, Integral a, Fractional f) |
=> Format Builder (f -> Builder) | formatter for the decimal part
-> Format r (a -> r) |

Renders a given byte count using an appropiate decimal binary suffix:

    >>> format (bytes shortest) 1024
    "1KB"

    >>> format (bytes (fixed 2 % " ")) (1024*1024*5)
    "5.00 MB"

# Buildables

build :: Buildable a => Format r (a -> r) Source #

Build anything that implements the Buildable class.

class Buildable p Source #

The class of types that can be rendered to a `Builder`.

Minimal complete definition

build

#### Instances

Instances details

Buildable Void Source # |
Instance details Defined in Formatting.Buildable Methods build :: Void -> Builder Source #
Buildable IntPtr Source # |
Instance details Defined in Formatting.Buildable Methods build :: IntPtr -> Builder Source #
Buildable WordPtr Source # |
Instance details Defined in Formatting.Buildable Methods build :: WordPtr -> Builder Source #
Buildable Int16 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Int16 -> Builder Source #
Buildable Int32 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Int32 -> Builder Source #
Buildable Int64 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Int64 -> Builder Source #
Buildable Int8 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Int8 -> Builder Source #
Buildable Word16 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Word16 -> Builder Source #
Buildable Word32 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Word32 -> Builder Source #
Buildable Word64 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Word64 -> Builder Source #
Buildable Word8 Source # |
Instance details Defined in Formatting.Buildable Methods build :: Word8 -> Builder Source #
Buildable Text Source # |
Instance details Defined in Formatting.Buildable Methods build :: Text -> Builder Source #
Buildable Builder Source # |
Instance details Defined in Formatting.Buildable Methods build :: Builder -> Builder Source #
Buildable Text Source # |
Instance details Defined in Formatting.Buildable Methods build :: Text -> Builder Source #
Buildable Day Source # |
Instance details Defined in Formatting.Buildable Methods build :: Day -> Builder Source #
Buildable DiffTime Source # |
Instance details Defined in Formatting.Buildable Methods build :: DiffTime -> Builder Source #
Buildable NominalDiffTime Source # |
Instance details Defined in Formatting.Buildable Methods build :: NominalDiffTime -> Builder Source #
Buildable UTCTime Source # |
Instance details Defined in Formatting.Buildable Methods build :: UTCTime -> Builder Source #
Buildable UniversalTime Source # |
Instance details Defined in Formatting.Buildable Methods build :: UniversalTime -> Builder Source #
Buildable LocalTime Source # |
Instance details Defined in Formatting.Buildable Methods build :: LocalTime -> Builder Source #
Buildable TimeOfDay Source # |
Instance details Defined in Formatting.Buildable Methods build :: TimeOfDay -> Builder Source #
Buildable TimeZone Source # |
Instance details Defined in Formatting.Buildable Methods build :: TimeZone -> Builder Source #
Buildable ZonedTime Source # |
Instance details Defined in Formatting.Buildable Methods build :: ZonedTime -> Builder Source #
Buildable Integer Source # |
Instance details Defined in Formatting.Buildable Methods build :: Integer -> Builder Source #
Buildable Bool Source # |
Instance details Defined in Formatting.Buildable Methods build :: Bool -> Builder Source #
Buildable Char Source # |
Instance details Defined in Formatting.Buildable Methods build :: Char -> Builder Source #
Buildable Double Source # |
Instance details Defined in Formatting.Buildable Methods build :: Double -> Builder Source #
Buildable Float Source # |
Instance details Defined in Formatting.Buildable Methods build :: Float -> Builder Source #
Buildable Int Source # |
Instance details Defined in Formatting.Buildable Methods build :: Int -> Builder Source #
Buildable Word Source # |
Instance details Defined in Formatting.Buildable Methods build :: Word -> Builder Source #
Integral a => Buildable (Hex a) Source # |
Instance details Defined in Formatting.Buildable Methods build :: Hex a -> Builder Source #
Show a => Buildable (Shown a) Source # |
Instance details Defined in Formatting.Buildable Methods build :: Shown a -> Builder Source #
Buildable (Ptr a) Source # |
Instance details Defined in Formatting.Buildable Methods build :: Ptr a -> Builder Source #
Buildable a => Buildable (Ratio a) Source # |
Instance details Defined in Formatting.Buildable Methods build :: Ratio a -> Builder Source #
Buildable a => Buildable (Maybe a) Source # |
Instance details Defined in Formatting.Buildable Methods build :: Maybe a -> Builder Source #
Buildable [Char] Source # |
Instance details Defined in Formatting.Buildable Methods build :: [Char] -> Builder Source #
Buildable a => Buildable [a] Source # |
Instance details Defined in Formatting.Buildable Methods build :: [a] -> Builder Source #
HasResolution a => Buildable (Fixed a) Source # |
Instance details Defined in Formatting.Buildable Methods build :: Fixed a -> Builder Source #