Add sgf-parsing (#140)

* Add sgf-parsing
* update test-helpers doc

Author: glennj

config.json

@@ -818,6 +818,14 @@
         "prerequisites": [],
         "difficulty": 8
       },
+      {
+        "slug": "sgf-parsing",
+        "name": "SGF Parsing",
+        "uuid": "f990927e-2fae-4ac0-ba8f-0cd90d500e62",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 8
+      },
       {
         "slug": "zebra-puzzle",
         "name": "Zebra Puzzle",

exercises/practice/sgf-parsing/.busted

@@ -0,0 +1,5 @@
+return {
+  default = {
+    ROOT = { '.' }
+  }
+}

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

@@ -0,0 +1,42 @@
+# Hints
+
+## General
+
+The SGF language has a recursive definition:
+
+```none
+GameTree = "(" Sequence { GameTree } ")"
+```
+
+That is, a GameTree is a piece of text that starts with a `(`, followed by some text called a "Sequence" (a list of game nodes), _followed by **zero or more** child GameTrees_, and ends with a `)`.
+
+You might want to use regular expressions to parse an SGF text.
+However, because game trees can be nested inside other game trees to any depth, standard regular expressions are not powerful enough to keep track of the nesting levels.
+
+There are a couple of approaches to solving this exercise:
+
+### State machine
+
+You could scan the input string character-by-character, maintaining a variable holding your current position.
+You can keep track of the current state of the parsed text based on the character at the current position.
+The "current state" might be something like "reading a property name" or "inside a property value".
+There are lots of values you need to keep track of with this approach.
+
+### Parser
+
+A [PEG-based parser][PEG-parser] is a very good way to parse a language that has a defined grammar.
+[LPeg][LPeg] is a PEG parser, and it is one of the required dependencies of MoonScript, so you'll already have access to it.
+A parser allows you to write rules for what the text should look like.
+For example, "a property name is all uppercase letters", or "a property value is enclosed in brackets".
+The parser then does the heavy lifting of matching the input text against your rules.
+
+A couple of learning resources for LPeg:
+
+* [LPeg tutorial][tutorial] in the lua-users wiki.
+* [Mastering LPeg][mastering-lpeg] is written by one of the authors of LPeg and Lua itself. 
+  He is a university professor and researcher, so this document reads like an academic paper.
+
+[PEG-parser]: https://en.wikipedia.org/wiki/Parsing_expression_grammar
+[LPeg]: https://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html
+[mastering-lpeg]: https://www.inf.puc-rio.br/~roberto/docs/lpeg-primer.pdf
+[tutorial]: http://lua-users.org/wiki/LpegTutorial

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": [
+    "glennj"
+  ],
+  "files": {
+    "solution": [
+      "sgf_parsing.moon"
+    ],
+    "test": [
+      "sgf_parsing_spec.moon"
+    ],
+    "example": [
+      ".meta/example.moon"
+    ]
+  },
+  "blurb": "Parsing a Smart Game Format string."
+}

exercises/practice/sgf-parsing/.meta/example.moon

@@ -0,0 +1,78 @@
+lpeg = require "lpeg"
+import P, V, R, S, C, Ct, Cg from lpeg
+
+-- Learning references:
+--   https://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html
+--   http://lua-users.org/wiki/LpegTutorial
+
+-- Define some "atomic" patterns that we'll use in the grammar.
+escaped_newlines = P"\\\n" / ""
+escaped_tabs = P"\\\t" / " "
+escaped = P"\\" / "" * C P 1
+plain = C 1 - S"]"
+-- SGF specifies that tabs and other whitespace characters are converted to spaces, but newlines are preserved.
+whitespace = S" \t\r\f\v" / " "
+
+prop_value = P"[" * (Ct((escaped_newlines + escaped_tabs + escaped + whitespace + plain)^0) / table.concat) * P"]"
+
+-- The Grammar
+sgf = P {
+  "GameTree"
+
+  -- A GameTree is '(' Sequence ')'
+  GameTree: P"(" * V"Sequence" * P")"
+
+  -- In Exercism, ;A;B means B is a child of A.
+  -- We nest the remainder of the sequence into the 'children' key.
+  Sequence: Ct(
+    P";" * Cg(V"PropMap", "properties") * Cg(Ct((V"Sequence" + V"Children")^-1), "children")
+  )
+
+  -- Maps tags like 'A' to a list of values ['x', 'y']
+  PropMap: Ct V"Property"^0
+  
+  -- A property is a PropIdent followed by one or more PropValues.
+  -- We allow zero PropValues here to catch the case of properties without delimiters,
+  -- which is invalid but would otherwise be hard to detect.
+  Property: Cg C(V"PropIdent") * Ct(V"PropValue"^0)
+
+  -- Variations: Multiple GameTrees inside a node's children list
+  Children: V"GameTree"^1
+
+  -- PropIdent is a sequence of uppercase letters, but we allow lowercase letters here to catch
+  -- the case of properties containing lowercase, which is invalid but would otherwise be hard to detect.
+  PropIdent: (R"AZ" + R"az")^1
+  PropValue: prop_value
+}
+
+-- The LPEG parser can only capture properties as a sequence of name-value pairs,
+-- so we need to remap them into a key-value table.
+-- Plus, we have a couple of extra validations to perform.
+remap_properties = (tree) ->
+  if tree.properties
+    props = {}
+    for i = 1, #tree.properties, 2
+      name, value = tree.properties[i], tree.properties[i + 1]
+      assert name\match('^%u+$'), 'property must be in uppercase'
+      assert #value > 0, 'properties without delimiter'
+      props[name] = value
+    tree.properties = props
+
+  if tree.children
+    for child in *tree.children
+      remap_properties child
+
+{
+  parse: (input) ->
+    result = sgf\match input
+    if not result
+      -- The LPEG parser will fail if the input doesn't match the grammar, 
+      -- but it won't give us any information about what went wrong.
+      -- Add some basic checks to provide more helpful error messages.
+      assert #input > 0 and input\match('^%(.*%)$'), 'tree missing'
+      assert input\find(';'), 'tree with no nodes'
+      error "unspecified parse error"
+    
+    remap_properties result
+    result
+}

exercises/practice/sgf-parsing/.meta/spec_generator.moon

@@ -0,0 +1,60 @@
+json = require 'dkjson'
+json_string = (s) -> json.encode s
+
+is_sequence = (t) ->
+  return false if type(t) != 'table'
+  size = 0
+  size += 1 for k, _ in pairs t when k != 'n'
+  size == #t
+
+is_empty = (t) -> not next t
+
+-- mostly taken from:
+-- https://github.com/leafo/moonscript/blob/7b7899741c6c1e971e436d36c9aabb56f51dc3d5/moonscript/util.moon#L58
+to_string = (what, level = 0) ->
+  seen = {}
+  _dump = (what, depth = 0) ->
+    t = type what
+    if t == 'string' then
+      json_string what
+    elseif t != 'table' then
+      tostring what
+    else
+      if seen[what] then
+        return "<cycle:#{tostring what}>"
+      seen[what] = true
+      if is_sequence what then
+        return "{" .. table.concat([to_string(v, level + depth + 1) for v in *what], ", ") .. "}"
+
+      depth += 1
+      lines = for k,v in pairs what do
+        key = if type(k) == 'number' then "[#{k}]" else k
+        (' ')\rep(depth * 2) .. "#{key}: " .. _dump(v, depth)
+      seen[what] = false
+      val = if not is_empty lines
+        table.concat [indent(line, level) .. "\n" for line in *lines]
+      else
+        ""
+      class_name = if type(what.__class) == 'table' and type(what.__class.__name) == 'string'
+        "<#{what.__class.__name}>"
+      "#{class_name or ""}{\n#{val}#{indent '}', level + depth - 1}"
+  _dump what
+
+
+{
+  module_name: 'SGFParser',
+
+  generate_test: (case, level) ->
+    lines = if case.expected.error
+      {
+        "f = -> SGFParser.parse #{json_string case.input.encoded}"
+        "assert.has_error f, #{quote case.expected.error}"
+      }
+    else
+      {
+        "result = SGFParser.#{case.property} #{json_string case.input.encoded}",
+        "expected = #{to_string case.expected, level}",
+        "assert.are.same expected, result"
+      }
+    table.concat [indent line, level for line in *lines], '\n'
+}

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.moon

@@ -0,0 +1,4 @@
+{
+  parse: (input) ->
+    error 'Implement me!'
+}