use table type with description

data/print-three-upper-math.asm

@@ -1,3 +1,4 @@
+; Colors that each screen pixel can be set to
 define COLOR_Black      $00
 define COLOR_White      $01
 define COLOR_Red        $02
@@ -16,6 +17,7 @@ define COLOR_LightBlue  $0E
 define COLOR_LightGrey  $0F
 
 
+; The screen as a collection of pixels
 define SCREEN $200
 
 

data/print-three-upper.asm

@@ -1,3 +1,4 @@
+; Colors that each screen pixel can be set to
 define COLOR_Black      $00
 define COLOR_White      $01
 define COLOR_Red        $02
@@ -16,6 +17,7 @@ define COLOR_LightBlue  $0E
 define COLOR_LightGrey  $0F
 
 
+; The screen as a collection of pixels
 define SCREEN $200
 
 

firepower-core/src/main/scala/com/htmlism/firepower/core/AsmBlock.scala

@@ -21,8 +21,7 @@ object AsmBlock:
   /**
     * Renders as a table of aliases
     */
-  // TODO needs descriptive field
-  case class DefinesBlock(xs: List[(String, Int)]) extends AsmBlock
+  case class DefinesBlock(comment: Option[String], xs: List[(String, Int)]) extends AsmBlock
 
   /**
     * Renders as a labeled subroutine
@@ -70,16 +69,19 @@ object AsmBlock:
       case CommentBlock(ys) =>
         ys.map(toComment)
 
-      case DefinesBlock(kvs) =>
+      case DefinesBlock(oComment, kvs) =>
         val maximumLength =
           kvs
             .map(_._1.length)
             .max
 
-        kvs
-          .map { case (k, v) =>
-            String.format(s"define %-${maximumLength}s ${toHex(v)}", k)
-          }
+        val defines =
+          kvs
+            .map { case (k, v) =>
+              String.format(s"define %-${maximumLength}s ${toHex(v)}", k)
+            }
+
+        oComment.map(toComment).toList ::: defines
 
       case NamedCodeBlock(label, oComment, intents) =>
         val headerParagraph =

firepower-demo/src/main/scala/com/htmlism/firepower/demo/Definable.scala

@@ -1,9 +1,7 @@
 package com.htmlism.firepower.demo
 
-import scala.collection.immutable._
-
 trait Definable[A]:
-  def table(x: A): ListMap[String, Int]
+  def table(x: A): Definable.Table
 
   extension (x: A) def toComment: String
 
@@ -14,5 +12,7 @@ trait Definable[A]:
   extension (x: A) def toDefineWithMath: String
 
 object Definable:
+  case class Table(description: String, xs: List[(String, Int)])
+
   def apply[A](using ev: Definable[A]): Definable[A] =
     ev

firepower-demo/src/main/scala/com/htmlism/firepower/demo/Easy6502.scala

@@ -1,6 +1,5 @@
 package com.htmlism.firepower.demo
 
-import scala.collection.immutable._
 import scala.util.chaining._
 
 object Easy6502:
@@ -10,14 +9,15 @@ object Easy6502:
 
   object Color:
     given Definable[Color] with
-      def table(x: Color): ListMap[String, Int] =
+      def table(x: Color): Definable.Table =
         Color
           .values
           .iterator
           .map { c =>
             "COLOR_" + c.toString -> c.ordinal
           }
-          .pipe(ListMap.from)
+          .toList
+          .pipe(Definable.Table("Colors that each screen pixel can be set to", _))
 
       extension (x: Color)
         def toComment: String =
@@ -44,8 +44,9 @@ object Easy6502:
 
     object Pixel:
       given Definable[Pixel] with
-        def table(x: Pixel): ListMap[String, Int] =
-          ListMap("SCREEN" -> x.baseAddr) // define table needs to be a function of an instance
+        def table(x: Pixel): Definable.Table =
+          // define table needs to be a function of an instance
+          Definable.Table("The screen as a collection of pixels", List("SCREEN" -> x.baseAddr))
 
         extension (x: Pixel)
           def toComment: String =

firepower-demo/src/main/scala/com/htmlism/firepower/demo/PrintThree.scala

@@ -1,6 +1,5 @@
 package com.htmlism.firepower.demo
 
-import scala.collection.immutable._
 import scala.util.chaining._
 
 import cats.syntax.all._
@@ -10,7 +9,7 @@ import com.htmlism.firepower.core._
 
 object PrintThree:
   case class Move[A: Definable, B: Definable](src: A, dest: B):
-    def defines: List[ListMap[String, Int]] =
+    def defines: List[Definable.Table] =
       List(
         Definable[A]
           .table(src),
@@ -42,10 +41,8 @@ object PrintThree:
         program
           .flatMap(_.defines)
           .distinct
-          .map { xs =>
-            xs
-              .toList
-              .pipe(AsmBlock.DefinesBlock(_))
+          .map { dt =>
+            AsmBlock.DefinesBlock(dt.description.some, dt.xs)
           }
 
   private def codes(opts: AssemblerOptions.DefinitionsMode) =