Add API to manipulate lists in builders

[rock3r]

If you create a builder — e.g., by using Podcast.builder().applyFrom(Podcast) — you have no way to manipulate its internal list of builders for its items. For example, you can add new episodes (always at the end of the list, after the existing ones) but there's no way to sort them, or filter them, before building.

The only option right now is to build the podcast, hoping it does build, and then use copy to manipulate the items:

val podcast = podcastBuilder.build()?.run {
    // Sort episodes by pubDate, from newest to oldest
    copy(episodes = episodes.sortedByPubDateDescending())
} ?: error("Unable to generate podcast feed")

It's not a very elegant way to do it.

[mpgirro]

You're absolutely right. So right now we do have manipulating methods, but just for adding:

fun addEpisodeBuilder(episodeBuilder: EpisodeBuilder): PodcastBuilder
fun addAllEpisodeBuilders(episodeBuilders: List<EpisodeBuilder>): PodcastBuilder

We can expose more methods mirroring standard collection methods for each list of builders. These are the ones that I'd propose for now:

fun removeEpisodeBuilder(episodeBuilder: EpisodeBuilder): PodcastBuilder
fun removeAllEpisodeBuilders(episodeBuilders: Collection<EpisodeBuilder>): PodcastBuilder
fun removeAllEpisodeBuilders(predicate: (EpisodeBuilder) -> Boolean): PodcastBuilder
fun retainAllEpisodeBuilders(episodeBuilders: Collection<EpisodeBuilder>): PodcastBuilder
fun retainAllEpisodeBuilders(predicate: (EpisodeBuilder) -> Boolean): PodcastBuilder
fun clearEpisodeBuilders(): PodcastBuilder
fun <R : Comparable<R>> sortEpisodeBuildersBy(selector: (EpisodeBuilder) -> R?): PodcastBuilder
fun <R : Comparable<R>> sortEpisodeBuildersByDescending(selector: (EpisodeBuilder) -> R?): PodcastBuilder

I think we should omit a

fun filterEpisodeBuilders(predicate: (EpisodeBuilder) -> Boolean): List<EpisodeBuilder>

because it only makes sense if it returns a list of matches, which in turn destroys the fluent API design of the builder. Besides,

fun removeAllEpisodeBuilders(predicate)
fun retainAllEpisodeBuilders(predicate)

should be sufficient for most cases anyway. If we really want to, we can also expose a

fun applyToEpisodeBuilders(block: MutableList<EpisodeBuilder>.() -> Unit): PodcastBuilder

but we'll have to check first if this jeopardises any validations.

All these methods will have to be added to all builders having a list of builders for its items of course.

[rock3r]

I reckon we can maybe get away with only exposing a way to get the current list of builders, and to clear the list — this way we don't have to reimplement/proxy other functionality and users can filter/modify the list as they see fit, then clear the builders list and addAll again. It would allow doing things like patching an existing feed (my current use case). Pseudo-code:

val podcast = readPodcastFromFeed()
val podcastBuilder = Podcast.builder().applyFrom(podcast)
val existingEpisodeBuilders = podcastBuilder.episodeBuilders() // This is new API

val episodeBuildersToAdd = getEpisodesToAdd().map { Episode.builder().applyFrom(it) }
val allEpisodeBuilders = (existingEpisodeBuilders + episodeBuildersToAdd).distinct()
    .sortedBy { it.pubDate }  // Hmm...

val newPodcast = podcastBuilder.clearEpisodeBuilders()
    .addAllEpisodeBuilders(allEpisodeBuilders)
    .build()

We also don't have an API to read the builder state, now that I think about it. The hack I have for now is to do something like:

val allEpisodeBuilders = (existingEpisodeBuilders + episodeBuildersToAdd).distinct()
    .sortedBy { checkNotNull(it.build()).pubDate } 

Which is obviously inefficient, and feels kinda gross.