feat: add public Pgn_to_tex entry point

Move parsing and rendering internals into the private
pgn_to_tex_internal library and rename pgn2tex to converter. Expose only
Pgn_to_tex with default to_tex arguments, abstract diagram_data,
empty_diagrams, and parse_diagrams_json. Update tests, JS bridge, and
README to the new names.
This commit is contained in:
2026-10-23 16:38:24 +02:00
committed by owenrees
parent 8df30f1746
commit 548f98f303
22 changed files with 111 additions and 48 deletions
+3 -3
View File
@@ -9,7 +9,7 @@
## Usage ## Usage
```ocaml ```ocaml
open Pgn_logic open Pgn_to_tex
let diagrams_json_stringified = let diagrams_json_stringified =
{| [ {| [
@@ -18,9 +18,9 @@ let diagrams_json_stringified =
{"ply":4,"fen":"rnbqkbnr/ppp1pppp/3p4/8/3PP3/8/PPP2PPP/RNBQKBNR b KQkq - 0 3","path":["d4","d5","e4","d6"]} {"ply":4,"fen":"rnbqkbnr/ppp1pppp/3p4/8/3PP3/8/PPP2PPP/RNBQKBNR b KQkq - 0 3","path":["d4","d5","e4","d6"]}
] |} ] |}
let diagram_data = Pgn2tex.parse_diagrams_json diagrams_json_stringified let diagram_data = parse_diagrams_json diagrams_json_stringified
let game_tex = Pgn2tex.to_tex pgn ~diagram_data ~clock:false 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 ply. Clock times can be rendered for both sides if you pass `~clock:true` to the `to_tex` function.
+4 -5
View File
@@ -1,6 +1,5 @@
open Js_of_ocaml open Js_of_ocaml
open Pgn_logic open Pgn_to_tex
open Ast
let convert_js pgn_js diagram_json_js display_clock = let convert_js pgn_js diagram_json_js display_clock =
let pgn = Js.to_string pgn_js in let pgn = Js.to_string pgn_js in
@@ -9,11 +8,11 @@ let convert_js pgn_js diagram_json_js display_clock =
let json_str = Js.to_string diagram_json_js in let json_str = Js.to_string diagram_json_js in
let diagram_data = let diagram_data =
if json_str = "" || json_str = "{}" then Ast.empty_diagrams if json_str = "" || json_str = "{}" then Pgn_to_tex.empty_diagrams
else Pgn2tex.parse_diagrams_json json_str else Pgn_to_tex.parse_diagrams_json json_str
in in
let result = Pgn2tex.to_tex pgn ~diagram_data ~clock:display_clock in let result = Pgn_to_tex.to_tex ~diagram_data ~clock:display_clock pgn in
Js.string result Js.string result
(* Exporting the module to the global JavaScript scope *) (* Exporting the module to the global JavaScript scope *)
+3 -8
View File
@@ -1,10 +1,5 @@
(library (library
(name pgn_logic) (name pgn_to_tex)
(public_name pgn_to_tex) (public_name pgn_to_tex)
(libraries sedlex menhirLib yojson) (modules pgn_to_tex)
(modules ast parser lexer parsing latex latex_helpers pgn2tex nag) (libraries pgn_to_tex_internal))
(preprocess
(pps sedlex.ppx)))
(menhir
(modules parser))
View File
+10
View File
@@ -0,0 +1,10 @@
(library
(name pgn_to_tex_internal)
(package pgn_to_tex)
(libraries sedlex menhirLib yojson)
(modules ast parser lexer parsing latex latex_helpers converter nag)
(preprocess
(pps sedlex.ppx)))
(menhir
(modules parser))
View File
+8
View File
@@ -0,0 +1,8 @@
type diagram_data = Pgn_to_tex_internal.Ast.diagram_data
let empty_diagrams = Pgn_to_tex_internal.Ast.empty_diagrams
let parse_diagrams_json = Pgn_to_tex_internal.Converter.parse_diagrams_json
let to_tex ?(diagram_data = empty_diagrams) ?(clock = false) pgn =
Pgn_to_tex_internal.Converter.to_tex pgn ~diagram_data ~clock
+39
View File
@@ -0,0 +1,39 @@
(** Convert chess PGN games to LaTeX.
[Pgn_to_tex] is the public entry point for the library. Open it to convert
a PGN string without referring to any internal parsing or rendering
modules:
{[
let tex = Pgn_to_tex.to_tex pgn
]}
Diagrams are optional and selected by passing {!diagram_data} built with
{!empty_diagrams} or {!parse_diagrams_json}. *)
(** Diagram selection data.
The representation is intentionally abstract; construct values with
{!empty_diagrams} or {!parse_diagrams_json}. *)
type diagram_data
val empty_diagrams : diagram_data
(** [empty_diagrams] selects no diagrams. It is the default used by
{!to_tex}. *)
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. *)
val to_tex : ?diagram_data:diagram_data -> ?clock:bool -> string -> string
(** [to_tex pgn] converts the PGN game in [pgn] to a LaTeX fragment.
@param diagram_data
diagram selections to render; defaults to {!empty_diagrams}.
@param clock
when [true], render clock times alongside diagrams; defaults to [false].
@raise Failure "Parse error" if [pgn] is not a valid PGN game. *)
+1 -1
View File
@@ -1,6 +1,6 @@
(test (test
(name test_suite) (name test_suite)
(modules (:standard)) (modules (:standard))
(libraries ounit2 sedlex sedlex.ppx pgn_to_tex helpers) (libraries ounit2 sedlex sedlex.ppx pgn_to_tex pgn_to_tex_internal helpers)
(deps (deps
(source_tree pgn_examples))) (source_tree pgn_examples)))
+1 -1
View File
@@ -1,4 +1,4 @@
(library (library
(name helpers) (name helpers)
(modules latex_helper) (modules latex_helper)
(libraries pgn_to_tex)) (libraries pgn_to_tex_internal))
+1 -1
View File
@@ -1,4 +1,4 @@
open Pgn_logic open Pgn_to_tex_internal
open Ast open Ast
let diagram_data = let diagram_data =
+1 -1
View File
@@ -1,5 +1,5 @@
open OUnit2 open OUnit2
open Pgn_logic open Pgn_to_tex_internal
open Ast open Ast
open Helpers open Helpers
+1 -1
View File
@@ -1,5 +1,5 @@
open OUnit2 open OUnit2
open Pgn_logic open Pgn_to_tex_internal
open Parser open Parser
let lex_all ?(is_header = false) s = let lex_all ?(is_header = false) s =
+1 -1
View File
@@ -1,5 +1,5 @@
open OUnit2 open OUnit2
open Pgn_logic open Pgn_to_tex_internal
open Ast open Ast
open Nag open Nag
@@ -1,8 +1,8 @@
open OUnit2 open OUnit2
open Pgn_logic open Pgn_to_tex_internal
open Ast open Ast
module MoveMap = Pgn2tex.MoveMap module MoveMap = Ast.MoveMap
module PathMap = Pgn2tex.PathMap module PathMap = Ast.PathMap
let ae expected actual = assert_equal ~printer:(fun x -> x) expected actual let ae expected actual = assert_equal ~printer:(fun x -> x) expected actual
@@ -18,26 +18,21 @@ let contains ~needle haystack =
let diagram_json_str = let diagram_json_str =
{| [{"ply":1,"fen":"rnbqkbnr/pppppppp/8/8/3P4/8/PPP1PPPP/RNBQKBNR b KQkq - 0 1"},{"ply":2,"fen":"rnbqkbnr/ppp1pppp/8/3p4/3P4/8/PPP1PPPP/RNBQKBNR w KQkq - 0 2"}] |} {| [{"ply":1,"fen":"rnbqkbnr/pppppppp/8/8/3P4/8/PPP1PPPP/RNBQKBNR b KQkq - 0 1"},{"ply":2,"fen":"rnbqkbnr/ppp1pppp/8/3p4/3P4/8/PPP1PPPP/RNBQKBNR w KQkq - 0 2"}] |}
let diagram_data = let game_diagram_json_str =
{ {| [
by_ply = {"ply":5,"fen":"rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 3"},
MoveMap.empty {"ply":6,"fen":"rnbqkbnr/pp1ppppp/8/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R b KQkq - 1 3"},
|> MoveMap.add 5 {"ply":10,"fen":"r1bqkbnr/pp1ppppp/2n5/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 3 5"},
"rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 3" {"ply":15,"fen":"r1bqkb1r/pp1ppppp/2n5/2p5/4P3/2N2N2/PPPP1PPP/R1BQKB1R b KQkq - 5 7"}
|> MoveMap.add 6 ] |}
"rnbqkbnr/pp1ppppp/8/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R b KQkq - 1 3"
|> MoveMap.add 10 let diagram_data = Pgn_to_tex.parse_diagrams_json game_diagram_json_str
"r1bqkbnr/pp1ppppp/2n5/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 3 5"
|> MoveMap.add 15
"r1bqkb1r/pp1ppppp/2n5/2p5/4P3/2N2N2/PPPP1PPP/R1BQKB1R b KQkq - 5 7";
by_path = PathMap.empty;
}
let variation_diagram_json_str = let variation_diagram_json_str =
{| [{"ply":4,"fen":"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1","path":["e4","e5","Nf3","d6"]}] |} {| [{"ply":4,"fen":"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1","path":["e4","e5","Nf3","d6"]}] |}
let test_json_str_to_map _ctxt = let test_json_str_to_map _ctxt =
let result = Pgn2tex.parse_diagrams_json diagram_json_str in let result = Converter.parse_diagrams_json diagram_json_str in
let actual_bindings = MoveMap.bindings result.by_ply in let actual_bindings = MoveMap.bindings result.by_ply in
let expected_bindings = let expected_bindings =
@@ -55,7 +50,7 @@ let test_json_str_to_map _ctxt =
assert_equal expected_bindings actual_bindings ~printer:string_of_bindings assert_equal expected_bindings actual_bindings ~printer:string_of_bindings
let test_json_path_to_map _ctxt = let test_json_path_to_map _ctxt =
let result = Pgn2tex.parse_diagrams_json variation_diagram_json_str in let result = Converter.parse_diagrams_json variation_diagram_json_str in
let actual = PathMap.bindings result.by_path in let actual = PathMap.bindings result.by_path in
let expected = let expected =
[ [
@@ -67,12 +62,15 @@ let test_json_path_to_map _ctxt =
let test_variation_diagram_to_tex _ctxt = let test_variation_diagram_to_tex _ctxt =
let pgn = "1. e4 e5 2. Nf3 Nc6 (2... d6) 3. Bb5" in let pgn = "1. e4 e5 2. Nf3 Nc6 (2... d6) 3. Bb5" in
let diagrams = Pgn2tex.parse_diagrams_json variation_diagram_json_str in let diagrams = Pgn_to_tex.parse_diagrams_json variation_diagram_json_str in
let rendered = Pgn2tex.to_tex pgn ~diagram_data:diagrams ~clock:false in let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams ~clock:false pgn in
let internal_diagrams =
Converter.parse_diagrams_json variation_diagram_json_str
in
let diagram = let diagram =
match match
Latex_helpers.get_diagram_by_path ~path:"e4 e5 Nf3 d6" ~small:true Latex_helpers.get_diagram_by_path ~path:"e4 e5 Nf3 d6" ~small:true
diagrams internal_diagrams
with with
| Some d -> d | Some d -> d
| None -> assert_failure "variation diagram not found by path" | None -> assert_failure "variation diagram not found by path"
@@ -95,7 +93,7 @@ let test_basic_pgn_to_tex _ctxt =
let filename = "pgn_examples/1.pgn" in let filename = "pgn_examples/1.pgn" in
let ic = In_channel.open_text filename in let ic = In_channel.open_text filename in
let input_string = In_channel.input_all ic in let input_string = In_channel.input_all ic in
let actual = Pgn2tex.to_tex input_string ~diagram_data ~clock:false in let actual = Pgn_to_tex.to_tex ~diagram_data ~clock:false input_string in
let expected = let expected =
{|\title{URS-chJ} {|\title{URS-chJ}
\author{Ibragimov, Ildar (2455)\\Kramnik, Vladimir (2480)} \author{Ibragimov, Ildar (2455)\\Kramnik, Vladimir (2480)}
@@ -118,7 +116,7 @@ let test_pgn_with_clock_to_tex _ctxt =
let filename = "pgn_examples/2.pgn" in let filename = "pgn_examples/2.pgn" in
let ic = In_channel.open_text filename in let ic = In_channel.open_text filename in
let input_string = In_channel.input_all ic in let input_string = In_channel.input_all ic in
let actual = Pgn2tex.to_tex input_string ~diagram_data ~clock:true in let actual = Pgn_to_tex.to_tex ~diagram_data ~clock:true input_string in
let expected = let expected =
{|\title{Casual Rapid game} {|\title{Casual Rapid game}
\author{montillo2015 (1919)\\reassessyourchess (1869)} \author{montillo2015 (1919)\\reassessyourchess (1869)}
@@ -137,13 +135,27 @@ let test_pgn_with_clock_to_tex _ctxt =
ae expected actual; ae expected actual;
close_in ic close_in ic
let test_default_arguments _ctxt =
let actual = Pgn_to_tex.to_tex "1. e4 e5" in
let expected =
"\\title{}\n\\author{}\n\\date{}\\maketitle\n\\newchessgame\n\
\\textbf{1.} \\textbf{e4} \\textbf{e5}"
in
ae expected actual
let test_invalid_pgn_raises _ctxt =
assert_raises (Failure "Parse error") (fun () ->
ignore (Pgn_to_tex.to_tex "1. e4 e5 (2. Nf3"))
let suite = let suite =
"pgn2tex tests" "pgn_to_tex tests"
>::: [ >::: [
"json_str_to_map" >:: test_json_str_to_map; "json_str_to_map" >:: test_json_str_to_map;
"json_path_to_map" >:: test_json_path_to_map; "json_path_to_map" >:: test_json_path_to_map;
"variation_diagram_to_tex" >:: test_variation_diagram_to_tex; "variation_diagram_to_tex" >:: test_variation_diagram_to_tex;
"basic_pgn_to_tex" >:: test_basic_pgn_to_tex; "basic_pgn_to_tex" >:: test_basic_pgn_to_tex;
"pgn_with_clock_to_tex" >:: test_pgn_with_clock_to_tex; "pgn_with_clock_to_tex" >:: test_pgn_with_clock_to_tex;
"default_arguments" >:: test_default_arguments;
"invalid_pgn_raises" >:: test_invalid_pgn_raises;
] ]
+1 -1
View File
@@ -6,7 +6,7 @@ let () =
>::: [ >::: [
Test_lexer.suite; Test_lexer.suite;
Test_latex.suite; Test_latex.suite;
Test_pgn2tex.suite; Test_pgn_to_tex.suite;
Test_nag.suite; Test_nag.suite;
] ]
in in