chore: Update bits syntax to use +<count>

2025-08-15 06:19:24 +02:00 · 2025-04-15 12:14:06 +05:30
parent d7730aba46
commit ea321168bd
5 changed files with 56 additions and 38 deletions
--- a/docs/syntax/packet.md
+++ b/docs/syntax/packet.md
@@ -25,14 +25,15 @@ start-end: "Block name" %% Multi-bit blocks

 ### 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 `bit` or `bits` interchangeably to set the number of bits, thus:
+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:

-````md
+```md
 packet-beta
-1bit: "Block name" %% Single-bit block
-8bits: "Block name" %% 8-bit block
+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

@@ -41,8 +42,32 @@ packet-beta
 title: "TCP Packet"
 ---
 packet-beta
-16bits: "Source Port"
-16bits: "Destination Port"
+0-15: "Source Port"
+16-31: "Destination Port"
+32-63: "Sequence Number"
+64-95: "Acknowledgment Number"
+96-99: "Data Offset"
+100-105: "Reserved"
+106: "URG"
+107: "ACK"
+108: "PSH"
+109: "RST"
+110: "SYN"
+111: "FIN"
+112-127: "Window"
+128-143: "Checksum"
+144-159: "Urgent Pointer"
+160-191: "(Options and Padding)"
+192-255: "Data (variable length)"
+```
+
+```mermaid
+---
+title: "TCP Packet"
+---
+packet-beta
+0-15: "Source Port"
+16-31: "Destination Port"
 32-63: "Sequence Number"
 64-95: "Acknowledgment Number"
 96-99: "Data Offset"
@@ -59,13 +84,12 @@ packet-beta
 160-191: "(Options and Padding)"
 192-255: "Data (variable length)"
 ```
-````

 ```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)"
@@ -74,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)"
--- a/packages/mermaid/src/diagrams/packet/packet.spec.ts
+++ b/packages/mermaid/src/diagrams/packet/packet.spec.ts
@@ -68,8 +68,8 @@ describe('packet diagrams', () => {

  it('should handle bit counts', async () => {
    const str = `packet-beta
-    8bits: "byte"
-    16bits: "word"
+    +8: "byte"
+    +16: "word"
    `;
    await expect(parser.parse(str)).resolves.not.toThrow();
    expect(getPacket()).toMatchInlineSnapshot(`
@@ -94,8 +94,8 @@ describe('packet diagrams', () => {

  it('should handle bit counts with bit or bits', async () => {
    const str = `packet-beta
-    8bit: "byte"
-    16bits: "word"
+    +8: "byte"
+    +16: "word"
    `;
    await expect(parser.parse(str)).resolves.not.toThrow();
    expect(getPacket()).toMatchInlineSnapshot(`
@@ -206,7 +206,7 @@ describe('packet diagrams', () => {

  it('should throw error if numbers are not continuous with bit counts', async () => {
    const str = `packet-beta
-    16bits: "test"
+    +16: "test"
    18-20: "error"
    `;
    await expect(parser.parse(str)).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -226,7 +226,7 @@ describe('packet diagrams', () => {

  it('should throw error if numbers are not continuous for single packets with bit counts', async () => {
    const str = `packet-beta
-    16 bits: "test"
+    +16: "test"
    18: "error"
    `;
    await expect(parser.parse(str)).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -257,7 +257,7 @@ describe('packet diagrams', () => {

  it('should throw error if bit count is 0', async () => {
    const str = `packet-beta
-    0bits: "test"
+    +0: "test"
    `;
    await expect(parser.parse(str)).rejects.toThrowErrorMatchingInlineSnapshot(
      `[Error: Packet block 0 is invalid. Cannot have a zero bit field.]`
--- a/packages/mermaid/src/diagrams/packet/parser.ts
+++ b/packages/mermaid/src/diagrams/packet/parser.ts
@@ -19,9 +19,7 @@ const populate = (ast: Packet) => {
    if (start !== undefined && end !== undefined && end < start) {
      throw new Error(`Packet block ${start} - ${end} is invalid. End must be greater than start.`);
    }
-    if (start == undefined) {
-      start = lastBit + 1;
-    }
+    start ??= lastBit + 1;
    if (start !== lastBit + 1) {
      throw new Error(
        `Packet block ${start} - ${end ?? start} is not contiguous. It should start from ${
@@ -32,12 +30,8 @@ const populate = (ast: Packet) => {
    if (bits === 0) {
      throw new Error(`Packet block ${start} is invalid. Cannot have a zero bit field.`);
    }
-    if (end == undefined) {
-      end = start + (bits ?? 1) - 1;
-    }
-    if (bits == undefined) {
-      bits = end - start + 1;
-    }
+    end ??= start + (bits ?? 1) - 1;
+    bits ??= end - start + 1;
    lastBit = end;
    log.debug(`Packet block ${start} - ${lastBit} with label ${label}`);

--- a/packages/mermaid/src/docs/syntax/packet.md
+++ b/packages/mermaid/src/docs/syntax/packet.md
@@ -19,14 +19,15 @@ start-end: "Block name" %% Multi-bit blocks

 ### 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 `bit` or `bits` interchangeably to set the number of bits, thus:
+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:

-````md
+```md
 packet-beta
-1bit: "Block name" %% Single-bit block
-8bits: "Block name" %% 8-bit block
+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

@@ -35,8 +36,8 @@ packet-beta
 title: "TCP Packet"
 ---
 packet-beta
-16bits: "Source Port"
-16bits: "Destination Port"
+0-15: "Source Port"
+16-31: "Destination Port"
 32-63: "Sequence Number"
 64-95: "Acknowledgment Number"
 96-99: "Data Offset"
@@ -53,13 +54,12 @@ packet-beta
 160-191: "(Options and Padding)"
 192-255: "Data (variable length)"
 ```
-````

 ```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)"
--- a/packages/parser/src/language/packet/packet.langium
+++ b/packages/parser/src/language/packet/packet.langium
@@ -13,8 +13,8 @@ entry Packet:

 PacketBlock:
  (
-    start=INT('-' (end=INT | bits=INT'bit''s'?))? 
-    | bits=INT'bit''s'?
+    start=INT('-' end=INT)?
+    | '+' bits=INT
  )
  ':' label=STRING
  EOL