wizards-1.0.1: High level, generic library for interrogative user interfaces

Safe HaskellTrustworthy





newtype Wizard backend a Source

A Wizard b a is a conversation with the user via back-end b that will result in a data type a, or may fail. A Wizard is made up of one or more "primitives" (see below), composed using the Applicative, Monad and Alternative instances. The Alternative instance is, as you might expect, a maybe-style cascade. If the first wizard fails, the next one is tried. mzero can be used to induce failure directly.

The Wizard constructor is exported here for use when developing backends, but it is better for end-users to simply pretend that Wizard is an opaque data type. Don't depend on this unless you have no other choice.

Wizards are, internally, just a maybe transformer over a free monad built from some coproduct of functors, each of which is a primitive action.


Wizard (MaybeT (Free backend) a) 


Functor backend => Monad (Wizard backend) 
Functor backend => Functor (Wizard backend) 
(Monad (Wizard backend), Functor backend) => MonadPlus (Wizard backend) 
(Functor (Wizard backend), Functor backend) => Applicative (Wizard backend) 
(Applicative (Wizard backend), Functor backend) => Alternative (Wizard backend) 
(Monad (Wizard b), :<: ArbitraryIO b) => MonadIO (Wizard b) 

type PromptString = StringSource

A string for a prompt

run :: (Functor f, Monad b, Run b f) => Wizard f a -> b (Maybe a)Source

Run a wizard using some back-end.

class (Functor sub, Functor sup) => sub :<: sup Source

Subsumption of two functors. You shouldn't define any of your own instances of this when writing back-ends, rely only on GeneralizedNewtypeDeriving.

data (f :+: g) w Source

Coproduct of two functors


(Run b f, Run b g) => Run b (:+: f g) 
(Functor (:+: h g), Functor f, Functor g, Functor h, :<: f g) => f :<: (:+: h g) 
(Functor (:+: f g), Functor f, Functor g) => f :<: (:+: f g) 
(Functor f, Functor g) => Functor (:+: f g) 


Primitives are the basic building blocks for wizards. Use these functions to produce wizards that ask for input from the user, or output information.

line :: Line :<: b => PromptString -> Wizard b StringSource

Read one line of input from the user. Cannot fail (but may throw exceptions, depending on the backend).



:: LinePrewritten :<: b 
=> PromptString 
-> String

Text to the left of the cursor

-> String

Text to the right of the cursor

-> Wizard b String 

Read one line of input, with some default text already present, before and/or after the editing cursor.



:: Password :<: b 
=> PromptString 
-> Maybe Char

Mask character, if any.

-> Wizard b String 

Read one line of password input, with an optional mask character.

character :: Character :<: b => PromptString -> Wizard b CharSource

Read a single character only from input. Cannot fail (but may throw exceptions, depending on the backend).

output :: Output :<: b => String -> Wizard b ()Source

Output a string. Does not fail.

outputLn :: OutputLn :<: b => String -> Wizard b ()Source

Output a string followed by a newline. Does not fail.


Modifiers change the behaviour of existing wizards.

retry :: Functor b => Wizard b a -> Wizard b aSource

Retry produces a wizard that will retry the entire conversation again if it fails. It is simply retry x = x <|> retry x.

retryMsg :: OutputLn :<: b => String -> Wizard b a -> Wizard b aSource

Same as retry, except an error message can be specified.

defaultTo :: Functor b => Wizard b a -> a -> Wizard b aSource

x `defaultTo` y will return y if x fails, e.g parseRead line `defaultTo` 0.

parser :: Functor b => (a -> Maybe c) -> Wizard b a -> Wizard b cSource

Like fmap, except the function may be partial (Nothing causes the wizard to fail).

validator :: Functor b => (a -> Bool) -> Wizard b a -> Wizard b aSource

validator p causes a wizard to fail if the output value does not satisfy the predicate p.


nonEmpty :: Functor b => Wizard b [a] -> Wizard b [a]Source

Simply validator (not . null), makes a wizard fail if it gets an empty string.

inRange :: (Ord a, Functor b) => (a, a) -> Wizard b a -> Wizard b aSource

Makes a wizard fail if it gets an ordered quantity outside of the given range.

parseRead :: (Read a, Functor b) => Wizard b String -> Wizard b aSource

Simply parser readP. Attaches a simple read parser to a Wizard.


liftMaybe :: Functor b => Maybe a -> Wizard b aSource

Translate a maybe value into wizard success/failure.

ensure :: (a -> Bool) -> a -> Maybe aSource

Ensures that a maybe value satisfies a given predicate.

readP :: Read a => String -> Maybe aSource

A read-based parser for the parser modifier.