Merge pull request #15 from mbarbin/myconf-example

mbarbin · web-flow · commit b0cbd1e37a39 · 2025-12-25T21:38:32.000+01:00
Add example (myconf)
diff --git a/.github/workflows/more-ci.yml b/.github/workflows/more-ci.yml
@@ -58,7 +58,7 @@ jobs:
       # the development workflow and as part of the main CI job. These are the
       # tests that are checked for every combination of os and ocaml-compiler.
       - name: Install dependencies
-        run: opam install ./auto-format.opam ./auto-format-tests.opam --deps-only --with-test
+        run: opam install ./auto-format.opam ./auto-format-tests.opam ./auto-format-example.opam --deps-only --with-test
 
       - name: Build & Run tests
-        run: opam exec -- dune build @all @runtest -p auto-format,auto-format-tests
+        run: opam exec -- dune build @all @runtest -p auto-format,auto-format-tests,auto-format-example
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,9 @@
+## 0.0.XX (unreleased)
+
+### Added
+
+- Added an example using the lib (#15, @mbarbin).
+
 ## 0.0.19 (2025-12-25)
 
 ### Added
diff --git a/README.md b/README.md
@@ -11,4 +11,10 @@ The code documentation of the latest release is built with `odoc` and published
 
 ## Examples & tests
 
-As of yet, there are no examples or tests in this repository. However, this library is extensively used and tested in the [bopkit](https://github.com/mbarbin/bopkit) project.
+The `example/` contains the implementation of a toy `key=value` config language, which includes a parser, a pretty-printer and `auto-fmt` utils built with the library.
+
+You can see examples of cli usage in `example/test/run.t`, and an example of `dune fmt` integration in `example/test/dune`.
+
+## See Also
+
+This library is extensively used and tested in the [bopkit](https://github.com/mbarbin/bopkit) project.
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,19 @@
+# Myconf
+
+**A toy key-value config DSL with support for auto-fmt.**
+
+This directory contains a little project that implements a toy config language for `key=value` entries.
+
+The goal is to serve as a code example using the auto-format library.
+
+The code was mostly contributed by Claude, with manual review from @mbarbin.
+
+## Dune Integration
+
+The `myconf` config files located in `test/` are auto-formatted as part of the `dune fmt` build target.
+
+## Using the auto-fmt CLI
+
+Using the library `auto-format` give you back an subcommand `fmt` which you can integrate into an existing cli (e.g. one related to your custom language).
+
+See usage examples in `test/run.t`.
diff --git a/example/bin/dune b/example/bin/dune
@@ -0,0 +1,11 @@
+(executable
+ (name main)
+ (public_name myconf)
+ (package auto-format-example)
+ (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
+ (libraries auto-format cmdlang cmdlang-cmdliner-err-runner myconf)
+ (instrumentation
+  (backend bisect_ppx))
+ (lint
+  (pps ppx_js_style -allow-let-operators -check-doc-comments))
+ (preprocess no_preprocessing))
diff --git a/example/bin/main.ml b/example/bin/main.ml
@@ -0,0 +1,16 @@
+let fmt_cmd =
+  Auto_format.fmt_cmd
+    (module struct
+      let language_id = "myconf"
+      let extensions = [ ".myconf" ]
+    end)
+    (module Myconf.Config)
+    (module Myconf.Config_parser)
+    (module Myconf.Config_pp)
+;;
+
+let main =
+  Cmdlang.Command.group ~summary:"Managing myconf configuration files." [ "fmt", fmt_cmd ]
+;;
+
+let () = Cmdlang_cmdliner_err_runner.run main ~name:"myconf" ~version:"dev"
diff --git a/example/src/config.ml b/example/src/config.ml
@@ -0,0 +1,55 @@
+module Sexp = Sexplib0.Sexp
+
+type value =
+  | String of string
+  | Int of int
+  | Bool of bool
+
+type entry =
+  | Comment of string
+  | Binding of
+      { loc : Loc.t
+      ; key : string
+      ; value : value
+      }
+
+type t = entry list
+
+let equal_value v1 v2 =
+  match v1, v2 with
+  | String s1, String s2 -> String.equal s1 s2
+  | Int i1, Int i2 -> Int.equal i1 i2
+  | Bool b1, Bool b2 -> Bool.equal b1 b2
+  | (String _ | Int _ | Bool _), _ -> false
+;;
+
+let equal_entry e1 e2 =
+  match e1, e2 with
+  | Comment c1, Comment c2 -> String.equal c1 c2
+  | Binding b1, Binding { loc; key; value } ->
+    Loc.equal b1.loc loc && String.equal b1.key key && equal_value b1.value value
+  | (Comment _ | Binding _), _ -> false
+;;
+
+let equal t1 t2 = List.equal equal_entry t1 t2
+
+let sexp_of_value = function
+  | String s -> Sexp.List [ Sexp.Atom "String"; Sexp.Atom s ]
+  | Int i -> Sexp.List [ Sexp.Atom "Int"; Sexp.Atom (Int.to_string i) ]
+  | Bool b -> Sexp.List [ Sexp.Atom "Bool"; Sexp.Atom (Bool.to_string b) ]
+;;
+
+let sexp_of_entry = function
+  | Comment c -> Sexp.List [ Sexp.Atom "Comment"; Sexp.Atom c ]
+  | Binding { loc; key; value } ->
+    Sexp.List
+      [ Sexp.Atom "Binding"
+      ; Sexp.List
+          [ Sexp.List [ Sexp.Atom "loc"; Loc.sexp_of_t loc ]
+          ; Sexp.List [ Sexp.Atom "key"; Sexp.Atom key ]
+          ; Sexp.List [ Sexp.Atom "value"; sexp_of_value value ]
+          ]
+      ]
+;;
+
+let sexp_of_t t = Sexp.List (List.map sexp_of_entry t)
diff --git a/example/src/config.mli b/example/src/config.mli
@@ -0,0 +1,17 @@
+type value =
+  | String of string
+  | Int of int
+  | Bool of bool
+
+type entry =
+  | Comment of string
+  | Binding of
+      { loc : Loc.t
+      ; key : string
+      ; value : value
+      }
+
+type t = entry list
+
+val equal : t -> t -> bool
+val sexp_of_t : t -> Sexplib0.Sexp.t
diff --git a/example/src/config_parser.ml b/example/src/config_parser.ml
@@ -0,0 +1,5 @@
+type token = Parser.token
+type t = Config.t
+
+let lexer = Lexer.read
+let parser = Parser.config
diff --git a/example/src/config_parser.mli b/example/src/config_parser.mli
@@ -0,0 +1,3 @@
+type t = Config.t
+
+include Parsing_utils.S with type t := t
diff --git a/example/src/config_pp.ml b/example/src/config_pp.ml
@@ -0,0 +1,50 @@
+type t = Config.t
+
+let sort_entries =
+  lazy
+    (match Sys.getenv_opt "MYCONF_SORT_ENTRIES" with
+     | Some "true" -> true
+     | None | Some "false" -> false
+     | Some value ->
+       failwith (Printf.sprintf "MYCONF_SORT_ENTRIES: unexpected value %S" value))
+;;
+
+let pp_value (value : Config.value) =
+  match value with
+  | String s -> Pp.verbatimf "\"%s\"" s
+  | Int i -> Pp.verbatimf "%d" i
+  | Bool b -> Pp.verbatimf "%b" b
+;;
+
+let pp_entry (entry : Config.entry) =
+  match entry with
+  | Comment c -> Pp.verbatimf "#%s" c
+  | Binding { loc = _; key; value } ->
+    Pp.concat [ Pp.verbatim key; Pp.verbatim " = "; pp_value value ]
+;;
+
+let pp (config : Config.t) =
+  let entries =
+    if Lazy.force sort_entries
+    then (
+      let comments, bindings =
+        List.partition_map
+          (function
+            | Config.Comment _ as c -> Either.Left c
+            | Config.Binding _ as b -> Either.Right b)
+          config
+      in
+      let sorted_bindings =
+        List.sort
+          (fun b1 b2 ->
+             match b1, b2 with
+             | Config.Binding { key = k1; _ }, Config.Binding { key = k2; _ } ->
+               String.compare k1 k2
+             | _ -> 0)
+          bindings
+      in
+      comments @ sorted_bindings)
+    else config
+  in
+  Pp.seq (Pp.concat_map entries ~sep:Pp.newline ~f:pp_entry) Pp.newline
+;;
diff --git a/example/src/config_pp.mli b/example/src/config_pp.mli
@@ -0,0 +1,3 @@
+type t = Config.t
+
+val pp : t -> unit Pp.t
diff --git a/example/src/dune b/example/src/dune
@@ -0,0 +1,11 @@
+(library
+ (name myconf)
+ (package auto-format-example)
+ (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
+ (libraries auto-format loc parsing-utils pp sexplib0)
+ (preprocess no_preprocessing))
+
+(ocamllex lexer)
+
+(menhir
+ (modules parser))
diff --git a/example/src/lexer.mli b/example/src/lexer.mli
@@ -0,0 +1 @@
+val read : Lexing.lexbuf -> Parser.token
diff --git a/example/src/lexer.mll b/example/src/lexer.mll
@@ -0,0 +1,21 @@
+{
+}
+
+let white = [' ' '\t']+
+let newline = '\r' | '\n' | "\r\n"
+let digit = ['0'-'9']
+let alpha = ['a'-'z' 'A'-'Z']
+let ident = (alpha | '_') (alpha | digit | '_' | '-')*
+
+rule read = parse
+  | white    { read lexbuf }
+  | newline  { Lexing.new_line lexbuf; read lexbuf }
+  | '#' ([^ '\r' '\n']* as c) { Parser.COMMENT c }
+  | '='      { Parser.EQUALS }
+  | "true"   { Parser.BOOL true }
+  | "false"  { Parser.BOOL false }
+  | digit+ as n { Parser.INT (int_of_string n) }
+  | '"' ([^ '"' '\n']* as s) '"' { Parser.STRING s }
+  | ident as id { Parser.KEY id }
+  | eof      { Parser.EOF }
+  | _ as c   { failwith (Printf.sprintf "Unexpected character: %c" c) }
diff --git a/example/src/parser.mly b/example/src/parser.mly
@@ -0,0 +1,31 @@
+%{
+%}
+
+%token <string> KEY
+%token <string> STRING
+%token <int> INT
+%token <bool> BOOL
+%token <string> COMMENT
+%token EQUALS
+%token EOF
+
+%start <Config.t> config
+
+%%
+
+config:
+  | entries = list(entry); EOF { entries }
+;
+
+entry:
+  | c = COMMENT
+    { Config.Comment c }
+  | key = KEY; EQUALS; value = value
+    { Config.Binding { loc = Loc.create $loc; key; value } }
+;
+
+value:
+  | s = STRING { Config.String s }
+  | i = INT    { Config.Int i }
+  | b = BOOL   { Config.Bool b }
+;
diff --git a/example/test/comments.myconf b/example/test/comments.myconf
@@ -0,0 +1,4 @@
+# This is a config file
+# With multiple comments
+name = "test"
+value = 123
diff --git a/example/test/dune b/example/test/dune
@@ -0,0 +1,22 @@
+(include dune.myconf.inc)
+
+(rule
+ (target dune.myconf.inc.raw)
+ (deps
+  (glob_files *.myconf))
+ (action
+  (with-stdout-to
+   %{target}
+   (run %{bin:myconf} fmt gen-dune "\%{bin:myconf}" fmt file))))
+
+(rule
+ (alias runtest)
+ (mode promote)
+ (action
+  (format-dune-file dune.myconf.inc.raw dune.myconf.inc)))
+
+(cram
+ (package auto-format-example)
+ (deps
+  (package auto-format-example)
+  (glob_files *.myconf)))
diff --git a/example/test/dune.myconf.inc b/example/test/dune.myconf.inc
@@ -0,0 +1,21 @@
+; dune file generated by '%{bin:myconf} fmt gen-dune' -- do not edit.
+
+(rule
+ (with-stdout-to
+  comments.myconf.pp.output
+  (run %{bin:myconf} fmt file %{dep:comments.myconf})))
+
+(rule
+ (alias fmt)
+ (action
+  (diff comments.myconf comments.myconf.pp.output)))
+
+(rule
+ (with-stdout-to
+  simple.myconf.pp.output
+  (run %{bin:myconf} fmt file %{dep:simple.myconf})))
+
+(rule
+ (alias fmt)
+ (action
+  (diff simple.myconf simple.myconf.pp.output)))
diff --git a/example/test/run.t b/example/test/run.t
diff --git a/example/test/simple.myconf b/example/test/simple.myconf

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+type t = Config.t`
	`2`	`+`
	`3`	`+include Parsing_utils.S with type t := t`