From 5af2af5c912cf369f37de3c53f33b4f2d4b9cc48 Mon Sep 17 00:00:00 2001 From: Jamie Willis Date: Sat, 28 Dec 2024 14:06:01 +0000 Subject: [PATCH] feat(debug)!: removed some unneeded functionality for cleaner API, can be accessed via parsley --- .../scala/parsley/debugger/DebugTree.scala | 4 +- .../scala/parsley/debugger/ParseAttempt.scala | 2 +- .../scala/parsley/debugger/combinator.scala | 79 ++++++++----------- .../debugger/frontend/DebugFrontend.scala | 2 +- 4 files changed, 38 insertions(+), 49 deletions(-) diff --git a/parsley-debug/shared/src/main/scala/parsley/debugger/DebugTree.scala b/parsley-debug/shared/src/main/scala/parsley/debugger/DebugTree.scala index 5bb341426..d88d84461 100644 --- a/parsley-debug/shared/src/main/scala/parsley/debugger/DebugTree.scala +++ b/parsley-debug/shared/src/main/scala/parsley/debugger/DebugTree.scala @@ -20,7 +20,7 @@ package parsley.debugger * * @since 4.5.0 */ -trait DebugTree extends Iterable[DebugTree] { +private [debugger] abstract class DebugTree extends Iterable[DebugTree] { /** The name of the parser that made this node. */ def parserName: String @@ -66,7 +66,7 @@ trait DebugTree extends Iterable[DebugTree] { } } -object DebugTree { +private [debugger] object DebugTree { def unapply(dt: DebugTree): Some[(String, String, Option[Long], String, Option[ParseAttempt], Map[String, DebugTree])] = { Some((dt.parserName, dt.internalName, dt.childNumber, dt.fullInput, dt.parseResults, dt.nodeChildren)) } diff --git a/parsley-debug/shared/src/main/scala/parsley/debugger/ParseAttempt.scala b/parsley-debug/shared/src/main/scala/parsley/debugger/ParseAttempt.scala index 63ffd1226..414fa682f 100644 --- a/parsley-debug/shared/src/main/scala/parsley/debugger/ParseAttempt.scala +++ b/parsley-debug/shared/src/main/scala/parsley/debugger/ParseAttempt.scala @@ -13,7 +13,7 @@ import ParseAttempt._ // scalastyle:ignore underscore.import * * @since 4.5.0 */ -final class ParseAttempt private [parsley] (inp: Input, fof: Offset, tof: Offset, fps: Pos, tps: Pos, scs: Success, res: Result) { +private [parsley] final class ParseAttempt private [parsley] (inp: Input, fof: Offset, tof: Offset, fps: Pos, tps: Pos, scs: Success, res: Result) { /** The input parsed, as raw text. */ val rawInput: Input = inp diff --git a/parsley-debug/shared/src/main/scala/parsley/debugger/combinator.scala b/parsley-debug/shared/src/main/scala/parsley/debugger/combinator.scala index 2c8d5947a..f10f76e39 100644 --- a/parsley-debug/shared/src/main/scala/parsley/debugger/combinator.scala +++ b/parsley-debug/shared/src/main/scala/parsley/debugger/combinator.scala @@ -7,7 +7,7 @@ package parsley.debugger import parsley.Parsley import parsley.Parsley.{atomic, empty, fresh} -import parsley.debugger.frontend.DebugFrontend +import parsley.debugger.frontend.{DebugFrontend, ReusableFrontend} import parsley.debugger.internal.{DebugContext, DivergenceContext} import parsley.internal.deepembedding.frontend.LazyParsley @@ -23,7 +23,7 @@ object combinator { private [debugger] val defaultRules: Seq[Any => Boolean] = Seq(_.isInstanceOf[Function[_, _]]) /** Shorthand representation of a pair of a tree extraction function and a debugged parser. */ - type DebuggedPair[+A] = (() => DebugTree, Parsley[A]) + private type DebuggedPair[+A] = (() => DebugTree, Parsley[A]) /** Attaches a debugger to a parser, returning a reference to the debug tree produced by * the parser's parse tree formed as it runs. @@ -77,7 +77,7 @@ object combinator { * @tparam A Output type of original parser. * @return A pair of the finalised tree, and the instrumented parser. */ - def attachDebugger[A](parser: Parsley[A], toStringRules: Seq[Any => Boolean]): DebuggedPair[A] = { + private [parsley] def attachDebugger[A](parser: Parsley[A], toStringRules: Seq[Any => Boolean]): DebuggedPair[A] = { val context: DebugContext = new DebugContext(toStringRules) val attached: LazyParsley[A] = TaggedWith.tagRecursively(parser.internal, new Debugging(context)) @@ -96,7 +96,7 @@ object combinator { resetter *> new Parsley(attached) } - /** Attaches a debugger to a parser. + /* Attaches a debugger to a parser. * * This assumes the default rules of converting only lambdas and closures into strings when * storing in the output debug tree. @@ -110,10 +110,10 @@ object combinator { * @tparam A Output type of original parser. * @return A pair of the finalised tree, and the instrumented parser. */ - def attachDebugger[A](parser: Parsley[A]): DebuggedPair[A] = attachDebugger[A](parser, defaultRules) + private [parsley] def attachDebugger[A](parser: Parsley[A]): DebuggedPair[A] = attachDebugger[A](parser, defaultRules) // $COVERAGE-OFF$ - /** Create a closure that freshly attaches a debugger to a parser every time it is called. + /* Create a closure that freshly attaches a debugger to a parser every time it is called. * This is used for creating debugged parsers that can be used as children to multiple parent * parsers, as using the same debugged parser as a child to multiple parsers is unsafe. * @@ -126,9 +126,9 @@ object combinator { * * @return Generator closure for debugged versions of the input parser. */ - def attachReusable[A](parser: Parsley[A], toStringRules: Seq[Any => Boolean]): () => DebuggedPair[A] = () => attachDebugger[A](parser, toStringRules) + //private def attachReusable[A](parser: Parsley[A], toStringRules: Seq[Any => Boolean]): () => DebuggedPair[A] = () => attachDebugger[A](parser, toStringRules) - /** Create a closure that freshly attaches a debugger to a parser every time it is called. + /* Create a closure that freshly attaches a debugger to a parser every time it is called. * This is used for creating debugged parsers that can be used as children to multiple parent * parsers, as using the same debugged parser as a child to multiple parsers is unsafe. * @@ -142,8 +142,9 @@ object combinator { * has more information on its usage. * @return Generator closure for debugged versions of the input parser. */ - def attachReusable[A](parser: Parsley[A]): () => DebuggedPair[A] = attachReusable[A](parser, defaultRules) + //private def attachReusable[A](parser: Parsley[A]): () => DebuggedPair[A] = attachReusable[A](parser, defaultRules) + // TODO: fix docs by incorporating some of the base stuff above /** Attach a debugger and an explicitly-available frontend in which the debug tree should be * proessed with. * @@ -159,11 +160,6 @@ object combinator { * large amounts of memory to be used for processing the tree. * * @note Do not run a parser through this combinator multiple times. - * @see - * [[parsley.debugger.combinator$.attachDebugger[A](parser:parsley\.Parsley[A],toStringRules* attachDebugger]] - * for more information on how attachment works and things you may want - * to do before using this debug combinator, as well as some warnings on what not to do when - * using this debugger (such as regarding re-use of debugged parsers). * * @param parser The parser to debug. * @param frontend The frontend instance to render with. @@ -175,7 +171,7 @@ object combinator { * @return A modified parser which will ask the frontend to process the produced debug tree after * a call to [[Parsley.parse]] is made. */ - def attachWithFrontend[A](parser: Parsley[A], frontend: DebugFrontend, toStringRules: Seq[Any => Boolean]): Parsley[A] = { + def attach[A](parser: Parsley[A], frontend: DebugFrontend, toStringRules: Seq[Any => Boolean]): Parsley[A] = { val (tree, attached) = attachDebugger(parser, toStringRules) // Ideally, this should run 'attached', and render the tree regardless of the parser's success. @@ -199,7 +195,7 @@ object combinator { * @note Do not run a parser through this combinator multiple times. * @see * The other overload of this method - * ([[parsley.debugger.combinator$.attachWithFrontend[A](parser:parsley\.Parsley[A],frontend:parsley\.debugger\.frontend\.DebugFrontend,toStringRules* attachDebugger]]) + * ([[parsley.debugger.combinator$.attach[A](parser:parsley\.Parsley[A],frontend:parsley\.debugger\.frontend\.DebugFrontend,toStringRules* attachDebugger]]) * has more information on its usage. * @param parser The parser to debug. * @param frontend The frontend instance to render with. @@ -208,19 +204,17 @@ object combinator { * a call to [[Parsley.parse]] is made. * */ - def attachWithFrontend[A](parser: Parsley[A], frontend: DebugFrontend): Parsley[A] = attachWithFrontend[A](parser, frontend, defaultRules) + def attach[A](parser: Parsley[A], frontend: DebugFrontend): Parsley[A] = attach[A](parser, frontend, defaultRules) /** Create a closure that freshly attaches a debugger and a tree-processing frontend to a parser every * time it is called. * * @note Do not run a parser through this combinator multiple times. - * @see - * [[parsley.debugger.combinator$.attachReusable[A](parser:parsley\.Parsley[A],toStringRules* attachReusable]] * * @return Generator closure for frontend-debugged versions of the input parser. */ - def attachReusableWithFrontend[A](parser: Parsley[A], frontend: () => DebugFrontend, toStringRules: Seq[Any => Boolean]): () => Parsley[A] = { - () => attachWithFrontend(parser, frontend(), toStringRules) + def attachReusable[A](parser: Parsley[A], frontend: =>ReusableFrontend, toStringRules: Seq[Any => Boolean]): () => Parsley[A] = { + () => attach(parser, frontend, toStringRules) } /** Create a closure that freshly attaches a debugger and a tree-processing frontend to a parser every @@ -232,15 +226,13 @@ object combinator { * @note Do not run a parser through this combinator multiple times. * @see * The other overload of this method - * ([[parsley.debugger.combinator$.attachReusableWithFrontend[A](parser:parsley\.Parsley[A],frontend:()=>parsley\.debugger\.frontend\.DebugFrontend,toStringRules* attachDebugger]]) + * ([[parsley.debugger.combinator$.attachReusable[A](parser:parsley\.Parsley[A],frontend:=>parsley\.debugger\.frontend\.ReusableFrontend,toStringRules* attachDebugger]]) * has more information on its usage. * @return Generator closure for frontend-debugged versions of the input parser. */ - def attachReusableWithFrontend[A](parser: Parsley[A], frontend: () => DebugFrontend): () => Parsley[A] = { - attachReusableWithFrontend[A](parser, frontend, defaultRules) - } + def attachReusable[A](parser: Parsley[A], frontend: =>ReusableFrontend): () => Parsley[A] = attachReusable[A](parser, frontend, defaultRules) - /** Attach a debugger and an implicitly-available frontend in which the debug tree should be + /* Attach a debugger and an implicitly-available frontend in which the debug tree should be * processed with. * * @note Do not run a parser through this combinator multiple times. @@ -248,11 +240,11 @@ object combinator { * [[parsley.debugger.combinator$.attachWithFrontend[A](parser:parsley\.Parsley[A],frontend:parsley\.debugger\.frontend\.DebugFrontend,toStringRules* attachWithFrontend]] * for more information. */ - def attachWithImplicitFrontend[A](parser: Parsley[A], toStringRules: Seq[Any => Boolean] = defaultRules)(implicit frontend: DebugFrontend): Parsley[A] = { - attachWithFrontend(parser, frontend, toStringRules) - } + /*def attach[A](parser: Parsley[A], toStringRules: Seq[Any => Boolean])(implicit frontend: DebugFrontend): Parsley[A] = { + attach(parser, frontend, toStringRules) + }*/ - /** Attach a debugger and an implicitly-available frontend in which the debug tree should be + /* Attach a debugger and an implicitly-available frontend in which the debug tree should be * processed with. * * This assumes the default rules of converting only lambdas and closures into strings when @@ -264,7 +256,7 @@ object combinator { * ([[parsley.debugger.combinator$.attachWithImplicitFrontend[A](parser:parsley\.Parsley[A],toStringRules* attachWithImplicitFrontend]]) * has more information on its usage. */ - def attachWithImplicitFrontend[A](parser: Parsley[A])(implicit frontend: DebugFrontend): Parsley[A] = attachWithImplicitFrontend[A](parser, defaultRules) + //def attach[A](parser: Parsley[A])(implicit frontend: DebugFrontend): Parsley[A] = attach[A](parser, defaultRules) /** Attach a name to a parser, for display within the debugger output. * Names assigned here have a higher precedence than names collected with [[parsley.debugger.util.Collector]]. @@ -276,22 +268,19 @@ object combinator { case _ => new Parsley(Named(parser.internal, name)) } - // TODO: just use these for everything? /** Dot accessor versions of the combinators. */ implicit class DebuggerOps[A](par: Parsley[A]) { - def attachDebugger(toStringRules: Seq[Any => Boolean]): DebuggedPair[A] = combinator.attachDebugger(par, toStringRules) - def attachReusable(toStringRules: Seq[Any => Boolean]): () => DebuggedPair[A] = combinator.attachReusable(par, toStringRules) - def attachWithFrontend(frontend: DebugFrontend, toStringRules: Seq[Any => Boolean]): Parsley[A] = - combinator.attachWithFrontend(par, frontend, toStringRules) - def attachReusableWithFrontend(frontend: () => DebugFrontend, toStringRules: Seq[Any => Boolean]): () => Parsley[A] = - combinator.attachReusableWithFrontend(par, frontend, toStringRules) - def attachWithImplicitFrontend(toStringRules: Seq[Any => Boolean])(implicit frontend: DebugFrontend): Parsley[A] = - combinator.attachWithImplicitFrontend(par, toStringRules) - def attachDebugger: DebuggedPair[A] = combinator.attachDebugger(par, defaultRules) - def attachReusable: () => DebuggedPair[A] = combinator.attachReusable(par, defaultRules) - def attachWithFrontend(frontend: DebugFrontend): Parsley[A] = combinator.attachWithFrontend(par, frontend, defaultRules) - def attachReusableWithFrontend(frontend: () => DebugFrontend): () => Parsley[A] = combinator.attachReusableWithFrontend(par, frontend, defaultRules) - def attachWithImplicitFrontend(implicit frontend: DebugFrontend): Parsley[A] = combinator.attachWithImplicitFrontend(par, defaultRules) + //def attachDebugger(toStringRules: Seq[Any => Boolean]): DebuggedPair[A] = combinator.attachDebugger(par, toStringRules) + //def attachReusable(toStringRules: Seq[Any => Boolean]): () => DebuggedPair[A] = combinator.attachReusable(par, toStringRules) + def attach(frontend: DebugFrontend, toStringRules: Seq[Any => Boolean]): Parsley[A] = combinator.attach(par, frontend, toStringRules) + def attachReusable(frontend: =>ReusableFrontend, toStringRules: Seq[Any => Boolean]): () => Parsley[A] = + combinator.attachReusable(par, frontend, toStringRules) + //def attach(toStringRules: Seq[Any => Boolean])(implicit frontend: DebugFrontend): Parsley[A] = combinator.attach(par, toStringRules) + //def attachDebugger: DebuggedPair[A] = combinator.attachDebugger(par, defaultRules) + //def attachReusable: () => DebuggedPair[A] = combinator.attachReusable(par, defaultRules) + def attach(frontend: DebugFrontend): Parsley[A] = combinator.attach(par, frontend, defaultRules) + def attachReusable(frontend: =>ReusableFrontend): () => Parsley[A] = combinator.attachReusable(par, frontend, defaultRules) + //def attach(implicit frontend: DebugFrontend): Parsley[A] = combinator.attach(par, defaultRules) def named(name: String): Parsley[A] = combinator.named(par, name) } // $COVERAGE-ON$ diff --git a/parsley-debug/shared/src/main/scala/parsley/debugger/frontend/DebugFrontend.scala b/parsley-debug/shared/src/main/scala/parsley/debugger/frontend/DebugFrontend.scala index 57651c5f7..b9d07edff 100644 --- a/parsley-debug/shared/src/main/scala/parsley/debugger/frontend/DebugFrontend.scala +++ b/parsley-debug/shared/src/main/scala/parsley/debugger/frontend/DebugFrontend.scala @@ -11,7 +11,7 @@ import parsley.debugger.internal.XIllegalStateException /** A common interface for a debug frontend for a debugger to present the debug tree. Inherit from * one of the two provided subtraits to use. * - * Any compliant implementation that handles all nodes of a [[parsley.debugger.DebugTree]] can be + * Any compliant implementation that handles all nodes of a `parsley.debugger.DebugTree` can be * used in place of any other implementation (e.g. a serialiser to JSON, a GUI, etc.). * * If a frontend is reusable, one can implement it as either an `object` or a `class`, but an `object`