Support for Flow Annotated Javascript as new codegen target

[bwestergard]

See discussion of analogous task for JSONSchema type definitions and discussion of Bucklescript as codegen target.

Would the maintainers of this repo accept PRs to support Flow-safe javascript code generation? Any advice on getting started?

[mjambon]

Hi, I'm the original author of atd (including atdgen). Due to conflicting priorities, I won't be able to spend sufficient time supervising the addition of new features to the existing codebase. @rgrinberg has been the most active on the project recently and he did some massive cleanup, but we haven't pushed new user-facing features in a long time. Some of the code has gotten really too complicated and makes it hard to add new features easily.

Given this situation, I think it would work better if the addition of a new code generation backend was done as a separate project. It gives you more freedom and more responsibility, while encouraging atd to expose a clean API.

That said, if someone is willing to take over the supervision of the whole atd project with all due credit (@rgrinberg?) and is capable of maintaining clean boundaries between code generators, that would work perfectly. An option is to create a subproject for the new code generator, much like atd and atdgen are now subprojects. If we go that route, it would make sense to also include atdj as a subproject. Note how the code for atdj is more straightforward than atdgen. Compare ag_oj_emit.ml which generates OCaml code dealing with json with atdj_trans.ml which generates Java code and served us well for an Android app.

[rgrinberg]

Martin Jambon <notifications@github.com> writes: All the cleanup that I'm doing is actually with an eye towards adding a JS target. Although I'm looking for something that is specific towards jsoo. So I'd love to help out @bwestergard with this task, but I do think that the cleanups are a prerequisite for doing this work. I also think it will be a good idea to fold atdj into this project as well. All the codegen backends can from sharing more than just the API. Testing, documentation, evolving the API, CI, are all easier when this is all centralized. But as I said, the cleanup work is required before proceeding with all these lofty goals. In summary, I'd love to help out with adding a new backend and make it easier so that this is more easily done in the future :)

[mjambon]

@bwestergard, @grinberg will help you.

For getting started, in my experience the most important thing is to nail down what code you're going to generate. How I proceed is by writing down sample code as I want it generated, and then write the OCaml code that translates the trees representing type definitions into code. Another general piece of advice is to have one module per major translation or per concern. The file naming conventions for the atdgen source are <namespacing prefix>_<initial of language 1><initial of language 2>_<evocative name of what it does>. You don't need to follow this strictly if it doesn't make sense and if you work in a new subfolder.

[mjambon]

@bwestergard you'll start from an AST provided by the atd library straight from the input file that contains the user's type definitions. Then you map it to a more specialized tree by interpreting the <...> annotations, failing if some are malformed, and ignoring those that you're not concerned about. In your case, maybe you'll want to reuse some <ocaml ...> annotations, or maybe you'll use something like <bs ...> for things specific to the Bucklescript target.

[mjambon]

@bwestergard as for emitting indented code, I was happy with what atdgen uses: it produces a tree made of Line, Block, and Inline nodes. Once we have the full tree, we call a function that prints it. The result is not as good as what we'd get with a full-blown pretty-printer for OCaml, but I find it good enough for generated code that the user won't inspect very often.