resized README images

README.md

@@ -1,3 +1,44 @@
 # rivet-typst
 
-Register / Instruction Visualizer & Explainer Tool with Typst, using CeTZ
+RIVET _(Register / Instruction Visualizer & Explainer Tool)_ is a [Typst](https://typst.app) package for visualizing binary instructions or describing the contents of a register, using the [CeTZ](https://typst.app/universe/package/cetz) package.
+
+It is based on the [homonymous Python script](https://git.kb28.ch/HEL/rivet/)
+
+## Examples
+<table>
+  <tr>
+    <td>
+      <a href="./gallery/example1.typ">
+        <img src="./gallery/example1.png" width="1000px">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>A bit of eveything</td>
+  </tr>
+  <tr>
+    <td>
+      <a href="./gallery/example2.typ">
+        <img src="./gallery/example2.png" width="1000px">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>RISC-V memory instructions (blueprint)</td>
+  </tr>
+</table>
+
+*Click on the example image to jump to the code.*
+
+## Usage
+For information, see the [manual](manual.pdf)
+
+To use this package, simply import `schema` [src/lib.typ](src/lib.typ) and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+```typ
+#import "src/lib.typ": schema
+#let doc = schema.load("path/to/schema.yaml")
+#schema.render(doc)
+```
+
+## Installing
+> TODO

docs/config.typ

@@ -0,0 +1,61 @@
+/// Creates a dictionary of all configuration parameters
+///
+/// - default-font-family (str): The default font family
+/// - default font-size (length): The absolute default font size
+/// - italic-font-family (str): The italic font family (for value descriptions)
+/// - italic-font-size (length): The absolute italic font size
+/// - background (color): The diagram background color
+/// - text-color (color): The default color used to display text
+/// - link-color (color): The color used to display links and arrows
+/// - bit-i-color (color): The color used to display bit indices
+/// - border-color (color): The color used to display borders
+/// - bit-width (float): The width of a bit
+/// - bit-height (float): The height of a bit
+/// - description-margin (float): The margin between descriptions
+/// - dash-length (float): The length of individual dashes (for dashed lines)
+/// - dash-space (float): The space between two dashes (for dashed lines)
+/// - arrow-size (float): The size of arrow heads
+/// - margins (tuple[float]): TODO -> remove
+/// - arrow-margin (float): The margin between arrows and the structures they link
+/// - values-gap (float): The gap between individual values
+/// - arrow-label-distance (float): The distance between arrows and their labels
+/// - force-descs-on-side (bool): If true, descriptions are placed on the side of the structure, otherwise, they are placed as close as possible to the bit
+/// - left-labels (bool): If true, descriptions are put on the left, otherwise, they default to the right hand side
+/// - width (float): TODO -> remove
+/// - height (float): TODO -> remove
+/// - full-page (bool): If true, the page will be resized to fit the diagram and take the background color
+/// -> dictionary
+#let config(
+  default-font-family: "Ubuntu Mono",
+  default-font-size: 15pt,
+  italic-font-family: "Ubuntu Mono",
+  italic-font-size: 12pt,
+  background: white,
+  text-color: black,
+  link-color: black,
+  bit-i-color: black,
+  border-color: black,
+  bit-width: 30,
+  bit-height: 30,
+  description-margin: 10,
+  dash-length: 6,
+  dash-space: 4,
+  arrow-size: 10,
+  margins: (20, 20, 20, 20),
+  arrow-margin: 4,
+  values-gap: 5,
+  arrow-label-distance: 5,
+  force-descs-on-side: false,
+  left-labels: false,
+  width: 1200,
+  height: 800,
+  full-page: false
+) = {}
+
+/// Dark theme config
+/// - ..args (any): see #doc-ref("config.config")
+#let dark(..args) = {}
+
+/// Blueprint theme config
+/// - ..args (any): see #doc-ref("config.config")
+#let blueprint(..args) = {}

docs/examples.typ

@@ -0,0 +1,73 @@
+#import "@preview/cetz:0.2.2": draw
+#import "../src/lib.typ": schema
+#import "../src/util.typ"
+
+#let example-preamble = "import \"../src/lib.typ\": *;"
+
+#let example(src, show-src: true, vertical: false, fill: true) = {
+  src = src.text.trim()
+  let full-src = example-preamble + src
+  let body = eval(full-src)
+
+  block(width: 100%,
+    align(center,
+      box(
+        stroke: black + 1pt,
+        radius: .5em,
+        fill: if fill {yellow.lighten(80%)} else {none},
+        if show-src {
+          let src-block = align(left, raw(src, lang: "typc"))
+          table(
+            columns: if vertical {1} else {2},
+            inset: 1em,
+            align: horizon + center,
+            stroke: none,
+            body,
+            if vertical {table.hline()} else {table.vline()}, src-block
+          )
+        } else {
+          table(
+            inset: 1em,
+            body
+          )
+        }
+      )
+    )
+  )
+}
+
+#let config-config = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: default
+```)
+schema.render(ex, config: config.config())
+"))
+
+#let config-dark = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: dark
+```)
+schema.render(ex, config: config.dark())
+"))
+
+#let config-blueprint = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: blueprint
+```)
+schema.render(ex, config: config.blueprint())
+"))

docs/schema.typ

@@ -0,0 +1,14 @@
+/// Loads a schema from a file or a raw block.
+/// This function returns a dictionary of structures
+/// 
+/// Supported formats: #schema.valid-extensions.map(e => raw("." + e)).join(", ")
+/// - path-or-schema (str, raw): If it is a string, defines the path to load. \
+///   If it is a raw block, its content is directly parsed (the block's language will define the format to use)
+/// -> dictionary
+#let load(path-or-schema) = {}
+
+/// Renders the given schema
+/// This functions
+/// - structures (dictionary): A schema dictionary, as returned by #doc-ref("schema.load")
+/// - config (auto, dictionary): The configuration parameters, as returned by #doc-ref("config.config")
+#let render(structures, config: auto)

gallery/example1.typ

@@ -0,0 +1,6 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example1.yaml")
+#schema.render(example, config: config.config(
+  full-page: true
+))

gallery/example1.yaml

@@ -0,0 +1,73 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-28:
+        name: cond
+      27:
+        name: 0
+      26:
+        name: 1
+      25:
+        name: I
+      24:
+        name: P
+        description: pre / post indexing bit
+        values:
+          0: post, add offset after transfer
+          1: pre, add offset before transfer
+      23:
+        name: U
+        description: up / down bit
+        values:
+          0: down, subtract offset from base
+          1: up, addition offset to base
+      22:
+        name: B
+        description: byte / word bit
+        values:
+          0: transfer word quantity
+          1: transfer byte quantity
+      21:
+        name: W
+        description: write-back bit
+        values:
+          0: no write-back
+          1: write address into base
+      20:
+        name: L
+        description: load / store bit
+        values:
+          0: store to memory
+          1: load from memory
+      19-16:
+        name: Rn
+        description: base register
+      15-12:
+        name: Rd
+        description: source / destination register
+      11-0:
+        name: offset
+        depends-on: 25
+        values:
+          0:
+            description: offset is an immediate value
+            structure: immediateOffset
+          1:
+            description: offset is a register
+            structure: registerOffset
+  immediateOffset:
+    bits: 12
+    ranges:
+      11-0:
+        name: 12-bit immediate offset
+        description: unsigned number
+  registerOffset:
+    bits: 12
+    ranges:
+      11-4:
+        name: shift
+        description: shift applied to Rm
+      3-0:
+        name: Rm
+        description: offset register

gallery/example2.typ

@@ -0,0 +1,7 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example2.yaml")
+#schema.render(example, config: config.blueprint(
+  full-page: true,
+  left-labels: true
+))

gallery/example2.yaml

@@ -0,0 +1,78 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: src
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: srcImmediate
+          1:
+            description:
+            structure: srcRegister
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: byte
+          001: half-word
+          "010": word
+          100: upper byte (load only)
+          101: upper half (load only)
+      11-7:
+        name: dst
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: dstRegister
+          1:
+            description:
+            structure: dstImmediate
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+
+  srcImmediate:
+    bits: 12
+    ranges:
+      11-0:
+        name: src
+        description: source memory address
+  srcRegister:
+    bits: 12
+    ranges:
+      11-5:
+        name: dstU
+        description: destination address upper bits
+      4-0:
+        name: rs2
+        description: source register
+
+  dstImmediate:
+    bits: 5
+    ranges:
+      4-0:
+        name: destL
+        description: destination address lower bits
+  dstRegister:
+    bits: 5
+    ranges:
+      4-0:
+        name: rd
+        description: destination register

gallery/riscv/alu_instr.yaml

@@ -0,0 +1,60 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: op2
+        depends-on: 5
+        values:
+          0:
+            description: second operand is an immediate value
+            structure: immediateOp
+          1:
+            description: second operand is a register
+            structure: registerOp
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: operation
+        values:
+          000: add / sub
+          100: xor
+          110: or
+          111: and
+          001: sl
+          101: sr
+      11-7:
+        name: rd
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 1
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+  immediateOp:
+    bits: 12
+    ranges:
+      11-0:
+        name: 12-bit immediate value
+        description: signed number
+  registerOp:
+    bits: 12
+    ranges:
+      11-5:
+        name: funct7
+        description: function modifier
+        values:
+          0000000: default (add, srl)
+          "0100000": sub, sra
+      4-0:
+        name: rs2
+        description: second register operand

gallery/riscv/branch_instr.yaml

@@ -0,0 +1,34 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-25:
+        name: imm
+      24-20:
+        name: rs2
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: if equal
+          001: if not equal
+          100: if less
+          101: if greater or equal
+      11-7:
+        name: imm
+      6:
+        name: 1
+      5:
+        name: 1
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1

gallery/riscv/mem_instr.yaml

@@ -0,0 +1,78 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: src
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: srcImmediate
+          1:
+            description:
+            structure: srcRegister
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: byte
+          001: half-word
+          "010": word
+          100: upper byte (load only)
+          101: upper half (load only)
+      11-7:
+        name: dst
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: dstRegister
+          1:
+            description:
+            structure: dstImmediate
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+
+  srcImmediate:
+    bits: 12
+    ranges:
+      11-0:
+        name: src
+        description: source memory address
+  srcRegister:
+    bits: 12
+    ranges:
+      11-5:
+        name: dstU
+        description: destination address upper bits
+      4-0:
+        name: rs2
+        description: source register
+
+  dstImmediate:
+    bits: 5
+    ranges:
+      4-0:
+        name: destL
+        description: destination address lower bits
+  dstRegister:
+    bits: 5
+    ranges:
+      4-0:
+        name: rd
+        description: destination register

gallery/riscv/riscv.typ

@@ -0,0 +1,14 @@
+#import "../../src/lib.typ": *
+
+#let conf = config.config(
+  full-page: true,
+  left-labels: true
+)
+#let alu = schema.load("/gallery/riscv/alu_instr.yaml")
+#schema.render(alu, config: conf)
+
+#let branch = schema.load("/gallery/riscv/branch_instr.yaml")
+#schema.render(branch, config: conf)
+
+#let mem = schema.load("/gallery/riscv/mem_instr.yaml")
+#schema.render(mem, config: conf)

gallery/test.typ

@@ -13,4 +13,16 @@
 #let test-xml = schema.load("/gallery/test.xml")
 #schema.render(test-xml, config: config.dark(
   full-page: true
+))
+
+#let test-raw = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: test
+```)
+#schema.render(test-raw, config: config.config(
+  full-page: true
 ))

manual.typ

@@ -0,0 +1,79 @@
+#import "@preview/tidy:0.3.0"
+#import "src/lib.typ"
+#import "src/schema.typ"
+#import "docs/examples.typ"
+
+#set heading(numbering: (..num) => if num.pos().len() < 4 {
+  numbering("1.1", ..num)
+})
+#{
+  outline(indent: true, depth: 3)
+}
+
+#set page(numbering: "1/1", header: align(right)[rivet #sym.dash.em v#lib.version])
+
+#let doc-ref(target, full: false, var: false) = {
+  let (module, func) = target.split(".")
+  let label-name = module + func
+  let display-name = func
+  if full {
+    display-name = target
+  }
+  if not var {
+    label-name += "()"
+    display-name += "()"
+  }
+  link(label(label-name))[#display-name]
+}
+
+#show link: set text(blue)
+
+= Introduction
+
+This package provides a way to make beautiful register diagrams using the CeTZ package. It can be used to document Assembly instructions or binary registers
+
+This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst. For more information on the schema format, please check out the original project's #link("https://git.kb28.ch/HEL/rivet/src/branch/main/format.md")[format.md]
+
+= Usage
+
+Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+#pad(left: 1em)[```typ
+#import "src/lib.typ": schema
+#let doc = schema.load("path/to/schema.yaml")
+#schema.render(doc)
+```]
+
+= Config presets
+
+Aside from the default config, some example presets are also provided:
+- #doc-ref("config.config", full: true): the default theme, black on white
+  #examples.config-config
+- #doc-ref("config.dark", full: true): a dark theme, with white text and lines on a black background
+  #examples.config-dark
+- #doc-ref("config.blueprint", full: true): a blueprint theme, with white text and lines on a blue background
+  #examples.config-blueprint
+
+#pagebreak(weak: true)
+
+= Reference
+
+#let doc-config = tidy.parse-module(
+  read("docs/config.typ"),
+  name: "config",
+  scope: (
+    doc-ref: doc-ref
+  )
+)
+#tidy.show-module(doc-config, sort-functions: false)
+
+#pagebreak()
+
+#let doc-schema = tidy.parse-module(
+  read("docs/schema.typ"),
+  name: "schema",
+  scope: (
+    schema: schema,
+    doc-ref: doc-ref
+  )
+)
+#tidy.show-module(doc-schema, sort-functions: false)

src/renderer.typ

@@ -117,7 +117,7 @@
   let txt-col = config.text-color
   let bit-w = config.bit-height  // Why ? I don't remember
   let gap = config.values-gap
-  
+
   for (val, desc) in values.pairs().sorted(key: p => p.first()) {
     desc-y += gap
     let txt = val + " = " + desc
@@ -159,16 +159,16 @@
   let mid-x = start-x + width / 2
   shapes += draw-link(config, mid-x, start-y, desc-x, desc-y)
 
-  let txt-anchor = "west"
+  let txt-x = desc-x
 
   if config.left-labels {
-    txt-anchor -= "east"
+    txt-x -= range_.description.len() * config.default-font-size / 2pt
   }
 
   shapes += draw-text(
     range_.description,
     config.text-color,
-    desc-x, desc-y + bit-h / 2,
+    txt-x, desc-y + bit-h / 2,
     anchor: "west"
   )
 
@@ -176,7 +176,7 @@
 
   if range_.values != none and range_.depends-on == none {
     let shapes_
-    (shapes_, _, desc-y) = draw-values(config, range_.values, desc-x, desc-y)
+    (shapes_, _, desc-y) = draw-values(config, range_.values, txt-x, desc-y)
     shapes += shapes_
   }
 
@@ -266,7 +266,8 @@
   let width = rng.bits(range_) * bit-w
 
   shapes += draw-underbracket(config, start-x, start-x + width, bits-y)
-  let depend-range = struct.ranges.at(rng.key(..range_.depends-on))
+  let depend-key = rng.key(..range_.depends-on)
+  let depend-range = struct.ranges.at(depend-key)
   let prev-range-y = bits-y + bit-h * 1.5
 
   let prev-depend-y = if depend-range.last-value-y == -1 {
@@ -335,7 +336,9 @@
     shapes += shapes_
   }
 
-  return (shapes, desc-x, desc-y)
+  struct.ranges.at(depend-key) = depend-range
+
+  return (shapes, desc-x, desc-y, struct)
 }
 
 #let draw-structure(config, struct, structures, ox: 0, oy: 0) = {
@@ -397,10 +400,16 @@
     let name-x = start-x + width / 2
     let name-y = bits-y + bit-h / 2
     
+    shapes += draw-rect(
+      bg-col,
+      start-x + bit-w / 2,
+      name-y - bit-h * 0.3,
+      width - bit-w,
+      bit-h * 0.6
+    )
     shapes += draw-text(range_.name, txt-col, name-x, name-y, fill: bg-col)
     
     if range_.description != "" {
-      //draw.circle((desc-x, -desc-y), radius: 5, fill: red)
       let shapes_
       (shapes_, desc-x, desc-y) = draw-description(
         config, range_, start-x, bits-y, width, desc-x, desc-y
@@ -413,7 +422,7 @@
   for range_ in ranges {
     if range_.values() != none and range_.depends-on != none {
       let shapes_
-      (shapes_, desc-x, desc-y) = draw-dependency(
+      (shapes_, desc-x, desc-y, struct) = draw-dependency(
         draw-structure, config,
         struct, structures, bits-x, bits-y, range_, desc-x, desc-y
       )
@@ -440,7 +449,8 @@
     (
       width: auto,
       height: auto,
-      fill: config.background
+      fill: config.background,
+      margin: 0cm
     )
   } else {
     (:)
@@ -454,8 +464,16 @@
       ox: ox,
       oy: config.margins.at(0)
     )
-    shapes
-    //draw.circle((300, -3000), fill: red, radius: 2)
+    // Workaround for margins
+    draw.group(name: "g", padding: config.margins, shapes)
+    draw.line(
+      "g.north-west",
+      "g.north-east",
+      "g.south-east",
+      "g.south-west",
+      stroke: none,
+      fill: none
+    )
   })
 }
 

src/schema.typ

@@ -23,7 +23,25 @@
   }
 }
 
-#let load(path-or-schema, config: auto) = {
+#let parse-raw(schema) = {
+  let lang = schema.lang
+  let content = schema.text
+  if not lang in valid-extensions {
+    let fmts = valid-extensions.join(", ")
+    fmts = "(" + fmts + ")"
+    panic("Unsupported format '" + lang + "'. Valid formats: " + fmts)
+  }
+
+  if lang == "yaml" {
+    return yaml.decode(content)
+  } else if lang == "json" {
+    return json.decode(content)
+  } else if lang == "xml" {
+    return xml-loader.parse(xml.decode(content).first())
+  }
+}
+
+#let load(path-or-schema) = {
   let schema = if type(path-or-schema) == str {
     parse-file(path-or-schema)
   } else {

src/xml-loader.typ

@@ -81,8 +81,7 @@
   )
 }
 
-#let load(path) = {
-  let content = xml(path).first()
+#let parse(content) = {
   let struct-elmts = content.children.filter(e => "tag" in e and e.tag == "structure")
 
   let structures = (:)
@@ -97,4 +96,9 @@
   return (
     structures: structures
   )
+}
+
+#let load(path) = {
+  let content = xml(path).first()
+  return parse(content)
 }