Design: Pseudo/Reserved keys structure

[aqw]

Currently we have the following keys:

• is_asset_directory: is the asset an Asset Directory
• directory: parent directory of the asset relative to repo root
• path: path of the asset relative to repo root
• template: template to use in onyo new

The addition of onyo get --type (specifically the directory type, see #673 and #674) and the idea of git pseudo keys made me think about this more.

I propose a structure that uses dot notation:

• is.asset: True or False
• is.directory: True or False
• is.template: TrueorFalse`
• is.empty: True or False (only ever True for directories and possibly templates)

_is_asset_directory would be retired. Asset Directories would return True for both is.asset and is.directory.

I also propose:

• path.relative: path relative to repo root (currently what path is)
• path.parent: parent directory (currently what directory is)
• path.file path.full: full path relative to repo root (relevant for asset directories and templates)

The git metadata would be:

• git.modified
• git.created

---

The above addresses all of our present keys and current plans, with the exception of template. That might remain as it is.

[TobiasKadelka]

This looks sane to me, and it definitely unifies many thoughts and ideas we discussed over the time of the project. I am going to reflect more on this.

As one little note for now: with the notation of all path.<> you are very close to naming of pathlib. The exception is path.full, which seems closer to path.absolute? But maybe I do not understand the difference you try to specify between path.relative and path.full, since the two descriptions you provided are only different through the usage of the word "full" again :)

In general I really like the dot-notation, because even after reading it once, it is immediately clear what everything means; it is intuitive and easy to remember. So big +1 on that :)

[aqw]

Thanks for the feedback! Glad that it feels intuitive for you too. :-)

I also considered absolute, but to me that means absolute on the filesystem (relative to /). Though I admit that full doesn't feel quite right either.

What about path.file? For Assets Files and Templates it will be the same as path.relative. For Asset Directories it will be the path to the actual file. And for Directories it will be None (or False or <unset>. Whatever makes most sense).

[bpoldrack]

I like it. path.file makes sense to me!

Not sure about is.* WRT to the toplevel name, though. is could easily be an abbreviation that a user wants to use. Doesn't feel like a "good" namespace to reserve. (path and git seem fine, IMO) However, no strong objection in absence of a clearly better idea. In itself, the is is kinda nice for these purposes.

[aqw]

Cool. I like path.file too. I have edited the above summary.

I have two remaining questions: 1) should everything be under a single name space (onyo. would make most sense). I dislike the verbosity. But I do like that:

• we only lay claim to a single namespace rather than many
• we make a guarantee that in the future we won't claim additional namespaces (i.e. repos that are valid now may become invalid with future versions due to new features and namespaces)
• that a user can query all pseudo/reserved keys in a single call such as onyo get --keys onyo. --asset shelf/desktop_intel_NUC5.lmnop12345 (this relies on the potential semi-glob feature discussed in #679) 2) for templates, should path.file be the same as path.relative (which is relative to template root) or be relative to repo root. I currently lean towards repo root.

[TobiasKadelka]

1. On first glance I do not like the verbosity either, but the namespace argument is strong, and I assume I would get used to it very soon anyway.

I wonder if it would be possible to allow something like this: onyo.is.path and is.path both exist. They do the same in principle, but is.path does first check in assets (for the case Ben describes, when is.* is used in an asset), and if it is not found it assumes the pseudo key is meant; while at the same time onyo.is.path assumes the usage as a pseudo-key (and asset contents are ignored)?

The explanation sounds complicated, but it is intuitive for the user, and allows to ignore the verbosity of onyo.is.path for most cases, while it lets me still use is.* in assets without disableing pseudo key functionality and without error.

2. This question is more easy. path.file should be from the repository root. I already had scenarios when I wanted this to exist. When path.relative exists, I see no reason why path.file should be from the template dir.

[aqw]

I wonder if it would be possible to allow something like this: onyo.is.path and is.path both exist. [...]

Yeah, I considered that, but I think that's the worst of both worlds. It's complicated to write and to document, and still ends up squatting a large namespace.

[...] I assume I would get used to it very soon anyway. [...]

That's how I'm feeling right now too. Perhaps we could offer o. as a shorthand for onyo. if we find the extra five chars to be onerous. But I'd suggest that we don't do that right away and let experience in real world situations guide/inform us.

Re 2: cool. Sounds like we're both on the same page. :-)

[aqw]

After a productive conversation with Ben, I think we have a design!

• everything will be under the onyo. namespace.
• we will add the concept of Aliases to onyo. We will create one by default (path -> onyo.path.relative)

The reasoning behind this is that we currently have 4 reserved/pseudo keys:

• path: this is by far the most commonly used pseudo-key. Onyo is built around the idea of piping onyo get --keys path to other onyo commands. This is deserving of a default alias.
• directory: in onyo new, it's only used in TSVs; verbosity is not an issue. Compared to path, it is rarely used. If someone uses it a lot, they can add an alias.
• template: only used in onyo new TSVs; verbosity is not an issue here
• is_asset_directory: ironically, onyo.is.directory is actually shorter

Alias's are wonderful, because if anyone "needs" path, they can change it. We're not actually reserving that key, we're just squatting on it. The only thing that is reserved is the onyo. namespace. Which is fair, and gives us one namespace for all future keys. If anyone finds onyo.path too long, they can setup an alias o.p -> onyo.path.

I will create issues for both Alias's and implementing new pseudo keys.

[aqw]

I have created issues:

• 688

• 689

I have updated the key names in #662, #673, #674, #675

Closing!