-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A high-powered, single-pass tree parser.
--
-- Please see the README on GitHub at
-- https://github.com/isovector/lasercutter#readme
@package lasercutter
@version 0.1.0.0
module Lasercutter.Types
-- | Lasercutter supports any inductive tree types, as witnessed by
-- getChildren.
class IsTree t
-- | Get all children of the current node.
getChildren :: IsTree t => t -> [t]
-- | A tree parser which runs all queries in a single pass. This is
-- accomplished via a free encoding of the applicative structure, which
-- can be arbitrarily reassociated for better performance.
data Parser bc t a
-- | The free pure constructor.
[Pure] :: a -> Parser bc t a
-- | The free liftA2 constructor. This is an inlining of Day
-- convolution.
[LiftA2] :: (b -> c -> a) -> Parser bc t b -> Parser bc t c -> Parser bc t a
-- | Get the breadcrumbs at the current part of the tree.
[GetCrumbs] :: Parser bc t bc
-- | Run the given parser at every subtree which matches the given
-- predicate. This is not recursive --- that is, a given subtree only
-- runs the given parser once, not in all further matching subtrees.
[Target] :: (t -> Bool) -> Parser bc t a -> Parser bc t [a]
-- | Run the given parser on each child of the current node.
[OnChildren] :: Parser bc t a -> Parser bc t [a]
-- | Get the current node.
[Current] :: Parser bc t t
-- | Swallow a parsed Maybe, failing the parser if it was
-- Nothing. Don't use this constructor explicitly; prefer
-- expect which maintains some invariants.
--
-- optional is the inverse to this parser.
[Expect] :: Parser bc t (Maybe a) -> Parser bc t a
-- | Immediately fail a parse. Equivalent to Expect (pure
-- Nothing).
[Fail] :: Parser bc t a
-- | Transform the type of tree that a Parser operates over.
mapTree :: (t -> t') -> Parser bc t' a -> Parser bc t a
-- | A parser to run on children, and a subsequent continuation for how to
-- parse the parent.
data Split bc t a
[Split] :: Parser bc t a -> ([a] -> Parser bc t b) -> Split bc t b
-- | Swallow a parsed Maybe, failing the parser if it was
-- Nothing.
--
-- Use try or optional as the inverse to this parser.
expect :: Parser bc t (Maybe a) -> Parser bc t a
-- | Like optional, but slightly more efficient.
try :: Parser bc t a -> Parser bc t (Maybe a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Lasercutter.Types.Parser bc t a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Lasercutter.Types.Parser bc t a)
instance GHC.Show.Show (Lasercutter.Types.Parser bc t a)
instance GHC.Base.Functor (Lasercutter.Types.Parser bc t)
instance GHC.Base.Applicative (Lasercutter.Types.Parser bc t)
instance GHC.Base.Alternative (Lasercutter.Types.Parser bc t)
instance Control.Selective.Selective (Lasercutter.Types.Parser bc t)
instance Witherable.Filterable (Lasercutter.Types.Parser bc t)
instance Data.Profunctor.Unsafe.Profunctor (Lasercutter.Types.Parser bc)
module Lasercutter.Internal
-- | Split a parser into a parser to run on the node's children, and how to
-- reassemble those pieces into a parser for the current node.
split :: bc -> Parser bc t a -> t -> Split bc t a
-- | There is no work to do for the children, so ignore them.
ignoreChildren :: Parser bc t b -> Split bc t b
-- | Append a continuation after a Split.
continue :: (Parser bc t a -> Parser bc t b) -> Split bc t a -> Split bc t b
-- | Parse the current node by splitting the parser, accumulating the
-- results of each child, and then running the continuation.
parseNode :: (Semigroup bc, IsTree t) => (t -> bc) -> bc -> Parser bc t a -> t -> Parser bc t a
-- | Run a parser on each child, accumulating the results.
parseChildren :: (IsTree t, Semigroup bc) => (t -> bc) -> bc -> Parser bc t a -> [t] -> [a]
-- | Extract a value from a parser. The way the applicative evaluates, all
-- "combinator" effects are guaranteed to have been run by the time this
-- function gets called.
getResult :: Parser bc t a -> Maybe a
-- | Run a parser over a tree in a single pass.
runParser :: (Monoid bc, IsTree t) => (t -> bc) -> t -> Parser bc t a -> Maybe a
-- | Transformer the breadcrumbs of a Parser.
mapBreadcrumbs :: (bc' -> bc) -> Parser bc t a -> Parser bc' t a
module Lasercutter
-- | A tree parser which runs all queries in a single pass. This is
-- accomplished via a free encoding of the applicative structure, which
-- can be arbitrarily reassociated for better performance.
data Parser bc t a
-- | Run a parser over a tree in a single pass.
runParser :: (Monoid bc, IsTree t) => (t -> bc) -> t -> Parser bc t a -> Maybe a
-- | Lasercutter supports any inductive tree types, as witnessed by
-- getChildren.
class IsTree t
-- | Get all children of the current node.
getChildren :: IsTree t => t -> [t]
-- | Get the current node.
self :: Parser bc t t
-- | Project a value out of the current node. This is the main way to build
-- primitive parsers.
--
--
proj :: (t -> a) -> Parser bc t a
-- | Swallow a parsed Maybe, failing the parser if it was
-- Nothing.
--
-- Use try or optional as the inverse to this parser.
expect :: Parser bc t (Maybe a) -> Parser bc t a
-- | Get the first result of a list of results, failing if there are none.
--
--
one :: Parser bc t [a] -> Parser bc t a
-- | Like optional, but slightly more efficient.
try :: Parser bc t a -> Parser bc t (Maybe a)
-- | The identity of <|>
empty :: Alternative f => f a
-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
infixl 3 <|>
-- | Run the given parser on every immediate child of the current node.
onChildren :: Parser bc t a -> Parser bc t [a]
-- | Run a parser on the immediate children of the current node, returning
-- the first success.
--
--
onSingleChild :: Parser bc t a -> Parser bc t (Maybe a)
-- | Run the given parser on every predicate-satisfying subtree of the
-- current node. This combinator is not recursive --- that is, if the
-- predicate is satisfied by both a node and its descendent, the
-- descendent *will not* receive the parser.
target :: (t -> Bool) -> Parser bc t a -> Parser bc t [a]
-- | Run the given function on every subtree, accumulating those which
-- return Just.
targetMap :: (t -> Maybe a) -> Parser bc t [a]
-- | when pc pa returns pa when pc
-- evaluates to True, failing otherwise.
when :: Parser bc t Bool -> Parser bc t a -> Parser bc t a
-- | whenNode f pa returns pa when pc
-- evaluates to True on the current node, failing otherwise.
--
--
whenNode :: (t -> Bool) -> Parser bc t a -> Parser bc t a
-- | Branch on a Boolean value, skipping unnecessary effects.
ifS :: Selective f => f Bool -> f a -> f a -> f a
-- | ifNode f pt pf runs pt when f
-- evaluates to True on the current node, running pf
-- otherwise.
--
--
ifNode :: (t -> Bool) -> Parser bc t a -> Parser bc t a -> Parser bc t a
-- | Get the breadcrumbs at the current node. This is useful for refining
-- the coarse-grained matches of target by restricting matches to
-- certain subtrees.
breadcrumbs :: Parser bc t bc
-- | Get a value computed on the current breadcrumbs.
--
--
onBreadcrumbs :: (bc -> a) -> Parser bc t a
-- | Transformer the breadcrumbs of a Parser.
mapBreadcrumbs :: (bc' -> bc) -> Parser bc t a -> Parser bc' t a
-- | Map over both arguments at the same time.
--
--
-- dimap f g ≡ lmap f . rmap g
--
dimap :: Profunctor p => (a -> b) -> (c -> d) -> p b c -> p a d
-- | Map the second argument covariantly.
--
--
-- rmap ≡ dimap id
--
rmap :: Profunctor p => (b -> c) -> p a b -> p a c
-- | Map the first argument contravariantly.
--
--
-- lmap f ≡ dimap f id
--
lmap :: Profunctor p => (a -> b) -> p b c -> p a c
-- | Lift a binary function to actions.
--
-- Some functors support an implementation of liftA2 that is more
-- efficient than the default one. In particular, if fmap is an
-- expensive operation, it is likely better to use liftA2 than to
-- fmap over the structure and then use <*>.
--
-- This became a typeclass method in 4.10.0.0. Prior to that, it was a
-- function defined in terms of <*> and fmap.
--
-- Using ApplicativeDo: 'liftA2 f as bs' can be
-- understood as the do expression
--
--
-- do a <- as
-- b <- bs
-- pure (f a b)
--
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)
-- | Conditional failure of Alternative computations. Defined by
--
--
-- guard True = pure ()
-- guard False = empty
--
--
-- Examples
--
-- Common uses of guard include conditionally signaling an error
-- in an error monad and conditionally rejecting the current choice in an
-- Alternative-based parser.
--
-- As an example of signaling an error in the error monad Maybe,
-- consider a safe division function safeDiv x y that returns
-- Nothing when the denominator y is zero and
-- Just (x `div` y) otherwise. For example:
--
--
-- >>> safeDiv 4 0
-- Nothing
-- >>> safeDiv 4 2
-- Just 2
--
--
-- A definition of safeDiv using guards, but not guard:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y | y /= 0 = Just (x `div` y)
-- | otherwise = Nothing
--
--
-- A definition of safeDiv using guard and Monad
-- do-notation:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y = do
-- guard (y /= 0)
-- return (x `div` y)
--
guard :: Alternative f => Bool -> f ()
-- | The sum of a collection of actions, generalizing concat.
--
--
-- >>> asum [Just "Hello", Nothing, Just "World"]
-- Just "Hello"
--
asum :: (Foldable t, Alternative f) => t (f a) -> f a
-- | Like mapMaybe.
mapMaybe :: Filterable f => (a -> Maybe b) -> f a -> f b
-- |
-- catMaybes ≡ mapMaybe id
--
catMaybes :: Filterable f => f (Maybe a) -> f a
select :: Selective f => f (Either a b) -> f (a -> b) -> f b
-- | An operator alias for select, which is sometimes convenient. It
-- tries to follow the notational convention for Applicative
-- operators. The angle bracket pointing to the left means we always use
-- the corresponding value. The value on the right, however, may be
-- skipped, hence the question mark.
(<*?) :: Selective f => f (Either a b) -> f (a -> b) -> f b
infixl 4 <*?
-- | The branch function is a natural generalisation of
-- select: instead of skipping an unnecessary effect, it chooses
-- which of the two given effectful functions to apply to a given
-- argument; the other effect is unnecessary. It is possible to implement
-- branch in terms of select, which is a good puzzle (give
-- it a try!).
--
-- We can also implement select via branch:
--
--
-- selectB :: Selective f => f (Either a b) -> f (a -> b) -> f b
-- selectB x y = branch x y (pure id)
--
branch :: Selective f => f (Either a b) -> f (a -> c) -> f (b -> c) -> f c
-- | A lifted version of fromMaybe.
fromMaybeS :: Selective f => f a -> f (Maybe a) -> f a
-- | Return the first Right value. If both are Left's,
-- accumulate errors.
orElse :: (Selective f, Semigroup e) => f (Either e a) -> f (Either e a) -> f (Either e a)
-- | Accumulate the Right values, or return the first
-- Left.
andAlso :: (Selective f, Semigroup a) => f (Either e a) -> f (Either e a) -> f (Either e a)
-- | A lifted version of lazy Boolean OR.
(<||>) :: Selective f => f Bool -> f Bool -> f Bool
-- | A lifted version of lazy Boolean AND.
(<&&>) :: Selective f => f Bool -> f Bool -> f Bool
-- | Generalised folding with the short-circuiting behaviour.
foldS :: (Selective f, Foldable t, Monoid a) => t (f (Either e a)) -> f (Either e a)
-- | A lifted version of any. Retains the short-circuiting
-- behaviour.
anyS :: Selective f => (a -> f Bool) -> [a] -> f Bool
-- | A lifted version of all. Retains the short-circuiting
-- behaviour.
allS :: Selective f => (a -> f Bool) -> [a] -> f Bool
-- | A restricted version of monadic bind. Fails with an error if the
-- Bounded and Enum instances for a do not cover
-- all values of a.
bindS :: (Bounded a, Enum a, Eq a, Selective f) => f a -> (a -> f b) -> f b