-
Notifications
You must be signed in to change notification settings - Fork 6
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Syntax page #200
Merged
+237
−2
Merged
Add Syntax page #200
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
ae2f577
Add Syntax page
feihong 5bacbf3
Edits in response to feedback
feihong ac4e7d6
Link to and from getting-started in syntaxes
feihong 390113c
Add links for setup of other editors
feihong 55b49d4
Delete line about error messages not being aware of Reason syntax
feihong File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,221 @@ | ||
# Supported syntaxes | ||
|
||
Melange supports two syntaxes: [OCaml | ||
syntax](https://ocamlpro.github.io/ocaml-cheat-sheets/ocaml-lang.pdf) (the | ||
default) and [Reason syntax](https://reasonml.github.io/). You can toggle | ||
between them by using the "Syntax" widget in the top left corner of this page. | ||
Try clicking on it now to see the two different versions of the following code | ||
snippet: | ||
|
||
```ocaml | ||
module Speech = struct | ||
type utterance | ||
|
||
external makeUtterance : string -> utterance = "SpeechSynthesisUtterance" | ||
[@@mel.new] | ||
|
||
external speak : utterance -> unit = "speechSynthesis.speak" | ||
end | ||
|
||
module App = struct | ||
let style = | ||
ReactDOM.Style.make ~fontSize:"1em" ~border:"1px solid white" | ||
~borderRadius:"0.5em" ~padding:"1em" () | ||
|
||
let make () = | ||
(button ~style | ||
~onClick:(fun _ -> | ||
"Hello ReasonReact" |> Speech.makeUtterance |> Speech.speak) | ||
~children:[ React.string "Say hello" ] | ||
() [@JSX]) | ||
[@@react.component] | ||
end | ||
|
||
let () = | ||
match ReactDOM.querySelector "#preview" with | ||
| None -> Js.log "Failed to start React: couldn't find the #preview element" | ||
| Some root -> | ||
let root = ReactDOM.Client.createRoot root in | ||
ReactDOM.Client.render root (App.createElement ~children:[] () [@JSX]) | ||
``` | ||
```reasonml | ||
module Speech = { | ||
type utterance; | ||
|
||
[@mel.new] | ||
external makeUtterance: string => utterance = "SpeechSynthesisUtterance"; | ||
|
||
external speak: utterance => unit = "speechSynthesis.speak"; | ||
}; | ||
|
||
module App = { | ||
let style = | ||
ReactDOM.Style.make( | ||
~fontSize="1em", | ||
~border="1px solid white", | ||
~borderRadius="0.5em", | ||
~padding="1em", | ||
(), | ||
); | ||
|
||
[@react.component] | ||
let make = () => | ||
<button | ||
style | ||
onClick={_ => | ||
"Hello ReasonReact" |> Speech.makeUtterance |> Speech.speak | ||
}> | ||
{React.string("Say hello")} | ||
</button>; | ||
}; | ||
|
||
let () = | ||
switch (ReactDOM.querySelector("#preview")) { | ||
| None => | ||
Js.log("Failed to start React: couldn't find the #preview element") | ||
| Some(root) => | ||
let root = ReactDOM.Client.createRoot(root); | ||
ReactDOM.Client.render(root, <App />); | ||
}; | ||
``` | ||
|
||
As you can see, Reason syntax resembles JavaScript and supports JSX, so it is | ||
more approachable to JavaScript and TypeScript developers. Most tooling, such as | ||
the [OCaml Platform VS Code | ||
extension](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform), | ||
works well with Reason, but some tools aren't completely aware of it—for | ||
example, error messages from the compiler still use OCaml syntax. | ||
|
||
## Installation | ||
|
||
### Reason syntax | ||
|
||
To install Reason syntax support add `reason` to the `depends` section of the | ||
`<project-name>.opam` file in your project's root directory: | ||
|
||
```opam | ||
depends: [ | ||
"ocaml" | ||
"reason" {>= "3.10.0"} # [!code ++] | ||
"dune" {>= "3.9"} | ||
"melange" {>= "2.0.0"} | ||
"reason-react" {>= "0.13.0"} | ||
"reason-react-ppx" | ||
"opam-check-npm-deps" {with-dev-setup} | ||
"ocaml-lsp-server" {with-dev-setup} | ||
"dot-merlin-reader" {with-setup} | ||
"odoc" {with-doc} | ||
] | ||
``` | ||
|
||
On the command line, run | ||
|
||
```bash | ||
opam install -y . --deps-only | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we mention that alternatively, users can just run There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added alternate command in 55b49d4 |
||
``` | ||
|
||
Note that Reason support is already set up for you in | ||
[melange-opam-template](https://github.com/melange-re/melange-opam-template). | ||
|
||
### OCaml syntax | ||
|
||
OCaml syntax is supported by default, but to get formatting support, you should | ||
add `ocamlformat` to the `depends` section of the `<project-name>.opam` file in | ||
your project's root directory: | ||
|
||
```opam | ||
depends: [ | ||
"ocaml" | ||
"dune" {>= "3.9"} | ||
"melange" {>= "2.0.0"} | ||
"reason-react" {>= "0.13.0"} | ||
"reason-react-ppx" | ||
"ocamlformat" {with-dev-setup} # [!code ++] | ||
"opam-check-npm-deps" {with-dev-setup} | ||
"ocaml-lsp-server" {with-dev-setup} | ||
"dot-merlin-reader" {with-setup} | ||
"odoc" {with-doc} | ||
] | ||
``` | ||
|
||
On the command line, run | ||
|
||
```bash | ||
opam install -y . --deps-only --with-dev-setup | ||
``` | ||
|
||
## VS Code configuration | ||
|
||
First, make sure you've already [installed and configured OCaml Platform VS Code | ||
extension](getting-started#editor-integration). | ||
|
||
### Reason syntax | ||
|
||
1. To enable format-on-save in VS Code, open your [User Settings JSON | ||
file](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson) | ||
and add this snippet: | ||
|
||
```json | ||
"[reason]": { | ||
"editor.formatOnSave": true | ||
}, | ||
``` | ||
|
||
1. To control how the Reason formatter breaks up long lines, you can also add | ||
this snippet: | ||
|
||
```json | ||
"ocaml.server.extraEnv": { | ||
"REFMT_PRINT_WIDTH": "120" | ||
}, | ||
``` | ||
|
||
In the snippet above, the print width is set to 120 characters, but you can | ||
use any number you prefer. If you don't set this, the default is 80. | ||
|
||
### OCaml syntax | ||
|
||
1. Add `.ocamlformat` to your project's root directory. If you want to change | ||
the print width, add this to the file: | ||
|
||
```ini | ||
m=120 | ||
``` | ||
|
||
In the snippet above, the print width is set to 120 characters, but you can | ||
use any number you prefer. If you don't set this, the default is 80. | ||
1. To enable format-on-save in VS Code, open your [User Settings JSON | ||
file](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson) | ||
and add this snippet: | ||
|
||
```json | ||
"[ocaml]": { | ||
"editor.formatOnSave": true | ||
}, | ||
``` | ||
|
||
## Other editors | ||
|
||
For Reason syntax, check out [Editor | ||
Plugins](https://reasonml.github.io/docs/en/editor-plugins) page from Reason | ||
documentation. | ||
|
||
For OCaml syntax, check out the [Editor | ||
Setup](https://ocamlverse.net/content/editor_setup.html) page from OCamlverse. | ||
|
||
## Formatters | ||
|
||
You can run this command to check the format of all your OCaml source files: | ||
|
||
```bash | ||
dune build @fmt | ||
``` | ||
|
||
If Reason syntax support is installed, it will automatically check the format of | ||
all Reason sources files (`.re` and `.rei`). | ||
|
||
To automatically fix the formatting, run this: | ||
|
||
```bash | ||
dune build @fmt --auto-promote | ||
``` |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would either link the issue here or not even mention this, since it's not always the case. Sometimes the error gets in reason and sometimes it doesn't
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deleted that line in 55b49d4