feat: TsxProviderBase with test function

[benni-tec]

Description

Currently a TsxProvider needs a getter for the filename it can provider. This PR seeks to introduce a new base class TsxProviderBase which instead uses a bool checkProvidable(String filename) function to determine if a TsxProviderBase is able to provide the source.

To accomplish this it also has Parser getSourceBase(String filename) and Parser? getCachedSourceBase(String filename) methods to retrieve the source when needed.

While do not like attaching Base to everything this naming scheme seems to be the easiest option to not break current implementations.

This new functionality is usefull for example to resolve all .tsx-files relative to a single directory.

Checklist

• The title of my PR starts with a Conventional Commit prefix (fix:, feat:, docs: etc).
• I have read the Contributor Guide and followed the process outlined for submitting PRs.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples.

Breaking Change

• Yes, this is a breaking change.
• No, this is not a breaking change.

While the internal functionig does change and new APIs are exposed I have recreated the old behaviour in TsxProvider as a sub class of the new TsxProviderBase. Therefore classes extending TsxProvider should work as before with no breaking changes.

However classes only implementing it will require additional methods, however if only implemented they should directly implement TsxProviderBase since (apart from the implementation of the old behaviour) TsxProvider does not offer more functionality. It is simply a Wrapper to emulate the old behaviour and not break convention.

Migration instructions

All classes only implementing TsxProvider should either

• extend TsxProvider if the old API is needed (this allows you to not have to look at any new functionality) or
• directly implement TsxProviderBase.

Related Issues

Completes #70
Allows for usecase described in #69

[benni-tec]

I've got some questions about the checklist:

• The old functionality was not covered by tests as far as I can see, nevertheless I will write some soon.
• There is no example folder in this repo. Where should examples go?

[spydon]

I've got some questions about the checklist:

• The old functionality was not covered by tests as far as I can see, nevertheless I will write some soon.

Super!

• There is no example folder in this repo. Where should examples go?

The checklist is copied from Flame, you can create an example directory if we don't have one (shame on us 😅).

[kurtome]

While do not like attaching Base to everything this naming scheme seems to be the easiest option to not break current implementations.

I would consider just breaking current implementations, as long as you are willing to write a PR for flame_tiled, which is the only major client of this library.

Overall it's hard to me to tell if this PR makes sense without concrete examples, maybe tests would help with that

[ufrshubham]

I can't seem to understand why TsxProviderBase had to be a separate class. If it is just to avoid breaking filename getter, then I think making that breaking change should be fine.

[spydon]

@benni-tec any updates on this? :)

[benni-tec]

Not yet. My fork currently does everything I need for my current project. I do plan to submit proper PRs for this and the other issues I've opened, however I am currently pretty time constrained.

As of now my current project should be wrapped up in January, I am currently planning to clean up and submit PRs then.

Is this something that is time-sensitive for you? If so I will see if can get the PRs done this year!

[spydon]

Just a few comments, over all it looks good :)

[jtmcdole]

LFTM (looks fine to me!)

[benni-tec]

Thanks for the review, I didn't have to time yet to write a proper comment:

I have generalised into a generic Provider that can also be used for templates, therby also resolving #73, also as being extensible to more easily discover the location of images in flame_tiled.

I also moved the methods from TileMapParser into TiledMap since there were already parsing method there, and I always thought it was confusing to have this in a different class that does nothing otherwise. While moving it over I also made the names nicer and more descriptive.

The fromString method seems to only have been used in the tests to generate TsxProvider's for every included tileset, which always seemed like a hack to me! Anyways this is not neccessary anymore since the new Provider can resolve multiple or even all files (see tests for an example). The rest of the functionality can be found in parseTmx()!

I took the liberty of adding the Lists of Provider's to the parser to make it more convenient and clean (instead of passing it through all parse calls, only the initial Parser creation is affected and the copies)!

However I split them into multiple Lists so one for tmx and one for templates. This however does not allow to integrate the same mechanism for images (e.g. of tilesets), because I don't think the actual loading of the images is supposed to be in this library and nothing is ever done with them I don't think that is a big deal. flame_tiled could still use the same Provider mechanism to discorver images (this would be great improvment compared to the current state), but just create it's own List when parsing the RenderableMap!

However I could also only pass one List and the Provider's could instead report their capability. What do you think is preferable?

[spydon]

Sorry for the extremely late reply @benni-tec, I had completely forgotten that we had open PRs on this repository!
What is the state of your PRs, are they ready to be merged?

[benni-tec]

Honestly I also forget about the PRs since my project was finished in January, I just merged the incoming changes into #77 and it should be ready to merge now.

I will merge theses changes here as well and incorporate the feedback today, this PR should then also make #59 obsolete.

As for #78 I believe you said it should be an extension package, however I beliebe I made some adjustments in that PR that should be merged to, I will have to look at it again

[benni-tec]

Alright so I rebased this branch onto #77 and fixed the docs as well as incorporating the feedback here. The tests also clear now, as for the analyze it failed due to the partof directives so I'm gussing thats fine? And I don't know whats up with format

[spydon]

@benni-tec could you do a final check on the PR just to see that everything looks correct after the rebase? :)

[spydon]

Ping @benni-tec, I think this is pretty much ready to merge right?

[benni-tec]

Hi everybody, I kept this discussion in my inbox (and the back of my mind) but never got around to checking-in again, sorry!

I just had a look and I believe it is indeed ready to be merged, the only thing that is missing is the appropriate PR for flame_tiled. Those changes should be minimal though.

If you are still interested in this I will try to get it done before the new year.

P.S.: I will be closing the export PR and try to move the code to a new repository. That is indeed a lot of code and potentially a huge maintanence burden

[benni-tec]

While integrating this into Flame I discovered a new problem: Loading from the bundle is asynchronous.

Therefore either the provider and thus the parsing needs to be asynchronous or we hack it in flame_tiled again by crawling the xml and loading all (?) of the files from the bundle. I believe this is how it was before therefore performance should not get worse. Alternativley we could pass a list of what files should be loaded.

If the provider and therefore the parser should stay synchronouse (which is a valid point IMO), then the getCachedSource() only makes sense for synchronous I/O. This is bad practice anyway so we could probably just remove it.

[spydon]

@benni-tec sounds good, go for it. :)

[benni-tec]

What would you prefer:

• Asynchronous Parsing
• Hack in flame_tiled which only supports xml (as it is now)