{React.string(greeting(person))}
+ } +}; +``` +> This snippet includes [@react.component] which comes from [reason-react](https://reasonml.github.io/reason-react/) + +For an introduction to most language features check out the [overview](overview.md) + +## Try Reason in your browser + +To start immediately an online REPL is available at [Sketch.sh](https://sketch.sh) +or open the [playground](playground) + +## Install Reason + +Install Reason on your computer to start writing Reason applications. +Check the [installation](installation.md) for a more detailed guide. diff --git a/docs/installation-esy.md b/docs/installation-esy.md new file mode 100644 index 0000000000..61dcba837c --- /dev/null +++ b/docs/installation-esy.md @@ -0,0 +1,62 @@ +--- +title: Installation via esy +--- + +This page is a detailed explanation on how to install Reason with [esy](https://esy.sh/) Easy package management for native Reason, OCaml and more, both manually and using a template. + +Reason can be installed with a package manager like [opam](https://opam.ocaml.org/) also, check the [installation page](installation.md) for more details. + +### Requirements + +System Requirements: + +- Node.js 16.14 or later. +- macOS, Windows (including WSL), and Linux are supported. + +Esy is distributed via npm, install it using the following command: + +``` +npm install -g esy +``` +> It's recommended to install esy globally + +### Automatic +Using the [`hello-reason`](https://github.com/esy-ocaml/hello-reason) template + +### Manual installation + +To add packages that happen to be hosted on npm, run `esy add npm-package-name`. + +To add packages from opam's registry, prefix the package name with `@opam`. `esy` treats the npm scope `@opam` specially. In this case, `esy` will install any package name with the `@opam` scope directly from [opam](https://opam.ocaml.org/packages/). + +```bash +esy add @opam/bos +``` + + + +We install reason from opam using the following command: + +``` +esy add @opam/reason +``` + +Link to getting started with esy https://esy.sh/docs/en/getting-started.html +See the [configuration](https://esy.sh/docs/en/configuration.html) section from the complete `esy` docs. + +To create your first Reason native CLI program, run the following commands: + +``` +git clone https://github.com/esy-ocaml/hello-reason.git +cd hello-reason + +# Install all dependencies (might take a while in the first run) +esy + +# Compile and run Hello.exe +esy x Hello +``` + +## What's Next? + +After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. Later on you can check out the [language basics](overview.md) to get a basic understanding of all the Reason language constructs. diff --git a/docs/installation.md b/docs/installation.md index 129a134d01..a491cc9430 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,73 +2,102 @@ title: Installation --- -> **Important:** If you are looking for ReScript (formerly BuckleScript) installation instructions, please refer to the [ReScript website](https://rescript-lang.org/docs/manual/latest/installation). +This page is a detailed explanation on how to install Reason with [opam](https://opam.ocaml.org/), both manually and using a template. There are other options available, such as [esy](https://esy.sh), but we recommend using opam for the best experience. Check the [esy installation page](installation-esy.md) if you want to use esy instead. -Reason comes with its own "npm like" package manager called [esy](https://esy.sh): +### System requirements +- macOS and Linux are supported natively +- Windows is supported via WSL (https://ocaml.org/docs/ocaml-on-windows) -``` -npm install -g esy -``` +## Install the package manager + +[opam](https://opam.ocaml.org) (short for OCaml Package Manager) is a tool for managing packages and environments. If you haven't installed opam yet, please follow the instructions provided on the [official website](https://opam.ocaml.org/doc/Install.html). Be aware that the initial setup might be notably slow due to compiler retrieval and build processes. + +### Using a template + +This template serves as a solid foundation, integrating essential configurations and structure to expedite your development process. Simply follow the link to access the template and initiate your ReasonML project effortlessly. -To create your first Reason native CLI program, run the following commands: +We recommend this method for beginners. +**Repository** [melange-re/melange-opam-template](https://github.com/melange-re/melange-opam-template) + +The template comes from the [Melange](https://melange.re) team, since it's a common duo to use Reason with Melange. +Melange is a compiler that emits JavaScript, from Reason code. You can find all the information about Melange in their docs: https://melange.re + +### Setup a new environment manually + +opam needs to be initialised (Initialize `~/.opam`). This step is only required once. + +```bash +opam init -y ``` -git clone https://github.com/esy-ocaml/hello-reason.git -cd hello-reason -# Install all dependencies (might take a while in the first run) -esy +During opam init, you will be asked if you want to add a hook to your shell to put the tools available in the current opam switch on your PATH. -# Compile and run Hello.exe -esy x Hello +```bash +eval $(opam env) ``` -Reason native development is essentially OCaml development. From here on, you want to read up following websites to get to understand the ecosystem: +### Create switch -- **esy**: The `esy` package manager is designed to manage your npm and opam dependencies and efficiently caches & sandboxes your project compiler and dependencies. Check out the [esy website](https://esy.sh) to find out how to install dependencies, setting up package resolutions, and executing compiled programs. -- **opam**: The [opam package index](https://opam.ocaml.org/packages/) lists all available packages available in the OCaml ecosystem -- **dune**: [`dune`](https://github.com/ocaml/dune) is the official build system in the OCaml ecosystem. Check out the [manual](https://dune.readthedocs.io/en/latest/) for more details on how to set up your project. +opam is now installed and configured. Before installing Reason, we need to create a switch which is set of packages that are installed in a given compiler version. This is similar to how [nvm](https://github.com/nvm-sh/nvm) manages different versions of packages on a Node version. -All your packages are managed in your `package.json` file. Usually you will find a `dune` file in each source code directory (such as `bin/` and `lib/`) for all the build system settings as well. +```bash +opam switch create . 5.1.0 --deps-only +``` +For a comprehensive guide on how to create an opam switch, refer to the following link: [ocaml.org/docs/installing-ocaml#create-an-opam-switch](https://ocaml.org/docs/up-and-running#3-create-an-opam-switch). -### Some `esy` Tips +### Install reason -**Adding dependencies:** +``` +opam install reason +``` + +Once the instalation of the [`reason`](https://opam.ocaml.org/packages/reason) package is done you will have available the following tools `refmt` and `rtop` and there's no configuration change to enable the build system (dune) to build your code. -To add Reason / OCaml packages that happen to be hosted on npm, run `esy add npm-package-name`. +Make sure you have installed the latest version of `refmt` and `rtop` by running the following command: ``` -esy add refmterr +refmt --version ``` -**Opam integration:** +## Install the build system -`esy` treats the npm scope `@opam` specially. `esy` will install any package name with the `@opam` scope directly from [opam](https://opam.ocaml.org/packages/). This is the only scope with special meaning. All other package names are assumed to be hosted on npm. +We introduced the build-system called `dune` that Reason projects can use to specify libraries, executables and applications. It’s optimized for monorepos and makes project maintenance easier. Check their docs in case you want to learn more about it: [dune.build](https://dune.build/). ``` -esy add @opam/bos +opam install dune ``` -**Advanced esy configuration:** +## Hello world -See the [configuration](https://esy.sh/docs/en/configuration.html) section from the complete `esy` docs. +To wrap up the installation process, let's create a simple hello world project. With the basic setup done: -## Compiling to JavaScript +Create a file `hello.re` with the following content: +``` +print_endline("Hello world!"); +``` -Reason + OCaml both leverage the [js_of_ocaml (JSOO)](https://ocsigen.org/js_of_ocaml/3.7.0/manual/overview) compiler to compile from bytecode to JavaScript. +Create a file `dune` with the following content: +``` +(executable + (name hello) + (public_name hello)) +``` +> Note: dune uniformly uses the .exe extension to build native executables, even on Unix where programs don’t usually have a .exe extension. -To get started with Reason + esy + JSOO, check out this [`hello-jsoo-esy`](https://github.com/jchavarri/hello-jsoo-esy) template: +The `executable` stanza is used to define executables and the `name` field is used to specify the name of the executable (Can run with `dune exec src/hello.exe`). The `public_name` field is used to specify the name of the executable when it is installed and allows you to run the executable with `hello` directly: `dune exec hello`. +Run the project (this will compile the project and run the executable): ``` -git clone https://github.com/jchavarri/hello-jsoo-esy.git -cd hello-jsoo-esy -esy +dune exec hello +``` +If you want to build only: -npm install -npm run webpack +``` +dune build ``` ## What's Next? -After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. Later on you can check out the [language basics](overview.md) to get a basic understanding of all the Reason language constructs. +After you have successfully intalled Reason, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. Later on you can check out the [language basics](overview.md) to get a basic understanding of all the Reason language constructs. diff --git a/docs/interop.md b/docs/interop.md index 97df8272f4..e64528be50 100644 --- a/docs/interop.md +++ b/docs/interop.md @@ -2,4 +2,6 @@ title: Interop --- -This section has been moved to the new ReScript project: https://rescript-lang.org/docs/manual/v8.0.0/introduction. More info on the transition [here](https://rescript-lang.org/blog/bucklescript-is-rebranding). +Interoperability with JavaScript is a first-class feature of Melange. This section will cover the different ways you can interact with JavaScript code from Reason using Melange. + +This section is documented under Melange's documentation: [Communicate with JavaScript](https://melange.re/v2.0.0/communicate-with-javascript/). diff --git a/docs/jsx.md b/docs/jsx.md index 03dcdb5c0d..ec3500b238 100644 --- a/docs/jsx.md +++ b/docs/jsx.md @@ -2,11 +2,26 @@ title: JSX --- -> **Note:** If you are looking for ReasonReact specific JSX infos, please refer to the [ReScript JSX docs](https://rescript-lang.org/docs/manual/v8.0.0/jsx) instead. +JSX is a syntax extension for HTML-like syntax inside a JavaScript file. It's a convenient way to write React components. -Would you like some HTML syntax in your Reason? If not, quickly skip over this section and pretend you didn't see anything! +Reason has built in support for JSX at the language-level, so you can use it without any extra tooling. -Reason supports the JSX syntax, with some slight differences compared to the one in [ReactJS](https://facebook.github.io/react/docs/introducing-jsx.html). Reason JSX isn't tied to ReactJS; they translate to normal function calls: +The design is slight different compared to the one in [React](https://facebook.github.io/react/docs/introducing-jsx.html), since Reason JSX isn't tied to React and it translate to normal function calls. + +### Features of Reason JSX +- Components are modules with a `make` function +- Props are labeled arguments +- Adds dynamic expressions that allow you to reference variables and functions within your JSX by using the `{ }` (block-scoped) syntax + +### Departures from JavaScript JSX + +- Attributes and children don't mandate `{}`, but we show them anyway for ease of learning. Once you format your file, some of them go away and some turn into parentheses. +- There is no support for JSX prop spread: `\[\|1, 2, 3\|\] |
+| `myArray[1] = 10` | Same |
+| `[1, "Bob", true]` \* | `(1, "Bob", true)` |
+| No immutable list | `[1, 2, 3]` |
+
+\* Tuples can be simulated in JavaScript with arrays, as JavaScript arrays can
+contain multiple types of elements.
+
+### Null
+
+| JavaScript | Reason |
+|---------------------|-----------------------|
+| `null`, `undefined` | `None` \* |
+
+\* There are no nulls, nor null bugs in OCaml. But it does have [an option type](https://reasonml.github.io/docs/en/option) for when you actually need nullability.
+
+### Function
+
+| JavaScript | Reason |
+|---------------------------------|----------------------------|
+| `arg => retVal` | `(arg) => retVal` |
+| `function named(arg) {...}` | `let named = (arg) => ...` |
+| `const f = function(arg) {...}` | `let f = (arg) => ...` |
+| `add(4, add(5, 6))` | Same |
+
+#### Blocks
+
+| JavaScript | +Reason th> + |
|---|---|
+ |
+
+ |
+
let \[\|a, b\|\] = data \* |
+| `const {a: aa, b: bb} = data` | `let {a: aa, b: bb} = data` |
+
+\* This will cause the compiler to warn that not all cases are handled, because
+`data` could be of length other than 2. Better switch to pattern-matching
+instead.
+
+### Loop
+
+| JavaScript | Reason |
+|---------------------------------------|--------------------------------|
+| `for (let i = 0; i <= 10; i++) {...}` | `for (i in 0 to 10) {...}` |
+| `for (let i = 10; i >= 0; i--) {...}` | `for (i in 10 downto 0) {...}` |
+| `while (true) {...}` | Same |
+
+### JSX
+
+| JavaScript | Reason |
+|----------------------------------------|--------------------------|
+| `try (a) { \| Err =\> ...} \* |
+
+\* No finally.
+
+### Blocks
+
+In Reason, "sequence expressions" are created with `{}` and evaluate to their
+last statement. In JavaScript, this can be simulated via an immediately-invoked
+function expression (since function bodies have their own local scope).
+
+| JavaScript | +Reason th> + |
|---|---|
+ |
+
+ |
+