What is the role of Binary?

[Xazax-hun]

After 802c786, Handler is no longer Binary, but its interface still has only two getters. We had some code that relied on some nodes being Binary so we can reduce the amount of code we need to write by utilizing the more regular structure of IPR. Does this mean we should no longer rely on nodes being Binary or Unary but call the specific getters directly? (Instead of using first/second in generic code.)

[GabrielDosReis]

The structural classes Unary, Binary, and Ternary are devices to capture structural commonalities of various IPR nodes in order to reduce implementation complexities (see how their are used <ipr/impl>). Their accessor functions are non-descriptive names such as first(), second(), and third() and -- in general -- not reflective of a deeper meaning. In particular, any permutation of such accessors is a structural isomorphism. Consequently, they are not interface functions to rely on directly. Of course, there are exceptions, e.g. arithmetic expressions, where a first() or second()` operand have more interface meaning.

If there is a more actionable issue to address in form of code, please feel free to create an issue for that.

[Xazax-hun]

Consequently, they are not interface functions to rely on directly.

Why? There are many scenarios where we do not care about the order of the constituents of a node. E.g., when we pretty print a node. In those scenarios, we are not interested in the deeper meaning of the children, we only want to make sure we visit everything we are interested in. No longer capturing these commonalities for some nodes can increase the complexity of some user code as we will no longer be able to use our generic Binary printer for Handler, we will need to introduce our own, which will ultimately end up doing the exact same thing but using methods with different names. This just forces us to write more boilerplate code without adding any substance.

Moreover, IPR gives little to no guidance on how it should be used/created/consumed. These methods should not have been relied on were not clearly communicated anywhere.

I am ok with IPR not considering these part of the interface, but in that case I believe IPR should provide the facilities to traverse the graph.

[Xazax-hun]

Treat this space as part of the documentation.

Sounds fair, but in this case it would be nice to call this out in the readme or some similar places as this is somewhat unique among the open source projects I worked with and I might not be the only one who would not start searching in the discussions to find this sort of information.

[GabrielDosReis]

Thanks for sharing your thoughts on how I could structure this repo. I don't plan on calling out every tab in the README; that pops up in the GitHub interface as the larger community evolves and develops new useful ways of building software. Have a look at #187.

[Xazax-hun]

I don't plan on calling out every tab in the README;

I was not referring to calling out the existence of the tab but calling out the nature of information that one is expected to find there. E.g., when a user is not supposed to use rely on a publicly available interface method, I would expect to see warnings in the source code rather than on some kind of discussion forums. But your repo, your way.

[GabrielDosReis]

Gabor -

You said:

but in this case it would be nice to call this out in the readme or some similar places as this is somewhat unique among the open source projects I worked with and I might not be the only one who would not start searching in the discussions to find this sort of information.

If you have constructive comments to make to help improve the library, please feel free to share that with all of us. Otherwise, I would ask you to exercise more thoughts about whether you're moving things forward, or if you derailing forward progress. Example of how to help move things forward was shown by @d-winsor through his thoughtful summary and injection of background.

If further comments don't help advance understanding of the real issue, I will be left with no other choice but to lock this particular conversation (which will be real bummer).

[Xazax-hun]

If you have constructive comments to make to help improve the library,

I thought the suggestion of documenting the fact whether and in what circumstances should a public interface function be relied on belongs to the source code rather than a forum was constructive. You disagreed. Ok. That was the end of the discussion on my end.

Example of how to help move things forward was shown by @d-winsor through his thoughtful summary and injection of background.

You specifically asked me in the past to state the problems and not to start with the solutions, yet later you praise someone who was summarizing possible solutions. I merely followed the guidelines you gave me in the past.

But don't worry. I realized that we cannot get to the same page no matter what approach I am using. Anything I said must be wrong, not worthy of consideration. So I no longer plan to engage in any discussions regarding IPR.