Initial api for "getTree"

[brprice]

Description

This is a feature request.

We need to return program trees from our api. In particular, to get the current program.

NB This FR is intentionally very basic, and does not worry about what information about the current program will be needed by a frontend. The purpose is to get something working to iterate on. We will flesh out more details (in a separate issue) after implementing the "0.1" version, when I have a better perspective and this task is out of the critical path.

Dependencies

None.

Spec

We don't want to expose the full complexity of our AST to a frontend, as it is mostly not needed for rendering purposes (and that is all the frontend should be doing).

We just send the skeleton of the tree, with an (ID, Text) decoration on each node. This Text is unspecified here, but is only to have something non-trivial to work with, and to make implementation/debugging easier.

The format of this data is as a literal rose tree in JSON

• Each node is of the form { id:3, label:"some-text", children: [...]}
• The children are nested occurrences of nodes
• Thus the tree will always be non-empty
• e.g. {id:0,desc:"root", children: [{id:1, label:"child",children:[]}]}

Implementation details

Previously, "all" our endpoints returned Result ProgError _. Since getting the current program can never fail, should we make this explicit in the API? For the 0.1 let's take the easy path and keep the error possibility.

A different representation would be to "flatten": use the ids as keys and explicitly list children and parents by id. E.g.

{existant:[0,1],
 nodes:{
    "0": {desc:"root",children:[1],parent:null},
    "1": {desc:"child", children:[], parent:0}
  }
 }

It would be worth thinking about which representation is most useful from a frontend-implementors point of view. However, for the sake of a 0.1 I shall do the literal-rose-tree thing.

Not in spec

In the future we will want to be able to represent diffs of trees compactly. This is both for network efficiency and also ease-of-implementation for visualising evaluation (these may well be different problems which need different solutions). This is not discussed here at all.

Discussion

<If there's a GitHub Discussions topic or a GitHub Issue where this feature has been/is being discussed, link it here.>

Future work

• Efficient tree diffs: see "Not in spec"
• A decent "1.0" version. This needs thought as to what is useful to know on the frontend.

[dhess]

Thanks, this looks good.

IMO, you can just move the "decent 1.0" comment to "Future work," as it will probably take us several iterations to get there, and we need not do them all under this one Feature Request. (If so, you may also want to re-title this issue, "Initial API for getTree" or similar.)