gradle
8.2

# flatMap

abstract fun <S> flatMap(transformer: Transformer<out @Nullable Provider<out S>, out Any>): Provider<S>

Returns a new Provider from the value of this provider transformed using the given function.

While very similar in functionality to the regular map operation, this method offers a convenient way of connecting together task inputs and outputs. (For a deeper understanding of the topic see the Lazy Configuration section of the Gradle manual.)

Task inputs and outputs often take the form of providers or properties, the latter being a special case of provider whose value can be changed at will. An example of using `flatMap` for connecting such properties would be following:

    class Producer extends DefaultTask {
        @OutputFile
        abstract RegularFileProperty getOutputFile()

        //irrelevant details omitted
    }

    class Consumer extends DefaultTask {
        @InputFile
        abstract RegularFileProperty getInputFile()

        //irrelevant details omitted
    }

    def producer = tasks.register("producer", Producer)
    def consumer = tasks.register("consumer", Consumer)

    consumer.configure {
        inputFile = producer.flatMap { it.outputFile }
    }

Content copied to clipboard

An added benefit of connecting input and output properties like this is that Gradle can automatically detect task dependencies based on such connections. To make this happen at code level, any task details associated with this provider (the one on which `flatMap` is being called) are ignored. The new provider will use whatever task details are associated with the return value of the transformation.

The new provider returned by `flatMap` will be live, so that each time it is queried, it queries this provider and applies the transformation to the result. Whenever this provider has no value, the new provider will also have no value and the transformation will not be called.

#### Parameters

transformer

The transformer to apply to values. May return `null`, in which case the provider will have no value.