Better interface for inlinging/translating references

[jfinkhaeuser]

I'll copy & paste from my comment on #77 here - maybe this is the right place after all.

---

Well, forgive me for bringing #76 into this again, but I think that's a broader topic than deciding on translate vs inline.

Originally, I spoke about resolving which is probably identical to inlining in its concern, though the words have slightly different meaning. If I'm being nitpicky, resolving just looks up what's referenced, and inlining puts it in place of the reference.

What is happening here is more akin to a translation, and also more closely related to what #76 wants: instead of inlining, rewrite the reference from a remote reference of some sort to a local one. I think that is a very valuable feature in the absolutely generic sense. It may be that inlining references to objects in other local files is not necessary, but inlining references to objects at remote URLs is what is required. And what type of URLs do we want to apply this to? Should it be possible to distinguish between URLs at third-party domains, and ones on our own domain?

After following this PR (thank you!) and #76 a little, and unfortunately having too little time to do much about either, it seems to me that a good future solution should follow a different path than what is implemented either before or after this PR. Hindsight is 20/20.

a) I think we need a better mechanism for filtering what kind of references we want to treat. I'm currently going by typing them, but the example with the third-party domains above would go beyond typing. Programming languages and Python in particular have a very flexible concept here in the form of Callables; I think I would like to see a system where a user-supplied callable decides what kind of action gets triggered for a reference. We can supply a standard one that does the same thing as now.
b) We similarly need a Callable that performs the action, instead of limiting things to what's implemented now. I dabbled with this a bit in order to unify your PR with something that would solve #76, because each case is about rewriting some references to a different location. But I ran into problems with the current resolver interface.

If you agree with this general assessment, then I would very much like to discuss what we can do in a next step. There is a good reason prance is still at a 0.x version, which is that I haven't had this kind of feedback from people like yourself yet. We have the ability to make fairly deep changes before a version 1, so I would like to invite you to participate in this.

For your information, the problem I'm having with the resolver is that it's a depth-first approach, and each referenced file gets its own resolver instance. For solving #76, a inner resolver would need the ability to make changes to the specs of an outer resolver. But the specs are not there yet, because we are currently in an inner resolver precisely to build the outer specs.

I can imagine some kind of two-pass approach, and/or we could give resolvers the ability to push "patches" back to the parent, to be applied when the spec is built. I'm not sure how other parsers do this, and it sometimes doesn't help that the actual parsing isn't even part of prance - but I also don't see much value in sinking time into doing that part as well. If you have suggestions, they're more than welcome at this point.

In the meantime, I'm thinking that this PR is solving your current issue just fine. But if you have bandwidth for looking beyond that at a more generic solution to related problems, I'd be very happy to hear your feedback.

---

Let's collect any feedback here from the #77 authors/reviewers and anyone else who wants to pitch in. I have some ideas, but nothing very concrete yet.

[jfinkhaeuser]

@Glutexo @tahmidefaz tagging you so you get the right notification. Don't feel obliged, I just want to open this discussion up a bit.

[RonnyPfannschmidt]

i'm going to slowly iterate this - i want to be able to automatically split and re-bundle specs in order to manage details

for that some extra details are needed as well as a mechanism to have main specs and referenced specs