doc: Description of `edit` property is confusing and/or not entirely accurate.
Transcript of a Slack conversation—
Hi! Can you answer a quick info question for me? In the docs for the edit property:
Xsmith doesn’t guarantee an ordering when filling in holes, but provides the edit property to take manual control. Xsmith used to always operate on the leftmost hole. It doesn’t do that any more? Why?
It probably still does operate on the leftmost hole. However, that was not a conscious decision and is just a side effect of an implementation detail of RACR. I don't know that RACR guarantees that ordering.
So I don't want to promise a particular ordering.
That said, sometimes we want a different order that leftmost. At any rate, any time you really care about the order in which holes are filled, you should use the edit property to enforce that.
Otherwise, maybe it's fine because RACR happens to do the order you want. But I just don't want to guarantee it myself.
This is used in the canned components to enforce “choose function before the argvector size.” Did that change fix a problem that someone was having?
Guy maybe wanted to use it. It was also something we wanted to improve in canned-components.
When a function application node was generated, it had to put a hole for the function, but also a hole list for the arguments.
Before the edit property, you had to choose the size of the argument list when generating the function application, but that was before choosing a function.
The edit property allows you to first choose a function then go back and set the list size.
But the function ref was the left child, no?
Yes, but list children are a special case. You have to choose a number of holes before you start filling any children.
So I guess it is even more than just choosing an ordering.
It is more generally for retroactive edits.
But edit doesn’t change what you said about the rule. You can’t fill the function ref without first choosing the # of list children.
Thus... the name edit rather than choose-order. But the motivation was to choose a function before committing to a number of arguments, so the ordering thing is what was in my mind when documenting it.
Well, yes, but by using the edit property you can make a canned base choice (0 children in the list) then go back and make the real choice later.
Maybe I should rewrite the documentation on the edit property. You can add an issue that it's confusing or not entirely accurate.