Add dot-dsl exercise

config.json

@@ -563,6 +563,14 @@
         "prerequisites": [],
         "difficulty": 4
       },
+      {
+        "slug": "dot-dsl",
+        "name": "DOT DSL",
+        "uuid": "08cf7c8e-a997-4e66-9af4-97faa5dc5a97",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 4
+      },
       {
         "slug": "eliuds-eggs",
         "name": "Eliud's Eggs",

exercises/practice/dot-dsl/.docs/instructions.append.md

@@ -0,0 +1,32 @@
+# Instructions append
+
+## Description of DSL
+
+Here's an example of what the DSL should look like:
+
+```roc
+graph = buildGraph { bgColor: Yellow } [
+    node "a" { color: Red },
+    node "b" { color: Green },
+    node "c" {},
+    edge "a" "b" { color: Red, style: Dotted },
+    edge "b" "c" { color: Blue },
+    edge "a" "c" { color: Green },
+]
+```
+
+This code should build a graph with a yellow background, and three nodes, "a", "b", and "c", respectively colored red, green, and black (which is the default color). They should be connected by 3 edges of different colors and styles: the edge between "a" and "b" should be red and dotted, and the edges between "b" and "c" and between "a" and "c" should be solid (which is the default style) and green.
+
+## The `node` and `edge` Functions
+
+The `node` function should simply create an `AddNode` value with the arguments as payload. This is a DSL command used only by the `buildGraph` function. For example, `node "a" { color: Red }` should return `AddNode "a" { color: Red } `. If an attribute is missing, its default value should be used. For example, `node "c" {}` should return `AddNode "c" { color: Black }`.
+
+Similarly, the `edge` function should create an `AddEdge` value. For example, `edge "a" "b" {}` should return `AddEdge "a" "b" {color: Default, style: Solid}`.
+
+These two simple functions make the DSL code much more pleasant to read & write.
+
+## Objective
+
+Once you have implemented the `node` and `edge` functions (they should be easy), your main goal is to write the `buildGraph` function: it must go through the list of DSL commands and produce the desired graph, represented as a record `{ bgColor: ..., nodes: ..., edges: ...}`.
+
+To double the fun, you can optionally try to implement a `toDot` function that converts the graph to a `Str` with using the Dot format!

exercises/practice/dot-dsl/.docs/instructions.md

@@ -0,0 +1,30 @@
+# Instructions
+
+A [Domain Specific Language (DSL)][dsl] is a small language optimized for a specific domain.
+Since a DSL is targeted, it can greatly impact productivity/understanding by allowing the writer to declare _what_ they want rather than _how_.
+
+One problem area where they are applied are complex customizations/configurations.
+
+For example the [DOT language][dot-language] allows you to write a textual description of a graph which is then transformed into a picture by one of the [Graphviz][graphviz] tools (such as `dot`).
+A simple graph looks like this:
+
+    graph {
+        graph [bgcolor="yellow"]
+        a [color="red"]
+        b [color="blue"]
+        a -- b [color="green"]
+    }
+
+Putting this in a file `example.dot` and running `dot example.dot -T png -o example.png` creates an image `example.png` with red and blue circle connected by a green line on a yellow background.
+
+Write a Domain Specific Language similar to the Graphviz dot language.
+
+Our DSL is similar to the Graphviz dot language in that our DSL will be used to create graph data structures.
+However, unlike the DOT Language, our DSL will be an internal DSL for use only in our language.
+
+More information about the difference between internal and external DSLs can be found [here][fowler-dsl].
+
+[dsl]: https://en.wikipedia.org/wiki/Domain-specific_language
+[dot-language]: https://en.wikipedia.org/wiki/DOT_(graph_description_language)
+[graphviz]: https://graphviz.org/
+[fowler-dsl]: https://martinfowler.com/bliki/DomainSpecificLanguage.html

exercises/practice/dot-dsl/.meta/Example.roc

@@ -0,0 +1,63 @@
+module [buildGraph, node, edge]
+
+Color : [Black, Red, Green, Blue, Yellow]
+Style : [Solid, Dotted]
+
+Graph : {
+    bgColor : Color,
+    nodes : Dict Str { color : Color },
+    edges : Dict (Str, Str) { color : Color, style : Style },
+}
+
+DslCommand : [AddNode Str { color : Color }, AddEdge Str Str { color : Color, style : Style }]
+
+node : Str, { color ? Color } -> [AddNode Str { color : Color }]
+node = \id, { color ? Black } ->
+    AddNode id { color }
+
+edge : Str, Str, { color ? Color, style ? Style } -> [AddEdge Str Str { color : Color, style : Style }]
+edge = \id1, id2, { color ? Black, style ? Solid } ->
+    AddEdge id1 id2 { color, style }
+
+buildGraph : { bgColor ? Color }, List DslCommand -> Graph
+buildGraph = \{ bgColor ? Black }, dslCommands ->
+    dslCommands
+    |> List.walk { bgColor, nodes: Dict.empty {}, edges: Dict.empty {} } \state, command ->
+        when command is
+            AddNode id attributes ->
+                nodes = state.nodes |> Dict.insert id attributes
+                { state & nodes }
+
+            AddEdge id1 id2 attributes ->
+                nodes =
+                    state.nodes
+                    |> Dict.update id1 \maybeAttrs ->
+                        when maybeAttrs is
+                            Ok existingAttrs -> Ok existingAttrs
+                            Err Missing -> Ok { color: Black }
+                    |> Dict.update id2 \maybeAttrs ->
+                        when maybeAttrs is
+                            Ok existingAttrs -> Ok existingAttrs
+                            Err Missing -> Ok { color: Black }
+                edgeId = if compareStrings id1 id2 == LT then (id1, id2) else (id2, id1)
+                edges =
+                    state.edges
+                    |> Dict.insert edgeId attributes
+                { state & nodes, edges }
+
+## Compare two strings, first by their UTF8 representations, then by length:
+## "" < "ABC" < "abc" < "abcdef"
+## This is used to sort the users in the JSON outputs
+compareStrings : Str, Str -> [LT, EQ, GT]
+compareStrings = \string1, string2 ->
+    b1 = string1 |> Str.toUtf8
+    b2 = string2 |> Str.toUtf8
+    result =
+        List.map2 b1 b2 \c1, c2 -> Num.compare c1 c2
+        |> List.walkTry (Ok EQ) \_state, cmp ->
+            when cmp is
+                EQ -> Ok EQ
+                res -> Err res
+    when result is
+        Ok _cmp -> Num.compare (List.len b1) (List.len b2)
+        Err res -> res

exercises/practice/dot-dsl/.meta/config.json

@@ -0,0 +1,19 @@
+{
+  "authors": [
+    "ageron"
+  ],
+  "files": {
+    "solution": [
+      "DotDsl.roc"
+    ],
+    "test": [
+      "dot-dsl-test.roc"
+    ],
+    "example": [
+      ".meta/Example.roc"
+    ]
+  },
+  "blurb": "Write a Domain Specific Language similar to the Graphviz dot language.",
+  "source": "Wikipedia",
+  "source_url": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)"
+}

exercises/practice/dot-dsl/DotDsl.roc

@@ -0,0 +1,24 @@
+module [buildGraph, node, edge]
+
+Color : [Black, Red, Green, Blue, Yellow]
+Style : [Solid, Dotted]
+
+Graph : {
+    bgColor : Color,
+    nodes : Dict Str { color : Color },
+    edges : Dict (Str, Str) { color : Color, style : Style },
+}
+
+DslCommand : [AddNode Str { color : Color }, AddEdge Str Str { color : Color, style : Style }]
+
+node : Str, { color ? Color } -> [AddNode Str { color : Color }]
+node = \id, { color ? Black } ->
+    crash "Please implement the 'node' function"
+
+edge : Str, Str, { color ? Color, style ? Style } -> [AddEdge Str Str { color : Color, style : Style }]
+edge = \id1, id2, { color ? Black, style ? Solid } ->
+    crash "Please implement the 'edge' function"
+
+buildGraph : { bgColor ? Color }, List DslCommand -> Graph
+buildGraph = \{ bgColor ? Black }, dslCommands ->
+    crash "Please implement the 'buildGraph' function"

exercises/practice/dot-dsl/dot-dsl-test.roc

@@ -0,0 +1,171 @@
+# File last updated on 2024-10-21
+app [main] {
+    pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.15.0/SlwdbJ-3GR7uBWQo6zlmYWNYOxnvo8r6YABXD-45UOw.tar.br",
+}
+
+main =
+    Task.ok {}
+
+import DotDsl exposing [buildGraph, node, edge]
+
+## The following function is a temporary workaround for Roc issue #7144:
+## comparing records containing dicts may return the wrong result depending on
+## the internal order of the dict data, so we have to extract the dicts and
+## compare them directly.
+isEq = \graph1, graph2 ->
+    (graph1.bgColor == graph2.bgColor)
+    && (graph1.nodes == graph2.nodes)
+    && (graph1.edges == graph2.edges)
+
+# Can create an AddNode command
+expect
+    result = node "a" { color: Red }
+    expected = AddNode "a" { color: Red }
+    result == expected
+
+# Can create an AddNode command with the default color
+expect
+    result = node "b" {}
+    expected = AddNode "b" { color: Black }
+    result == expected
+
+# Can create an AddEdge command
+expect
+    result = edge "a" "b" { color: Red, style: Dotted }
+    expected = AddEdge "a" "b" { color: Red, style: Dotted }
+    result == expected
+
+# Can create an AddEdge command with the default color and style
+expect
+    result = edge "c" "d" {}
+    expected = AddEdge "c" "d" { color: Black, style: Solid }
+    result == expected
+
+# Can create an empty graph
+expect
+    result = buildGraph {} []
+    expected = {
+        bgColor: Black,
+        nodes: Dict.empty {},
+        edges: Dict.empty {},
+    }
+    result |> isEq expected
+
+# can set the background color
+expect
+    result = buildGraph { bgColor: Red } []
+    expected = {
+        bgColor: Red,
+        nodes: Dict.empty {},
+        edges: Dict.empty {},
+    }
+    result |> isEq expected
+
+# can create a graph with a few nodes of various colors
+expect
+    result = buildGraph {} [
+        node "a" {},
+        node "b" { color: Green },
+        node "c" { color: Blue },
+    ]
+    expected = {
+        bgColor: Black,
+        nodes: Dict.fromList [("a", { color: Black }), ("b", { color: Green }), ("c", { color: Blue })],
+        edges: Dict.empty {},
+    }
+    result |> isEq expected
+
+# can create a graph with a two nodes connected by one edge
+expect
+    result = buildGraph {} [
+        node "a" {},
+        node "b" {},
+        edge "a" "b" { color: Yellow, style: Dotted },
+    ]
+    expected = {
+        bgColor: Black,
+        nodes: Dict.fromList [("a", { color: Black }), ("b", { color: Black })],
+        edges: Dict.fromList [(("a", "b"), { color: Yellow, style: Dotted })],
+    }
+    result |> isEq expected
+
+# creating an edge automatically creates the nodes if they don't exist yet
+expect
+    result = buildGraph {} [
+        edge "a" "b" {},
+    ]
+    expected = {
+        bgColor: Black,
+        nodes: Dict.fromList [("a", { color: Black }), ("b", { color: Black })],
+        edges: Dict.fromList [(("a", "b"), { color: Black, style: Solid })],
+    }
+    result |> isEq expected
+
+# creating a node after an edge it's connected to is possible
+expect
+    result = buildGraph {} [
+        edge "a" "b" { color: Red },
+        node "a" { color: Blue },
+    ]
+    expected = {
+        bgColor: Black,
+        nodes: Dict.fromList [("a", { color: Blue }), ("b", { color: Black })],
+        edges: Dict.fromList [(("a", "b"), { color: Red, style: Solid })],
+    }
+    result |> isEq expected
+
+# can create a multicolor triangle
+expect
+    result = buildGraph { bgColor: Yellow } [
+        node "a" { color: Red },
+        node "b" { color: Green },
+        node "c" { color: Blue },
+        edge "a" "b" { color: Red, style: Dotted },
+        edge "b" "c" { color: Blue },
+        edge "a" "c" { color: Green },
+    ]
+    expected = {
+        bgColor: Yellow,
+        nodes: Dict.fromList [("a", { color: Red }), ("b", { color: Green }), ("c", { color: Blue })],
+        edges: Dict.fromList [
+            (("a", "b"), { color: Red, style: Dotted }),
+            (("b", "c"), { color: Blue, style: Solid }),
+            (("a", "c"), { color: Green, style: Solid }),
+        ],
+    }
+    result |> isEq expected
+
+# edge ids are sorted alphabetically
+expect
+    result = buildGraph {} [
+        edge "b" "a" {},
+        edge "c" "b" {},
+        edge "c" "a" {},
+    ]
+    expected = {
+        bgColor: Black,
+        nodes: Dict.fromList [("a", { color: Black }), ("b", { color: Black }), ("c", { color: Black })],
+        edges: Dict.fromList [
+            (("a", "b"), { color: Black, style: Solid }),
+            (("b", "c"), { color: Black, style: Solid }),
+            (("a", "c"), { color: Black, style: Solid }),
+        ],
+    }
+    result |> isEq expected
+
+# adding the same node or edge multiple times only keeps the last occurrence
+expect
+    result = buildGraph {} [
+        node "a" { color: Blue },
+        node "a" { color: Red },
+        node "a" { color: Green },
+        edge "a" "b" { color: Yellow },
+    ]
+    expected = {
+        bgColor: Black,
+        nodes: Dict.fromList [("a", { color: Green }), ("b", { color: Black })],
+        edges: Dict.fromList [
+            (("a", "b"), { color: Yellow, style: Solid }),
+        ],
+    }
+    result |> isEq expected