xformat-0.1.2.1: Extensible, type-safe formatting with scanf- and printf-like functions

Portabilitynon-portable
Stabilityexperimental
Maintainerleather@cs.uu.nl
Safe HaskellSafe-Inferred

Text.XFormat.Show

Contents

Description

This module defines an extensible, type-indexed function for showing well-typed values with a format descriptor. This may be considered a Haskell variant of the C printf function.

If you are primarily interested in using this library, you will want to see showsf and showf, the more user-friendly functions.

If you are also interested in extending this library with your own format descriptors, you should read about the Format class.

Synopsis

The Classes

class Functor f => Format d f | d -> f whereSource

This class provides the signature for an extensible, type-indexed function that uses a format descriptor to print a variable number of well-typed arguments to a string. The type variable d is the format descriptor, and the Functor variable f determines the type of the value to be shown.

An instance of Format adds a (type) case to the function. Before defining an instance, you must first define a format descriptor for your specific type and expected input. The descriptor is often very simple. See the descriptors in this module for examples.

Here is the instance for types that are instances of Show.

   data ShowF a = Show -- Format descriptor
   instance (Show a) => Format (ShowF a) (Arr a) where
     showsf' Show = Arr shows

The Arr type is one of several Functor wrappers necessary for defining these instances.

Methods

showsf' :: d -> f ShowSSource

Given a format descriptor d, return a Functor wrapping a String -> String type. This function may not be very useful outside of defining an instance for Format. Instead, consider using showsf or showf.

Instances

Format Char Id

Print the enclosed Char.

Format String Id

Print the enclosed String.

Format SpacesF Id 
Format DoubleF (Arr Double) 
Format FloatF (Arr Float) 
Format IntegerF (Arr Integer) 
Format IntF (Arr Int) 
Format StringF (Arr String) 
Format CharF (Arr Char) 
Format d f => Format (AlignChopF d) f 
Format d f => Format (AlignF d) f 
(Num a, Show a) => Format (NumF a) (Arr a) 
Show a => Format (ShowF a) (Arr a) 
(Format d1 f1, Format d2 f2) => Format (d1, d2) (:.: f1 f2) 
(Format din fin, Format dout fout) => Format (WrapF din dout) (:.: fout (:.: fin fout)) 
(Format d1 f1, Format d2 f2) => Format (:%: d1 d2) (:.: f1 f2) 
(Format d1 f1, Format d2 f2, Format d3 f3) => Format (d1, d2, d3) (:.: f1 (:.: f2 f3)) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4) => Format (d1, d2, d3, d4) (:.: f1 (:.: f2 (:.: f3 f4))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5) => Format (d1, d2, d3, d4, d5) (:.: f1 (:.: f2 (:.: f3 (:.: f4 f5)))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6) => Format (d1, d2, d3, d4, d5, d6) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 f6))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7) => Format (d1, d2, d3, d4, d5, d6, d7) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 f7)))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8) => Format (d1, d2, d3, d4, d5, d6, d7, d8) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 f8))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 f9)))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 f10))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 f11)))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 f12))))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 (:.: f12 f13)))))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13, Format d14 f14) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 (:.: f12 (:.: f13 f14))))))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13, Format d14 f14, Format d15 f15) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14, d15) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 (:.: f12 (:.: f13 (:.: f14 f15)))))))))))))) 

class Functor f => Apply f a b | f a -> b whereSource

Methods

apply :: f a -> bSource

Instances

Apply Id a a 
Apply (Arr a) b (a -> b) 
(Apply f b c, Apply g a b) => Apply (:.: f g) a c 

The Functions

showsf :: (Format d f, Apply f ShowS a) => d -> aSource

Given a format descriptor d, a variable number of arguments represented by a (and determined by d), and a String, return a String result. This function removes the Functor wrappers from the output of showsf' to get the variable number of arguments.

showf :: (Format d f, Apply f String a) => d -> aSource

Given a format descriptor d and a variable number of arguments represented by a (and determined by d), return a String result. This function is the same as showsf but has already been applied to a String input.

Format Descriptors

These are used to indicate which values and types to show.

Basic Format Descriptors

data CharF Source

Print a character argument.

Constructors

Char 

Instances

data IntF Source

Print an Int argument.

Constructors

Int 

Instances

data IntegerF Source

Print an Integer argument.

Constructors

Integer 

Instances

data FloatF Source

Print a Float argument.

Constructors

Float 

Instances

data DoubleF Source

Print a Double argument.

Constructors

Double 

Instances

data StringF Source

Print a string argument.

Constructors

String 

Instances

Class-based Format Descriptors

data ShowF a Source

Print an argument whose type is an instance of the class Show.

Constructors

Show 

Instances

Show a => Format (ShowF a) (Arr a) 

data NumF a Source

Print an argument whose type is an instance of the class Num.

Constructors

Num 

Instances

(Num a, Show a) => Format (NumF a) (Arr a) 

Recursive Format Descriptors

data a :%: b Source

Right-associative pair. First print a a-type format and then a b-type format.

Constructors

a :%: b 

Instances

(Eq a, Eq b) => Eq (:%: a b) 
(Show a, Show b) => Show (:%: a b) 
(Format d1 f1, Format d2 f2) => Format (:%: d1 d2) (:.: f1 f2) 

(%) :: a -> b -> a :%: bSource

Right-associative pair. This is a shorter, functional equivalent to the type (:%:).

data WrapF inner outer Source

Print a format of one type wrapped by two other formats of a different type.

Constructors

Wrap outer inner outer 

Instances

(Format din fin, Format dout fout) => Format (WrapF din dout) (:.: fout (:.: fin fout)) 

data AlignF a Source

Print a format aligned left or right within a column of the given width.

Constructors

Align Dir Int a 

Instances

Format d f => Format (AlignF d) f 

data AlignChopF a Source

Same as AlignF but chop off the output if it extends past the column width.

Constructors

AlignChop Dir Int a 

Instances

Format d f => Format (AlignChopF d) f 

data Dir Source

Direction (left or right) used for AlignF and AlignChopF.

Constructors

L 
R 

Other Format Descriptors

data SpacesF Source

Print a specified number of spaces.

Constructors

Spaces Int 

Instances

Utilities for Defining Instances

newtype Id a Source

Wrapper for a format constant that does not take any arguments. Used in instance Format String Id for example.

Constructors

Id a 

Instances

Functor Id 
Format Char Id

Print the enclosed Char.

Format String Id

Print the enclosed String.

Format SpacesF Id 
Apply Id a a 

newtype Arr a b Source

Wrapper for a format descriptor that takes an argument. Used in instance (Show a) => Format (ShowF a) (Arr a) for example.

Constructors

Arr (a -> b) 

newtype (f :.: g) a Source

Wrapper for a format descriptor that composes two descriptors. Used in instance (Format d1 f1, Format d2 f2) => Format (d1 :%: d2) (f1 :.: f2) for example.

Constructors

Comp (f (g a)) 

Instances

(Functor f, Functor g) => Functor (:.: f g) 
(Apply f b c, Apply g a b) => Apply (:.: f g) a c 
(Format d1 f1, Format d2 f2) => Format (d1, d2) (:.: f1 f2) 
(Format din fin, Format dout fout) => Format (WrapF din dout) (:.: fout (:.: fin fout)) 
(Format d1 f1, Format d2 f2) => Format (:%: d1 d2) (:.: f1 f2) 
(Format d1 f1, Format d2 f2, Format d3 f3) => Format (d1, d2, d3) (:.: f1 (:.: f2 f3)) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4) => Format (d1, d2, d3, d4) (:.: f1 (:.: f2 (:.: f3 f4))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5) => Format (d1, d2, d3, d4, d5) (:.: f1 (:.: f2 (:.: f3 (:.: f4 f5)))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6) => Format (d1, d2, d3, d4, d5, d6) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 f6))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7) => Format (d1, d2, d3, d4, d5, d6, d7) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 f7)))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8) => Format (d1, d2, d3, d4, d5, d6, d7, d8) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 f8))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 f9)))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 f10))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 f11)))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 f12))))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 (:.: f12 f13)))))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13, Format d14 f14) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 (:.: f12 (:.: f13 f14))))))))))))) 
(Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13, Format d14 f14, Format d15 f15) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14, d15) (:.: f1 (:.: f2 (:.: f3 (:.: f4 (:.: f5 (:.: f6 (:.: f7 (:.: f8 (:.: f9 (:.: f10 (:.: f11 (:.: f12 (:.: f13 (:.: f14 f15)))))))))))))) 

(<>) :: (Functor f, Functor g) => f (b -> c) -> g (a -> b) -> :.: f g (a -> c)Source

Helpful function for defining instances of composed format descriptors.