Merge pull request #375 from scodec/topic/hexdump

Add support for generating hex dumps

Author: mpilquist

core/shared/src/main/scala/scodec/bits/ByteVector.scala

@@ -32,7 +32,7 @@ package scodec.bits
 
 import java.io.{InputStream, OutputStream}
 import java.nio.{ByteBuffer, CharBuffer}
-import java.nio.charset.{CharacterCodingException, Charset}
+import java.nio.charset.{CharacterCodingException, Charset, CodingErrorAction}
 import java.util.UUID
 import java.util.concurrent.atomic.{AtomicInteger, AtomicLong}
 
@@ -806,6 +806,20 @@ sealed abstract class ByteVector
     bldr.toString
   }
 
+  /** Generates a hex dump of this vector using the default format (with ANSI enabled).
+    * To customize the output, use the `ByteVector.HexDumpFormat` class instead.
+    * For example, `ByteVector.HexDumpFormat.NoAnsi.render(bytes)` or
+    * `ByteVector.HexDumpFormat.Default.withIncludeAddressColumn(false).render(bytes)`.
+    *
+    * @group conversions
+    */
+  final def toHexDump: String = HexDumpFormat.Default.render(this)
+
+  /** Like [[toHexDump]] but no ANSI escape codes are included.
+    * @group conversions
+    */
+  final def toHexDumpNoAnsi: String = HexDumpFormat.NoAnsi.render(this)
+
   /** Helper alias for [[toHex:String*]]
     *
     * @group conversions
@@ -1067,18 +1081,45 @@ sealed abstract class ByteVector
     }
   }
 
+  /** Like [[decodeString]] but does not fail on bad input.
+    * @group conversions
+    */
+  final def decodeStringLenient(
+      replaceMalformedInput: Boolean = true,
+      replaceUnmappableChars: Boolean = true,
+      replacement: String = "�"
+  )(implicit charset: Charset): String = {
+    val decoder = charset.newDecoder
+      .replaceWith(replacement)
+      .onMalformedInput(
+        if (replaceMalformedInput) CodingErrorAction.REPLACE else CodingErrorAction.IGNORE
+      )
+      .onUnmappableCharacter(
+        if (replaceUnmappableChars) CodingErrorAction.REPLACE else CodingErrorAction.IGNORE
+      )
+    decoder.decode(toByteBuffer).toString
+  }
+
   /** Decodes this vector as a string using the UTF-8 charset.
     * @group conversions
     */
   final def decodeUtf8: Either[CharacterCodingException, String] =
     decodeString(Charset.forName("UTF-8"))
 
+  /** Like [[decodeUtf8]] but does not fail on bad input. */
+  final def decodeUtf8Lenient: String =
+    decodeStringLenient()(Charset.forName("UTF-8"))
+
   /** Decodes this vector as a string using the US-ASCII charset.
     * @group conversions
     */
   final def decodeAscii: Either[CharacterCodingException, String] =
     decodeString(Charset.forName("US-ASCII"))
 
+  /** Like [[decodeAscii]] but does not fail on bad input. */
+  final def decodeAsciiLenient: String =
+    decodeStringLenient()(Charset.forName("US-ASCII"))
+
   final def not: ByteVector = mapS(new F1B { def apply(b: Byte) = (~b).toByte })
 
   final def or(other: ByteVector): ByteVector =
@@ -2298,4 +2339,185 @@ object ByteVector extends ByteVectorCompanionCrossPlatform {
       }
     }
   }
+
+  final class HexDumpFormat private (
+      includeAddressColumn: Boolean,
+      dataColumnCount: Int,
+      dataColumnWidthInBytes: Int,
+      includeAsciiColumn: Boolean,
+      alphabet: Bases.HexAlphabet,
+      ansiEnabled: Boolean
+  ) {
+    def withIncludeAddressColumn(newIncludeAddressColumn: Boolean): HexDumpFormat =
+      new HexDumpFormat(
+        newIncludeAddressColumn,
+        dataColumnCount,
+        dataColumnWidthInBytes,
+        includeAsciiColumn,
+        alphabet,
+        ansiEnabled
+      )
+    def withDataColumnCount(newDataColumnCount: Int): HexDumpFormat =
+      new HexDumpFormat(
+        includeAddressColumn,
+        newDataColumnCount,
+        dataColumnWidthInBytes,
+        includeAsciiColumn,
+        alphabet,
+        ansiEnabled
+      )
+    def withDataColumnWidthInBytes(newDataColumnWidthInBytes: Int): HexDumpFormat =
+      new HexDumpFormat(
+        includeAddressColumn,
+        dataColumnCount,
+        newDataColumnWidthInBytes,
+        includeAsciiColumn,
+        alphabet,
+        ansiEnabled
+      )
+    def withIncludeAsciiColumn(newIncludeAsciiColumn: Boolean): HexDumpFormat =
+      new HexDumpFormat(
+        includeAddressColumn,
+        dataColumnCount,
+        dataColumnWidthInBytes,
+        newIncludeAsciiColumn,
+        alphabet,
+        ansiEnabled
+      )
+    def withAlphabet(newAlphabet: Bases.HexAlphabet): HexDumpFormat =
+      new HexDumpFormat(
+        includeAddressColumn,
+        dataColumnCount,
+        dataColumnWidthInBytes,
+        includeAsciiColumn,
+        newAlphabet,
+        ansiEnabled
+      )
+    def withAnsi(newAnsiEnabled: Boolean): HexDumpFormat =
+      new HexDumpFormat(
+        includeAddressColumn,
+        dataColumnCount,
+        dataColumnWidthInBytes,
+        includeAsciiColumn,
+        alphabet,
+        newAnsiEnabled
+      )
+
+    def render(bytes: ByteVector): String = {
+      val bldr = new StringBuilder
+      val numBytesPerLine = dataColumnWidthInBytes * dataColumnCount
+      val bytesPerLine = bytes.groupedIterator(numBytesPerLine)
+      bytesPerLine.zipWithIndex.foreach { case (bytesInLine, index) =>
+        renderLine(bldr, bytesInLine, index * numBytesPerLine)
+      }
+      bldr.toString
+    }
+
+    object Ansi {
+      val Faint = "\u001b[;2m"
+      val Normal = "\u001b[;22m"
+      val Reset = "\u001b[0m"
+      def foregroundColor(bldr: StringBuilder, rgb: (Int, Int, Int)): Unit =
+        bldr
+          .append("\u001b[38;2;")
+          .append(rgb._1)
+          .append(";")
+          .append(rgb._2)
+          .append(";")
+          .append(rgb._3)
+          .append("m")
+    }
+
+    private def renderLine(bldr: StringBuilder, bytes: ByteVector, address: Int): Unit = {
+      if (includeAddressColumn) {
+        if (ansiEnabled) bldr.append(Ansi.Faint)
+        bldr.append(ByteVector.fromInt(address).toHex(alphabet))
+        if (ansiEnabled) bldr.append(Ansi.Normal)
+        bldr.append("  ")
+      }
+      bytes.groupedIterator(dataColumnWidthInBytes).foreach { columnBytes =>
+        renderHex(bldr, columnBytes)
+        bldr.append(" ")
+      }
+      if (ansiEnabled)
+        bldr.append(Ansi.Reset)
+      if (includeAsciiColumn) {
+        val padding = {
+          val bytesOnFullLine = dataColumnWidthInBytes * dataColumnCount
+          val bytesOnThisLine = bytes.size.toInt
+          val dataBytePadding = (bytesOnFullLine - bytesOnThisLine) * 3 - 1
+          val numFullDataColumns = bytesOnThisLine / dataColumnWidthInBytes
+          val numAdditionalColumnSpacers = dataColumnCount - numFullDataColumns
+          dataBytePadding + numAdditionalColumnSpacers
+        }
+        bldr.append(" " * padding)
+        bldr.append('│')
+        renderAsciiBestEffort(bldr, bytes)
+        bldr.append('│')
+      }
+      bldr.append('\n')
+    }
+
+    private def renderHex(bldr: StringBuilder, bytes: ByteVector): Unit =
+      bytes.foreachS {
+        new F1BU {
+          def apply(b: Byte) = {
+            if (ansiEnabled) Ansi.foregroundColor(bldr, rgbForByte(b))
+            bldr
+              .append(alphabet.toChar((b >> 4 & 0x0f).toByte.toInt))
+              .append(alphabet.toChar((b & 0x0f).toByte.toInt))
+              .append(' ')
+            ()
+          }
+        }
+      }
+
+    private def rgbForByte(b: Byte): (Int, Int, Int) = {
+      val saturation = 0.4
+      val value = 0.75
+      val hue = ((b & 0xff) / 256.0) * 360.0
+      hsvToRgb(hue, saturation, value)
+    }
+
+    // From https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB
+    private def hsvToRgb(hue: Double, saturation: Double, value: Double): (Int, Int, Int) = {
+      val c = saturation * value
+      val h = hue / 60
+      val x = c * (1 - (h % 2 - 1).abs)
+      val z = 0d
+      val (r1, g1, b1) = h.toInt match {
+        case 0 => (c, x, z)
+        case 1 => (x, c, z)
+        case 2 => (z, c, x)
+        case 3 => (z, x, c)
+        case 4 => (x, z, c)
+        case 5 => (c, z, x)
+      }
+      val m = value - c
+      val (r, g, b) = (r1 + m, g1 + m, b1 + m)
+      def scale(v: Double) = (v * 256).toInt
+      (scale(r), scale(g), scale(b))
+    }
+
+    private val FaintDot = s"${Ansi.Faint}.${Ansi.Normal}"
+    private val FaintUnmappable = s"${Ansi.Faint}�${Ansi.Normal}"
+    private val NonPrintablePattern = "[^�\\p{Print}]".r
+
+    private def renderAsciiBestEffort(bldr: StringBuilder, bytes: ByteVector): Unit = {
+      val decoded = bytes.decodeAsciiLenient
+      val nonPrintableReplacement = if (ansiEnabled) FaintDot else "."
+      val printable = NonPrintablePattern.replaceAllIn(decoded, nonPrintableReplacement)
+      val colorized = if (ansiEnabled) printable.replaceAll("�", FaintUnmappable) else printable
+      bldr.append(colorized)
+    }
+  }
+
+  object HexDumpFormat {
+    val Default: HexDumpFormat =
+      new HexDumpFormat(true, 2, 8, true, Bases.Alphabets.HexLowercase, true)
+    val NoAnsi: HexDumpFormat =
+      Default.withAnsi(false)
+    val NoAscii: HexDumpFormat =
+      new HexDumpFormat(true, 3, 8, false, Bases.Alphabets.HexLowercase, true)
+  }
 }