Compare commits
10 Commits
83d7a8d85b
...
v0.0.1
Author | SHA1 | Date | |
---|---|---|---|
8bcedbfc53
|
|||
bdbed8f8b0
|
|||
56bfe03c44
|
|||
e584dc4e36
|
|||
6d59f4bc92
|
|||
03361db784
|
|||
8d93e6473e
|
|||
44fd298edb
|
|||
5e0e680f60
|
|||
4ccfa43e51
|
43
README.md
43
README.md
@ -1,3 +1,44 @@
|
|||||||
# rivet-typst
|
# 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
|
||||||
|
61
docs/config.typ
Normal file
61
docs/config.typ
Normal file
@ -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) = {}
|
73
docs/examples.typ
Normal file
73
docs/examples.typ
Normal file
@ -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())
|
||||||
|
"))
|
14
docs/schema.typ
Normal file
14
docs/schema.typ
Normal file
@ -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)
|
BIN
gallery/example1.pdf
Normal file
BIN
gallery/example1.pdf
Normal file
Binary file not shown.
BIN
gallery/example1.png
Normal file
BIN
gallery/example1.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 378 KiB |
6
gallery/example1.typ
Normal file
6
gallery/example1.typ
Normal file
@ -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
|
||||||
|
))
|
73
gallery/example1.yaml
Normal file
73
gallery/example1.yaml
Normal file
@ -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
|
BIN
gallery/example2.pdf
Normal file
BIN
gallery/example2.pdf
Normal file
Binary file not shown.
BIN
gallery/example2.png
Normal file
BIN
gallery/example2.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 303 KiB |
7
gallery/example2.typ
Normal file
7
gallery/example2.typ
Normal file
@ -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
|
||||||
|
))
|
78
gallery/example2.yaml
Normal file
78
gallery/example2.yaml
Normal file
@ -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
|
60
gallery/riscv/alu_instr.yaml
Normal file
60
gallery/riscv/alu_instr.yaml
Normal file
@ -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
|
34
gallery/riscv/branch_instr.yaml
Normal file
34
gallery/riscv/branch_instr.yaml
Normal file
@ -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
|
78
gallery/riscv/mem_instr.yaml
Normal file
78
gallery/riscv/mem_instr.yaml
Normal file
@ -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
|
BIN
gallery/riscv/riscv.pdf
Normal file
BIN
gallery/riscv/riscv.pdf
Normal file
Binary file not shown.
14
gallery/riscv/riscv.typ
Normal file
14
gallery/riscv/riscv.typ
Normal file
@ -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)
|
BIN
gallery/test.pdf
BIN
gallery/test.pdf
Binary file not shown.
@ -13,4 +13,16 @@
|
|||||||
#let test-xml = schema.load("/gallery/test.xml")
|
#let test-xml = schema.load("/gallery/test.xml")
|
||||||
#schema.render(test-xml, config: config.dark(
|
#schema.render(test-xml, config: config.dark(
|
||||||
full-page: true
|
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
|
||||||
))
|
))
|
BIN
manual.pdf
Normal file
BIN
manual.pdf
Normal file
Binary file not shown.
79
manual.typ
Normal file
79
manual.typ
Normal file
@ -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)
|
@ -117,7 +117,7 @@
|
|||||||
let txt-col = config.text-color
|
let txt-col = config.text-color
|
||||||
let bit-w = config.bit-height // Why ? I don't remember
|
let bit-w = config.bit-height // Why ? I don't remember
|
||||||
let gap = config.values-gap
|
let gap = config.values-gap
|
||||||
|
|
||||||
for (val, desc) in values.pairs().sorted(key: p => p.first()) {
|
for (val, desc) in values.pairs().sorted(key: p => p.first()) {
|
||||||
desc-y += gap
|
desc-y += gap
|
||||||
let txt = val + " = " + desc
|
let txt = val + " = " + desc
|
||||||
@ -159,16 +159,16 @@
|
|||||||
let mid-x = start-x + width / 2
|
let mid-x = start-x + width / 2
|
||||||
shapes += draw-link(config, mid-x, start-y, desc-x, desc-y)
|
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 {
|
if config.left-labels {
|
||||||
txt-anchor -= "east"
|
txt-x -= range_.description.len() * config.default-font-size / 2pt
|
||||||
}
|
}
|
||||||
|
|
||||||
shapes += draw-text(
|
shapes += draw-text(
|
||||||
range_.description,
|
range_.description,
|
||||||
config.text-color,
|
config.text-color,
|
||||||
desc-x, desc-y + bit-h / 2,
|
txt-x, desc-y + bit-h / 2,
|
||||||
anchor: "west"
|
anchor: "west"
|
||||||
)
|
)
|
||||||
|
|
||||||
@ -176,7 +176,7 @@
|
|||||||
|
|
||||||
if range_.values != none and range_.depends-on == none {
|
if range_.values != none and range_.depends-on == none {
|
||||||
let shapes_
|
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_
|
shapes += shapes_
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -266,7 +266,8 @@
|
|||||||
let width = rng.bits(range_) * bit-w
|
let width = rng.bits(range_) * bit-w
|
||||||
|
|
||||||
shapes += draw-underbracket(config, start-x, start-x + width, bits-y)
|
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-range-y = bits-y + bit-h * 1.5
|
||||||
|
|
||||||
let prev-depend-y = if depend-range.last-value-y == -1 {
|
let prev-depend-y = if depend-range.last-value-y == -1 {
|
||||||
@ -335,7 +336,9 @@
|
|||||||
shapes += shapes_
|
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) = {
|
#let draw-structure(config, struct, structures, ox: 0, oy: 0) = {
|
||||||
@ -397,10 +400,16 @@
|
|||||||
let name-x = start-x + width / 2
|
let name-x = start-x + width / 2
|
||||||
let name-y = bits-y + bit-h / 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)
|
shapes += draw-text(range_.name, txt-col, name-x, name-y, fill: bg-col)
|
||||||
|
|
||||||
if range_.description != "" {
|
if range_.description != "" {
|
||||||
//draw.circle((desc-x, -desc-y), radius: 5, fill: red)
|
|
||||||
let shapes_
|
let shapes_
|
||||||
(shapes_, desc-x, desc-y) = draw-description(
|
(shapes_, desc-x, desc-y) = draw-description(
|
||||||
config, range_, start-x, bits-y, width, desc-x, desc-y
|
config, range_, start-x, bits-y, width, desc-x, desc-y
|
||||||
@ -413,7 +422,7 @@
|
|||||||
for range_ in ranges {
|
for range_ in ranges {
|
||||||
if range_.values() != none and range_.depends-on != none {
|
if range_.values() != none and range_.depends-on != none {
|
||||||
let shapes_
|
let shapes_
|
||||||
(shapes_, desc-x, desc-y) = draw-dependency(
|
(shapes_, desc-x, desc-y, struct) = draw-dependency(
|
||||||
draw-structure, config,
|
draw-structure, config,
|
||||||
struct, structures, bits-x, bits-y, range_, desc-x, desc-y
|
struct, structures, bits-x, bits-y, range_, desc-x, desc-y
|
||||||
)
|
)
|
||||||
@ -440,7 +449,8 @@
|
|||||||
(
|
(
|
||||||
width: auto,
|
width: auto,
|
||||||
height: auto,
|
height: auto,
|
||||||
fill: config.background
|
fill: config.background,
|
||||||
|
margin: 0cm
|
||||||
)
|
)
|
||||||
} else {
|
} else {
|
||||||
(:)
|
(:)
|
||||||
@ -454,8 +464,16 @@
|
|||||||
ox: ox,
|
ox: ox,
|
||||||
oy: config.margins.at(0)
|
oy: config.margins.at(0)
|
||||||
)
|
)
|
||||||
shapes
|
// Workaround for margins
|
||||||
//draw.circle((300, -3000), fill: red, radius: 2)
|
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
|
||||||
|
)
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -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 {
|
let schema = if type(path-or-schema) == str {
|
||||||
parse-file(path-or-schema)
|
parse-file(path-or-schema)
|
||||||
} else {
|
} else {
|
||||||
|
@ -81,8 +81,7 @@
|
|||||||
)
|
)
|
||||||
}
|
}
|
||||||
|
|
||||||
#let load(path) = {
|
#let parse(content) = {
|
||||||
let content = xml(path).first()
|
|
||||||
let struct-elmts = content.children.filter(e => "tag" in e and e.tag == "structure")
|
let struct-elmts = content.children.filter(e => "tag" in e and e.tag == "structure")
|
||||||
|
|
||||||
let structures = (:)
|
let structures = (:)
|
||||||
@ -97,4 +96,9 @@
|
|||||||
return (
|
return (
|
||||||
structures: structures
|
structures: structures
|
||||||
)
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
#let load(path) = {
|
||||||
|
let content = xml(path).first()
|
||||||
|
return parse(content)
|
||||||
}
|
}
|
Reference in New Issue
Block a user