Merge branch 'release_v0.2.0'

motchy869 · Mar 13, 2024 · 82be9ab · 82be9ab
2 parents 6551d07 + 0d9545d
commit 82be9ab
Show file tree

Hide file tree

Showing 12 changed files with 447 additions and 81 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -2,6 +2,8 @@
     "cSpell.words": [
         "bidir",
         "divname",
-        "hdelk"
+        "elkjs",
+        "hdelk",
+        "LEFTUP"
     ]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2024-03-13
+
+- Added:
+  - C-style comment and string interpolation
+  - show dimension in edge label with `rank` option (e.g.: `rank: [2,8]` automatically appends `[1:0][7:0]` to the label)
+  - edge bus visual width override by `edge_bus_visual_width` argument of `hdelk.layout` function (e.g. `hdelk.layout(graph, "diagram", edge_bus_visual_width=3)`).
+
 ## [0.1.0] - 2024-03-11
 
 initial release
diff --git a/README.md b/README.md
@@ -0,0 +1,62 @@
+# HDElk mod
+
+![banner](images/banner_2.png)
+
+This is a fork from [HDElk](https://github.com/davidthings/hdelk).
+Some features are added:
+
+## 1. New features
+
+1. arrow-head at edge termination
+2. Bi-directional edge with `bidir` option (reverse is not supported)
+3. multi-line node and edge label
+4. show dimension in port and edge label with `rank` option (e.g.: `rank: [2,8]` automatically appends `[1:0][7:0]` to the label)
+5. You can specify `thoroughness` layout algorithm parameter of ELK. `hdelk.layout(graph, "title", [thoroughness]);`
+6. You can fix port orders (do not sort ports in layout calculation) per node.
+7. C-style comments in `.jsonc` file (see: [C-style comments and Julia-based string interpolation](#2-c-style-comments-and-julia-based-string-interpolation))
+8. Julia-based string interpolation (see: [C-style comments and Julia-based string interpolation](#2-c-style-comments-and-julia-based-string-interpolation))
+9. You can override edge bus visual width by `edge_bus_visual_width` argument of `hdelk.layout` function (e.g. `hdelk.layout(graph, "diagram", edge_bus_visual_width=3)`).
+10. new colors
+
+![new colors](images/new_colors.png)
+
+## 2. C-style comments and Julia-based string interpolation
+
+### 2.1. Prerequisites
+
+This program is tested in the following environment:
+
+- GNU bash 5.1.16
+- GNU sed 4.8
+- Python 3.10.13
+- Julia 1.10.2
+
+### 2.2. How to use
+
+1. Put constants used in JSONC file in `constants.jl`. This `.jl` file should be placed in the same directory as the target JSONC file.
+   Example usage is shown in `example/constants.jl`.
+2. Write the target JSONC file.
+In this file, the HDElk syntax is valid.
+In addition, the following features can be used:
+
+    1. C-style comments (`/* ... */`)
+    2. Julia string interpolation (`$(...)`)
+
+   Example usage is shown in `example/example_count.jsonc`.
+3. Run the following command:
+
+    ```bash
+    py_scripts/jsonc2html.py <path to the target JSONC file>
+
+    # example:
+    # $ py_scripts/jsonc2html.py example/example_count.jsonc
+    ```
+
+    The intermediate `julia_code.jl` is generated and Julia runs it.
+
+4. The generated HTML file's base name is the same as that of the input JSONC file.
+To render this HTML file, make sure that **HDElk's `js` folder is in the same directory as the HTML file** (or you can modify the js library path in the html template in `jsonc2html.py` script, or manually edit the generated html file).
+
+## 3. modified files
+
+- `js/hdelk.js`
diff --git a/example.html b/example.html
diff --git a/example/constants.jl b/example/constants.jl
@@ -0,0 +1 @@
+BIT_WIDTH_CNT = 48;
diff --git a/example/example.html b/example/example.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html>
+<body>
+
+<h1>HDElk Bare Bones Example</h1>
+
+<script src="../js/elk.bundled.js"></script>
+<script src="../js/svg.min.js"></script>
+<script src="../js/hdelk.js"></script>
+
+<div id="simple_diagram"></div>
+
+<script type="text/javascript">
+
+    var simple_graph = {
+        color:"#EEE",
+        children:[
+            {
+                id:"C1", type:"TypeA", highlight:6,
+                inPorts:[
+                    {id: "In"}
+                ],
+                outPorts: [
+                    {id: "Out"}
+                ],
+                eastPorts: [
+                {id: "InOut", rank:[2,8]}
+                ]
+            },
+            {id:"C2", type:"TypeB", ports:["In", "Out"], label:"C2\nmultiple-line\nnode name", highlight:7},
+            {id:"C3", type:"TypeC", highlight:8}
+        ],
+        edges:[
+            {route:["C1.InOut","C2.In"], label:"Path1\nbi-directional edge", bus:1, bidir:1},
+            {route: ["C2.Out","C3"], label:"Path2\nmultiple-line", bus:1}
+        ]
+    }
+
+    hdelk.layout(
+        simple_graph, "simple_diagram",
+        /*edge_bus_width=3*/ // can override default edge bus width
+    );
+</script>
+
+</body>
+</html>
diff --git a/example/example_count.html b/example/example_count.html
@@ -0,0 +1,86 @@
+
+<!DOCTYPE html>
+<html>
+<body>
+
+<script src="../js/elk.bundled.js"></script>
+<script src="../js/svg.min.js"></script>
+<script src="../js/hdelk.js"></script>
+
+<div id="diagram"></div>
+
+<script type="text/javascript">
+var diagram =
+{
+    "id": "count block diagram",
+    "children": [
+        {
+            "id": "count",
+            "inPorts": [
+                "i_clk",
+                "i_sync_rst",
+                "i_clr_cnt",
+                "s_axi4_lite"
+            ],
+            "outPorts": [
+                {"id": "o_cnt", "rank": [48]}
+            ],
+            "children": [
+                {
+                    "id": "csr",
+                    "inPorts": [
+                        "i_clk",
+                        "i_sync_rst",
+                        "s_axi4_lite",
+                        "i_cnt"
+                    ],
+                    "outPorts": [
+                        "o_clr_cnt"
+                    ]
+                },
+                {
+                    "id": "core",
+                    "inPorts": [
+                        "i_clk",
+                        "i_sync_rst",
+                        "i_clr_cnt"
+                    ],
+                    "outPorts": [
+                        {"id": "o_cnt", "rank": [48]}
+                    ]
+                },
+                {
+                    "id": "or",
+                    "inPorts": [
+                        "i_a",
+                        "i_b"
+                    ],
+                    "outPorts": [
+                        "o"
+                    ]
+                }
+            ],
+            "edges": [
+                {"route": ["count.i_clk", "csr.i_clk"]},
+                {"route": ["count.i_sync_rst", "csr.i_sync_rst"]},
+                {"route": ["count.s_axi4_lite", "csr.s_axi4_lite"], "bus": 1},
+                {"route": ["count.i_clk", "core.i_clk"]},
+                {"route": ["count.i_sync_rst", "core.i_sync_rst"]},
+                {"route": ["count.i_clr_cnt", "or.i_a"]},
+                {"route": ["core.o_cnt", "count.o_cnt"], "bus": 1},
+
+                {"route": ["csr.o_clr_cnt", "or.i_b"]},
+                {"route": ["or.o", "core.i_clr_cnt"]},
+                {"route": ["count.i_clr_cnt", "or.i_a"]},
+                {"route": ["core.o_cnt", "csr.i_cnt"], "bus": 1}
+            ]
+        }
+    ]
+}
+
+
+hdelk.layout(diagram, "diagram");
+</script>
+
+</body>
+</html>
diff --git a/example/example_count.jsonc b/example/example_count.jsonc
@@ -0,0 +1,69 @@
+
+{
+    "id": "count block diagram",
+    "children": [
+        {
+            "id": "count",
+            "inPorts": [
+                "i_clk",
+                "i_sync_rst",
+                "i_clr_cnt",
+                "s_axi4_lite"
+            ],
+            "outPorts": [
+                {"id": "o_cnt", "rank": [$BIT_WIDTH_CNT]}
+            ],
+            "children": [
+                {
+                    "id": "csr",
+                    "inPorts": [
+                        "i_clk",
+                        "i_sync_rst",
+                        "s_axi4_lite",
+                        "i_cnt"
+                    ],
+                    "outPorts": [
+                        "o_clr_cnt"
+                    ]
+                },
+                {
+                    "id": "core",
+                    "inPorts": [
+                        "i_clk",
+                        "i_sync_rst",
+                        "i_clr_cnt"
+                    ],
+                    "outPorts": [
+                        {"id": "o_cnt", "rank": [$BIT_WIDTH_CNT]}
+                    ]
+                },
+                {
+                    "id": "or",
+                    "inPorts": [
+                        "i_a",
+                        "i_b"
+                    ],
+                    "outPorts": [
+                        "o"
+                    ]
+                }
+            ],
+            "edges": [
+                /* connections between block's ports and sub-blocks' ports */
+                {"route": ["count.i_clk", "csr.i_clk"]},
+                {"route": ["count.i_sync_rst", "csr.i_sync_rst"]},
+                {"route": ["count.s_axi4_lite", "csr.s_axi4_lite"], "bus": 1},
+                {"route": ["count.i_clk", "core.i_clk"]},
+                {"route": ["count.i_sync_rst", "core.i_sync_rst"]},
+                {"route": ["count.i_clr_cnt", "or.i_a"]},
+                {"route": ["core.o_cnt", "count.o_cnt"], "bus": 1},
+
+                /* connections between sub-blocks */
+                {"route": ["csr.o_clr_cnt", "or.i_b"]},
+                {"route": ["or.o", "core.i_clr_cnt"]},
+                {"route": ["count.i_clr_cnt", "or.i_a"]},
+                {"route": ["core.o_cnt", "csr.i_cnt"], "bus": 1}
+            ]
+        }
+    ]
+}