diff --git a/README.md b/README.md index 9655518..db61c33 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,35 @@ let diagram_data = parse_diagrams_json diagrams_json_stringified let game_tex = to_tex ~diagram_data ~clock:false pgn ``` -This will return a LaTex markdown representation of the PGN file along with chess board diagrams at the specified ply. Clock times can be rendered for both sides if you pass `~clock:true` to the `to_tex` function. +This will return a LaTex markdown representation of the PGN file along with chess board diagrams at the specified positions. Clock times can be rendered for both sides if you pass `~clock:true` to the `to_tex` function. -Each diagram is placed at the position identified by its path — the SAN move sequence from the start of the game (e.g. ["d4","d5","e4","d6"]). `path` uniquely identifies positions in both the mainline and in variations, and diagrams inside a variation are rendered inline within that variation. The legacy `ply` field is still accepted and used as a fallback for mainline diagrams when path is omitted. +### Diagram JSON schema -Variation diagrams are rendered at a slightly smaller size (smallboard) so they don't dominate the subline. Clock times can be rendered for both sides by passing ~clock:true to to_tex. +`parse_diagrams_json` accepts a JSON array of objects: + +```json +[ + {"fen": "...", "path": ["d4", "d5", "e4", "d6"]}, + {"fen": "...", "ply": 5}, + {"fen": "...", "ply": 9, "path": ["e4", "e5", "Nf3", "Nc6"]} +] +``` + +| Field | Type | Required | Description | +| ------ | --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `fen` | string | yes | The board position to render. | +| `path` | array of string | one of path/ply | SAN move sequence from the start of the game (e.g. `["d4","d5","e4","d6"]`). It uniquely identifies mainline and variation positions. | +| `ply` | integer | one of path/ply | Legacy half-move count from the start of the game (1 after White's first move). Used for mainline positions. | + +Resolution rules: + +- An entry may carry `path`, `ply`, or both. +- When a rendered position has a matching `path`, that diagram takes precedence. +- If no `path` matches, mainline positions fall back to a matching legacy `ply`. +- Variation diagrams require `path`; a `ply`-only entry only matches mainline positions. +- Malformed diagram JSON yields empty diagram data instead of raising. + +Diagrams inside a variation are rendered inline within that variation and at a slightly smaller size (`smallboard`) so they don't dominate the subline. Latex preample and document setup markdown is not included in the output. You will need to add something similar to below around the `game_tex` output to create a valid document: diff --git a/lib/internal/converter.ml b/lib/internal/converter.ml index d4a97c7..05f1279 100644 --- a/lib/internal/converter.ml +++ b/lib/internal/converter.ml @@ -10,10 +10,12 @@ let parse_diagrams_json diagrams_json_str = let diagrams_list = to_list json in List.fold_left (fun acc item -> - let ply = item |> member "ply" |> to_int in let fen = item |> member "fen" |> to_string in let acc = - { acc with Ast.by_ply = MoveMap.add ply fen acc.Ast.by_ply } + match item |> member "ply" with + | `Int ply -> + { acc with Ast.by_ply = MoveMap.add ply fen acc.Ast.by_ply } + | _ -> acc in match item |> member "path" with | `List path_items -> diff --git a/lib/pgn_to_tex.mli b/lib/pgn_to_tex.mli index 9311c4f..6b274b7 100644 --- a/lib/pgn_to_tex.mli +++ b/lib/pgn_to_tex.mli @@ -25,8 +25,10 @@ val parse_diagrams_json : string -> diagram_data (** [parse_diagrams_json json] parses diagram selections from a JSON string. The input is expected to be a JSON array of objects. Each object contains - a [fen] string and may contain a [ply] number and a [path] array of SAN - moves. Malformed JSON yields {!empty_diagrams} rather than raising. *) + a [fen] string and either a legacy [ply] number, a [path] array of SAN + moves, or both. A matching [path] takes precedence; [ply] is the fallback + for mainline positions. Malformed JSON yields {!empty_diagrams} rather than + raising. *) val to_tex : ?diagram_data:diagram_data -> ?clock:bool -> string -> string (** [to_tex pgn] converts the PGN game in [pgn] to a LaTeX fragment. diff --git a/test/test_diagram_resolution.ml b/test/test_diagram_resolution.ml new file mode 100644 index 0000000..16f0a14 --- /dev/null +++ b/test/test_diagram_resolution.ml @@ -0,0 +1,111 @@ +open OUnit2 + +let contains ~needle haystack = + let n = String.length needle and h = String.length haystack in + let rec loop i = + if i + n > h then false + else if String.sub haystack i n = needle then true + else loop (i + 1) + in + n = 0 || loop 0 + +let path_only_variation_json = + {| [{"fen":"8/8/8/8/8/8/4K3/7k w - - 0 1","path":["e4","e5","Nf3","d6"]}] |} + +let test_path_only_variation_diagram _ctxt = + let pgn = "1. e4 e5 2. Nf3 Nc6 (2... d6) 3. Bb5" in + let diagrams = Pgn_to_tex.parse_diagrams_json path_only_variation_json in + let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in + assert_bool + (Printf.sprintf "path-only variation diagram missing from:\n%s" rendered) + (contains ~needle:"setfen=8/8/8/8/8/8/4K3/7k w - - 0 1" rendered); + assert_bool "path-only variation diagram should use smallboard" + (contains ~needle:"smallboard" rendered) + +let path_only_mainline_json = + {| [{"fen":"8/8/8/8/8/8/4K3/7k w - - 0 1","path":["e4","e5"]}] |} + +let test_path_only_mainline_diagram _ctxt = + let pgn = "1. e4 e5 2. Nf3" in + let diagrams = Pgn_to_tex.parse_diagrams_json path_only_mainline_json in + let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in + assert_bool + (Printf.sprintf "path-only mainline diagram missing from:\n%s" rendered) + (contains ~needle:"setfen=8/8/8/8/8/8/4K3/7k w - - 0 1" rendered) + +let test_path_takes_precedence_over_ply _ctxt = + let pgn = "1. e4 e5 2. Nf3" in + let path_fen = "8/8/8/8/8/8/4K3/7k w - - 0 1" in + let ply_fen = "7k/8/8/8/8/8/8/4K3 b - - 0 1" in + let json = + Printf.sprintf + {| [{"fen":"%s","path":["e4","e5"]},{"ply":2,"fen":"%s"}] |} path_fen + ply_fen + in + let diagrams = Pgn_to_tex.parse_diagrams_json json in + let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in + assert_bool "path diagram should win over the ply fallback" + (contains ~needle:("setfen=" ^ path_fen) rendered); + assert_bool "ply diagram should not replace the matching path diagram" + (not (contains ~needle:("setfen=" ^ ply_fen) rendered)) + +let test_entry_with_path_and_ply _ctxt = + let pgn = "1. e4 e5" in + let both_fen = "8/8/8/8/8/8/4K3/7k w - - 0 1" in + let path_fen = "7k/8/8/8/8/8/8/4K3 b - - 0 1" in + let json = + Printf.sprintf + {| [{"ply":9,"fen":"%s","path":["e4"]},{"fen":"%s","path":["e4","e5"]}] |} + both_fen path_fen + in + let diagrams = Pgn_to_tex.parse_diagrams_json json in + let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in + assert_bool "entry carrying both path and ply should still resolve by path" + (contains ~needle:("setfen=" ^ both_fen) rendered); + assert_bool "second path-only entry should resolve by path" + (contains ~needle:("setfen=" ^ path_fen) rendered) + +let test_ply_only_entry_falls_back _ctxt = + let pgn = "1. e4 e5 2. Nf3" in + let ply_fen = "7k/8/8/8/8/8/8/4K3 b - - 0 1" in + let json = Printf.sprintf {| [{"ply":2,"fen":"%s"}] |} ply_fen in + let diagrams = Pgn_to_tex.parse_diagrams_json json in + let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in + assert_bool "legacy ply-only diagram should still resolve by ply" + (contains ~needle:("setfen=" ^ ply_fen) rendered) + +let test_malformed_json_yields_empty_diagrams _ctxt = + let pgn = "1. e4 e5" in + let expected = Pgn_to_tex.to_tex pgn in + let malformed = + [ + "not json at all"; + {| {"ply":1} |}; + {| [{"path":["e4"]}] |}; + {| [{"fen":"8/8/8/8/8/8/4K3/7k w - - 0 1","ply":"not-a-number"}] |}; + ] + in + List.iter + (fun json -> + let actual = + Pgn_to_tex.to_tex + ~diagram_data:(Pgn_to_tex.parse_diagrams_json json) + pgn + in + assert_equal ~printer:(fun x -> x) + ~msg:("malformed JSON: " ^ json) + expected actual) + malformed + +let suite = + "diagram resolution tests" + >::: [ + "path_only_variation_diagram" >:: test_path_only_variation_diagram; + "path_only_mainline_diagram" >:: test_path_only_mainline_diagram; + "path_takes_precedence_over_ply" + >:: test_path_takes_precedence_over_ply; + "entry_with_path_and_ply" >:: test_entry_with_path_and_ply; + "ply_only_entry_falls_back" >:: test_ply_only_entry_falls_back; + "malformed_json_yields_empty_diagrams" + >:: test_malformed_json_yields_empty_diagrams; + ] diff --git a/test/test_suite.ml b/test/test_suite.ml index 0017bd3..e9a50bb 100644 --- a/test/test_suite.ml +++ b/test/test_suite.ml @@ -7,6 +7,7 @@ let () = Test_lexer.suite; Test_latex.suite; Test_pgn_to_tex.suite; + Test_diagram_resolution.suite; Test_nag.suite; ] in