From a20db2d9092baa82f5d7ac0b9aa5b3f5b5ce6342 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C2=B7=F0=90=91=91=F0=90=91=B4=F0=90=91=95=F0=90=91=91?= =?UTF-8?q?=F0=90=91=A9=F0=90=91=A4?= Date: Sat, 10 May 2025 16:09:03 +0700 Subject: [PATCH 1/3] Remove implicit OCamlFormat bias from the formatter section --- .../{1_07_ocamlformat.md => 1_07_code_formatting.md} | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) rename data/tutorials/platform/{1_07_ocamlformat.md => 1_07_code_formatting.md} (87%) diff --git a/data/tutorials/platform/1_07_ocamlformat.md b/data/tutorials/platform/1_07_code_formatting.md similarity index 87% rename from data/tutorials/platform/1_07_ocamlformat.md rename to data/tutorials/platform/1_07_code_formatting.md index 25cdb0f5b3..992f87672c 100644 --- a/data/tutorials/platform/1_07_ocamlformat.md +++ b/data/tutorials/platform/1_07_code_formatting.md @@ -1,12 +1,14 @@ --- id: "formatting-your-code" -title: "Formatting Your Code With OCamlFormat" +title: "Formatting Your Code" short_title: "Formatting Your Code" description: | - How to set up OCamlFormat to automatically format your code + How to set up formatting of your code category: "Editor Support" --- +## Using OCamlFormat + Automatic formatting with OCamlFormat requires an `.ocamlformat` configuration file at the root of the project. An empty file is accepted, but since different versions of OCamlFormat will vary in formatting, it From 36859373d417a9a604ff224bf2ce72aca565e392 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C2=B7=F0=90=91=91=F0=90=91=B4=F0=90=91=95=F0=90=91=91?= =?UTF-8?q?=F0=90=91=A9=F0=90=91=A4?= Date: Mon, 19 May 2025 20:25:35 +0700 Subject: [PATCH 2/3] Applied previously-unfollowed line length limit fixes some CI linter --- .../platform/1_07_code_formatting.md | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/data/tutorials/platform/1_07_code_formatting.md b/data/tutorials/platform/1_07_code_formatting.md index 992f87672c..550fa64299 100644 --- a/data/tutorials/platform/1_07_code_formatting.md +++ b/data/tutorials/platform/1_07_code_formatting.md @@ -9,19 +9,24 @@ category: "Editor Support" ## Using OCamlFormat -Automatic formatting with OCamlFormat requires an `.ocamlformat` configuration file at the root of the project. +Automatic formatting with OCamlFormat requires an `.ocamlformat` configuration +file at the root of the project. -An empty file is accepted, but since different versions of OCamlFormat will vary in formatting, it -is good practice to specify the version you're using. Running +An empty file is accepted, but since different versions of OCamlFormat will +vary in formatting, it is good practice to specify the version you're using. +Running ```shell -$ echo "version = `ocamlformat --version`" > .ocamlformat +echo "version = `ocamlformat --version`" > .ocamlformat ``` -creates a configuration file for the currently installed version of OCamlFormat. +creates a configuration file for the currently installed version of +OCamlFormat. -In addition to editor plugins that use OCamlFormat for automatic code formatting, Dune also offers a command to run OCamlFormat to automatically format all files from your codebase: +In addition to editor plugins that use OCamlFormat for automatic code +formatting, Dune also offers a command to run OCamlFormat to automatically +format all files from your codebase: ```shell -$ opam exec -- dune fmt -``` \ No newline at end of file +opam exec -- dune fmt +``` From e2c017b759a298efbedf9368e86f3e3e45f8b774 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C2=B7=F0=90=91=91=F0=90=91=B4=F0=90=91=95=F0=90=91=91?= =?UTF-8?q?=F0=90=91=A9=F0=90=91=A4?= Date: Sat, 10 May 2025 16:45:50 +0700 Subject: [PATCH 3/3] =?UTF-8?q?Add=20Topiary=20to=20=E2=80=9CFormatting=20?= =?UTF-8?q?Your=20Code=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../platform/1_07_code_formatting.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/data/tutorials/platform/1_07_code_formatting.md b/data/tutorials/platform/1_07_code_formatting.md index 550fa64299..284b5a8f35 100644 --- a/data/tutorials/platform/1_07_code_formatting.md +++ b/data/tutorials/platform/1_07_code_formatting.md @@ -30,3 +30,64 @@ format all files from your codebase: ```shell opam exec -- dune fmt ``` + +## Using Topiary + +[Topiary](https://topiary.tweag.io) is a Tree-sitter-based code formatter +supporting multiple languages, including OCaml & OCamllex. It can be invoked +with + + +```shell-session +$ topiary format source.ml +``` + + +Topiary does not require an empty configuration file to operate & has its own +set of defaults, however, it can be +[configured](https://topiary.tweag.io/book/cli/configuration.html). + +### Example configuration setup + +This example configuration will override the default configuration to use 1 tab +character for indentation by creating a `.topiary.ncl` Nickel configuration +file. + + +```shell-session +$ touch .topiary.ncl +$ $EDITOR .topiary.ncl +``` + + + +```nickel +{ + languages = { + nickel.indent | priority 1 = "\t", + ocaml.indent | priority 1 = "\t", + ocaml_interface.indent | priority 1 = "\t", + ocamllex.indent | priority 1 = "\t", + }, +} +``` + + +Then this file needs to be exported to the environment such as `export +TOPIARY_CONFIG_FILE=".topiary.ncl"` in Bash/ZSH or `set -x TOPIARY_CONFIG_FILE +".topiary.ncl"` in Fish. + +TIP: If using Direnv, the environment variable can also be added to the user’s +personal `.envrc` so it is exported on switching to the project directory by +appending with `echo 'export TOPIARY_CONFIG_FILE=".topiary.ncl"' >> .envrc`. + +Afterwards, `--merge-configuration` will always merge in the example +configuration. Invoke Topiary’s formatting with + + +```shell-session +$ topiary format --merge-configuration source.ml +``` + + +and/or configure your editor to run this command on saving the file.