marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-11-14 09:44:51 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5980 from BryanCrotazGivEnergy/packet-diagram-bit-counts

Browse Source 
Feature: Packet diagram can use bit counts - implements #5978
This commit is contained in:
Sidharth Vinod
2025-05-09 04:59:53 +00:00
committed by GitHub
parent 6b886abf39 fa22ed137c
commit 17a156901a
6 changed files with 162 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.changeset/quiet-hotels-shine.md Normal file
View File

@@ -0,0 +1,6 @@
---
'mermaid': minor
'@mermaid-js/parser': minor
---
feat: Add shorter `+<count>: Label` syntax in packet diagram

22
docs/syntax/packet.md
View File

@@ -16,13 +16,25 @@ This diagram type is particularly useful for developers, network engineers, educ
## Syntax
```md
```
packet-beta
start: "Block name" %% Single-bit block
start-end: "Block name" %% Multi-bit blocks
... More Fields ...
```
### Bits Syntax (v\<MERMAID_RELEASE_VERSION>+)
Using start and end bit counts can be difficult, especially when modifying a design. For this we add a bit count field, which starts from the end of the previous field automagically. Use `+<count>` to set the number of bits, thus:
```
packet-beta
+1: "Block name" %% Single-bit block
+8: "Block name" %% 8-bit block
9-15: "Manually set start and end, it's fine to mix and match"
... More Fields ...
```
## Examples
```mermaid-example
@@ -76,8 +88,8 @@ packet-beta
```mermaid-example
packet-beta
title UDP Packet
0-15: "Source Port"
16-31: "Destination Port"
+16: "Source Port"
+16: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"
@@ -86,8 +98,8 @@ title UDP Packet
```mermaid
packet-beta
title UDP Packet
0-15: "Source Port"
16-31: "Destination Port"
+16: "Source Port"
+16: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"

91
packages/mermaid/src/diagrams/packet/packet.spec.ts
View File

@@ -30,6 +30,7 @@ describe('packet diagrams', () => {
[
[
{
"bits": 11,
"end": 10,
"label": "test",
"start": 0,
@@ -49,11 +50,13 @@ describe('packet diagrams', () => {
[
[
{
"bits": 11,
"end": 10,
"label": "test",
"start": 0,
},
{
"bits": 1,
"end": 11,
"label": "single",
"start": 11,
@@ -63,6 +66,58 @@ describe('packet diagrams', () => {
`);
});
it('should handle bit counts', async () => {
const str = `packet-beta
+8: "byte"
+16: "word"
`;
await expect(parser.parse(str)).resolves.not.toThrow();
expect(getPacket()).toMatchInlineSnapshot(`
[
[
{
"bits": 8,
"end": 7,
"label": "byte",
"start": 0,
},
{
"bits": 16,
"end": 23,
"label": "word",
"start": 8,
},
],
]
`);
});
it('should handle bit counts with bit or bits', async () => {
const str = `packet-beta
+8: "byte"
+16: "word"
`;
await expect(parser.parse(str)).resolves.not.toThrow();
expect(getPacket()).toMatchInlineSnapshot(`
[
[
{
"bits": 8,
"end": 7,
"label": "byte",
"start": 0,
},
{
"bits": 16,
"end": 23,
"label": "word",
"start": 8,
},
],
]
`);
});
it('should split into multiple rows', async () => {
const str = `packet-beta
0-10: "test"
@@ -73,11 +128,13 @@ describe('packet diagrams', () => {
[
[
{
"bits": 11,
"end": 10,
"label": "test",
"start": 0,
},
{
"bits": 20,
"end": 31,
"label": "multiple",
"start": 11,
@@ -85,6 +142,7 @@ describe('packet diagrams', () => {
],
[
{
"bits": 31,
"end": 63,
"label": "multiple",
"start": 32,
@@ -92,6 +150,7 @@ describe('packet diagrams', () => {
],
[
{
"bits": 26,
"end": 90,
"label": "multiple",
"start": 64,
@@ -111,11 +170,13 @@ describe('packet diagrams', () => {
[
[
{
"bits": 17,
"end": 16,
"label": "test",
"start": 0,
},
{
"bits": 14,
"end": 31,
"label": "multiple",
"start": 17,
@@ -123,6 +184,7 @@ describe('packet diagrams', () => {
],
[
{
"bits": 31,
"end": 63,
"label": "multiple",
"start": 32,
@@ -142,6 +204,16 @@ describe('packet diagrams', () => {
);
});
it('should throw error if numbers are not continuous with bit counts', async () => {
const str = `packet-beta
+16: "test"
18-20: "error"
`;
await expect(parser.parse(str)).rejects.toThrowErrorMatchingInlineSnapshot(
`[Error: Packet block 18 - 20 is not contiguous. It should start from 16.]`
);
});
it('should throw error if numbers are not continuous for single packets', async () => {
const str = `packet-beta
0-16: "test"
@@ -152,6 +224,16 @@ describe('packet diagrams', () => {
);
});
it('should throw error if numbers are not continuous for single packets with bit counts', async () => {
const str = `packet-beta
+16: "test"
18: "error"
`;
await expect(parser.parse(str)).rejects.toThrowErrorMatchingInlineSnapshot(
`[Error: Packet block 18 - 18 is not contiguous. It should start from 16.]`
);
});
it('should throw error if numbers are not continuous for single packets - 2', async () => {
const str = `packet-beta
0-16: "test"
@@ -172,4 +254,13 @@ describe('packet diagrams', () => {
`[Error: Packet block 25 - 20 is invalid. End must be greater than start.]`
);
});
it('should throw error if bit count is 0', async () => {
const str = `packet-beta
+0: "test"
`;
await expect(parser.parse(str)).rejects.toThrowErrorMatchingInlineSnapshot(
`[Error: Packet block 0 is invalid. Cannot have a zero bit field.]`
);
});
});

38
packages/mermaid/src/diagrams/packet/parser.ts
View File

@@ -10,26 +10,33 @@ const maxPacketSize = 10_000;
const populate = (ast: Packet) => {
populateCommonDb(ast, db);
let lastByte = -1;
let lastBit = -1;
let word: PacketWord = [];
let row = 1;
const { bitsPerRow } = db.getConfig();
for (let { start, end, label } of ast.blocks) {
if (end && end < start) {
for (let { start, end, bits, label } of ast.blocks) {
if (start !== undefined && end !== undefined && end < start) {
throw new Error(`Packet block ${start} - ${end} is invalid. End must be greater than start.`);
}
if (start !== lastByte + 1) {
start ??= lastBit + 1;
if (start !== lastBit + 1) {
throw new Error(
`Packet block ${start} - ${end ?? start} is not contiguous. It should start from ${
lastByte + 1
lastBit + 1
}.`
);
}
lastByte = end ?? start;
log.debug(`Packet block ${start} - ${lastByte} with label ${label}`);
if (bits === 0) {
throw new Error(`Packet block ${start} is invalid. Cannot have a zero bit field.`);
}
end ??= start + (bits ?? 1) - 1;
bits ??= end - start + 1;
lastBit = end;
log.debug(`Packet block ${start} - ${lastBit} with label ${label}`);
while (word.length <= bitsPerRow + 1 && db.getPacket().length < maxPacketSize) {
const [block, nextBlock] = getNextFittingBlock({ start, end, label }, row, bitsPerRow);
const [block, nextBlock] = getNextFittingBlock({ start, end, bits, label }, row, bitsPerRow);
word.push(block);
if (block.end + 1 === row * bitsPerRow) {
db.pushWord(word);
@@ -39,7 +46,7 @@ const populate = (ast: Packet) => {
if (!nextBlock) {
break;
}
({ start, end, label } = nextBlock);
({ start, end, bits, label } = nextBlock);
}
}
db.pushWord(word);
@@ -50,8 +57,11 @@ const getNextFittingBlock = (
row: number,
bitsPerRow: number
): [Required<PacketBlock>, PacketBlock | undefined] => {
if (block.start === undefined) {
throw new Error('start should have been set during first phase');
}
if (block.end === undefined) {
block.end = block.start;
throw new Error('end should have been set during first phase');
}
if (block.start > block.end) {
@@ -62,16 +72,20 @@ const getNextFittingBlock = (
return [block as Required<PacketBlock>, undefined];
}
const rowEnd = row * bitsPerRow - 1;
const rowStart = row * bitsPerRow;
return [
{
start: block.start,
end: row * bitsPerRow - 1,
end: rowEnd,
label: block.label,
bits: rowEnd - block.start,
},
{
start: row * bitsPerRow,
start: rowStart,
end: block.end,
label: block.label,
bits: block.end - rowStart,
},
];
};

18
packages/mermaid/src/docs/syntax/packet.md
View File

@@ -10,13 +10,25 @@ This diagram type is particularly useful for developers, network engineers, educ
## Syntax
```md
```
packet-beta
start: "Block name" %% Single-bit block
start-end: "Block name" %% Multi-bit blocks
... More Fields ...
```
### Bits Syntax (v<MERMAID_RELEASE_VERSION>+)
Using start and end bit counts can be difficult, especially when modifying a design. For this we add a bit count field, which starts from the end of the previous field automagically. Use `+<count>` to set the number of bits, thus:
```
packet-beta
+1: "Block name" %% Single-bit block
+8: "Block name" %% 8-bit block
9-15: "Manually set start and end, it's fine to mix and match"
... More Fields ...
```
## Examples
```mermaid-example
@@ -46,8 +58,8 @@ packet-beta
```mermaid-example
packet-beta
title UDP Packet
0-15: "Source Port"
16-31: "Destination Port"
+16: "Source Port"
+16: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"

9
packages/parser/src/language/packet/packet.langium
View File

@@ -12,5 +12,10 @@ entry Packet:
;
PacketBlock:
start=INT('-' end=INT)? ':' label=STRING EOL
;
(
start=INT('-' end=INT)?
| '+' bits=INT
)
':' label=STRING
EOL
;