Standardize and document storage paths

[slouken]

When implementing Steam storage, I had some questions about valid paths:

• Should paths always be relative, e.g. "games/file.sav", or can they start with '/', e.g. "/games/file.sav"
• If they can start with '/', is that equivalent to omitting the leading '/'? e.g. "games/file.sav" is equivalent to "/games/file.sav"?
• When working with directories, should they or can they have trailing '/'?
• Is "." a valid path when enumerating the top level directory?
• Is "" and "/" equivalent to enumerating the top level directory?
• When enumerating a storage directory, should the path passed to the callback have a leading '/'?
• Should we collapse multiple '/' separators into one? e.g. "///games//file.sav" -> "games/file.sav"?

Depending on the answers to these questions, it might make sense for us to have code to standardize paths, e.g. skip leading '/', trim trailing '/', convert "." to "", etc. so the underlying storage implementations don't have to think about them.

[slouken]

I think the only time-critical part of this was the question about whether the directory passed to the enumeration callback has a trailing '/', and the documentation says that it does, so I fixed Steam storage in https://github.com/libsdl-org/SDL/commit/eba06309077777c6ce0efbe5fb2ebca06fbef096

[flibitijibibo]

Can confirm, directories should always have a trailing '/'.

[flibitijibibo]

For the rest:

Should paths always be relative, e.g. "games/file.sav", or can they start with '/', e.g. "/games/file.sav"

Storage paths should not start with '/' or contain a drive letter likeC:.

If they can start with '/', is that equivalent to omitting the leading '/'? e.g. "games/file.sav" is equivalent to "/games/file.sav"?

If we want to we can strip the above out, but it's probably better to be strict so we're not always mangling strings behind everyone's back.

When working with directories, should they or can they have trailing '/'?

Directories passed in can have a trailing slash but it is not necessary - this makes stuff like PathInfo easier to deal with, especially when enumerating all files/folders in a directory. We should try to always have them when passed out.

Is "." a valid path when enumerating the top level directory?

"." is valid, as is ".."; we can treat the storage root as the container's working directory

Is "" and "/" equivalent to enumerating the top level directory?

Yes to the first, not sure about the second - we have reasons to support "." and ".." and "" would work with the idea of storage having an immutable working directory, the second not so much

When enumerating a storage directory, should the path passed to the callback have a leading '/'?

No

Should we collapse multiple '/' separators into one? e.g. "///games//file.sav" -> "games/file.sav"?

Yes, we should collapse redundant separators and resolve relative paths. (We can do what PhysFS does here and disallow going above the root.)

Let's add testautomation_storage to my TODO 😅