System.Console.Wizard

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

Safe Haskell | Trustworthy
Language | Haskell98

System.Console.Wizard

Contents

- Wizards
- Primitives
- Modifiers
- Convenience
- Utility
- Orphan instances

Synopsis

- newtype Wizard (backend :: Type -> Type) a = Wizard (MaybeT (Free backend) a)
- type PromptString = String
- run :: forall (f :: Type -> Type) b a. (Functor f, Monad b, Run b f) => Wizard f a -> b (Maybe a)
- class (Functor sub, Functor sup) => (sub :: Type -> Type) :<: (sup :: Type -> Type)
- data ((f :: Type -> Type) :+: (g :: Type -> Type)) w
- data Line w
- line :: forall (b :: Type -> Type). Line :<: b => PromptString -> Wizard b String
- data LinePrewritten w
- linePrewritten :: forall (b :: Type -> Type). LinePrewritten :<: b => PromptString -> String -> String -> Wizard b String
- data Password w
- password :: forall (b :: Type -> Type). Password :<: b => PromptString -> Maybe Char -> Wizard b String
- data Character w
- character :: forall (b :: Type -> Type). Character :<: b => PromptString -> Wizard b Char
- data Output w
- output :: forall (b :: Type -> Type). Output :<: b => String -> Wizard b ()
- data OutputLn w
- outputLn :: forall (b :: Type -> Type). OutputLn :<: b => String -> Wizard b ()
- data ArbitraryIO w
- retry :: forall (b :: Type -> Type) a. Functor b => Wizard b a -> Wizard b a
- retryMsg :: forall (b :: Type -> Type) a. OutputLn :<: b => String -> Wizard b a -> Wizard b a
- defaultTo :: forall (b :: Type -> Type) a. Functor b => Wizard b a -> a -> Wizard b a
- parser :: forall (b :: Type -> Type) a c. Functor b => (a -> Maybe c) -> Wizard b a -> Wizard b c
- validator :: forall (b :: Type -> Type) a. Functor b => (a -> Bool) -> Wizard b a -> Wizard b a
- nonEmpty :: forall (b :: Type -> Type) a. Functor b => Wizard b [a] -> Wizard b [a]
- inRange :: forall a (b :: Type -> Type). (Ord a, Functor b) => (a, a) -> Wizard b a -> Wizard b a
- parseRead :: forall a (b :: Type -> Type). (Read a, Functor b) => Wizard b String -> Wizard b a
- liftMaybe :: forall (b :: Type -> Type) a. Functor b => Maybe a -> Wizard b a
- ensure :: (a -> Bool) -> a -> Maybe a
- readP :: Read a => String -> Maybe a

# Wizards

newtype Wizard (backend :: Type -> Type) 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.

`Wizard`s 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

Instances details

ArbitraryIO :<: b => MonadIO (Wizard b) # |
Instance details Defined in System.Console.Wizard Methods liftIO :: IO a -> Wizard b a #
Functor backend => Alternative (Wizard backend) # |
Instance details Defined in System.Console.Wizard.Internal Methods empty :: Wizard backend a # (<|>) :: Wizard backend a -> Wizard backend a -> Wizard backend a # some :: Wizard backend a -> Wizard backend [a] # many :: Wizard backend a -> Wizard backend [a] #
Functor backend => Applicative (Wizard backend) # |
Instance details Defined in System.Console.Wizard.Internal Methods pure :: a -> Wizard backend a # (<*>) :: Wizard backend (a -> b) -> Wizard backend a -> Wizard backend b # liftA2 :: (a -> b -> c) -> Wizard backend a -> Wizard backend b -> Wizard backend c # (*>) :: Wizard backend a -> Wizard backend b -> Wizard backend b # (<*) :: Wizard backend a -> Wizard backend b -> Wizard backend a #
Functor backend => Functor (Wizard backend) # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> Wizard backend a -> Wizard backend b # (<$) :: a -> Wizard backend b -> Wizard backend a #
Functor backend => Monad (Wizard backend) # |
Instance details Defined in System.Console.Wizard.Internal Methods (>>=) :: Wizard backend a -> (a -> Wizard backend b) -> Wizard backend b # (>>) :: Wizard backend a -> Wizard backend b -> Wizard backend b # return :: a -> Wizard backend a #
Functor backend => MonadPlus (Wizard backend) # |
Instance details Defined in System.Console.Wizard.Internal Methods mzero :: Wizard backend a # mplus :: Wizard backend a -> Wizard backend a -> Wizard backend a #

type PromptString = String #

A string for a prompt

run :: forall (f :: Type -> Type) b a. (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 :: Type -> Type) :<: (sup :: Type -> Type) #

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

Instances details

WithSettings :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: WithSettings a -> Haskeline a
ArbitraryIO :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: ArbitraryIO a -> BasicIO a
ArbitraryIO :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: ArbitraryIO a -> Haskeline a
Character :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: Character a -> BasicIO a
Character :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Character a -> Haskeline a
Character :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: Character a -> Pure a
Line :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: Line a -> BasicIO a
Line :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Line a -> Haskeline a
Line :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: Line a -> Pure a
LinePrewritten :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: LinePrewritten a -> Haskeline a
Output :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: Output a -> BasicIO a
Output :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Output a -> Haskeline a
Output :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: Output a -> Pure a
OutputLn :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: OutputLn a -> BasicIO a
OutputLn :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: OutputLn a -> Haskeline a
OutputLn :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: OutputLn a -> Pure a
Password :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Password a -> Haskeline a
Functor f => f :<: f # |
Instance details Defined in System.Console.Wizard.Internal Methods inj :: f a -> f a
(Functor f, Functor g) => f :<: (f :+: g) # |
Instance details Defined in System.Console.Wizard.Internal Methods inj :: f a -> (f :+: g) a
(Functor f, Functor g, Functor h, f :<: g) => f :<: (h :+: g) # |
Instance details Defined in System.Console.Wizard.Internal Methods inj :: f a -> (h :+: g) a

data ((f :: Type -> Type) :+: (g :: Type -> Type)) w infixr 9 #

Coproduct of two functors

#### Instances

Instances details

(Functor f, Functor g) => f :<: (f :+: g) # |
Instance details Defined in System.Console.Wizard.Internal Methods inj :: f a -> (f :+: g) a
(Functor f, Functor g, Functor h, f :<: g) => f :<: (h :+: g) # |
Instance details Defined in System.Console.Wizard.Internal Methods inj :: f a -> (h :+: g) a
(Run b f, Run b g) => Run b (f :+: g) # |
Instance details Defined in System.Console.Wizard.Internal Methods runAlgebra :: (f :+: g) (b v) -> b v #
(Functor f, Functor g) => Functor (f :+: g) # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> (f :+: g) a -> (f :+: g) b # (<$) :: a -> (f :+: g) b -> (f :+: g) a #

# 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

Instances details

Functor Line # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> Line a -> Line b # (<$) :: a -> Line b -> Line a #
Line :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: Line a -> BasicIO a
Line :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Line a -> Haskeline a
Line :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: Line a -> Pure a
Run IO Line # |
Instance details Defined in System.Console.Wizard.BasicIO Methods runAlgebra :: Line (IO v) -> IO v #
Run (InputT IO) Line # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: Line (InputT IO v) -> InputT IO v #
Run (State PureState) Line # |
Instance details Defined in System.Console.Wizard.Pure Methods runAlgebra :: Line (State PureState v) -> State PureState v #

line :: forall (b :: Type -> Type). 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

Instances details

Functor LinePrewritten # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> LinePrewritten a -> LinePrewritten b # (<$) :: a -> LinePrewritten b -> LinePrewritten a #
LinePrewritten :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: LinePrewritten a -> Haskeline a
Run (InputT IO) LinePrewritten # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: LinePrewritten (InputT IO v) -> InputT IO v #

linePrewritten #

Arguments

:: forall (b :: Type -> Type). 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

Instances details

Functor Password # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> Password a -> Password b # (<$) :: a -> Password b -> Password a #
Password :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Password a -> Haskeline a
Run (InputT IO) Password # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: Password (InputT IO v) -> InputT IO v #

password #

Arguments

:: forall (b :: Type -> Type). 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

Instances details

Functor Character # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> Character a -> Character b # (<$) :: a -> Character b -> Character a #
Character :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: Character a -> BasicIO a
Character :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Character a -> Haskeline a
Character :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: Character a -> Pure a
Run IO Character # |
Instance details Defined in System.Console.Wizard.BasicIO Methods runAlgebra :: Character (IO v) -> IO v #
Run (InputT IO) Character # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: Character (InputT IO v) -> InputT IO v #
Run (State PureState) Character # |
Instance details Defined in System.Console.Wizard.Pure Methods runAlgebra :: Character (State PureState v) -> State PureState v #

character :: forall (b :: Type -> Type). 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

Instances details

Functor Output # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> Output a -> Output b # (<$) :: a -> Output b -> Output a #
Output :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: Output a -> BasicIO a
Output :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: Output a -> Haskeline a
Output :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: Output a -> Pure a
Run IO Output # |
Instance details Defined in System.Console.Wizard.BasicIO Methods runAlgebra :: Output (IO v) -> IO v #
Run (InputT IO) Output # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: Output (InputT IO v) -> InputT IO v #
Run (State PureState) Output # |
Instance details Defined in System.Console.Wizard.Pure Methods runAlgebra :: Output (State PureState v) -> State PureState v #

output :: forall (b :: Type -> Type). Output :<: b => String -> Wizard b () #

Output a string. Does not fail.

data OutputLn w #

#### Instances

Instances details

Functor OutputLn # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> OutputLn a -> OutputLn b # (<$) :: a -> OutputLn b -> OutputLn a #
OutputLn :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: OutputLn a -> BasicIO a
OutputLn :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: OutputLn a -> Haskeline a
OutputLn :<: Pure # |
Instance details Defined in System.Console.Wizard.Pure Methods inj :: OutputLn a -> Pure a
Run IO OutputLn # |
Instance details Defined in System.Console.Wizard.BasicIO Methods runAlgebra :: OutputLn (IO v) -> IO v #
Run (InputT IO) OutputLn # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: OutputLn (InputT IO v) -> InputT IO v #
Run (State PureState) OutputLn # |
Instance details Defined in System.Console.Wizard.Pure Methods runAlgebra :: OutputLn (State PureState v) -> State PureState v #

outputLn :: forall (b :: Type -> Type). OutputLn :<: b => String -> Wizard b () #

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

data ArbitraryIO w #

#### Instances

Instances details

Functor ArbitraryIO # |
Instance details Defined in System.Console.Wizard.Internal Methods fmap :: (a -> b) -> ArbitraryIO a -> ArbitraryIO b # (<$) :: a -> ArbitraryIO b -> ArbitraryIO a #
ArbitraryIO :<: BasicIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods inj :: ArbitraryIO a -> BasicIO a
ArbitraryIO :<: Haskeline # |
Instance details Defined in System.Console.Wizard.Haskeline Methods inj :: ArbitraryIO a -> Haskeline a
Run IO ArbitraryIO # |
Instance details Defined in System.Console.Wizard.BasicIO Methods runAlgebra :: ArbitraryIO (IO v) -> IO v #
Run (InputT IO) ArbitraryIO # |
Instance details Defined in System.Console.Wizard.Haskeline Methods runAlgebra :: ArbitraryIO (InputT IO v) -> InputT IO v #

# Modifiers

Modifiers change the behaviour of existing wizards.

retry :: forall (b :: Type -> Type) a. 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 :: forall (b :: Type -> Type) a. OutputLn :<: b => String -> Wizard b a -> Wizard b a #

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

defaultTo :: forall (b :: Type -> Type) a. 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 :: forall (b :: Type -> Type) a c. 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 :: forall (b :: Type -> Type) a. 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 :: forall (b :: Type -> Type) a. Functor b => Wizard b [a] -> Wizard b [a] #

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

inRange :: forall a (b :: Type -> Type). (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 :: forall a (b :: Type -> Type). (Read a, Functor b) => Wizard b String -> Wizard b a #

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

# Utility

liftMaybe :: forall (b :: Type -> Type) a. 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.

# Orphan instances

ArbitraryIO :<: b => MonadIO (Wizard b) # |
Instance details Methods liftIO :: IO a -> Wizard b a #