Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darklang/philip2

An Elm to OCaml compiler
https://github.com/darklang/philip2

bucklescript compiler elm elm-architecture elm-lang frontend functional ocaml reasonml

Last synced: 4 months ago
JSON representation

An Elm to OCaml compiler

Awesome Lists containing this project

README 

        
Philip2 ("*fee-leap* the second") is a compiler from Elm to OCaml, using the ReasonML/Bucklescript ecosystem. You can use it to do a semi-automated port of a codebase from Elm to Bucklescript/ReasonML.



# Quickstart



To start translating your files:



```

npm install -g [email protected] # we build using esy

./install-elm-format # philip2 requires a modified version of elm-format.

esy install

esy build

esy test

./translate MyFile.elm > MyFile.ml

```



# Useful scripts in the repo



- debug: run and then type OCaml code to get pretty-printed OCaml AST. This is useful for figuring out how to generate the code you're trying to create an AST for. (run ./debug, then type your code, then press Ctrl-D)



- parse: a script that parses an Elm file and dumps philip2's understanding of the parse tree.



- translate: a script to translate a single file from Elm to OCaml.



- port: a script to help you port your project over to OCaml. Often, you will have to change your Elm code to make the compiler work (for example, the compiler doesn't support the points-free style of function declaration). This script was helpful to me as I changed my code hundreds of times as I developed philip2.



# Source files



- elm.ml: a parser for the modified json output of elm-format, as well as type definitions which match the type definitions in elm-format.



- translate.ml: the compiler's main file. Reads input, calls elm.ml, then translates from the Elm AST and prints out OCaml.



# How to port your project



- Create an empty bucklescript project using bucklescript-tea. A pretty good tutorial on this is: https://quernd.github.io/tutorials/tea-chess/index.html

- Copy [Porting.ml](https://github.com/darklang/philip2/blob/master/useful_ocaml/Porting.ml) into your repo. (update: you should be able to use [Tablecloth](https://github.com/darklang/tablecloth) instead now)

- Tweak Porting.ml until it you get it to convert something to Elm.

- Run bsb with the watcher to see errors in the generated files.

- Modify the source Elm until everything converts to OCaml cleanly. See tactics below. By doing this, you'll be able to make changes and validate that your old code continues to work, eg by running tests and unit tests.

- At some point (hopefully quite quickly) it becomes easier to edit the generated OCaml than the Elm.

- Edit the OCaml until it fully compiles.



## Tactics for making elm compile to ocaml



- There are a number of ways to tweak the code generated by the compiler, namely by changing the following [variables](https://github.com/darklang/philip2/blob/master/src/translate.ml#L17) in translate.ml:

  - config_function_patterns

  - config_module_patterns

  - config_post_process_patterns

  - config_type_patterns

  - post_process



These allow you to use regex to modify module, function, and type names, as well as a coarse-grained regex-across-the-whole-file (post_process).



- Have a [DontPort.elm](https://github.com/darklang/philip2/blob/master/useful_elm/DontPort.elm) file, in which you put things which don't make sense in OCaml, but which allow you make changes that don't exist in Elm.



- You're probably going to take on some technical debt during the transition. Sorry.



- Elm's dicts are more general than Belt's (`Belt.Map.String.t` vs `Dict String v`). Change your Elm `Dict Str x` to `StrDict x` and then add StrDict to config_module_patterns. You can use our definition in [Elm](https://github.com/darklang/philip2/blob/master/useful_elm/StrDict.elm) and [Ocaml](https://github.com/darklang/philip2/blob/master/useful_ocaml/Porting.ml#L417)



- Because OCaml isn't great at errors, I found it useful to keep regenerating the OCaml code (using the `port` script) while tweaking things, esp file and type ordering. (However, this was necessary for me because I was writing the compiler alongside it; you may find it simpler to do a conversion once and update by hand afterwards).



- The compiler will use `type x = ... and y = ...` for any types that are adjacent. This should simplify using recursive types.



- The compiler doesn't do anything for recursive function definitions. Use `post_process_patterns` to rename `let myFunc` to `let rec myFunc`.



- Many functions, especially if you plan to use Belt, take arguments in a different order than Elm. To avoid the hassle, use a Porting.ml file which you open everywhere. The compiler will add a `open Porting!` to every file regardless.



- [bs-json](https://github.com/glennsl/bs-json) appears to be much nicer to use for decoders than Tea.Json.



- You have to decide which standard libraries to use. We ended up porting lots of Elm code directly (eg using the compiler to translate it) rather than calling OCaml libraries (see https://reasonml.chat/t/advice-on-standard-library-to-use/1165) (update: you can now use [Tablecloth](https://github.com/darklang/tablecloth) for this)



- Elm's Result takes parameters in a different order than Tea.Result and Belt.Result.



- Check out the [useful_elm](/useful_elm) and [useful_ocaml](/useful_ocaml) directories (update: you can now use [Tablecloth](https://github.com/darklang/tablecloth) instead)

.



# Contributing



This project has a code of conduct - please read and abide by it.



Philip2 is extremely alpha quality. Contributions are welcome to improve this and make it more automated and less semi-automated. In order of priority:



- add tests (read directory of Elm files, check that they are identical to the OCaml file of the same name)

- add CI

- fix bugs



PRs welcome!



# Known bugs



PRs welcome (feel free to open an issue or PR to discuss your plans!)



- Philip2 will strip all your comments.

- Points-free style is not supported

- .mli files are not generated

- `++` does not take into account the type of its arguments: it just becomes `^` when sometimes it should become `@`. An easy improvement is to check the argument for list or string literals, or known list/string functions. I suspect we can also use the type system but I think this would be hard to make work.

- Phillip2 generates OCaml syntax only. Add a flag for ReasonML syntax.

- In the pattern below, i1 and i2 are incorrectly flipped by the compiler. This is true of all literal lists in pattern match clauses.



```

match x with

| [i2; i1] -> 5

```



- Nested-else-ifs are reversed. Eg



```

if a then b

else if c then d

else if e then f

else g

```



becomes



```

if e then f

else if c then d

else if a then b

else g

```



- We should add an ability to target "flavors": whether the generated code uses functions and modules from Bucklescript functions, OCaml pervasives, Jane Street Base, or ported Elm libraries.



# License



Files in the toplevel directory use the [MIT](https://github.com/darklang/philip2/blob/master/LICENSE) license. Elm.ml is somewhat based on avh4/elm-format, which has a [BSD](https://github.com/avh4/elm-format/blob/master/LICENSE). Some functions in [useful_ocaml/Porting.ml](https://github.com/darklang/philip2/blob/master/useful_ocaml/Porting.ml) are based on elm/core ([BSD](https://github.com/elm/core/blob/1.0.0/LICENSE)), and from the \*.Extra packages in elm-community, which use a [BSD](https://github.com/elm-community/string-extra/blob/master/LICENSE) license). Others may derive from elsewhere and have unclear providence.