From 4e375ae61566188dd73c545acf28546f4fda3a27 Mon Sep 17 00:00:00 2001 From: Heath Henley <heath.j.henley@gmail.com> Date: Sun, 25 Feb 2024 10:50:27 -0500 Subject: [PATCH 1/8] DOC: switch dream and yojson in first program --- .../1_02_your_first_ocaml_program.md | 53 +++++++------------ 1 file changed, 19 insertions(+), 34 deletions(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index 34481edf7c..f430b3b7d2 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -241,58 +241,43 @@ A more detailed introduction to modules can be found at [Modules](/docs/modules) OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from opam's open-source repository. -To illustrate this, let's turn our `hello` project into a web server using [Anton Bachin](https://github.com/aantron)'s [Dream](https://aantron.github.io/dream/) web framework. First, update the package list for Opam, by running `opam update`. Then, install the `dream` package with this command: +To illustrate this, let's update our `hello` project to parse a string into +JSON using [Yojson](https://ocaml-community.github.io/yojson/yojson/index.html). First, update the package list for Opam, by running `opam update`. Then, install the `Yojson` package with this command: ```shell -$ opam install dream +$ opam install yojson ``` -This tutorial requires at least version `1.0.0~alpha5` of Dream. You can verify that you have a new enough version of Dream by running `opam show -f version dream`. - -Next, run the Dream web server in the `bin/main.ml` file by changing the code to read: +Next, define a string containing some valid JSON in `bin/main.ml` and parse it +using the `Yojson.Safe.from_string` function: ```ocaml -let () = Dream.(run (router [ get "/" (fun (_ : request) -> html Hello.En.v) ])) -``` - -This gives us a web server. It responds to HTTP '/' requests with the content of `Hello.En.v`. Refer to the [Dream documentation](https://aantron.github.io/dream/) for more information. - -<!-- TODO: we have to probably refer to the Dream docs for an explanation -Before detailing how things work, let's explain how Dream types works. - -The function type `request -> response promise` is the type of request handlers. Functions of this type take an HTTP request and return an HTTP response. The response is wrapped in a promise. This prevents the server from waiting for the response to be ready before sending it and also allows processing multiple requests concurrently. The type route `route` represents the binding between a URL path and a handler. +let json_string = {| + {"number" : 42, + "string" : "yes", + "list": ["for", "sure", 42]}|} -Let's detail the roles of each piece: -- `run` triggers the execution of the server process. Its parameter is a handler function. -- `router` turns a list of `route` values into a single handler binding them together. -- `get "/"` declares a route, HTTP GET requests to the `/` path are handled by the provided function. -- `(fun (_ : request) -> ...)` this a handler function. The typed pattern `(_ : request)` means the data from the request is ignored. -- `html Hello.En.v` has type `response promise`. When data inside the promise becomes available, the server will send it, too. In our case, it is immediately available as it is a static constant stored in memory. +let json = Yojson.Safe.from_string json_string -In summary, this is telling: “run a web server responding with the content of `Hello.En.v` to requests to the '/' path” +let () = Format.printf "Parsed to %a" Yojson.Safe.pp json +``` +The JSON string is parsed into a [JSON type](https://ocaml-community.github.io/yojson/yojson/Yojson/Safe/index.html) so that you can use it in your program. Refer to the [Yojson documentation](https://ocaml-community.github.io/yojson/yojson/index.html) for more information. -The `Dream.(` syntax stands for locally opening a module inside an expression. ---> +Before the example will build and run, you need to tell Dune that it needs `Yojson` to compile the project. Do this by adding `Yojson` to the `library` stanza of the `bin/dune` file. The full `bin/dune` file should then match the following. -You need to tell Dune it needs Dream to compile the project. Do this by adding `dream` to the `library` stanza of the `bin/dune` file. The full `bin/dune` file should then match the following. ```lisp (executable (public_name hello) (name main) - (libraries hello dream)) + (libraries hello yojson)) ``` -Launch the server from a new terminal. +Finally, execute as before: ```shell $ opam exec -- dune exec hello -20.07.23 13:14:07.801 0 -20.07.23 13:14:07.801 Type Ctrl+C to stop -``` -**Note**: If on macOS a key icon is displayed, like when asking for a password, you can ignore it and type `Ctrl+C` to get back to the command prompt. +Parsed to `Assoc ([("number", `Int (42)); ("string", `String ("yes")); + ("list", + `List ([`String ("for"); `String ("sure"); `Int (42)])) -Then test from the first terminal: -```shell -$ curl http://localhost:8080/ -Hello, world! ``` ## Using the Preprocessor to Generate Code From 135e03baa5ca4d4540d4d451aee1d8e5d5179637 Mon Sep 17 00:00:00 2001 From: Christine Rose <christinerose@users.noreply.github.com> Date: Mon, 26 Feb 2024 07:35:29 +0000 Subject: [PATCH 2/8] opam formatting --- data/tutorials/getting-started/1_02_your_first_ocaml_program.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index f430b3b7d2..6dbfe22fb6 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -242,7 +242,7 @@ A more detailed introduction to modules can be found at [Modules](/docs/modules) OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from opam's open-source repository. To illustrate this, let's update our `hello` project to parse a string into -JSON using [Yojson](https://ocaml-community.github.io/yojson/yojson/index.html). First, update the package list for Opam, by running `opam update`. Then, install the `Yojson` package with this command: +JSON using [Yojson](https://ocaml-community.github.io/yojson/yojson/index.html). First, update the package list for opam, by running `opam update`. Then, install the `Yojson` package with this command: ```shell $ opam install yojson ``` From e51a01a6c68517580298ddba6e92cb1abac7503a Mon Sep 17 00:00:00 2001 From: Heath Henley <heath.j.henley@gmail.com> Date: Sun, 10 Mar 2024 14:43:43 -0400 Subject: [PATCH 3/8] Try Sexplib for example instaed of yojson --- .../1_02_your_first_ocaml_program.md | 36 +++++++++---------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index 6dbfe22fb6..72c5255247 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -239,45 +239,41 @@ A more detailed introduction to modules can be found at [Modules](/docs/modules) ## Installing and Using Modules From a Package -OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from opam's open-source repository. +OCaml has an active community of open-source contributors. Most projects are available using the Opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from Opam's open-source repository. -To illustrate this, let's update our `hello` project to parse a string into -JSON using [Yojson](https://ocaml-community.github.io/yojson/yojson/index.html). First, update the package list for opam, by running `opam update`. Then, install the `Yojson` package with this command: +To illustrate this, let's update our `hello` project to parse a string containing an S-expression and print back to a string using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for `Opam`, by running `opam update`. Then, install the `Sexplib` package with this command: ```shell -$ opam install yojson +$ opam install sexplib ``` -Next, define a string containing some valid JSON in `bin/main.ml` and parse it -using the `Yojson.Safe.from_string` function: +Next, define a string containing a valid S-expression in `bin/main.ml`. Parse +it into a S-expression with the `Sexplib.Sexp.of_string` function, and then +convert it back into a string with `Sexplib.Sexp.to_string` and print it. + ```ocaml -let json_string = {| - {"number" : 42, - "string" : "yes", - "list": ["for", "sure", 42]}|} +(* Read in Sexp from string *) +let exp1 = Sexplib.Sexp.of_string "(This (is an) (s expression))" -let json = Yojson.Safe.from_string json_string +(* Do something with the Sexp ... *) -let () = Format.printf "Parsed to %a" Yojson.Safe.pp json +(* Convert back to a string to print *) +let () = Printf.printf "%s\n" (Sexplib.Sexp.to_string exp1) ``` -The JSON string is parsed into a [JSON type](https://ocaml-community.github.io/yojson/yojson/Yojson/Safe/index.html) so that you can use it in your program. Refer to the [Yojson documentation](https://ocaml-community.github.io/yojson/yojson/index.html) for more information. +The string you entered representing a valid S-expression is parsed into `List`of `List`s of `strings` so that you can use it in your program. Refer to the [Sexplib documentation](https://github.com/janestreet/sexplib) for more information. -Before the example will build and run, you need to tell Dune that it needs `Yojson` to compile the project. Do this by adding `Yojson` to the `library` stanza of the `bin/dune` file. The full `bin/dune` file should then match the following. +Before the example will build and run, you need to tell Dune that it needs `Sexplib` to compile the project. Do this by adding `Sexplib` to the `library` stanza of the `bin/dune` file. The full `bin/dune` file should then match the following. ```lisp (executable (public_name hello) (name main) - (libraries hello yojson)) + (libraries hello sexplib)) ``` Finally, execute as before: ```shell $ opam exec -- dune exec hello - -Parsed to `Assoc ([("number", `Int (42)); ("string", `String ("yes")); - ("list", - `List ([`String ("for"); `String ("sure"); `Int (42)])) - +(This(is an)(s expression)) ``` ## Using the Preprocessor to Generate Code From f0cbc1c8f6a353c90dcc7bc3baa6c5a99a5d5acb Mon Sep 17 00:00:00 2001 From: Heath Henley <heath.j.henley@gmail.com> Date: Sun, 10 Mar 2024 14:48:23 -0400 Subject: [PATCH 4/8] make opam lowercase --- .../getting-started/1_02_your_first_ocaml_program.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index 72c5255247..a6d87cd8ee 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -239,9 +239,9 @@ A more detailed introduction to modules can be found at [Modules](/docs/modules) ## Installing and Using Modules From a Package -OCaml has an active community of open-source contributors. Most projects are available using the Opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from Opam's open-source repository. +OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from opam's open-source repository. -To illustrate this, let's update our `hello` project to parse a string containing an S-expression and print back to a string using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for `Opam`, by running `opam update`. Then, install the `Sexplib` package with this command: +To illustrate this, let's update our `hello` project to parse a string containing an S-expression and print back to a string using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for opam, by running `opam update`. Then, install the `Sexplib` package with this command: ```shell $ opam install sexplib ``` From f0b829a2bb8cd70e4519195f1bb447ff57a1720b Mon Sep 17 00:00:00 2001 From: Heath Henley <heath.j.henley@gmail.com> Date: Sun, 10 Mar 2024 17:03:30 -0400 Subject: [PATCH 5/8] fix type error --- .../getting-started/1_02_your_first_ocaml_program.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index a6d87cd8ee..6d6eb7f556 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -259,7 +259,9 @@ let exp1 = Sexplib.Sexp.of_string "(This (is an) (s expression))" (* Convert back to a string to print *) let () = Printf.printf "%s\n" (Sexplib.Sexp.to_string exp1) ``` -The string you entered representing a valid S-expression is parsed into `List`of `List`s of `strings` so that you can use it in your program. Refer to the [Sexplib documentation](https://github.com/janestreet/sexplib) for more information. +The string you entered representing a valid S-expression is parsed into +an S-expression type, which is defined as `List` of items that can be either an +`Atom` (string) or an S-expression (it's a recursive type). Refer to the [Sexplib documentation](https://github.com/janestreet/sexplib) for more information. Before the example will build and run, you need to tell Dune that it needs `Sexplib` to compile the project. Do this by adding `Sexplib` to the `library` stanza of the `bin/dune` file. The full `bin/dune` file should then match the following. From 51f9f5cfceb3f385e785388e9c0ddf2d81f42bc2 Mon Sep 17 00:00:00 2001 From: Heath Henley <heath.j.henley@gmail.com> Date: Mon, 18 Mar 2024 23:40:03 -0400 Subject: [PATCH 6/8] fix type description --- .../getting-started/1_02_your_first_ocaml_program.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index 6d6eb7f556..fffa6d2281 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -260,8 +260,8 @@ let exp1 = Sexplib.Sexp.of_string "(This (is an) (s expression))" let () = Printf.printf "%s\n" (Sexplib.Sexp.to_string exp1) ``` The string you entered representing a valid S-expression is parsed into -an S-expression type, which is defined as `List` of items that can be either an -`Atom` (string) or an S-expression (it's a recursive type). Refer to the [Sexplib documentation](https://github.com/janestreet/sexplib) for more information. +an S-expression type, which is defined as either an `Atom` (string) or a `List` +of S-expressions (it's a recursive type). Refer to the [Sexplib documentation](https://github.com/janestreet/sexplib) for more information. Before the example will build and run, you need to tell Dune that it needs `Sexplib` to compile the project. Do this by adding `Sexplib` to the `library` stanza of the `bin/dune` file. The full `bin/dune` file should then match the following. From cec5a2fa6db6cdb15386c2ff71a4b9446ee8ced8 Mon Sep 17 00:00:00 2001 From: Christine Rose <christinerose@users.noreply.github.com> Date: Thu, 21 Mar 2024 04:30:29 -0700 Subject: [PATCH 7/8] remove comma --- data/tutorials/getting-started/1_02_your_first_ocaml_program.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index fffa6d2281..92cd3e755c 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -241,7 +241,7 @@ A more detailed introduction to modules can be found at [Modules](/docs/modules) OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from opam's open-source repository. -To illustrate this, let's update our `hello` project to parse a string containing an S-expression and print back to a string using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for opam, by running `opam update`. Then, install the `Sexplib` package with this command: +To illustrate this, let's update our `hello` project to parse a string containing an S-expression and print back to a string using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for opam by running `opam update`. Then, install the `Sexplib` package with this command: ```shell $ opam install sexplib ``` From 10568c01424bfed4d922e467aec93fec30f8146a Mon Sep 17 00:00:00 2001 From: Heath Henley <heath.j.henley@gmail.com> Date: Tue, 2 Apr 2024 10:30:53 -0400 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Cuihtlauac Alvarado <cuihtlauac@users.noreply.github.com> --- .../getting-started/1_02_your_first_ocaml_program.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md index 92cd3e755c..24fdd569ba 100644 --- a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md +++ b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md @@ -241,7 +241,7 @@ A more detailed introduction to modules can be found at [Modules](/docs/modules) OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the [Install OCaml](/docs/up-and-ready) tutorial. The following section shows you how to install and use a package from opam's open-source repository. -To illustrate this, let's update our `hello` project to parse a string containing an S-expression and print back to a string using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for opam by running `opam update`. Then, install the `Sexplib` package with this command: +To illustrate this, let's update our `hello` project to parse a string containing an [S-expression](https://en.wikipedia.org/wiki/S-expression) and print back to a string, both using [Sexplib](https://github.com/janestreet/sexplib). First, update the package list for opam by running `opam update`. Then, install the `Sexplib` package with this command: ```shell $ opam install sexplib ``` @@ -272,6 +272,8 @@ Before the example will build and run, you need to tell Dune that it needs `Sexp (libraries hello sexplib)) ``` +**Fun fact**: Dune configuration files are S-expressions. + Finally, execute as before: ```shell $ opam exec -- dune exec hello