Merge pull request #1050 from robstoll/api-infix_add-report-to-in-order-only

add report option to `inGiven order only` in api-infix

Author: robstoll

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/deprecatedIterableAssertions.kt

@@ -109,10 +109,6 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.contains(
  *
  * It is a shortcut for `contains.inOrder.only.values(expected, *otherExpected)`
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @return an [Expect] for the subject of `this` expectation.
  */
 @Deprecated(
@@ -129,10 +125,6 @@ fun <E, T : Iterable<E>> Expect<T>.containsExactly(expected: E, vararg otherExpe
  *
  * It is a shortcut for `contains.inOrder.only.entry(assertionCreatorOrNull)`
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
@@ -154,10 +146,6 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.containsExactly(assertionCreatorOrNull
  *
  * It is a shortcut for `contains.inOrder.only.entries(assertionCreatorOrNull, *otherAssertionCreatorsOrNulls)`
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/iterableExpectations.kt

@@ -108,11 +108,12 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContain(
  * Expects that the subject of `this` expectation (an [Iterable]) contains only
  * the [expected] value and the [otherExpected] values (if given) in the defined order.
  *
- * It is a shortcut for `toContain.inOrder.only.values(expected, *otherExpected)`
+ * It is a shortcut for `toContain.inOrder.only.values(expected, *otherExpected, report = { ... })`
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
+ * @param expected The first expected value.
+ * @param otherExpected The other expected values in the given order.
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
@@ -124,8 +125,7 @@ fun <E, T : Iterable<E>> Expect<T>.toContainExactly(
     expected: E,
     vararg otherExpected: E,
     report: InOrderOnlyReportingOptions.() -> Unit = {}
-): Expect<T> =
-    toContain.inOrder.only.values(expected, *otherExpected, report = report)
+): Expect<T> = toContain.inOrder.only.values(expected, *otherExpected, report = report)
 
 /**
  * Expects that the subject of `this` expectation (an [Iterable]) contains only an entry holding
@@ -134,10 +134,6 @@ fun <E, T : Iterable<E>> Expect<T>.toContainExactly(
  *
  * It is a shortcut for `toContain.inOrder.only.entry(assertionCreatorOrNull)`
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
@@ -159,15 +155,13 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContainExactly(assertionCreatorOrNul
  *
  * It is a shortcut for `toContain.inOrder.only.entries(assertionCreatorOrNull, *otherAssertionCreatorsOrNulls)`
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
  * @param otherAssertionCreatorsOrNulls Additional identification lambdas which each identify (separately) an entry
  *   which we are looking for (see [assertionCreatorOrNull] for more information).
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
@@ -192,6 +186,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContainExactly(
  * are passed. This function expects [IterableLike] (which is a typealias for [Any]) to avoid cluttering the API.
  *
  * @param expectedIterableLike The [IterableLike] whose elements are expected to be contained within this [Iterable].
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  * @throws IllegalArgumentException in case [expectedIterableLike] is not an [Iterable], [Sequence] or one of the [Array] types or the given

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/iterableLikeToContainInAnyOrderOnlyCreators.kt

@@ -20,10 +20,6 @@ import ch.tutteli.kbox.glue
  *
  * Delegates to [values].
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param expected The value which is expected to be contained within the subject (an [IterableLike]).
  *
  * @return an [Expect] for the subject of `this` expectation.
@@ -38,10 +34,6 @@ fun <E, T: IterableLike> EntryPointStep<E, T, InAnyOrderOnlySearchBehaviour>.val
  * needs to contain only the [expected] value as well as the [otherExpected] values
  * where it does not matter in which order.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param expected The value which is expected to be contained within the subject (an [IterableLike]).
  * @param otherExpected Additional values which are expected to be contained within [IterableLike].
  *
@@ -61,10 +53,6 @@ fun <E, T: IterableLike> EntryPointStep<E, T, InAnyOrderOnlySearchBehaviour>.val
  *
  * Delegates to [entries].
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
@@ -92,10 +80,6 @@ fun <E : Any, T: IterableLike> EntryPointStep<out E?, T, InAnyOrderOnlySearchBeh
  * `isGreaterThan(0)` matches `1` before `toEqual(1)` would match it. As a consequence `toEqual(1)` could only match the
  * entry which is left -- in this case `2` -- and of course this would fail.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
@@ -121,10 +105,6 @@ fun <E : Any, T: IterableLike> EntryPointStep<out E?, T, InAnyOrderOnlySearchBeh
  * are passed (this can be changed via [IterableLikeToIterableTransformer]).
  * This function expects [IterableLike] (which is a typealias for [Any]) to avoid cluttering the API.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param expectedIterableLike The [IterableLike] whose elements are expected to be contained within this [IterableLike]
  *
  * @return an [Expect] for the subject of `this` expectation.

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/iterableLikeToContainInOrderOnlyCreators.kt

@@ -19,10 +19,6 @@ import ch.tutteli.kbox.glue
  *
  * Delegates to [values].
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param expected The value which is expected to be contained within the subject (an [IterableLike]).
  *
  * @return an [Expect] for the subject of `this` expectation.
@@ -37,12 +33,10 @@ fun <E, T : IterableLike> EntryPointStep<E, T, InOrderOnlySearchBehaviour>.value
  * needs to contain only the [expected] value as well as the [otherExpected] values
  * in the specified order.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param expected The value which is expected to be contained within the subject (an [IterableLike]).
  * @param otherExpected Additional values which are expected to be contained within [IterableLike].
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
@@ -61,10 +55,6 @@ fun <E, T : IterableLike> EntryPointStep<E, T, InOrderOnlySearchBehaviour>.value
  *
  * Delegates to `entries(assertionCreatorOrNull)`.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
@@ -84,15 +74,13 @@ fun <E : Any, T : IterableLike> EntryPointStep<out E?, T, InOrderOnlySearchBehav
  * holds all assertions [assertionCreatorOrNull] creates or
  * needs to be `null` in case [assertionCreatorOrNull] is defined as `null`.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param assertionCreatorOrNull The identification lambda which creates the assertions which the entry we are looking
  *   for has to hold; or in other words, the function which defines whether an entry is the one we are looking for
  *   or not. In case it is defined as `null`, then an entry is identified if it is `null` as well.
  * @param otherAssertionCreatorsOrNulls Additional identification lambdas which each identify (separately) an entry
  *   which we are looking for (see [assertionCreatorOrNull] for more information).
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
@@ -114,11 +102,9 @@ fun <E : Any, T : IterableLike> EntryPointStep<out E?, T, InOrderOnlySearchBehav
  * are passed (this can be changed via [IterableLikeToIterableTransformer]).
  * This function expects [IterableLike] (which is a typealias for [Any]) to avoid cluttering the API.
  *
- * Note that we might change the signature of this function with the next version
- * which will cause a binary backward compatibility break (see
- * [#292](https://github.com/robstoll/atrium/issues/292) for more information)
- *
  * @param expectedIterableLike The [IterableLike] whose elements are expected to be contained within this [IterableLike].
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  * @throws IllegalArgumentException in case [expectedIterableLike] is not an

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/iterableLikeToContainInOrderOnlyGroupedCreators.kt

@@ -22,6 +22,8 @@ import kotlin.jvm.JvmName
  *   within the [IterableLike].
  * @param otherExpectedGroups Additional groups of values which are expected to appear after the [secondGroup] within
  *   [IterableLike] whereas the groups have to appear in the given order.
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
@@ -50,6 +52,8 @@ fun <E, T : IterableLike> EntryPointStep<E, T, InOrderOnlyGroupedWithinSearchBeh
  *   within the [IterableLike].
  * @param otherExpectedGroups Additional groups of values which are expected to appear after the [secondGroup] within
  *   [IterableLike] whereas the groups have to appear in the given order.
+ * @param report The lambda configuring the [InOrderOnlyReportingOptions] -- it is optional where
+ *   the default [InOrderOnlyReportingOptions] apply if not specified.
  *
  * @return an [Expect] for the subject of `this` expectation.
  *

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/test/kotlin/ch/tutteli/atrium/api/fluent/en_GB/IterableToContainInOrderOnlyElementsOfExpectationsSpec.kt

@@ -52,19 +52,17 @@ class IterableToContainInOrderOnlyElementsOfExpectationsSpec : Spek({
             aX: Array<out Double>,
             report: InOrderOnlyReportingOptions.() -> Unit
         ): Expect<Iterable<Double>> =
-            //TODO 0.18.0 remove if once implemented
             if (report === emptyInOrderOnlyReportOptions) expect.toContain.inOrder.only.elementsOf(listOf(a, *aX))
-            else expect.toContain.inOrder.only._logicAppend { valuesInOrderOnly(listOf(a, *aX), report) }
+            else expect.toContain.inOrder.only.elementsOf(listOf(a, *aX), report = report)
 
         private fun toContainInOrderOnlyNullableValues(
             expect: Expect<Iterable<Double?>>,
             a: Double?,
             aX: Array<out Double?>,
             report: InOrderOnlyReportingOptions.() -> Unit = {}
         ): Expect<Iterable<Double?>> =
-            //TODO 0.18.0 remove if once implemented
             if (report === emptyInOrderOnlyReportOptions) expect.toContain.inOrder.only.elementsOf(sequenceOf(a, *aX))
-            else expect.toContain.inOrder.only._logicAppend { valuesInOrderOnly(listOf(a, *aX), report) }
+            else expect.toContain.inOrder.only.elementsOf(listOf(a, *aX), report = report)
 
         private fun toContainExactlyElementsOfShortcut(
             expect: Expect<Iterable<Double>>,
@@ -81,7 +79,6 @@ class IterableToContainInOrderOnlyElementsOfExpectationsSpec : Spek({
         ): Expect<Iterable<Double?>> = expect.toContainExactlyElementsOf(sequenceOf(a, *aX).asIterable(), report)
     }
 
-
     @Suppress("unused", "UNUSED_VALUE")
     private fun ambiguityTest() {
         var list: Expect<List<Number>> = notImplemented()
@@ -93,16 +90,16 @@ class IterableToContainInOrderOnlyElementsOfExpectationsSpec : Spek({
         nList = nList.toContain.inOrder.only.elementsOf(listOf<Int>())
         subList = subList.toContain.inOrder.only.elementsOf(listOf<Int>())
         star = star.toContain.inOrder.only.elementsOf(listOf<Int>())
-        //TODO use the following with 0.18.0
-//        list = list.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { showAlwaysSummary() })
-//        nList = nList.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { showOnlyFailing() })
-//        subList = subList.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { })
-//        star = star.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { })
-
-        list = list.toContainExactlyElementsOf(1, report = { })
-        nList = nList.toContainExactlyElementsOf(1, report = { })
-        subList = subList.toContainExactlyElementsOf(1, report = { })
-        star = star.toContainExactlyElementsOf(1, report = { })
+
+        list = list.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { showAlwaysSummary() })
+        nList = nList.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { showOnlyFailing() })
+        subList = subList.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { })
+        star = star.toContain.inOrder.only.elementsOf(listOf<Int>(), report = { })
+
+        list = list.toContainExactlyElementsOf(listOf(1))
+        nList = nList.toContainExactlyElementsOf(listOf(1))
+        subList = subList.toContainExactlyElementsOf(listOf(1))
+        star = star.toContainExactlyElementsOf(listOf(1))
 
         list = list.toContainExactlyElementsOf(listOf(1, 1.2), report = { })
         nList = nList.toContainExactlyElementsOf(listOf(1, 1.2), report = { })