Arrays and singletons in `to` syntax

[Gary Bressler]

Following up on a comment thread here.

Rich was questioning whether we should allow singletons in `to` syntax. He reminded me that at one point during the CML syntax discussions, we declared a preference that properties which take an array should only take an array, not a singleton.

However, since then I think we've deviated from this stance. In particular, the outcome of the decision for capability typenames (`protocol` etc.) was to allow string-or-array for all of them. The reason was that it's often useful to declare singleton capabilities, and for certain types (runner/resolver) singleton is the choice that usually makes sense.

I think we can apply similar logic to the `to` property (and `rights`, for that matter). Often, you just want to offer a capability to a single target. In fact, some CMLs are structured around grouping `offers` by target. The feature does add some cognitive overhead, but I think it's a pretty slight amount: the concept of "singleton == array of one" is pretty intuitive, and if we allow it for capability typenames it would be consistent to allow it for other keywords.

Thoughts?

[Yegor Pomortsev]

The mental model of "singleton == array of one" by itself is reasonable, and I could see developers choosing either the singleton or array based on style or preference.

I'm interested in the cases where a developer wants to transform a singleton into an array-of-multiple, e.g.

to: "#foo"   ->    to: ["#foo", "#bar"]

If this transformation is allowed in most places, but there are some exceptions (runner/resolver), how do we make them easier to identify? Ideally developers wouldn't have to memorize exceptions if the syntax makes it obvious.

Would this apply to the `to` property in `expose`?

--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "component-framework-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to component-framewo...@fuchsia.dev.
To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/component-framework-dev/CAK1yh2%3DfoCOLTT0m28PpNEFGonjhZj0Zq5K%3De_wkkMFmcxyGkQ%40mail.gmail.com.

[Gary Bressler]

Ideally I think there shouldn't be exceptions to this rule, so we don't surprise developers. The `to` in expose is still a singleton, but that's ok because the converse of the rule is not true (i.e. an array field must support singletons, but a singleton field doesn't have to support arrays).

To clarify, I think we would allow the array syntax in runner/resolver to be consistent with other capability types, it's just not that useful most of the time because a component usually only wants to declare one. (That's for `capability`, though; `offer/expose`ing multiple runners seems pretty standard.)

[Rich Kadel]

I'm not emotionally invested in the outcome here (I'm ok with whatever we decide) but I got confused (and I'm still a little confused) because we've considered a lot of different options.

Re-reading one of @Bryan Henry's early posts in the CTP-035 (2 of 3) thread, I believe he proposed always using arrays for properties that accept multiple values because that has a couple of useful properties: It is self-documenting (you always know which properties accept multiple values and which don't), and (perhaps less important) they are easier to extend from one item to more than one, by just adding an item to the array (rather than first converting a string to an array of string, then adding the new property).

Later, you're right, Gary, I think the final agreement was to allow either strings or arrays of strings for capability keywords. (I assumed by "capability keywords", you meant only the keyword property names that identified the capability type, like "protocol" and "storage", but maybe you meant all properties of all capabilities.)

My question now is, are we really doing this to be helpful to the developers or are we doing it because it looks cleaner? 

I think an argument can be made that this is less helpful, particularly for some properties where it's not inherently obvious if they must be single values or can have multiple values. (So, maybe, for consistency, we shouldn't allow singular strings for "protocol" and just bite the bullet, and convert them all to arrays... We have a tool to do that now!)

But, if you want to extend this rule to all properties that can accept multiple values (assuming no one objects) I won't object to it, and I don't think it has any substantial effect on the other parts of CTP-035.

Rich

[Gary Bressler]

On Thu, Apr 8, 2021 at 4:09 PM Rich Kadel <rich...@google.com> wrote:

I'm not emotionally invested in the outcome here (I'm ok with whatever we decide) but I got confused (and I'm still a little confused) because we've considered a lot of different options.

Re-reading one of @Bryan Henry's early posts in the CTP-035 (2 of 3) thread, I believe he proposed always using arrays for properties that accept multiple values because that has a couple of useful properties: It is self-documenting (you always know which properties accept multiple values and which don't), and (perhaps less important) they are easier to extend from one item to more than one, by just adding an item to the array (rather than first converting a string to an array of string, then adding the new property).

Those are valid points, there's no good way to know without reading the documentation or experience with reading enough CML. I'm hoping that both patterns should be common enough that developers intuitively learn to use both. (If we auto-generated a JSON schema we could make this more discoverable and even integrate it with tooling.)

 

Later, you're right, Gary, I think the final agreement was to allow either strings or arrays of strings for capability keywords. (I assumed by "capability keywords", you meant only the keyword property names that identified the capability type, like "protocol" and "storage", but maybe you meant all properties of all capabilities.)

Yes, looking back this was all we agreed to at the time. I don't think we reached an outcome for other keywords.

 

 

My question now is, are we really doing this to be helpful to the developers or are we doing it because it looks cleaner? 

Given the number of places this syntax simplifies, it appears to me to be helpful, although we won't know for sure until we get feedback.

 

I think an argument can be made that this is less helpful, particularly for some properties where it's not inherently obvious if they must be single values or can have multiple values. (So, maybe, for consistency, we shouldn't allow singular strings for "protocol" and just bite the bullet, and convert them all to arrays... We have a tool to do that now!)

But, if you want to extend this rule to all properties that can accept multiple values (assuming no one objects) I won't object to it, and I don't think it has any substantial effect on the other parts of CTP-035.

I think the only places that currently require an array are `to`, `rights`, `modes`, and `subscriptions` (the last two are event specific). For `rights` it's also useful since you almost always want to specify one string. For the latter two it also seems useful but the pluralization is a wrinkle.

[Hunter Freyer]

I tend to prefer arrays being arrays and singletons being singletons. Saving developers having to press [ and then ] is not that big a win, and having One Way to Do It is more self-documenting and more amenable to tooling.

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/component-framework-dev/CAK1yh2%3DHm6ynSaB48tMzTgz6%2BpAReFmkyMuV_UvZHqw1UGUFWQ%40mail.gmail.com.