Adding SourceCollector to enable debuggers to access source files. (#263)

Enables the collection of all source files that use the @debuggable
annotation.

Author: j-mie6

docs/parsley-debug/recursion-detection.md

@@ -34,7 +34,7 @@ object parsers {
 }
 ```
 ```scala mdoc:invisible
-parsley.debug.util.Collector.registerNames(Map(parsers.p -> "p", parsers.q -> "q", parsers.r -> "r"))
+parsley.debug.util.Collector.registerNames(Map(parsers.p -> "p", parsers.q -> "q", parsers.r -> "r"), None)
 ```
 
 While `parsers.top.parse("a")` would work fine, consider what happens if we pass the empty string:
@@ -97,7 +97,7 @@ object stateful {
 }
 ```
 ```scala mdoc:invisible
-parsley.debug.util.Collector.registerNames(Map(stateful.p -> "p", stateful.q -> "q", stateful.top -> "top"))
+parsley.debug.util.Collector.registerNames(Map(stateful.p -> "p", stateful.q -> "q", stateful.top -> "top"), None)
 ```
 
 This parser is a contrived example, admittedly, but illustrates what `detectDivergence` is capable of.
@@ -134,7 +134,7 @@ object nameless {
 }
 ```
 ```scala mdoc:invisible
-parsley.debug.util.Collector.registerNames(Map(nameless.top -> "top"))
+parsley.debug.util.Collector.registerNames(Map(nameless.top -> "top"), None)
 ```
 
 While we might expect this to work out much like the `stateful` example above, in reality we see

parsley-debug/shared/src/main/scala-2/parsley/debuggable.scala

@@ -113,7 +113,7 @@ private object debuggable {
         // the idea is we inject a call to Collector.registerNames with a constructed
         // map from these identifiers to their compile-time names
         val listOfParsers = q"List(..${parsers.map(tr => q"${Ident(tr)} -> ${tr.toString}")})"
-        val registration = q"parsley.debug.util.Collector.registerNames($listOfParsers.toMap)"
+        val registration = q"parsley.debug.util.Collector.registerNames($listOfParsers.toMap, $None)"
         // add the registration as the last statement in the object
         // TODO: in future, we want to modify all `def`s with a top level `opaque` combinator
         // that will require a bit more modification of the overall `body`, unfortunately

parsley-debug/shared/src/main/scala-3/parsley/debuggable.scala

@@ -26,14 +26,22 @@ import scala.quoted.*
             case cls@ClassDef(clsName, constr, parents, selfOpt, body) =>
                 val parsleyTy = TypeRepr.of[Parsley[?]].typeSymbol
                 val fields = cls.symbol.fieldMembers.view.map(_.termRef)
-                val parsers = fields.filter(_.typeSymbol == parsleyTy)
-
+                val parsers = fields.filter(_.typeSymbol == parsleyTy).toList
                 // the idea is we inject a call to Collector.registerNames with a constructed
                 // map from these identifiers to their compile-time names
                 val listOfParsers = Expr.ofList {
-                    parsers.map(tr => Expr.ofTuple((Ident(tr).asExprOf[parsley.Parsley[?]], Expr(tr.name)))).toList
+                    parsers.map(tr => Expr.ofTuple((Ident(tr).asExprOf[parsley.Parsley[?]], Expr(tr.name))))
                 }
-                val registration = '{parsley.debug.util.Collector.registerNames($listOfParsers.toMap)}.asTerm
+                
+                val filePath = Expr(cls.pos.sourceFile.path)
+                val positionInfo = Expr.ofList(
+                    for termRef <- parsers
+                        pos <- termRef.termSymbol.pos
+                    yield Expr.ofTuple(Expr(pos.start), Expr(pos.end))
+                )
+                val parserInfo = '{Some(($filePath, $positionInfo))}
+
+                val registration = '{parsley.debug.util.Collector.registerNames($listOfParsers.toMap, $parserInfo)}.asTerm
 
                 // add the registration as the last statement in the object
                 // TODO: in future, we want to modify all `def`s with a top level `opaque` combinator

parsley-debug/shared/src/main/scala/parsley/debug/internal/ParserInfoCollector.scala

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2020 Parsley Contributors <https://github.com/j-mie6/Parsley/graphs/contributors>
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+package parsley.debug.internal
+
+import scala.collection.mutable
+
+/**
+  * The ParserInfo class represents metadata about a parser module obtained
+  * using the debuggable macro.
+  *
+  * @param path The absolute path to a parser.
+  * @param positions A list of (start, end) positions of parsers within a 
+  *   module.
+  */
+final private [parsley] case class ParserInfo(val path: String, val positions: List[(Int, Int)])
+
+/**
+  * Object with methods to add detected parser information to a mutable set,
+  * allowing debugged source files and the locations of their parsers to be
+  * known at runtime.
+  * 
+  * This is mainly to enable a debugger to display source files inside of the
+  * application so that debugging faulty code can easily be done in the same 
+  * application.
+  */
+private [parsley] object ParserInfoCollector {
+    // The set of collected source file paths
+    private lazy val collected: mutable.Set[ParserInfo] = mutable.Set.empty
+    
+    /**
+      * Add an iterable set of parser information to the collection.
+      *
+      * @param info The parser information to add.
+      */
+    private [parsley] def addInfos(info: Seq[ParserInfo]): Unit = collected ++= info
+
+    /**
+      * Add a single parser information class to the collection.
+      *
+      * @param info The parser info to add.
+      */
+    private [parsley] def addInfo(info: ParserInfo): Unit = collected += info
+
+    // Obtain the collected information.
+    private [parsley] lazy val info: Set[ParserInfo] = collected.toSet
+}

parsley-debug/shared/src/main/scala/parsley/debug/util/Collector.scala

@@ -8,7 +8,7 @@ package parsley.debug.util
 //import scala.annotation.nowarn
 
 import parsley.Parsley
-import parsley.debug.internal.Renamer
+import parsley.debug.internal.{Renamer, ParserInfoCollector, ParserInfo}
 import parsley.token.Lexer
 
 import parsley.internal.deepembedding.frontend.LazyParsley
@@ -35,8 +35,18 @@ object Collector {
         Renamer.addNames(XCollector.collectNames(obj))
     }*/
 
-    /** This is an internal method used by the `parsley.debuggable` annotation */
-    def registerNames(names: Map[Parsley[_], String]): Unit = {
+    /**
+      * This is an internal method used by the `parsley.debuggable` annotation. 
+      * 
+      * This function registers the names collected by the annotation to the 
+      * `Renamer` object, and also adds parser information the annotation has
+      * found inside of the the `ParserInfoCollector` object.
+      *
+      * @param names List of parsers mapped to their string representations.
+      * @param parserInfo Parser info collected from the annotation.
+      */
+    def registerNames(names: Map[Parsley[_], String], parserInfo: Option[(String, List[(Int, Int)])]): Unit = {
+        parserInfo.map { case (filename, positions) => ParserInfoCollector.addInfo(ParserInfo(filename, positions)) }
         Renamer.addNames(names.map { case (k, v) => k.internal -> v })
     }