Add sgf-parsing exercise

config.json

@@ -837,6 +837,14 @@
         "practices": [],
         "prerequisites": [],
         "difficulty": 1
+      },
+      {
+        "slug": "sgf-parsing",
+        "name": "SGF Parsing",
+        "uuid": "e9e9edd4-30cb-4511-ac38-f54f25c89c32",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 1
       }
     ],
     "foregone": [

exercises/practice/sgf-parsing/.docs/instructions.md

@@ -0,0 +1,83 @@
+# Instructions
+
+Parsing a Smart Game Format string.
+
+[SGF][sgf] is a standard format for storing board game files, in particular go.
+
+SGF is a fairly simple format. An SGF file usually contains a single
+tree of nodes where each node is a property list. The property list
+contains key value pairs, each key can only occur once but may have
+multiple values.
+
+The exercise will have you parse an SGF string and return a tree structure of properties.
+
+An SGF file may look like this:
+
+```text
+(;FF[4]C[root]SZ[19];B[aa];W[ab])
+```
+
+This is a tree with three nodes:
+
+- The top level node has three properties: FF\[4\] (key = "FF", value
+  = "4"), C\[root\](key = "C", value = "root") and SZ\[19\] (key =
+  "SZ", value = "19"). (FF indicates the version of SGF, C is a
+  comment and SZ is the size of the board.)
+  - The top level node has a single child which has a single property:
+    B\[aa\]. (Black plays on the point encoded as "aa", which is the
+    1-1 point).
+    - The B\[aa\] node has a single child which has a single property:
+      W\[ab\].
+
+As you can imagine an SGF file contains a lot of nodes with a single
+child, which is why there's a shorthand for it.
+
+SGF can encode variations of play. Go players do a lot of backtracking
+in their reviews (let's try this, doesn't work, let's try that) and SGF
+supports variations of play sequences. For example:
+
+```text
+(;FF[4](;B[aa];W[ab])(;B[dd];W[ee]))
+```
+
+Here the root node has two variations. The first (which by convention
+indicates what's actually played) is where black plays on 1-1. Black was
+sent this file by his teacher who pointed out a more sensible play in
+the second child of the root node: `B[dd]` (4-4 point, a very standard
+opening to take the corner).
+
+A key can have multiple values associated with it. For example:
+
+```text
+(;FF[4];AB[aa][ab][ba])
+```
+
+Here `AB` (add black) is used to add three black stones to the board.
+
+All property values will be the [SGF Text type][sgf-text].
+You don't need to implement any other value type.
+Although you can read the [full documentation of the Text type][sgf-text], a summary of the important points is below:
+
+- Newlines are removed if they come immediately after a `\`, otherwise they remain as newlines.
+- All whitespace characters other than newline are converted to spaces.
+- `\` is the escape character.
+  Any non-whitespace character after `\` is inserted as-is.
+  Any whitespace character after `\` follows the above rules.
+  Note that SGF does **not** have escape sequences for whitespace characters such as `\t` or `\n`.
+
+Be careful not to get confused between:
+
+- The string as it is represented in a string literal in the tests
+- The string that is passed to the SGF parser
+
+Escape sequences in the string literals may have already been processed by the programming language's parser before they are passed to the SGF parser.
+
+There are a few more complexities to SGF (and parsing in general), which
+you can mostly ignore. You should assume that the input is encoded in
+UTF-8, the tests won't contain a charset property, so don't worry about
+that. Furthermore you may assume that all newlines are unix style (`\n`,
+no `\r` or `\r\n` will be in the tests) and that no optional whitespace
+between properties, nodes, etc will be in the tests.
+
+[sgf]: https://en.wikipedia.org/wiki/Smart_Game_Format
+[sgf-text]: https://www.red-bean.com/sgf/sgf4.html#text

exercises/practice/sgf-parsing/.meta/config.json

@@ -0,0 +1,17 @@
+{
+  "authors": [
+    "erikschierboom"
+  ],
+  "files": {
+    "solution": [
+      "sgf_parsing.pl"
+    ],
+    "test": [
+      "sgf_parsing_tests.plt"
+    ],
+    "example": [
+      ".meta/sgf_parsing.example.pl"
+    ]
+  },
+  "blurb": "Parsing a Smart Game Format string."
+}

exercises/practice/sgf-parsing/.meta/sgf_parsing.example.pl

@@ -0,0 +1,31 @@
+:- use_module(library(dcg/basics)).
+:- use_module(library(dcg/high_order)).
+:- set_prolog_flag(double_quotes, chars).
+
+char(' ') --> "\t" | "\\\t".
+char(C) --> "\\\n", char(C).
+char(C) --> "\\", [C], { member(C, "tn]\\")}.
+char(C) --> [C], { C \== ']' }.
+text(Text) --> sequence(char, Chars), { string_chars(Text, Chars) }.
+
+value(Value) --> "[", text(Value) , "]".
+values(Values) --> sequence(value, Values), { length(Values, Length), Length > 0 }.
+
+key(Key) --> [C], { char_type(C, upper), string_chars(Key, [C]) }.
+
+prop(Key-Values) --> key(Key), values(Values).
+
+child(Tree) --> basic_tree(Tree).
+child(Tree) --> shorthand_tree(Tree).
+
+basic_tree(Tree) --> ";", 
+    sequence(prop, Properties),
+    sequence(child, Children),
+    { Tree = sgf_tree(properties(Properties), children(Children))}.
+
+shorthand_tree(Tree) --> "(", basic_tree(Tree), ")".
+
+parse(Input, Tree) :-
+    string_chars(Input, Chars),
+    phrase(shorthand_tree(Tree), Chars),
+    !.

exercises/practice/sgf-parsing/.meta/tests.toml

@@ -0,0 +1,84 @@
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
+
+[2668d5dc-109f-4f71-b9d5-8d06b1d6f1cd]
+description = "empty input"
+
+[84ded10a-94df-4a30-9457-b50ccbdca813]
+description = "tree with no nodes"
+
+[0a6311b2-c615-4fa7-800e-1b1cbb68833d]
+description = "node without tree"
+
+[8c419ed8-28c4-49f6-8f2d-433e706110ef]
+description = "node without properties"
+
+[8209645f-32da-48fe-8e8f-b9b562c26b49]
+description = "single node tree"
+
+[6c995856-b919-4c75-8fd6-c2c3c31b37dc]
+description = "multiple properties"
+
+[a771f518-ec96-48ca-83c7-f8d39975645f]
+description = "properties without delimiter"
+
+[6c02a24e-6323-4ed5-9962-187d19e36bc8]
+description = "all lowercase property"
+
+[8772d2b1-3c57-405a-93ac-0703b671adc1]
+description = "upper and lowercase property"
+
+[a759b652-240e-42ec-a6d2-3a08d834b9e2]
+description = "two nodes"
+
+[cc7c02bc-6097-42c4-ab88-a07cb1533d00]
+description = "two child trees"
+
+[724eeda6-00db-41b1-8aa9-4d5238ca0130]
+description = "multiple property values"
+
+[28092c06-275f-4b9f-a6be-95663e69d4db]
+description = "within property values, whitespace characters such as tab are converted to spaces"
+
+[deaecb9d-b6df-4658-aa92-dcd70f4d472a]
+description = "within property values, newlines remain as newlines"
+
+[8e4c970e-42d7-440e-bfef-5d7a296868ef]
+description = "escaped closing bracket within property value becomes just a closing bracket"
+
+[cf371fa8-ba4a-45ec-82fb-38668edcb15f]
+description = "escaped backslash in property value becomes just a backslash"
+
+[dc13ca67-fac0-4b65-b3fe-c584d6a2c523]
+description = "opening bracket within property value doesn't need to be escaped"
+
+[a780b97e-8dbb-474e-8f7e-4031902190e8]
+description = "semicolon in property value doesn't need to be escaped"
+
+[0b57a79e-8d89-49e5-82b6-2eaaa6b88ed7]
+description = "parentheses in property value don't need to be escaped"
+
+[c72a33af-9e04-4cc5-9890-1b92262813ac]
+description = "escaped tab in property value is converted to space"
+
+[3a1023d2-7484-4498-8d73-3666bb386e81]
+description = "escaped newline in property value is converted to nothing at all"
+
+[25abf1a4-5205-46f1-8c72-53273b94d009]
+description = "escaped t and n in property value are just letters, not whitespace"
+
+[08e4b8ba-bb07-4431-a3d9-b1f4cdea6dab]
+description = "mixing various kinds of whitespace and escaped characters in property value"
+reimplements = "11c36323-93fc-495d-bb23-c88ee5844b8c"
+
+[11c36323-93fc-495d-bb23-c88ee5844b8c]
+description = "escaped property"
+include = false

exercises/practice/sgf-parsing/sgf_parsing.pl

@@ -0,0 +1 @@
+parse(Input, Tree).

exercises/practice/sgf-parsing/sgf_parsing_tests.plt

@@ -0,0 +1,108 @@
+pending :-
+    current_prolog_flag(argv, ['--all'|_]).
+pending :-
+    write('\nA TEST IS PENDING!\n'),
+    fail.
+
+:- begin_tests(sgf_parsing).
+
+    test(empty_input, [fail, condition(true)]) :-
+        parse("", _).
+
+    test(tree_with_no_nodes, [fail, condition(pending)]) :-
+        parse("()", _).
+
+    test(node_without_tree, [fail, condition(pending)]) :-
+        parse(";", _).
+
+    test(node_without_properties, condition(pending)) :-
+        parse("(;)", Tree),
+        Tree == sgf_tree(properties([]), children([])).
+
+    test(single_node_tree, condition(pending)) :-
+        parse("(;A[B])", Tree),
+        Tree == sgf_tree(properties(["A"-["B"]]), children([])).
+
+    test(multiple_properties, condition(pending)) :-
+        parse("(;A[b]C[d])", Tree),
+        Tree == sgf_tree(properties(["A"-["b"], "C"-["d"]]), children([])).
+
+    test(properties_without_delimiter, [fail, condition(pending)]) :-
+        parse("(;A)", _).
+
+    test(all_lowercase_property, [fail, condition(pending)]) :-
+        parse("(;a[b])", _).
+
+    test(upper_and_lowercase_property, [fail, condition(pending)]) :-
+        parse("(;Aa[b])", _).
+
+    test(two_nodes, condition(pending)) :-
+        parse("(;A[B];B[C])", Tree),
+        Tree == sgf_tree(properties(["A"-["B"]]), children([sgf_tree(properties(["B"-["C"]]), children([]))])).
+
+    test(two_child_trees, condition(pending)) :-
+        parse("(;A[B](;B[C])(;C[D]))", Tree),
+        Tree == sgf_tree(
+            properties(["A"-["B"]]),
+            children([
+                sgf_tree(properties(["B"-["C"]]), children([])), 
+                sgf_tree(properties(["C"-["D"]]), children([]))
+            ])
+        ).
+
+    test(multiple_property_values, condition(pending)) :-
+        parse("(;A[b][c][d])", Tree),
+        Tree == sgf_tree(properties(["A"-["b", "c", "d"]]), children([])).
+
+    test(within_property_values_whitespace_characters_such_as_tab_are_converted_to_spaces, condition(pending)) :-
+        parse("(;A[hello\t\tworld])", Tree),
+        Tree == sgf_tree(properties(["A"-["hello  world"]]), children([])).
+
+    test(within_property_values_newlines_remain_as_newlines, condition(pending)) :-
+        parse("(;A[hello\n\nworld])", Tree),
+        Tree == sgf_tree(properties(["A"-["hello\n\nworld"]]), children([])).
+
+    test(escaped_closing_bracket_within_property_value_becomes_just_a_closing_bracket, condition(pending)) :-
+        parse("(;A[\\]])", Tree),
+        Tree == sgf_tree(properties(["A"-["]"]]), children([])).
+
+    test(escaped_backslash_in_property_value_becomes_just_a_backslash, condition(pending)) :-
+        parse("(;A[\\\\])", Tree),
+        Tree == sgf_tree(properties(["A"-["\\"]]), children([])).
+
+    test(opening_bracket_within_property_value_doesn_t_need_to_be_escaped, condition(pending)) :-
+        parse("(;A[x[y\\]z][foo]B[bar];C[baz])", Tree),
+        Tree == sgf_tree(
+            properties(["A"-["x[y]z", "foo"], "B"-["bar"]]),
+            children([sgf_tree(properties(["C"-["baz"]]), children([]))])).
+
+    test(semicolon_in_property_value_doesn_t_need_to_be_escaped, condition(pending)) :-    
+        parse("(;A[a;b][foo]B[bar];C[baz])", Tree),
+        Tree == sgf_tree(
+            properties(["A"-["a;b", "foo"], "B"-["bar"]]),
+            children([sgf_tree(properties(["C"-["baz"]]), children([]))])).
+
+    test(parentheses_in_property_value_don_t_need_to_be_escaped, condition(pending)) :-    
+        parse("(;A[x(y)z][foo]B[bar];C[baz])", Tree),
+        Tree == sgf_tree(
+            properties(["A"-["x(y)z", "foo"], "B"-["bar"]]),
+            children([sgf_tree(properties(["C"-["baz"]]), children([]))])
+        ).
+
+    test(escaped_tab_in_property_value_is_converted_to_space, condition(pending)) :-
+        parse("(;A[hello\\\tworld])", Tree),
+        Tree == sgf_tree(properties(["A"-["hello world"]]), children([])).
+
+    test(escaped_newline_in_property_value_is_converted_to_nothing_at_all, condition(pending)) :-
+        parse("(;A[hello\\\nworld])", Tree),
+        Tree == sgf_tree(properties(["A"-["helloworld"]]), children([])).
+
+    test(escaped_t_and_n_in_property_value_are_just_letters_not_whitespace, condition(pending)) :-
+        parse("(;A[\\t = t and \\n = n])", Tree),
+        Tree == sgf_tree(properties(["A"-["t = t and n = n"]]), children([])).
+
+    test(mixing_various_kinds_of_whitespace_and_escaped_characters_in_property_value, condition(pending)) :-
+        parse("(;A[\\]b\nc\\\nd\t\te\\\\ \\\n\\]])", Tree),
+        Tree == sgf_tree(properties(["A"-["]b\ncd  e\\ ]"]]), children([])).
+
+:- end_tests(sgf_parsing).