turtle-1.3.1: Shell programming, Haskell-style

Safe Haskell | Safe
Language | Haskell2010

Turtle.Format

Contents

- Format
- Parameters
- Utilities

Description

Minimalist implementation of type-safe formatted strings, borrowing heavily from the implementation of the `formatting` package.

Example use of this module:

    >>> :set -XOverloadedStrings
    >>> import Turtle.Format
    >>> format ("This is a "%s%" string that takes "%d%" arguments") "format" 2
    "This is a format string that takes 2 arguments"

A `Format` string that takes no arguments has this type:

    "I take 0 arguments" :: Format r r

    format "I take 0 arguments" :: Text

    >>> format "I take 0 arguments"
    "I take 0 arguments"

A `Format` string that takes one argument has this type:

    "I take "%d%" arguments" :: Format r (Int -> r)

    format ("I take "%d%" argument") :: Int -> Text

    >>> format ("I take "%d%" argument") 1
    "I take 1 argument"

A `Format` string that takes two arguments has this type:

    "I "%s%" "%d%" arguments" :: Format r (Text -> Int -> r)

    format ("I "%s%" "%d%" arguments") :: Text -> Int -> Text

    >>> format ("I "%s%" "%d%" arguments") "take" 2
    "I take 2 arguments"

Synopsis

- data Format a b
- (%) :: Format b c -> Format a b -> Format a c
- format :: Format Text r -> r
- printf :: MonadIO io => Format (io ()) r -> r
- makeFormat :: (a -> Text) -> Format r (a -> r)
- w :: Show a => Format r (a -> r)
- d :: Integral n => Format r (n -> r)
- u :: Format r (Word -> r)
- o :: Format r (Word -> r)
- x :: Format r (Word -> r)
- f :: Format r (Double -> r)
- e :: Format r (Double -> r)
- g :: Format r (Double -> r)
- s :: Format r (Text -> r)
- fp :: Format r (FilePath -> r)
- utc :: Format r (UTCTime -> r)
- repr :: Show a => a -> Text

# Format

data Format a b #

A `Format` string

Instances

Category * Format # |
Methods id :: cat a a # (.) :: cat b c -> cat a b -> cat a c #
(~) * a b => IsString (Format a b) # |
Methods fromString :: String -> Format a b #

(%) :: Format b c -> Format a b -> Format a c #

Concatenate two `Format` strings

format :: Format Text r -> r #

Convert a `Format` string to a print function that takes zero or more typed arguments and returns a `Text` string

printf :: MonadIO io => Format (io ()) r -> r #

Print a `Format` string to standard output (without a trailing newline)

    >>> printf ("Hello, "%s%"!\n") "world"
    Hello, world!

makeFormat :: (a -> Text) -> Format r (a -> r) #

Create your own format specifier

# Parameters

w :: Show a => Format r (a -> r) #

`Format` any `Show`able value

    >>> format w True
    "True"

d :: Integral n => Format r (n -> r) #

`Format` an `Integral` value as a signed decimal

    >>> format d 25
    "25"
    >>> format d (-25)
    "-25"

u :: Format r (Word -> r) #

`Format` a `Word` value as an unsigned decimal

    >>> format u 25
    "25"

o :: Format r (Word -> r) #

`Format` a `Word` value as an unsigned octal number

    >>> format o 25
    "31"

x :: Format r (Word -> r) #

`Format` a `Word` value as an unsigned hexadecimal number (without a leading "0x")

    >>> format x 25
    "19"

f :: Format r (Double -> r) #

`Format` a `Double` using decimal notation with 6 digits of precision

    >>> format f 25.1
    "25.100000"

e :: Format r (Double -> r) #

`Format` a `Double` using scientific notation with 6 digits of precision

    >>> format e 25.1
    "2.510000e1"

g :: Format r (Double -> r) #

`Format` a `Double` using decimal notation for small exponents and scientific notation for large exponents

    >>> format g 25.1
    "25.100000"
    >>> format g 123456789
    "1.234568e8"
    >>> format g 0.00000000001
    "1.000000e-11"

s :: Format r (Text -> r) #

`Format` that inserts `Text`

    >>> format s "ABC"
    "ABC"

fp :: Format r (FilePath -> r) #

`Format` a `FilePath` into `Text`

utc :: Format r (UTCTime -> r) #

`Format` a `UTCTime` into `Text`

# Utilities

repr :: Show a => a -> Text #

Convert a `Show`able value to `Text`

Short-hand for `(format w)`

    >>> repr (1,2)
    "(1,2)"