System.Console.Wizard

Wizards

newtype Wizard backend a

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.

Constructors

Wizard (MaybeT (Free backend) a)

Instances

Functor backend => Alternative (Wizard backend)

Functor backend => Monad (Wizard backend)

Functor backend => Functor (Wizard backend)

Functor backend => MonadPlus (Wizard backend)

Functor backend => Applicative (Wizard backend)

(:<:) ArbitraryIO b => MonadIO (Wizard b)

type PromptString = String

A string for a prompt

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

Run a wizard using some back-end.

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

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

Minimal complete definition

inj

Instances

Functor f => f :<: f

ArbitraryIO :<: Haskeline

ArbitraryIO :<: BasicIO

Password :<: Haskeline

LinePrewritten :<: Haskeline

Character :<: Haskeline

Character :<: BasicIO

Character :<: Pure

Line :<: Haskeline

Line :<: BasicIO

Line :<: Pure

OutputLn :<: Haskeline

OutputLn :<: BasicIO

OutputLn :<: Pure

Output :<: Haskeline

Output :<: BasicIO

Output :<: Pure

WithSettings :<: Haskeline

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

(Functor f, Functor g) => f :<: ((:+:) f g)

data (f :+: g) w infixr 9

Coproduct of two functors

Instances

(Run b f, Run b g) => Run b ((:+:) f g)

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

(Functor f, Functor g) => f :<: ((:+:) f g)

(Functor f, Functor g) => Functor ((:+:) f g)

Primitives

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

data Line w

Instances

Functor Line

Run IO Line

Line :<: Haskeline

Line :<: BasicIO

Line :<: Pure

Run (InputT IO) Line

Run (State PureState) Line

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

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

data LinePrewritten w

Instances

Functor LinePrewritten

LinePrewritten :<: Haskeline

Run (InputT IO) LinePrewritten

linePrewritten

Arguments

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

data Password w

Instances

Functor Password

Password :<: Haskeline

Run (InputT IO) Password

password

Arguments

:: Password :<: b

=> PromptString

-> Maybe Char

Mask character, if any.

-> Wizard b String

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

data Character w

Instances

Functor Character

Run IO Character

Character :<: Haskeline

Character :<: BasicIO

Character :<: Pure

Run (InputT IO) Character

Run (State PureState) Character

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

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

data Output w

Instances

Functor Output

Run IO Output

Output :<: Haskeline

Output :<: BasicIO

Output :<: Pure

Run (InputT IO) Output

Run (State PureState) Output

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

Output a string. Does not fail.

data OutputLn w

Instances

Functor OutputLn

Run IO OutputLn

OutputLn :<: Haskeline

OutputLn :<: BasicIO

OutputLn :<: Pure

Run (InputT IO) OutputLn

Run (State PureState) OutputLn

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

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

data ArbitraryIO w

Instances

Functor ArbitraryIO

Run IO ArbitraryIO

ArbitraryIO :<: Haskeline

ArbitraryIO :<: BasicIO

Run (InputT IO) ArbitraryIO

Modifiers

Modifiers change the behaviour of existing wizards.

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

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 a

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

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

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 c

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

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

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

Convenience

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

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 a

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 a

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

Utility

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

Translate a maybe value into wizard success/failure.

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

Ensures that a maybe value satisfies a given predicate.

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

A read-based parser for the parser modifier.