Text.Format

Format vs Text.Printf

• Printf is more ligth-weight

• Printf is more effective in basic formatting, e.g.:

    printf "%s %d %f" "hello" 123 456.789
    format "{:s} {:d} {:f}" "hello" 123 456.789
  

• Format is more effective in complex formatting, e.g.:

    printf "%30s %30d %30f" "hello" 123 456.789
    format "{:>30s} {:>30d} {:>30f}" "hello" 123 456.789
  

• Printf can only consume args in order, e.g.:

    printf "%s %d %f" "hello" 123 456.789
    format "{2:s} {1:d} {0:f}" 456.789 123 "hello"
  

• Printf can only consume position args, e.g.:

    printf "%s %d %f" "hello" 123 456.789
    format "{hello:s} {int:d} {float:f}" ("hello" := "hello") ("int" := 123)
      ("float" := 456.789)
  

• Format is easier to implement for a new type, e.g.:

    instance FormatArg UTCTime where
      formatArg x _ fmt = formatTime defaultTimeLocale (fmtSpecs fmt) x
  
    format "{:%Y-%m-%d}" $ read "2019-01-01" :: UTCTime
  

    data Student = Student { name     :: String
                           , age      :: Int
                           , email    :: String
                           } deriving Generic
  
    instance FormatArg Student
  
    format "{0!name:<20s} {0!age:<10d} {0!email:<20s}" $
      Student "Jorah Gao" 27 "[e-mail]"
  

Documentation

format :: FormatType r => Format -> r

Format a variable number of argument with Python-style formatting string

>>> format "hello {} {}" "world" "!" :: String
hello world !
>>> format "hello {1} {0}" "!" "world" :: String
hello world !
>>> format "hello {to} {bang}" ("to" := "world") ("bang" := "!")
hello world !

format1 :: FormatArg a => Format1 -> a -> String

Format argument with Python-style formatting string

>>> :set -XDeriveGeneric
>>> data Greeting = Greeting {to :: String, bang :: String} deriving Generic
>>> instance FormatArg Greeting
>>> format1 "hello {to} {bang}" (Greeting "world" "!")
hello world !
>>> format "hello {0!to} {0!bang}" (Greeting "world" "!")
hello world !

type Formatter = ArgKey -> ArgFmt -> String

class FormatArg a where

Typeclass of formatable values.

Make an instance for your own data types:

 data Coffe = Black | Latte | Other deriving Show

 instance FormatArg Coffe where
   formatArg x k fmt = formatArg (show x) k fmt

 newtype Big a = Big { unBig :: a}

 instance FormatArg a => FormatArg (Big a) where
   formatArg (Big x) k fmt = formatArg x k fmt

 data Student = Student { name     :: String
                        , age      :: Int
                        , email    :: String
                        } deriving Generic

 instance FormatArg Student

 data Address = Address { country :: String
                        , city    :: String
                        , street  :: String
                        }

 instance FormatArg Address where
   formatArg x k fmt = formatArg result k fmt
     where
       result :: String
       result = format "{:s},{:s},{:s}" (street x) (city x) (country x)

Minimal complete definition

Nothing

Methods

formatArg :: a -> Formatter

formatArg :: (Generic a, GFormatArg (Rep a)) => a -> Formatter

keyOf :: a -> ArgKey

Instances

FormatArg Char

Defined in Text.Format.Class

Methods

formatArg :: Char -> Formatter

keyOf :: Char -> ArgKey

FormatArg Double

Defined in Text.Format.Class

Methods

formatArg :: Double -> Formatter

keyOf :: Double -> ArgKey

FormatArg Float

Defined in Text.Format.Class

Methods

formatArg :: Float -> Formatter

keyOf :: Float -> ArgKey

FormatArg Int

Defined in Text.Format.Class

Methods

formatArg :: Int -> Formatter

keyOf :: Int -> ArgKey

FormatArg Int8

Defined in Text.Format.Class

Methods

formatArg :: Int8 -> Formatter

keyOf :: Int8 -> ArgKey

FormatArg Int16

Defined in Text.Format.Class

Methods

formatArg :: Int16 -> Formatter

keyOf :: Int16 -> ArgKey

FormatArg Int32

Defined in Text.Format.Class

Methods

formatArg :: Int32 -> Formatter

keyOf :: Int32 -> ArgKey

FormatArg Int64

Defined in Text.Format.Class

Methods

formatArg :: Int64 -> Formatter

keyOf :: Int64 -> ArgKey

FormatArg Integer

Defined in Text.Format.Class

Methods

formatArg :: Integer -> Formatter

keyOf :: Integer -> ArgKey

FormatArg Natural

Defined in Text.Format.Class

Methods

formatArg :: Natural -> Formatter

keyOf :: Natural -> ArgKey

FormatArg Word

Defined in Text.Format.Class

Methods

formatArg :: Word -> Formatter

keyOf :: Word -> ArgKey

FormatArg Word8

Defined in Text.Format.Class

Methods

formatArg :: Word8 -> Formatter

keyOf :: Word8 -> ArgKey

FormatArg Word16

Defined in Text.Format.Class

Methods

formatArg :: Word16 -> Formatter

keyOf :: Word16 -> ArgKey

FormatArg Word32

Defined in Text.Format.Class

Methods

formatArg :: Word32 -> Formatter

keyOf :: Word32 -> ArgKey

FormatArg Word64

Defined in Text.Format.Class

Methods

formatArg :: Word64 -> Formatter

keyOf :: Word64 -> ArgKey

FormatTime t => FormatArg t

Defined in Text.Format.Class

Methods

formatArg :: t -> Formatter

keyOf :: t -> ArgKey

FormatArg String

Defined in Text.Format.Class

Methods

formatArg :: String -> Formatter

keyOf :: String -> ArgKey

FormatArg a => FormatArg [a]

Defined in Text.Format.Class

Methods

formatArg :: [a] -> Formatter

keyOf :: [a] -> ArgKey

FormatArg a => FormatArg ((:=) a)

Defined in Text.Format.Class

Methods

formatArg :: (:=) a -> Formatter

keyOf :: (:=) a -> ArgKey

FormatArg a => FormatArg (Map Int a)

Defined in Text.Format.Class

Methods

formatArg :: Map Int a -> Formatter

keyOf :: Map Int a -> ArgKey

FormatArg a => FormatArg (Map String a)

Defined in Text.Format.Class

Methods

formatArg :: Map String a -> Formatter

keyOf :: Map String a -> ArgKey

class FormatType t where

A typeclass provides the variable arguments magic for format

Methods

sfmt :: Format -> Map ArgKey Formatter -> t

Instances

FormatType String

Defined in Text.Format.Class

Methods

sfmt :: Format -> Map ArgKey Formatter -> String

(FormatArg a, FormatType r) => FormatType (a -> r)

Defined in Text.Format.Class

Methods

sfmt :: Format -> Map ArgKey Formatter -> a -> r

data FmtItem

Constructors

Lit String

Arg ArgKey ArgFmt

Instances

Eq FmtItem

Defined in Text.Format.Format

Methods

(==) :: FmtItem -> FmtItem -> Bool

(/=) :: FmtItem -> FmtItem -> Bool

Show FmtItem

Defined in Text.Format.Format

Methods

showsPrec :: Int -> FmtItem -> ShowS

show :: FmtItem -> String

showList :: [FmtItem] -> ShowS

newtype Format

Format is a list of FmtItem

A format contains a variet of literal chars and arguments to be replaced, argument sytax is as follows:

{[key][:fmt]}

• {} means it must be wraped in a pair of braces,
• [] means an optional field (or field group),
• key is argument's key, see ArgKey,
• fmt (must leading with a colon) is argument's format, see ArgFmt.

If you need to include a brace character in the literal text, it can be escaped by doubling: {{ and }}.

if key is ommited, it means an automically positioned argument.

Examples:

>>> unFormat "a left brace {{"
[Lit "a left brace {"]

>>> unFormat "hello {}"
[Lit "hello ", Arg (Index 0) (ArgFmt ...)]

>>> unFormat "{} {}"
[Arg (Index 0) (ArgFmt ...), Arg (Index 1) (ArgFmt ...)]

>>> unFormat "{1} {0}"
[Arg (Index 1) (ArgFmt ...), Arg (Index 0) (ArgFmt ...)]

>>> unFormat "{gender} {age}"
[Arg (Name "gender") (ArgFmt ...), Arg (Name "age") (ArgFmt ...)]

>>> unFormat "{0!gender}"
[Arg (Nest (Index 0) (Name "gender")) (ArgFmt ..)]

>>> unFormat "{:<30s}"
[Arg (Index 0) (ArgFmt { fmtAlgin = AlignLeft, fmtWidth = Left 30, ...})]

>>> unFormat "{:<{width}s}"
[Arg (Index 0) (ArgFmt {fmtWidth = Right (Name "width"), ...})]

Constructors

Format

Fields

• unFormat :: [FmtItem]

Instances

Eq Format

Defined in Text.Format.Format

Methods

(==) :: Format -> Format -> Bool

(/=) :: Format -> Format -> Bool

Show Format

Defined in Text.Format.Format

Methods

showsPrec :: Int -> Format -> ShowS

show :: Format -> String

showList :: [Format] -> ShowS

IsString Format

Defined in Text.Format.Format

Methods

fromString :: String -> Format

newtype Format1

A variant of Format, it transforms all argument's key to Nest (Index 0) key

Constructors

Format1

Fields

• unFormat1 :: [FmtItem]

Instances

Eq Format1

Defined in Text.Format.Format

Methods

(==) :: Format1 -> Format1 -> Bool

(/=) :: Format1 -> Format1 -> Bool

Show Format1

Defined in Text.Format.Format

Methods

showsPrec :: Int -> Format1 -> ShowS

show :: Format1 -> String

showList :: [Format1] -> ShowS

IsString Format1

Defined in Text.Format.Format

Methods

fromString :: String -> Format1

data ArgKey

ArgKey indicates a key of format argument

There are two kinds of basic key, named and indexed, and a composed key indicates a key which is a attribute of an argument.

When read from a String, the sytax is as followings:

1. if all chars are digits, it means an indexed key,
2. if there is a "!", it means a nested key, the chars before "!" is parent key, and the chars after are child key,
3. if you want to use literal "!" in the key, you can write it doublely, "!!",
4. if there are not all digits, it's a named key.

Examples:

>>> read "country" :: ArgKey
Name "country"

>>> read "123" :: ArgKey
Index 123

>>> read "country!name" :: ArgKey
Nest (Name "country") (Name "name")

>>> read "country!cities!10" :: ArgKey
Nest (Name "country") (Nest (Name "cities") (Index 10))

>>> read "coun!!try" :: ArgKey
Name "coun!try"

Constructors

Index Int

Name String

Nest ArgKey ArgKey

Instances

Eq ArgKey

Defined in Text.Format.ArgKey

Methods

(==) :: ArgKey -> ArgKey -> Bool

(/=) :: ArgKey -> ArgKey -> Bool

Ord ArgKey

Defined in Text.Format.ArgKey

Methods

compare :: ArgKey -> ArgKey -> Ordering

(<) :: ArgKey -> ArgKey -> Bool

(<=) :: ArgKey -> ArgKey -> Bool

(>) :: ArgKey -> ArgKey -> Bool

(>=) :: ArgKey -> ArgKey -> Bool

max :: ArgKey -> ArgKey -> ArgKey

min :: ArgKey -> ArgKey -> ArgKey

Read ArgKey

Defined in Text.Format.ArgKey

Methods

readsPrec :: Int -> ReadS ArgKey

readList :: ReadS [ArgKey]

readPrec :: ReadPrec ArgKey

readListPrec :: ReadPrec [ArgKey]

Show ArgKey

Defined in Text.Format.ArgKey

Methods

showsPrec :: Int -> ArgKey -> ShowS

show :: ArgKey -> String

showList :: [ArgKey] -> ShowS

data FmtAlign

How to align argument

Note: AlignNone is equivalent to AlignLeft unless number's sign aware enabled

Constructors

AlignNone

alignment is not specified

AlignLeft

pad chars before argument

AlignRight

pad chars before argument

AlignCenter

pad chars before and after argument

AlignSign

number specified, pad between sign and digits

Instances

Eq FmtAlign

Defined in Text.Format.ArgFmt

Methods

(==) :: FmtAlign -> FmtAlign -> Bool

(/=) :: FmtAlign -> FmtAlign -> Bool

Show FmtAlign

Defined in Text.Format.ArgFmt

Methods

showsPrec :: Int -> FmtAlign -> ShowS

show :: FmtAlign -> String

showList :: [FmtAlign] -> ShowS

data FmtSign

How to show number's sign

Note: SignNone is equivalent to SignMinus for signed numbers

Constructors

SignNone

sign is not specified

SignPlus

show '+' for positive and '-' for negative

SignMinus

show negative's sign only

SignSpace

show ' ' for positive and - for negative

Instances

Eq FmtSign

Defined in Text.Format.ArgFmt

Methods

(==) :: FmtSign -> FmtSign -> Bool

(/=) :: FmtSign -> FmtSign -> Bool

Show FmtSign

Defined in Text.Format.ArgFmt

Methods

showsPrec :: Int -> FmtSign -> ShowS

show :: FmtSign -> String

showList :: [FmtSign] -> ShowS

data FmtNumSep

Number separator

Constructors

NumSepNone

don't seprate

NumSepDash

seprate by '_'

NumSepComma

seprate by ','

Instances

Eq FmtNumSep

Defined in Text.Format.ArgFmt

Methods

(==) :: FmtNumSep -> FmtNumSep -> Bool

(/=) :: FmtNumSep -> FmtNumSep -> Bool

Show FmtNumSep

Defined in Text.Format.ArgFmt

Methods

showsPrec :: Int -> FmtNumSep -> ShowS

show :: FmtNumSep -> String

showList :: [FmtNumSep] -> ShowS

data ArgFmt

Description of argument format options

When read from string, the sytax is as follows:

[[pad]align][sign][#][0][width][separator][.precision][specs]

• [] means an optional field (or filed group)
• pad means char to be used for padding, it should be a literal Char, default is space
• align means align option

     <       AlignLeft
     >       AlignRight
     ^       AlignCenter
     =       AlignSign
     empty   AlignNone
   

• sign means number sign option

     +       SignPlus
     -       SignMinus
     space   SignSpace
     empty   SignNone
   

• # means number alternate form option
• 0 preceding width option means sign-aware as well as zero-padding

     number       AlignNone & sign aware = AlignSign & pad '0'
     other types  means nothing
   

• width means minimum argument width, it may be an ArgKey indicates it's value from another integer argument

     integer   minimum width
     empty     no minimum widht constrain
   

• separator number separator option

     _       NumSepDash
     ,       NumSepComma
     empty   NumSepNone
   

• precision (must leading with a dot) number preceding or maximum with option it may be an ArgKey indicates it's value from another integer argument

     for number (floating point) types   number precision
     for non-number types                maximum widht
   

• specs type specified options, it determines how data should be presented, see available type presentions below

String presentions

   s               explicitly specified string type
   empty           implicitly specified string type
 

Integer presentions

   b               binary format integer
   c               char point (Char will be trasformed by ord first)
   d               decimal format integer
   o               octal format integer
   x               hex format integer (use lower-case letters)
   X               hex format integer (use upper-case letters)
   empty           same as "d"
 

Floating point number presentions

   e               exponent notation, see showEFloat
   E               same as "e", but use upper-case E as separator
   f               fixed-point notation see showFFloat
   F               same as "f", but converts nan to NAN and inf to INF
   g               general format, see showGFloat
   G               same as "g", but use upper-case E as separator and
                   converts nan to NAN and inf to INF
   %               percentage, same as "f" except multiplies 100 first and
                   followed by a percent sign
   empty           same as "g"
 

Examples

>>> read "*<30s" :: ArgFmt
>>> read "<10.20s" :: ArgFmt
>>> read "0=10_.20d" :: ArgFmt
>>> read "#010_.20b" :: ArgFmt

Constructors

ArgFmt

Fields

• fmtAlign :: FmtAlign
• fmtPad :: Char
• fmtSign :: FmtSign
• fmtAlternate :: Bool
• fmtSignAware :: Bool
• fmtWidth :: Either Int ArgKey
• fmtNumSep :: FmtNumSep
• fmtPrecision :: Either Int ArgKey
• fmtSpecs :: String

Instances

Eq ArgFmt

Defined in Text.Format.ArgFmt

Methods

(==) :: ArgFmt -> ArgFmt -> Bool

(/=) :: ArgFmt -> ArgFmt -> Bool

Read ArgFmt

Defined in Text.Format.ArgFmt

Methods

readsPrec :: Int -> ReadS ArgFmt

readList :: ReadS [ArgFmt]

readPrec :: ReadPrec ArgFmt

readListPrec :: ReadPrec [ArgFmt]

Show ArgFmt

Defined in Text.Format.ArgFmt

Methods

showsPrec :: Int -> ArgFmt -> ShowS

show :: ArgFmt -> String

showList :: [ArgFmt] -> ShowS

formatText :: ArgFmt -> ShowS

formatNumber :: ArgFmt -> Bool -> Int -> Maybe Char -> ShowS

data (:=) a infixr 6

A type represent a named ArgKey and an another data

Constructors

String := a infixr 6

Instances

FormatArg a => FormatArg ((:=) a)

Defined in Text.Format.Class

Methods

formatArg :: (:=) a -> Formatter

keyOf :: (:=) a -> ArgKey

ferror :: String -> a

errorArgFmt :: String -> a

errorCloseTag :: a

errorTypeFmt :: String -> String -> a

errorMissingArg :: a