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

Constructors

Wizard (MaybeT (Free backend) a)

Instances

Instances details

ArbitraryIO :<: b => MonadIO (Wizard b) Source #
Instance details Defined in System.Console.Wizard Methods liftIO :: IO a -> Wizard b a #
Functor backend => Alternative (Wizard backend) Source #
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) Source #
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) Source #
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) Source #
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) Source #
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 Source #

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) Source #

Run a wizard using some back-end.

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

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

Coproduct of two functors

Instances

Instances details

(Functor f, Functor g) => f :<: (f :+: g) Source #
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) Source #
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) Source #
Instance details Defined in System.Console.Wizard.Internal Methods runAlgebra :: (f :+: g) (b v) -> b v Source #
(Functor f, Functor g) => Functor (f :+: g) Source #
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 Source #

Instances

Instances details

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

line :: forall (b :: Type -> Type). Line :<: b => PromptString -> Wizard b String Source #

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

data LinePrewritten w Source #

Instances

Instances details

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

linePrewritten Source #

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 Source #

Instances

Instances details

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

password Source #

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 Source #

Instances

Instances details

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

character :: forall (b :: Type -> Type). Character :<: b => PromptString -> Wizard b Char Source #

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

data Output w Source #

Instances

Instances details

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

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

Output a string. Does not fail.

data OutputLn w Source #

Instances

Instances details

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

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

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

data ArbitraryIO w Source #

Instances

Instances details

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

Modifiers

Modifiers change the behaviour of existing wizards.

retry :: forall (b :: Type -> Type) a. Functor b => Wizard b a -> Wizard b a Source #

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 Source #

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 Source #

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 Source #

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 Source #

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] Source #

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 Source #

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 Source #

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 Source #

Translate a maybe value into wizard success/failure.

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

Ensures that a maybe value satisfies a given predicate.

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

A read-based parser for the parser modifier.

Orphan instances

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