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

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

Text.XFormat.Read

Contents

Description

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.

Synopsis

The Class

class Format d a | d -> a whereSource

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 aSource

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 aSource

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 aSource

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 Source

Parse a character.

Constructors

Char 

Instances

data IntF Source

Parse an Int.

Constructors

Int 

Instances

data IntegerF Source

Parse an Integer.

Constructors

Integer 

data FloatF Source

Parse a Float.

Constructors

Float 

Instances

data DoubleF Source

Parse a Double.

Constructors

Double 

Instances

data StringF Source

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

Constructors

String 

Instances

Class-based Format Descriptors

data ReadF a Source

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

Constructors

Read 

Instances

Read a => Format (ReadF a) a 

data NumF a Source

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 Source

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 :%: bSource

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

data WrapF inner outer Source

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 Source

Parse an optional value.

Constructors

Maybe a 

Instances

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

data ChoiceF a Source

Parse one of the optional formats in a list.

Constructors

Choice [a] 

Instances

Format d a => Format (ChoiceF d) a 

data EitherF a b Source

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 Source

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 Source

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

Constructors

Space 

Instances