reason

Reason

Simple, fast & type safe code that leverages the JavaScript & OCaml ecosystems

Getting Started

Community

Contributing

Documentations

Go to https://github.com/reasonml/reasonml.github.io to contribute to the Reason documentation.

Codebase

See the src folder's README.

Installation for Programmatic Usage

If you're not using Reason programmatically, disregard this section and see the Getting Started guide above. This is for using Reason's refmt as a third-party library.

JavaScript API

We expose a refmt.js for you to use on the web. Again, for local development, please use the native refmt that comes with the installation here. It's an order of magnitude faster than the JS version. Don't use the JS version unless you know what you're doing. Let's keep our ecosystem fast please.

Aaaanyways, to install refmt.js: npm install reason. Here's the API:

• parseRE(codeString): returns an AST + comments info that you'd use for printing
• parseREI(codeString): same, but for interface
• printRE(astAndComments): receives the data structure returned by parseRE and others
• printREI(astAndComments): same, but for interface
• parseML(codeString), parseMLI(codeString), printML(astAndComments), printMLI(astAndComments): the OCaml syntax counterparts.

The parse* functions potentially throw an error of this shape:

{
  message: string,
  // location can be undefined
  location: {
    // all 1-indexed
    startLine: number, // inclusive
    startLineStartChar: number, // inclusive
    endLine: number, // inclusive
    endLineEndChar: number, // **exclusive**
  }
}

Example usage:

const refmt = require('refmt')
// convert the ocaml syntax to reason syntax
console.log(refmt.printRE(refmt.parseML('let f a = 1')))

refmt.js is minified for you through Closure Compiler, with an accompanying refmt.map. The size is 2.3MB but don't get fooled; it gzips down to just 345KB. This way, you can carry it around in your own blog and use it to create interactive refmt playground, without worrying about imposing bandwidth overhead to your readers. Again, keep our ecosystem fast and lean.

Native API

We're spoiled with more APIs on the native side. To use Reason from OPAM as a native library, you have these functions. So:

• Reason_toolchain.RE.implementation_with_comments
• Reason_toolchain.RE.interface_with_comments
• Reason_toolchain.RE.print_interface_with_comments
• Reason_toolchain.ML.implementation_with_comments
• etc.

The RE parsing functions might throw this (docs on Location.t here). The ML parsing functions might throw Syntaxerr.Error error.

Example usage:

let ast_and_comments =
  Lexing.from_string "let f a => 1"
  |> Reason_toolchain.RE.implementation_with_comments

(* Convert Reason back to OCaml syntax. That'll show these Reason users! *)
let ocaml_syntax =
  Reason_toolchain.ML.print_implementation_with_comments
    Format.str_formatter
    ast_and_comments;
  Format.flush_str_formatter ()

License

See Reason license in LICENSE.txt.

Works that are forked from other projects are under their original licenses.

Credit

The general structure of refmt repo was copied from whitequark's m17n project, including parts of the README that instruct how to use this with the OPAM toolchain. Thank you OCaml!

Changelog

3.0.0

Our biggest release! Please see our blog post on https://reasonml.github.io/blog/2017/10/27/reason3.html.

Summary: this is, practically speaking, a non-breaking change. You can mix and match two projects with different syntax versions in BuckleScript 2 (which just got release too! Go check), and they'll Just Work (tm).

To upgrade your own project, we've released a script, https://github.com/reasonml/upgradeSyntaxFrom2To3

Improvements:

• Much better printing for most common idioms.
• Even better infix operators formatting for ==, &&, > and the rest (1380, 1386, etc.).
• More predictable keyword swapping behavior (1539).
• BuckleScript's Js.t {. foo: bar} now formats to {. "foo": bar}, just like its value counterpart ([%bs.obj {foo: 1}] to {"foo": bar}.
• [@foo], [@@foo] and [@@@foo] are now unified into [@foo] and placed in front instead of at the back.
• ! is now the logical negation. It was not previously.
• Dereference was !. Now it's a postfix ^.
• Labeled argument with type now has punning!
• String concat is now ++ instead of the old ^.
• For native, Reason now works on OCaml 4.05 and the latest topkg (1438).
• Record field punning for module field prefix now prints well too: {M.x, y} is {M.x: x, y: y}.
• JSX needs {} like in JS.
• Fix reason-specific keywords printing in interface files (e.g. ==, match, method).
• Record punning with renaming (1517).
• The combination of function label renaming + type annotation + punning is now supported!
• Label is now changed from ::foo back to ~foo, just like for OCaml.
• Fix LOTS of bugs regarding parsing & formatting (closing around 100 improvement-related issues!).
• Official refmt.js, with public API. See README.md.
• Official refmt native public API too.
• New JS application/abstraction syntax. Yes yes, we know. Despite the 100+ fixes, this one's all you cared about. Modern software engineering ¯\_(ツ)_/¯. Please do read the blog post though.

Breaking Changes:

• Remove --use-stdin and --is-interface-pp option from refmt; they've been deprecated for a long time now
• Remove unused binaries: reup, etc.
• Remove the old reactjs_jsx_ppx.ml. You've all been on reactjs_jsx_ppx_2.ml for a long time now.
• Reserved keywords can no longer be used as an external declaration's labels.

Deprecated:

• Deprecate --add-printers option from refmt; we'll have a better strategy soon.