-- | This module contains an arrow interface for option parsers, which allows

-- to define and combine parsers using the arrow notation and arrow

-- combinators.

--

-- The arrow syntax is particularly useful to create parsers of nested

-- structures, or records where the order of fields is different from the order

-- in which the parsers should be applied.

--

-- For example, an 'Options.Applicative.Builder.arguments` parser often needs

-- to be applied last, and that makes it inconvenient to use it for a field

-- which is not the last one in a record.

--

-- Using the arrow syntax and the functions in this module, one can write, e.g.:

--

-- > data Options = Options

-- >   { optArgs :: [String]

-- >   , optVerbose :: Bool }

-- >

-- > opts :: Parser Options

-- > opts = runA $ proc () -> do

-- >   verbose <- asA (switch (short 'v')) -< ()

-- >   args <- asA (arguments str idm) -< ()

-- >   returnA -< Options args verbose

--

-- Parser arrows, created out of regular 'Parser' values using the 'asA'

-- function, are arrows taking @()@ as argument and returning the parsed value.

module Options.Applicative.Arrows (

  module Control.Arrow,

  A(..),

  asA,

  runA,

  ParserA,

  ) where

import Control.Arrow

import Control.Category (Category(..))

import Options.Applicative

import Prelude hiding ((.), id)

-- | For any 'Applicative' functor @f@, @A f@ is the 'Arrow' instance

-- associated to @f@.

--

-- The 'A' constructor can be used to convert a value of type @f (a -> b)@ into

-- an arrow.

newtype A f a b = A

  { unA :: f (a -> b) }

-- | Convert a value of type @f a@ into an arrow taking @()@ as argument.

--

-- Applied to a value of type 'Parser', it turns it into an arrow that can be

-- used inside an arrow command, or passed to arrow combinators.

asA :: Applicative f => f a -> A f () a

asA x = A $ const <$> x

-- | Convert an arrow back to an applicative value.

--

-- This function can be used to return a result of type 'Parser' from an arrow

-- command.

runA :: Applicative f => A f () a -> f a

runA a = unA a <*> pure ()

instance Applicative f => Category (A f) where

  id = A $ pure id

  -- use reverse composition, because we want effects to run from

  -- top to bottom in the arrow syntax

  (A f) . (A g) = A $ flip (.) <$> g <*> f

instance Applicative f => Arrow (A f) where

  arr = A . pure

  first (A f) = A $ first <$> f

-- | The type of arrows associated to the applicative 'Parser' functor.

type ParserA = A Parser