OpenAssetIO / OpenAssetIO-MediaCreation

OpenAssetIO extensions for use in the Media Creation industry.
Apache License 2.0
12 stars 10 forks source link

Formalize string - token expansion. #70

Open elliotcmorris opened 9 months ago

elliotcmorris commented 9 months ago

What

Formalize how string-token expansion works in the mediacreation ecosystem. Provide a method for hosts to easily perform string substitution in the correct manner, and documentation for both hosts and managers to understand and implement correctly templated strings.

Document and provide examples for this behaviour, as well as documenting the specific standard substitution variables we support in templated LocatableContents.

Why

So managers don't have to branch on specific DCC when building templated strings.

### Tasks
- [ ] https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation/issues/91
- [ ] https://github.com/OpenAssetIO/OpenAssetIO/issues/1213
- [ ] https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation/issues/96

Background

From an external discussion :

we need to formalize how string expansions in “file names” occur. Ideally, we don’t want this to be application specific (as this defeats the point of having a common API). As such, we need to agree at least amongst ourselves to start with, how we want to represent common path tokens such as frame number, view, etc… in a portable way. Anyone have any initial preferences? Ideally it should not predicate any specific ordering within the string (i.e some.{frame}.{view}.exr and some.{view}.{frame}.exr should be possible. An initial suggestion would be to use fmt which we already have on-hand in the library, which would result in expansions looking like the above. This gives asset management system the flexibility to use tokens in the position/order required without having to worry about which tool they are in, and you as host authors, a one liner to use in OpenAssetIO to expand the tokens defined by the standard.

Api Design

Free function in openassetio::utils namespace

cpp

Str substitute(string_view input, std::unordered_map<Str, std::variant<int, float, string>>); (Use the PropertyValues variant rather than declaring directly)

python

By default will support above signature bound taking a dict. Also support kwargs, like : substitute(input, frame=24, view="L")

elliotcmorris commented 8 months ago

"Formalizing" in this context means moving from "just use libfmt rules" to "Use the intersection of libfmt and python formatting", update the docs for that, and build the method around that. (They should be the same anyway)