{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE Unsafe #-}

-- |
-- Module      :  Text.Megaparsec.Debug
-- Copyright   :  © 2015–present Megaparsec contributors
-- License     :  FreeBSD
--
-- Maintainer  :  Mark Karpov <markkarpov92@gmail.com>
-- Stability   :  experimental
-- Portability :  portable
--
-- Debugging helpers.
--
-- @since 7.0.0
module Text.Megaparsec.Debug
  ( dbg,
    dbg',
  )
where

import qualified Data.List.NonEmpty as NE
import Data.Proxy
import Debug.Trace
import Text.Megaparsec.Error
import Text.Megaparsec.Internal
import Text.Megaparsec.State
import Text.Megaparsec.Stream

-- | @'dbg' label p@ parser works exactly like @p@, but when it's evaluated
-- it prints information useful for debugging. The @label@ is only used to
-- refer to this parser in the debugging output. This combinator uses the
-- 'trace' function from "Debug.Trace" under the hood.
--
-- Typical usage is to wrap every sub-parser in misbehaving parser with
-- 'dbg' assigning meaningful labels. Then give it a shot and go through the
-- print-out. As of current version, this combinator prints all available
-- information except for /hints/, which are probably only interesting to
-- the maintainer of Megaparsec itself and may be quite verbose to output in
-- general. Let me know if you would like to be able to see hints in the
-- debugging output.
--
-- The output itself is pretty self-explanatory, although the following
-- abbreviations should be clarified (they are derived from the low-level
-- source code):
--
--     * @COK@—“consumed OK”. The parser consumed input and succeeded.
--     * @CERR@—“consumed error”. The parser consumed input and failed.
--     * @EOK@—“empty OK”. The parser succeeded without consuming input.
--     * @EERR@—“empty error”. The parser failed without consuming input.
--
-- Finally, it's not possible to lift this function into some monad
-- transformers without introducing surprising behavior (e.g. unexpected
-- state backtracking) or adding otherwise redundant constraints (e.g.
-- 'Show' instance for state), so this helper is only available for
-- 'ParsecT' monad, not any instance of 'Text.Megaparsec.MonadParsec' in
-- general.
dbg ::
  forall e s m a.
  ( VisualStream s,
    ShowErrorComponent e,
    Show a
  ) =>
  -- | Debugging label
  String ->
  -- | Parser to debug
  ParsecT e s m a ->
  -- | Parser that prints debugging messages
  ParsecT e s m a
dbg :: forall e s (m :: * -> *) a.
(VisualStream s, ShowErrorComponent e, Show a) =>
String -> ParsecT e s m a -> ParsecT e s m a
dbg String
lbl ParsecT e s m a
p = forall e s (m :: * -> *) a.
(forall b.
 State s e
 -> (a -> State s e -> Hints (Token s) -> m b)
 -> (ParseError s e -> State s e -> m b)
 -> (a -> State s e -> Hints (Token s) -> m b)
 -> (ParseError s e -> State s e -> m b)
 -> m b)
-> ParsecT e s m a
ParsecT forall a b. (a -> b) -> a -> b
$ \State s e
s a -> State s e -> Hints (Token s) -> m b
cok ParseError s e -> State s e -> m b
cerr a -> State s e -> Hints (Token s) -> m b
eok ParseError s e -> State s e -> m b
eerr ->
  let l :: DbgItem s e a -> String
l = forall s e a.
(VisualStream s, ShowErrorComponent e, Show a) =>
String -> DbgItem s e a -> String
dbgLog String
lbl :: DbgItem s e a -> String
      unfold :: s -> [Token s]
unfold = forall s. Stream s => Int -> s -> [Token s]
streamTake Int
40
      cok' :: a -> State s e -> Hints (Token s) -> m b
cok' a
x State s e
s' Hints (Token s)
hs =
        forall a b c. (a -> b -> c) -> b -> a -> c
flip forall a. String -> a -> a
trace (a -> State s e -> Hints (Token s) -> m b
cok a
x State s e
s' Hints (Token s)
hs) forall a b. (a -> b) -> a -> b
$
          DbgItem s e a -> String
l (forall s e a. [Token s] -> DbgItem s e a
DbgIn (s -> [Token s]
unfold (forall s e. State s e -> s
stateInput State s e
s)))
            forall a. [a] -> [a] -> [a]
++ DbgItem s e a -> String
l (forall s e a. [Token s] -> a -> DbgItem s e a
DbgCOK (forall s. Stream s => Int -> s -> [Token s]
streamTake (forall s e. State s e -> State s e -> Int
streamDelta State s e
s State s e
s') (forall s e. State s e -> s
stateInput State s e
s)) a
x)
      cerr' :: ParseError s e -> State s e -> m b
cerr' ParseError s e
err State s e
s' =
        forall a b c. (a -> b -> c) -> b -> a -> c
flip forall a. String -> a -> a
trace (ParseError s e -> State s e -> m b
cerr ParseError s e
err State s e
s') forall a b. (a -> b) -> a -> b
$
          DbgItem s e a -> String
l (forall s e a. [Token s] -> DbgItem s e a
DbgIn (s -> [Token s]
unfold (forall s e. State s e -> s
stateInput State s e
s)))
            forall a. [a] -> [a] -> [a]
++ DbgItem s e a -> String
l (forall s e a. [Token s] -> ParseError s e -> DbgItem s e a
DbgCERR (forall s. Stream s => Int -> s -> [Token s]
streamTake (forall s e. State s e -> State s e -> Int
streamDelta State s e
s State s e
s') (forall s e. State s e -> s
stateInput State s e
s)) ParseError s e
err)
      eok' :: a -> State s e -> Hints (Token s) -> m b
eok' a
x State s e
s' Hints (Token s)
hs =
        forall a b c. (a -> b -> c) -> b -> a -> c
flip forall a. String -> a -> a
trace (a -> State s e -> Hints (Token s) -> m b
eok a
x State s e
s' Hints (Token s)
hs) forall a b. (a -> b) -> a -> b
$
          DbgItem s e a -> String
l (forall s e a. [Token s] -> DbgItem s e a
DbgIn (s -> [Token s]
unfold (forall s e. State s e -> s
stateInput State s e
s)))
            forall a. [a] -> [a] -> [a]
++ DbgItem s e a -> String
l (forall s e a. [Token s] -> a -> DbgItem s e a
DbgEOK (forall s. Stream s => Int -> s -> [Token s]
streamTake (forall s e. State s e -> State s e -> Int
streamDelta State s e
s State s e
s') (forall s e. State s e -> s
stateInput State s e
s)) a
x)
      eerr' :: ParseError s e -> State s e -> m b
eerr' ParseError s e
err State s e
s' =
        forall a b c. (a -> b -> c) -> b -> a -> c
flip forall a. String -> a -> a
trace (ParseError s e -> State s e -> m b
eerr ParseError s e
err State s e
s') forall a b. (a -> b) -> a -> b
$
          DbgItem s e a -> String
l (forall s e a. [Token s] -> DbgItem s e a
DbgIn (s -> [Token s]
unfold (forall s e. State s e -> s
stateInput State s e
s)))
            forall a. [a] -> [a] -> [a]
++ DbgItem s e a -> String
l (forall s e a. [Token s] -> ParseError s e -> DbgItem s e a
DbgEERR (forall s. Stream s => Int -> s -> [Token s]
streamTake (forall s e. State s e -> State s e -> Int
streamDelta State s e
s State s e
s') (forall s e. State s e -> s
stateInput State s e
s)) ParseError s e
err)
   in forall e s (m :: * -> *) a.
ParsecT e s m a
-> forall b.
   State s e
   -> (a -> State s e -> Hints (Token s) -> m b)
   -> (ParseError s e -> State s e -> m b)
   -> (a -> State s e -> Hints (Token s) -> m b)
   -> (ParseError s e -> State s e -> m b)
   -> m b
unParser ParsecT e s m a
p State s e
s a -> State s e -> Hints (Token s) -> m b
cok' ParseError s e -> State s e -> m b
cerr' a -> State s e -> Hints (Token s) -> m b
eok' ParseError s e -> State s e -> m b
eerr'

-- | Just like 'dbg', but doesn't require the return value of the parser to
-- be 'Show'-able.
--
-- @since 9.1.0
dbg' ::
  forall e s m a.
  ( VisualStream s,
    ShowErrorComponent e
  ) =>
  -- | Debugging label
  String ->
  -- | Parser to debug
  ParsecT e s m a ->
  -- | Parser that prints debugging messages
  ParsecT e s m a
dbg' :: forall e s (m :: * -> *) a.
(VisualStream s, ShowErrorComponent e) =>
String -> ParsecT e s m a -> ParsecT e s m a
dbg' String
lbl ParsecT e s m a
p = forall x. Blind x -> x
unBlind forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall e s (m :: * -> *) a.
(VisualStream s, ShowErrorComponent e, Show a) =>
String -> ParsecT e s m a -> ParsecT e s m a
dbg String
lbl (forall x. x -> Blind x
Blind forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> ParsecT e s m a
p)

-- | A wrapper type with a dummy 'Show' instance.
newtype Blind x = Blind {forall x. Blind x -> x
unBlind :: x}

instance Show (Blind x) where
  show :: Blind x -> String
show Blind x
_ = String
"NOT SHOWN"

-- | A single piece of info to be rendered with 'dbgLog'.
data DbgItem s e a
  = DbgIn [Token s]
  | DbgCOK [Token s] a
  | DbgCERR [Token s] (ParseError s e)
  | DbgEOK [Token s] a
  | DbgEERR [Token s] (ParseError s e)

-- | Render a single piece of debugging info.
dbgLog ::
  forall s e a.
  (VisualStream s, ShowErrorComponent e, Show a) =>
  -- | Debugging label
  String ->
  -- | Information to render
  DbgItem s e a ->
  -- | Rendered result
  String
dbgLog :: forall s e a.
(VisualStream s, ShowErrorComponent e, Show a) =>
String -> DbgItem s e a -> String
dbgLog String
lbl DbgItem s e a
item = ShowS
prefix String
msg
  where
    prefix :: ShowS
prefix = [String] -> String
unlines forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((String
lbl forall a. [a] -> [a] -> [a]
++ String
"> ") forall a. [a] -> [a] -> [a]
++) forall b c a. (b -> c) -> (a -> b) -> a -> c
. String -> [String]
lines
    pxy :: Proxy s
pxy = forall {k} (t :: k). Proxy t
Proxy :: Proxy s
    msg :: String
msg = case DbgItem s e a
item of
      DbgIn [Token s]
ts ->
        String
"IN: " forall a. [a] -> [a] -> [a]
++ forall s. VisualStream s => Proxy s -> [Token s] -> String
showStream Proxy s
pxy [Token s]
ts
      DbgCOK [Token s]
ts a
a ->
        String
"MATCH (COK): " forall a. [a] -> [a] -> [a]
++ forall s. VisualStream s => Proxy s -> [Token s] -> String
showStream Proxy s
pxy [Token s]
ts forall a. [a] -> [a] -> [a]
++ String
"\nVALUE: " forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> String
show a
a
      DbgCERR [Token s]
ts ParseError s e
e ->
        String
"MATCH (CERR): " forall a. [a] -> [a] -> [a]
++ forall s. VisualStream s => Proxy s -> [Token s] -> String
showStream Proxy s
pxy [Token s]
ts forall a. [a] -> [a] -> [a]
++ String
"\nERROR:\n" forall a. [a] -> [a] -> [a]
++ forall s e.
(VisualStream s, ShowErrorComponent e) =>
ParseError s e -> String
parseErrorPretty ParseError s e
e
      DbgEOK [Token s]
ts a
a ->
        String
"MATCH (EOK): " forall a. [a] -> [a] -> [a]
++ forall s. VisualStream s => Proxy s -> [Token s] -> String
showStream Proxy s
pxy [Token s]
ts forall a. [a] -> [a] -> [a]
++ String
"\nVALUE: " forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> String
show a
a
      DbgEERR [Token s]
ts ParseError s e
e ->
        String
"MATCH (EERR): " forall a. [a] -> [a] -> [a]
++ forall s. VisualStream s => Proxy s -> [Token s] -> String
showStream Proxy s
pxy [Token s]
ts forall a. [a] -> [a] -> [a]
++ String
"\nERROR:\n" forall a. [a] -> [a] -> [a]
++ forall s e.
(VisualStream s, ShowErrorComponent e) =>
ParseError s e -> String
parseErrorPretty ParseError s e
e

-- | Pretty-print a list of tokens.
showStream :: VisualStream s => Proxy s -> [Token s] -> String
showStream :: forall s. VisualStream s => Proxy s -> [Token s] -> String
showStream Proxy s
pxy [Token s]
ts =
  case forall a. [a] -> Maybe (NonEmpty a)
NE.nonEmpty [Token s]
ts of
    Maybe (NonEmpty (Token s))
Nothing -> String
"<EMPTY>"
    Just NonEmpty (Token s)
ne ->
      let (String
h, String
r) = forall a. Int -> [a] -> ([a], [a])
splitAt Int
40 (forall s. VisualStream s => Proxy s -> NonEmpty (Token s) -> String
showTokens Proxy s
pxy NonEmpty (Token s)
ne)
       in if forall (t :: * -> *) a. Foldable t => t a -> Bool
null String
r then String
h else String
h forall a. [a] -> [a] -> [a]
++ String
" <…>"

-- | Calculate number of consumed tokens given 'State' of parser before and
-- after parsing.
streamDelta ::
  -- | State of parser before consumption
  State s e ->
  -- | State of parser after consumption
  State s e ->
  -- | Number of consumed tokens
  Int
streamDelta :: forall s e. State s e -> State s e -> Int
streamDelta State s e
s0 State s e
s1 = forall s e. State s e -> Int
stateOffset State s e
s1 forall a. Num a => a -> a -> a
- forall s e. State s e -> Int
stateOffset State s e
s0

-- | Extract a given number of tokens from the stream.
streamTake :: forall s. Stream s => Int -> s -> [Token s]
streamTake :: forall s. Stream s => Int -> s -> [Token s]
streamTake Int
n s
s =
  case forall a b. (a, b) -> a
fst forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall s. Stream s => Int -> s -> Maybe (Tokens s, s)
takeN_ Int
n s
s of
    Maybe (Tokens s)
Nothing -> []
    Just Tokens s
chk -> forall s. Stream s => Proxy s -> Tokens s -> [Token s]
chunkToTokens (forall {k} (t :: k). Proxy t
Proxy :: Proxy s) Tokens s
chk