Text.XFormat.Read

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

If you are primarily interested in using this library, you will want to see readsf and readf, 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.

The Class

class Format d a | d -> a where

This class provides the signature for an extensible, type-indexed function that uses a format descriptor to parse a string input and return a well-typed value. The type variable d is the format descriptor, and the variable a is the type of the value to be read from the input.

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 Read.

   data ReadF a = Read -- Format descriptor

   instance (Read a) => Format (ReadF a) a where
     readpf Read = readS_to_P reads

Note that you will need some of the combinators (such as readS_to_P) in Text.ParserCombinators.ReadP.

Methods

readpf :: d -> ReadP a

Given a format descriptor d, return a ReadP parser for a type a. This function may not be very useful outside of defining an instance for Format. Instead, consider using readsf or readf.

Instances

Format Char Char

Parse a Char and return it if it is equal to the enclosed value.

Format String String

Parse a String and return it if it is equal to the enclosed value.

Format SpaceF String

Format DoubleF Double

Format FloatF Float

Format IntegerF Integer

Format IntF Int

Format StringF String

Format CharF Char

Format (ReadP a) a

Parse a ReadP a value.

Format d a => Format (ChoiceF d) a

(Read a, Num a) => Format (NumF a) a

Read a => Format (ReadF a) a

Format d a => Format (MaybeF d) (Maybe a)

(Format d1 a1, Format d2 a2) => Format (d1, d2) (a1, a2)

(Format d1 a1, Format d2 a2) => Format (EitherLF d1 d2) (Either a1 a2)

(Format d1 a1, Format d2 a2) => Format (EitherF d1 d2) (Either a1 a2)

(Format din ain, Format dout aout) => Format (WrapF din dout) (:%: aout (:%: ain aout))

(Format d1 a1, Format d2 a2) => Format (:%: d1 d2) (:%: a1 a2)

(Format d1 a1, Format d2 a2, Format d3 a3) => Format (d1, d2, d3) (a1, a2, a3)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4) => Format (d1, d2, d3, d4) (a1, a2, a3, a4)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5) => Format (d1, d2, d3, d4, d5) (a1, a2, a3, a4, a5)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6) => Format (d1, d2, d3, d4, d5, d6) (a1, a2, a3, a4, a5, a6)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7) => Format (d1, d2, d3, d4, d5, d6, d7) (a1, a2, a3, a4, a5, a6, a7)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8) => Format (d1, d2, d3, d4, d5, d6, d7, d8) (a1, a2, a3, a4, a5, a6, a7, a8)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9) (a1, a2, a3, a4, a5, a6, a7, a8, a9)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12, Format d13 a13) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12, Format d13 a13, Format d14 a14) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14)

(Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12, Format d13 a13, Format d14 a14, Format d15 a15) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14, d15) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15)

The Functions

readsf :: Format d a => d -> ReadS a

Given a format descriptor d and a String, return a list of successes for the type a, i.e. [(a, String)]. This function simply transforms the ReadP parser of readpf to a ReadS function.

readf :: Format d a => d -> String -> Maybe a

Given a format descriptor d and a String, return an optional result of the type a. This function simply returns the head of the list from readsf if it was successful.

Format Descriptors

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

Basic Format Descriptors

data CharF

Parse a character.

Constructors

Char

Instances

Format CharF Char

data IntF

Parse an Int.

Constructors

Int

Instances

Format IntF Int

data IntegerF

Parse an Integer.

Constructors

Integer

Instances

Format IntegerF Integer

data FloatF

Parse a Float.

Constructors

Float

Instances

Format FloatF Float

data DoubleF

Parse a Double.

Constructors

Double

Instances

Format DoubleF Double

data StringF

Parse a string. Reads until the end of the input.

Constructors

String

Instances

Format StringF String

Class-based Format Descriptors

data ReadF a

Parse a value whose type is an instance of the class Read.

Constructors

Read

Instances

Read a => Format (ReadF a) a

data NumF a

Parse a value whose type is an instance of the class Num.

Constructors

Num

Instances

(Read a, Num a) => Format (NumF a) a

Recursive Format Descriptors

data a :%: b

Right-associative pair. First parse 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 din ain, Format dout aout) => Format (WrapF din dout) (:%: aout (:%: ain aout))

(Format d1 a1, Format d2 a2) => Format (:%: d1 d2) (:%: a1 a2)

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

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

data WrapF inner outer

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

Constructors

Wrap outer inner outer

Instances

(Format din ain, Format dout aout) => Format (WrapF din dout) (:%: aout (:%: ain aout))

data MaybeF a

Parse an optional value.

Constructors

Maybe a

Instances

Format d a => Format (MaybeF d) (Maybe a)

data ChoiceF a

Parse one of the optional formats in a list.

Constructors

Choice [a]

Instances

Format d a => Format (ChoiceF d) a

data EitherF a b

Parse one of two formats in a fully symmetric choice.

Constructors

Either a b

Instances

(Format d1 a1, Format d2 a2) => Format (EitherF d1 d2) (Either a1 a2)

data EitherLF a b

Parse one of two formats, trying the left one first.

Constructors

EitherL a b

Instances

(Format d1 a1, Format d2 a2) => Format (EitherLF d1 d2) (Either a1 a2)

Other Format Descriptors

data SpaceF

Parse zero or more whitespace characters. Stop when a non-whitespace character is reached.

Constructors

Space

Instances

Format SpaceF String