From 4f5c6ad897facc7a7f01211e272657f13d7c324c Mon Sep 17 00:00:00 2001
From: Julien Moutinho <julm+symantic-parser@sourcephile.fr>
Date: Fri, 30 Apr 2021 12:46:06 +0200
Subject: [PATCH] machine: improve comments
---
src/Symantic/Parser/Grammar/Combinators.hs | 2 ++
src/Symantic/Parser/Machine/Generate.hs | 25 ++++++++++++----------
2 files changed, 16 insertions(+), 11 deletions(-)
diff --git a/src/Symantic/Parser/Grammar/Combinators.hs b/src/Symantic/Parser/Grammar/Combinators.hs
index e3cd7f6..b07875b 100644
--- a/src/Symantic/Parser/Grammar/Combinators.hs
+++ b/src/Symantic/Parser/Grammar/Combinators.hs
@@ -449,8 +449,10 @@ data instance Failure CombMatchable
-- * Class 'CombSatisfiable'
class CombSatisfiable tok repr where
+ -- | Like 'satisfyOrFail' but with no custom failure.
satisfy :: TermGrammar (tok -> Bool) -> repr tok
satisfy = satisfyOrFail Set.empty
+ -- | Like 'satisfy' but with a custom set of 'SomeFailure's.
satisfyOrFail ::
Set SomeFailure ->
TermGrammar (tok -> Bool) -> repr tok
diff --git a/src/Symantic/Parser/Machine/Generate.hs b/src/Symantic/Parser/Machine/Generate.hs
index a44676f..a268294 100644
--- a/src/Symantic/Parser/Machine/Generate.hs
+++ b/src/Symantic/Parser/Machine/Generate.hs
@@ -156,10 +156,12 @@ runGenAnalysis ::
runGenAnalysis ga = (($ []) <$>) $ polyfix ga
-- | Poly-variadic fixpoint combinator.
--- Used to express mutual recursion and to transparently introduce memoization.
--- Used to "tie the knot" between observed sharing ('defLet', 'call', 'jump')
--- and join points ('defJoin', 'refJoin').
--- All mutually dependent functions are restricted to the same polymorphic type @(a)@.
+-- Used to express mutual recursion and to transparently introduce memoization,
+-- more precisely to "tie the knot"
+-- between observed sharing ('defLet', 'call', 'jump')
+-- and also between join points ('defJoin', 'refJoin').
+-- Because it's enough for its usage here,
+-- all mutually dependent functions are restricted to the same polymorphic type @(a)@.
-- See http://okmij.org/ftp/Computation/fixed-point-combinators.html#Poly-variadic
polyfix :: Functor f => f (f a -> a) -> f a
polyfix fs = fix $ \finals -> ($ finals) <$> fs
@@ -181,8 +183,8 @@ type Offset = Int
-- | Minimal input length required for a successful parsing.
type Horizon = Offset
--- seqGenAnalysis =
-- altGenAnalysis = List.foldl' (\acc x -> either Left (\h -> Right (either (const h) (min h) acc)) x)
+-- | Merge given 'GenAnalysis' as sequences.
seqGenAnalysis :: NonEmpty GenAnalysis -> GenAnalysis
seqGenAnalysis aas@(a:|as) = GenAnalysis
{ minReads = List.foldl' (\acc x ->
@@ -190,6 +192,7 @@ seqGenAnalysis aas@(a:|as) = GenAnalysis
) (minReads a) as
, mayRaise = sconcat (mayRaise <$> aas)
}
+-- | Merge given 'GenAnalysis' as alternatives.
altGenAnalysis :: NonEmpty GenAnalysis -> GenAnalysis
altGenAnalysis aas@(a:|as) = GenAnalysis
{ minReads = List.foldl' (\acc x ->
@@ -361,7 +364,8 @@ instance InstrExceptionable Gen where
let _ = $$(liftTypedString ("catch.ko "<>show exn)) in
$$({-trace ("unGen.catch.ko: "<>show exn) $-} unGen ko ctx
-- Push 'input' and 'checkedHorizon'
- -- as they were when entering 'catch'.
+ -- as they were when entering 'catch',
+ -- they will be available to 'loadInput', if any.
{ valueStack =
ValueStackCons (H.Term (input ctx)) $
--ValueStackCons (H.Term [||exn||]) $
@@ -371,12 +375,11 @@ instance InstrExceptionable Gen where
-- Note that 'catchStackByLabel' is reset.
-- Move the input to the failing position.
, input = [||failInp||]
- -- The 'checkedHorizon' at the 'raise's
- -- are not known here.
- -- Nor whether 'failInp' is after
- -- 'checkedHorizon' 'ctx' or not.
+ -- The 'checkedHorizon' at the 'raise's are not known here.
+ -- Nor whether 'failInp' is after 'checkedHorizon' or not.
+ -- Hence fallback to a safe value.
, checkedHorizon = 0
- -- Set the farthestInput to the farthest computed by 'fail'.
+ -- Set the farthestInput to the farthest computed in 'fail'.
, farthestInput = [||farInp||]
, farthestExpecting = [||farExp||]
})
--
2.47.2